Build an Object-Oriented Python Project

Building an object-oriented Python project from scratch is the culmination of every concept, pattern, and practice covered in this section. You have learned how to define classes and create objects, how to use inheritance and composition, how to hide implementation details with encapsulation, how to design clean interfaces with abstraction, and how to make objects work naturally with Python's syntax through magic methods. This article walks through the process of applying all of those skills to a single project, from the initial planning stage through implementation and organization. The specific project, a task management application, is less important than the process used to build it. That process, identifying the right classes, designing their interfaces, choosing the right relationships, and organizing the code into a maintainable structure, transfers to every object-oriented project you will build in the future.

The task management application lets users create projects, add tasks to those projects, assign tasks to team members, track progress, and generate simple reports. It is complex enough to require multiple interacting classes but small enough to plan and implement in a single focused session. The requirements are intentionally modest so that the emphasis stays on the design process rather than on feature completeness. You can extend the application with persistence, a user interface, or additional features after completing the core design.

The article on building a library management system walked through a complete project with full code for each class. This article takes a different approach: it focuses on the planning and design decisions that precede the code, showing you how to think about a project before you start typing. The implementation details follow naturally from a well-thought-out design.

Planning the class structure

The first step in any object-oriented project is to identify the classes. Read through the requirements and extract the nouns: project, task, team member, report. Each noun is a candidate class. Not every noun becomes a class; some are attributes of other classes, and some are too simple to warrant their own abstraction. But the list of nouns gives you a starting point for the class diagram that will guide your implementation.

Next, identify the verbs in the requirements: create, assign, track, generate. Each verb is a candidate method. Ask which class should own each verb. Creating a task is something a project does, so the Project class should have an add_task method. Assigning a task to a team member is something a task does, so the Task class should have an assign_to method. Tracking progress is something the project does by examining its tasks, so the Project class should have a progress method that aggregates task statuses.

The relationships between classes emerge from the requirements as well. A project contains tasks, which is composition: the project creates and owns its tasks. A task is assigned to a team member, which is aggregation: the team member exists independently and can be assigned to multiple tasks. A report reads data from projects and tasks, which is dependency: the report uses project and task data but does not own or contain them. The article on class relationships in Python covers the full spectrum, and choosing the right relationship for each connection is one of the most important design decisions you make.

Designing the Task class

The Task class is the central data object in the application. Every task has a description, a priority, a status, and an optional assignee. The status starts as "pending" and progresses through "in progress" to "completed." The priority can be "low," "medium," or "high." The assignee starts as None and is set when a team member is assigned to the task.

The Task class's public interface should be small and focused. Methods for updating status, assigning a team member, and querying the task's state cover the operations that the rest of the system needs. Internal validation, like ensuring that a completed task cannot be reassigned, is handled inside the methods and hidden from callers:

python

class Task:
    VALID_PRIORITIES = {"low", "medium", "high"}
 
    def __init__(self, description, priority="medium"):
        if priority not in self.VALID_PRIORITIES:
            raise ValueError(f"Priority must be one of {self.VALID_PRIORITIES}")
        self.description = description
        self.priority = priority
        self._status = "pending"
        self._assignee = None

The constructor validates priority immediately, failing fast if an invalid value is provided. The status transition methods enforce the valid state progression from pending through in progress to completed:

python

    def start(self):
        if self._status == "pending":
            self._status = "in progress"
 
    def complete(self):
        self._status = "completed"
 
    def assign_to(self, member):
        self._assignee = member

The class attribute VALID_PRIORITIES defines the allowed values as a set, which makes the validation check both readable and efficient. The status transitions are controlled by dedicated methods rather than by directly setting the status attribute, which prevents invalid transitions like jumping from "pending" directly to "completed" without passing through "in progress."

Designing the Project class

The Project class aggregates tasks and provides operations that span multiple tasks. It stores tasks in a list, which is initialized in the constructor. The public interface includes methods for adding tasks, retrieving tasks by status, and calculating overall progress as a percentage of completed tasks:

python

class Project:
    def __init__(self, name, description=""):
        self.name = name
        self._tasks = []
 
    def add_task(self, description, priority="medium"):
        task = Task(description, priority)
        self._tasks.append(task)
        return task

The add_task method creates a Task and adds it to the internal list, returning the new task for further configuration. The progress and filtering methods operate across all tasks:

python

    def progress(self):
        if not self._tasks:
            return 0.0
        completed = sum(1 for t in self._tasks if t._status == "completed")
        return (completed / len(self._tasks)) * 100
 
    def tasks_by_status(self, status):
        return [t for t in self._tasks if t._status == status]

This pattern, where the container creates the contained object, is composition. The Project owns its tasks, and tasks do not exist independently of the project that contains them. The progress method calculates the percentage of completed tasks, handling the edge case of an empty project gracefully.

Organizing code into modules

As the project grows beyond a single file, organizing classes into modules keeps the codebase navigable. A module is a Python file, and related classes should live in the same module. The task management application might have a models module containing Task, Project, and TeamMember, a services module containing Report and any business logic that spans multiple models, and a main module that ties everything together and provides the entry point.

Module organization follows the principle of cohesion: classes that change together should live together. If every change to Task requires a corresponding change to Project, the two classes belong in the same module. If changes to Report never affect Task or Project, Report belongs in its own module. This organization emerges over time as you observe which parts of the codebase change together, and the initial module layout is a starting point that you refine as the project evolves.

The article on building reusable Python classes covers interface design and dependency management in depth, and the article on Python OOP design best practices covers the SOLID principles adapted for Python. Together with the planning and organization patterns in this article, they give you a complete methodology for building object-oriented Python projects of any size.