Python Capstone Project

Build, test, and package a small delivery-order tracker that brings together domain models, SQLite persistence, a CLI, and production-minded error handling.

Est. 75 min Updated Suggest a fix
// Part 01 — The Brief

Build a Delivery Order Tracker You Can Actually Run

In this capstone you will create a small command-line application for a local delivery team. Staff can add an order, list saved orders, and move an order through a controlled lifecycle. Data must survive a restart, invalid transitions must fail clearly, and tests must run without touching a real user database.

The project intentionally uses Python's standard library: dataclasses for the domain record, Enum for status values, sqlite3 for persistence, argparse for the command-line interface, and unittest for automated tests. The focus is integration and clean boundaries, not adding a framework.

💡 Note
Prerequisites: functions, classes and dataclasses (Lesson 26), exceptions, modules, command-line basics (Lesson 47), and SQLite transactions (Lesson 40). Do the project in a virtual environment and keep the database file out of source control.
// Part 02 — Requirements and Boundaries

Write Down What Done Means

  • Create orders with a customer name and positive amount in paise.
  • Persist each order with a unique ID, current status, and creation timestamp.
  • List all orders or filter by a known status.
  • Allow only explicit lifecycle transitions: placed → confirmed or cancelled; confirmed → in_transit or cancelled; in_transit → delivered.
  • Report a missing order and an illegal transition as useful errors; never silently change the record.
  • Provide automated tests for normal behavior, validation, persistence, and invalid transitions.

Keep three responsibilities distinct. The domain layer owns status rules. The storage layer owns SQL and transactions. The CLI parses human input and formats output. This boundary makes it possible to test a transition without starting a terminal or opening a database.

A small project layout
delivery-tracker/
├── delivery_tracker.py   # domain, storage, CLI for this small first version
├── test_delivery_tracker.py
├── .gitignore
└── README.md

For a larger application, split this into a package with separate domain, repository, and CLI modules. Starting with one easy-to-run file keeps the first version reviewable; clear functions make a later split straightforward.

// Part 03 — Domain Model

Make Invalid State Changes Explicit

Start with a data class and enum. Store the amount as integer paise so arithmetic does not depend on binary floating-point rounding. Use an allow-list of transitions and raise a domain error when a requested move is not legal.

delivery_tracker.py — domain
from dataclasses import dataclass
from enum import Enum

class Status(str, Enum):
    PLACED = "placed"
    CONFIRMED = "confirmed"
    IN_TRANSIT = "in_transit"
    DELIVERED = "delivered"
    CANCELLED = "cancelled"

@dataclass(frozen=True)
class Order:
    id: int
    customer: str
    total_paise: int
    status: Status
    created_at: str

ALLOWED_TRANSITIONS = {
    Status.PLACED: {Status.CONFIRMED, Status.CANCELLED},
    Status.CONFIRMED: {Status.IN_TRANSIT, Status.CANCELLED},
    Status.IN_TRANSIT: {Status.DELIVERED},
    Status.DELIVERED: set(),
    Status.CANCELLED: set(),
}

class OrderNotFoundError(LookupError):
    pass

class InvalidTransitionError(ValueError):
    pass

def require_transition(current: Status, target: Status) -> None:
    if target not in ALLOWED_TRANSITIONS[current]:
        raise InvalidTransitionError(
            f"Cannot move an order from {current.value} to {target.value}"
        )

The domain function does not know SQLite or command-line arguments. That is deliberate: later we can test it with ordinary values. A frozen dataclass prevents callers from accidentally reassigning fields; it does not recursively freeze nested objects, but this record contains immutable values.

// Part 04 — SQLite Repository

Persist with Parameters and Transaction Scope

Next add database helpers. Each operation opens and closes its own connection, which keeps this small CLI's resource lifetime obvious. The schema includes constraints so basic data rules are enforced even if another code path writes to the database. Queries bind values rather than interpolating them into SQL.

delivery_tracker.py — storage
import sqlite3
from contextlib import closing
from datetime import datetime, timezone
from pathlib import Path


def connect(db_path: Path) -> sqlite3.Connection:
    connection = sqlite3.connect(db_path)
    connection.row_factory = sqlite3.Row
    return connection


def initialize(db_path: Path) -> None:
    with closing(connect(db_path)) as connection:
        with connection:
            connection.execute("""
                CREATE TABLE IF NOT EXISTS orders (
                    id INTEGER PRIMARY KEY,
                    customer TEXT NOT NULL CHECK (length(customer) > 0),
                    total_paise INTEGER NOT NULL CHECK (total_paise > 0),
                    status TEXT NOT NULL,
                    created_at TEXT NOT NULL
                )
            """)


def add_order(db_path: Path, customer: str, total_paise: int) -> Order:
    customer = customer.strip()
    if not customer:
        raise ValueError("Customer name cannot be empty")
    if total_paise <= 0:
        raise ValueError("Amount in paise must be positive")
    created_at = datetime.now(timezone.utc).isoformat()
    with closing(connect(db_path)) as connection:
        with connection:
            cursor = connection.execute(
                "INSERT INTO orders (customer, total_paise, status, created_at) "
                "VALUES (?, ?, ?, ?)",
                (customer, total_paise, Status.PLACED.value, created_at),
            )
            order_id = cursor.lastrowid
            if order_id is None:
                raise RuntimeError("SQLite did not return the new order ID")
    return Order(order_id, customer, total_paise, Status.PLACED, created_at)


def list_orders(db_path: Path, status: Status | None = None) -> list[Order]:
    query = "SELECT id, customer, total_paise, status, created_at FROM orders"
    parameters: tuple[str, ...] = ()
    if status is not None:
        query += " WHERE status = ?"
        parameters = (status.value,)
    query += " ORDER BY id"
    with closing(connect(db_path)) as connection:
        rows = connection.execute(query, parameters).fetchall()
    return [
        Order(row["id"], row["customer"], row["total_paise"],
              Status(row["status"]), row["created_at"])
        for row in rows
    ]


def transition_order(db_path: Path, order_id: int, target: Status) -> Order:
    with closing(connect(db_path)) as connection:
        with connection:
            row = connection.execute(
                "SELECT id, customer, total_paise, status, created_at "
                "FROM orders WHERE id = ?", (order_id,),
            ).fetchone()
            if row is None:
                raise OrderNotFoundError(f"Order {order_id} does not exist")
            current = Status(row["status"])
            require_transition(current, target)
            connection.execute(
                "UPDATE orders SET status = ? WHERE id = ?",
                (target.value, order_id),
            )
    return Order(row["id"], row["customer"], row["total_paise"],
                 target, row["created_at"])
⚠️ Important
The query appends a fixed SQL fragment chosen by the program and binds the status value. Do not append a user-provided column or SQL expression directly. If sorting or filtering by dynamic fields is added, map public choices to known SQL identifiers.
// Part 05 — Command-Line Interface

Make the Application Useful from a Terminal

Use argparse to define clear subcommands and let it generate help text. The database path is configurable, so tests and developers can use separate files. Parse state names against the enum rather than accepting arbitrary values.

delivery_tracker.py — CLI and entry point
import argparse
import sys


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Track delivery orders")
    parser.add_argument("--db", type=Path, default=Path("orders.sqlite3"))
    commands = parser.add_subparsers(dest="command", required=True)

    add = commands.add_parser("add", help="create an order")
    add.add_argument("customer")
    add.add_argument("total_paise", type=int)

    show = commands.add_parser("list", help="list orders")
    show.add_argument("--status", choices=[s.value for s in Status])

    move = commands.add_parser("transition", help="change order status")
    move.add_argument("order_id", type=int)
    move.add_argument("status", choices=[s.value for s in Status])
    return parser


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    try:
        initialize(args.db)
        if args.command == "add":
            order = add_order(args.db, args.customer, args.total_paise)
            print(f"Created order {order.id} for {order.customer}")
        elif args.command == "list":
            status = Status(args.status) if args.status else None
            for order in list_orders(args.db, status):
                print(f"{order.id} | {order.customer} | "
                      f"{order.total_paise} paise | {order.status.value}")
        elif args.command == "transition":
            order = transition_order(args.db, args.order_id, Status(args.status))
            print(f"Order {order.id} is now {order.status.value}")
        return 0
    except (ValueError, OrderNotFoundError, sqlite3.Error) as error:
        print(f"error: {error}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())

The code initializes the schema before each operation and returns a meaningful process exit status. Test the commands manually in a disposable directory:

Run the application
python delivery_tracker.py --db demo.sqlite3 add Asha 129900
python delivery_tracker.py --db demo.sqlite3 list
python delivery_tracker.py --db demo.sqlite3 transition 1 confirmed
python delivery_tracker.py --db demo.sqlite3 list --status confirmed
// Part 06 — Tests

Test Behavior Without Reusing a Real Database

Tests should create isolated data and clean it up automatically. This example creates a uniquely named database beside the test and removes it in teardown. Cover both the successful path and the failure contract, and check persisted results through the same public functions a user would call.

test_delivery_tracker.py
import unittest
from pathlib import Path
from uuid import uuid4

from delivery_tracker import (
    InvalidTransitionError, OrderNotFoundError, Status,
    add_order, initialize, list_orders, transition_order,
)

class DeliveryTrackerTests(unittest.TestCase):
    def setUp(self) -> None:
        self.db_path = Path(f"test-orders-{uuid4().hex}.sqlite3")
        initialize(self.db_path)

    def tearDown(self) -> None:
        if self.db_path.exists():
            self.db_path.unlink()

    def test_create_and_list_order(self) -> None:
        created = add_order(self.db_path, "Asha", 129900)
        saved = list_orders(self.db_path)
        self.assertEqual(len(saved), 1)
        self.assertEqual(saved[0].id, created.id)
        self.assertEqual(saved[0].status, Status.PLACED)

    def test_reject_non_positive_amount(self) -> None:
        with self.assertRaises(ValueError):
            add_order(self.db_path, "Asha", 0)

    def test_allowed_transition_persists(self) -> None:
        order = add_order(self.db_path, "Ravi", 50000)
        moved = transition_order(self.db_path, order.id, Status.CONFIRMED)
        self.assertEqual(moved.status, Status.CONFIRMED)
        self.assertEqual(list_orders(self.db_path)[0].status, Status.CONFIRMED)

    def test_reject_terminal_transition(self) -> None:
        order = add_order(self.db_path, "Meera", 70000)
        transition_order(self.db_path, order.id, Status.CANCELLED)
        with self.assertRaises(InvalidTransitionError):
            transition_order(self.db_path, order.id, Status.CONFIRMED)

    def test_missing_order_is_clear(self) -> None:
        with self.assertRaises(OrderNotFoundError):
            transition_order(self.db_path, 999, Status.CONFIRMED)

if __name__ == "__main__":
    unittest.main()
Run the test suite
python -m unittest -v
🎯 Pro Tip
Add a test for invalid customer names and CLI argument parsing. If you extract transition rules into their own function, test that function directly with no database setup.
// Part 07 — Production Readiness

Make the Demo Responsible Before Calling It Production

This is a learning project, not a production order platform. Before real customer data is involved, decide how you will authenticate staff, authorize each action, validate user input, back up and restore data, protect personal information, and monitor failures. A local SQLite file does not provide a multi-user access-control system.

For distribution, keep the application in a version-controlled repository, document supported Python environments, add a .gitignore entry for database files and virtual environments, and package a console command through project metadata once the code is split into an importable package. For deployment to a server, move configuration out of source, plan database migrations, test restore procedures, and choose a database suited to the concurrency and availability requirements.

Useful .gitignore entries
.venv/
__pycache__/
*.py[cod]
*.sqlite3
orders.sqlite3
⚠️ Important
Never commit a real database containing customer information. A local demo database can still contain personal data; use synthetic records in examples and tests.
// Part 08 — Review Rubric

Evaluate the Result Like an Engineer

AreaReady when…Evidence
Domain rulesIllegal status changes cannot be persistedA focused transition test
Data integritySQL values are bound and schema constraints are presentReview INSERT/UPDATE and failure tests
Resource handlingConnections close and transactions roll back on errorContext-managed code paths
UsabilityHelp, validation messages, and exit status are clearTry invalid CLI inputs
MaintainabilityDomain, storage, and CLI responsibilities are separableFunctions can be tested independently
OperationsDatabase location, backup, migration, and privacy limits are documentedREADME checklist and safe sample data

Ask someone else to run the setup from a clean checkout. If they need undocumented steps, or if tests depend on your local data, the project is not yet reproducible.

// Part 09 — Extensions and Practice

Make the Next Iteration Deliberate

  1. Split the file into a domain, repository, and cli package without changing behavior.
  2. Add an order event-history table and write each allowed transition and its audit event in one transaction.
  3. Add a CSV export using the standard library, and write output atomically so an interrupted export does not leave a partial report.
  4. Add Pydantic validation at a future HTTP boundary while keeping the core domain rules independent of the web framework.
  5. Use SQLAlchemy instead of sqlite3 and compare readability, query behavior, and migration requirements.

Submission checklist: source code, tests passing from a clean checkout, sample CLI commands, no committed database or secrets, and a short design note describing trade-offs.

🎯 Key Takeaways

  • ✓A useful capstone begins with explicit requirements and separates domain decisions from persistence and user interaction.
  • ✓Dataclasses and enums make the order model and status vocabulary explicit; transition rules remain application logic.
  • ✓SQLite plus parameterized queries provides durable storage while preserving control over SQL and transactions.
  • ✓A small argparse CLI can return clear output and meaningful exit codes without a web framework.
  • ✓Isolated tests should prove persistence, validation, legal transitions, and failure behavior.
  • ✓A learning project needs documented limits: authentication, privacy, migrations, backup, and deployment are real production work.

What comes next

Lesson 50 synthesizes the track's core concepts into interview questions, patterns, and trade-offs.

Lesson 50 → Python Interview Prep — Common Questions and Patterns

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...