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.
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.
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.
delivery-tracker/
├── delivery_tracker.py # domain, storage, CLI for this small first version
├── test_delivery_tracker.py
├── .gitignore
└── README.mdFor 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.
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.
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.
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.
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"])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.
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:
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 confirmedTest 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.
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()python -m unittest -vMake 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.
.venv/
__pycache__/
*.py[cod]
*.sqlite3
orders.sqlite3Evaluate the Result Like an Engineer
| Area | Ready when… | Evidence |
|---|---|---|
| Domain rules | Illegal status changes cannot be persisted | A focused transition test |
| Data integrity | SQL values are bound and schema constraints are present | Review INSERT/UPDATE and failure tests |
| Resource handling | Connections close and transactions roll back on error | Context-managed code paths |
| Usability | Help, validation messages, and exit status are clear | Try invalid CLI inputs |
| Maintainability | Domain, storage, and CLI responsibilities are separable | Functions can be tested independently |
| Operations | Database location, backup, migration, and privacy limits are documented | README 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.
Make the Next Iteration Deliberate
- Split the file into a
domain,repository, andclipackage without changing behavior. - Add an order event-history table and write each allowed transition and its audit event in one transaction.
- Add a CSV export using the standard library, and write output atomically so an interrupted export does not leave a partial report.
- Add Pydantic validation at a future HTTP boundary while keeping the core domain rules independent of the web framework.
- 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 PatternsHELP US IMPROVE
How was this lesson?
Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.
Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.
Discussion
0Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.
