Capstone: Ship a Real Python Project

This is the moment you stop being a student and start being a builder. A working artifact your grandmother can actually use will always beat a stack of completion certificates. This is the link you send to recruiters, the demo you open in interviews, the project that turns "I'm learning Python" into "here's what I shipped."

Learning Objectives

After this lesson, you will be able to:

Plan a real project end-to-end — from a 1-paragraph problem statement to a working spec to running code
Apply everything you've learned (functions, classes, file I/O, error handling, APIs) inside a single coherent codebase
Write a README that explains the problem, your approach, and how to run it — clearly enough for a stranger to follow
Get specific, actionable feedback on your code by asking the AI tutor for a senior-engineer code review

#Pick your project

This is a real capstone, not a worked example. You'll pick one project from the four options below, build it over the next 4-8 hours (spread across as many days as you like), and submit it.

Read all four options before choosing. Pick the one that excites you most. Excitement is the only fuel that gets you through hour three of a real project.

#Option A: CLI LLM Pet Project · Beginner · ~4 hours

A command-line chatbot powered by Claude. The user picks a "persona" — cooking coach, code reviewer, stoic philosopher, tarot reader, dungeon master, midwestern aunt — and chats with it from the terminal. The chat history persists across runs so the bot remembers prior conversations.

Skills you'll exercise: requests (or the anthropic SDK), JSON parsing, functions, dicts, file I/O for chat-history persistence.

Architecture hint

personas.json, a dict of {persona_name: system_prompt} so adding a new persona is a 2-line change
chat_history.json, which appends every user/assistant turn so the bot has memory between sessions
chat.py — the CLI entry point: picks a persona, loads history, loops on input(), calls the API, prints the reply, saves history

Stretch goals: add a --reset flag to wipe history; let the user /switch persona mid-chat; colorize the output with rich.

#Option B: Personal Data Analyzer · Intermediate · ~6 hours

Pick one dataset from your own life and build a CLI tool that loads the file, computes 5 interesting stats, and saves a report. Examples that work well:

Spotify listening history (request your data from Spotify — comes as JSON)
GitHub commit history (use the GitHub REST API or git log --pretty=format: exported to CSV)
Screen-time export from your phone
Browser history (history.sqlite on most browsers)
Fitness app data (Apple Health, Strava, Garmin)

Skills you'll exercise: file I/O, csv / json / pandas, datetime, classes to organize the analyzer, matplotlib for one chart, argparse for CLI args.

Architecture hint

analyzer.py, a DataAnalyzer class with methods load(), compute_stats(), top_n(), by_month()
report.py — formats the stats into a Markdown or plain-text report
main.py — CLI entry point parsing --input file.csv --output report.md

Stretch goals: save the chart as a PNG and embed it in the report; add a --compare flag to diff two time periods.

#Option C: Mini FastAPI Service · Advanced · ~8 hours

A real HTTP API you can curl. Pick a topic (jokes, recipe search, currency converter, dad-jokes-with-attitude, anything). Build a FastAPI service with 3-4 endpoints, Pydantic models for every request and response, real error handling, and a /health route for production-readiness.

Skills you'll exercise: FastAPI routing, Pydantic schemas, type hints, error handling with HTTPException, JSON serialization, basic pytest coverage.

Architecture hint

main.py — FastAPI app with route handlers
models.py — Pydantic schemas (JokeIn, JokeOut, ErrorOut)
service.py — business logic, separated from routing so it's testable
tests/ — at least 3 pytest tests hitting the API via TestClient

Stretch goals: add request logging middleware; deploy it to Render or Fly.io with a public URL; write an OpenAPI client.

#Option D: Propose your own · Any difficulty

If none of the above fit you, write your own. Constraints:

Must be a single coherent Python project (not 5 disconnected scripts).
Must produce something a real user, including a non-programmer in your life, can actually use.
Must touch at least 4 skills from the prerequisite recap above.

Submit a 1-paragraph proposal to the AI tutor first — say what it does, who it's for, and how you'll build it. The tutor will sanity-check scope (is it too small? too large? missing the "real user" piece?) before you start. Spend 10 minutes on the proposal — it'll save you 2 hours of wrong-direction coding.

#The build process: 4 phases

You're not going to write everything at once. You're going to build it the way professionals do: one slice at a time, running the code constantly.

#Phase 1: Plan (30 minutes)

Write a 1-paragraph spec: What does it do? Who uses it? What's the input, what's the output?
Sketch the file structure. Three to five files is right for this size of project.
List the 3-5 functions or classes you'll need. Just the names and one-line descriptions — no implementation yet.

That's it. Resist the urge to start coding. Spec first.

#Phase 2: Skeleton (1 hour)

Create the empty files.
Define every function signature with pass as the body.
Add a docstring to each function explaining what it should do when implemented.
Run python main.py (or whatever your entry point is) and verify the import graph doesn't crash. The skeleton should run silently — no logic, no output, no errors.

This phase feels pointless. It is not. A working skeleton you can extend feature by feature is what makes the difference between finishing and stalling.

#Phase 3: Implement (most of the time, ~2-5 hours)

Pick ONE function. Make it work end-to-end. Test it manually in the terminal. Move on to the next function. Repeat.

#Phase 4: Polish (1 hour)

Write the README (template below — copy/paste it).
Add error handling for the obvious failure modes: missing files, bad API keys, malformed input, empty user input.
Take a screenshot of it working, or record a 30-second screen recording. This is for your portfolio and your LinkedIn post.
Run the whole thing one more time on a clean terminal as if you were a stranger. Did anything surprise you? Fix it.

#A starter for Option A: the persona chatbot

If you picked Option A, here is a minimal skeleton to get you past Phase 2. Edit, run, extend.

pythonplayground.py · Pyodide

Input for this program

This exercise calls input(). Python here can't pause to ask you, so type the answers below before running — one value per line, in the order the program asks for them.

import json
import os
from pathlib import Path
from anthropic import Anthropic

PERSONAS_FILE = Path("personas.json")
HISTORY_FILE = Path("chat_history.json")

def load_personas() -> dict:
  """Load the personas dict from JSON, or return defaults."""
  if PERSONAS_FILE.exists():
      return json.loads(PERSONAS_FILE.read_text())
  return {
      "cooking_coach": "You are an upbeat cooking coach. Suggest recipes from whatever the user has in their fridge. Be encouraging.",
      "code_reviewer": "You are a senior Python reviewer. Be direct, point at line numbers, and never lie to spare feelings.",
      "stoic": "You are a stoic philosopher in the tradition of Marcus Aurelius. Reply in short, calming aphorisms."
  }

def load_history() -> list:
  """Load prior chat turns so the bot has memory across runs."""
  if HISTORY_FILE.exists():
      return json.loads(HISTORY_FILE.read_text())
  return []

def save_history(history: list) -> None:
  """Persist the full conversation to disk."""
  HISTORY_FILE.write_text(json.dumps(history, indent=2))

def chat(persona_name: str, system_prompt: str) -> None:
  """Run the REPL: prompt user, call Claude, print reply, save."""
  client = Anthropic()  # reads ANTHROPIC_API_KEY from env
  history = load_history()
  print(f"\nChatting with {persona_name}. Type 'quit' to exit.\n")

while True:
      user_msg = input("You: ").strip()
      if user_msg.lower() in {"quit", "exit"}:
          break
      if not user_msg:
          continue

history.append({"role": "user", "content": user_msg})
      try:
          response = client.messages.create(
              model="claude-opus-4-7",
              max_tokens=400,
              system=system_prompt,
              messages=history,
          )
          reply = response.content[0].text
      except Exception as e:
          print(f"[API error: {e}]")
          history.pop()  # don't poison history with an un-replied turn
          continue

history.append({"role": "assistant", "content": reply})
      save_history(history)
      print(f"\n{persona_name}: {reply}\n")

def main() -> None:
  personas = load_personas()
  print("Available personas:")
  for name in personas:
      print(f"  - {name}")
  choice = input("\nPick one: ").strip()
  if choice not in personas:
      raise ValueError(f"Unknown persona: {choice}")
  chat(choice, personas[choice])

if __name__ == "__main__":
  main()

Watch Out

Don't hardcode your API key

Fix: Always read the key from an environment variable. The Anthropic SDK does this automatically when you call Anthropic() with no arguments — it looks up ANTHROPIC_API_KEY. Set it once in your shell: export ANTHROPIC_API_KEY=sk-ant-... and add .env, *.env, and chat_history.json to .gitignore before your first commit.

Hardcoding the API key directly in source: client = Anthropic(api_key='sk-ant-real-secret-here')

Hardcoded secrets get committed to git. GitHub's secret scanners pick them up within seconds of a public push, bots drain hundreds of dollars from your account within minutes, and you spend the rest of the day rotating credentials and emailing Anthropic support. Environment variables keep secrets out of the codebase entirely. This is non-negotiable.

#The README template: copy this exactly

Your README is half the project. Recruiters and hiring managers read it before they read code — sometimes instead of reading code. A good README converts a casual GitHub visit into "I want to interview this person." Copy the template below and fill in each section.

markdown

# Project Name

> One-sentence tagline. What it does, in plain English.

## What it does

A 3-5 sentence paragraph explaining the problem you wanted to solve, who
it's for, and what the program does. Plain English. No jargon. Imagine
explaining it to a smart friend who doesn't code.

## Demo

![Screenshot of the app running](./demo.png)

(Or embed a 30-second screen recording, or a link to a deployed URL.)

## Setup

```bash
# 1. Clone the repo
git clone https://github.com/your-username/your-project.git
cd your-project

# 2. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate     # macOS / Linux
# .venv\Scripts\activate      # Windows
pip install -r requirements.txt

# 3. Set your API key (if applicable)
export ANTHROPIC_API_KEY=sk-ant-...
```

## Usage

```bash
python main.py --input data.csv --output report.md
```

Sample output:

```
=== Personal Data Analyzer ===
Loaded 1,243 rows.
Top track: "Sunset Lover" — 89 plays
Most-listened month: October 2025
Report saved to report.md
```

## How it works

A 1-paragraph architectural overview. What are the main files? What does
each one do? What's the data flow from input to output? Don't reproduce
the code — describe the *shape* of it.

## What I learned

- One specific technical lesson (e.g., "Pydantic's validation errors are
  way more useful than try/except chains.")
- A second specific lesson — ideally one you got wrong first, then fixed.
- A debugging story — the bug that took you the longest to find.
- One thing about your own process (e.g., "I shipped faster once I stopped
  trying to design the whole API before writing any of it.")

## What I'd add next

- A concrete feature you'd add with another week.
- A second feature — something a real user has asked for, or that would
  obviously improve the product.
- An infrastructure or quality improvement (tests, CI, deployment, logging).
```

The "What I learned" and "What I'd add next" sections are the ones that turn a project from "homework" into "this person thinks like an engineer." Do not skip them.

#Get an AI code review

Once your project runs end-to-end, drop your full code into the reviewer below. Claude is genuinely good at this — better than most code reviews you'll get as a junior developer. You'll get back three concrete bugs, three specific strengths, and the ONE highest-impact change that would make this resume-grade.

pythonGet an AI code reviewClaude · senior-engineer review

Paste your capstone code. You'll get back a senior-engineer-style review — three concrete bugs to fix, three specific strengths, and the ONE highest-impact change that would make this resume-grade.

capstone.py1 line · 0 chars

When the review comes back, don't just accept it. Push back. Ask "why?" Ask "what's the alternative?" Ask "would Pydantic actually fix that?" Open the AI tutor (the button bottom-right of any lesson page) and have the conversation. You will learn more from one 15-minute review-and-pushback session than from another hour of reading docs.

Prefer the manual prompt? Open the AI tutor and paste this:

You are a senior Python code reviewer. I just wrote this for a Python
learning capstone. Review it as if I were applying for a junior Python
job. Tell me:

1. Three concrete bugs or risks (even if minor) — be specific, cite line
   numbers if possible.
2. Three things I did well that I should keep doing.
3. The ONE thing I should change to make this resume-grade.

Be direct. Don't be polite — be useful.

[paste my code below]

You finished. You shipped a thing. The world doesn't know yet — fix that.

Push it to a fresh public GitHub repo. New repo, clean history, good README at the top.
Add the link to your portfolio at /portfolio/python (or wherever your portfolio lives). One line: "Python capstone — built X in N hours. [link]"
Post it to LinkedIn using this structure:

I just built [X] with Python in [N] hours as my capstone project. It [does Y for Z users]. The thing that surprised me most: [one honest lesson]. Code + README here: [link]. Feedback welcome.

Don't oversell. Don't underplay. Just describe what you did and what you learned. The honesty is what makes recruiters reach out.
(Optional) Reply to the QuizBlock below with what you built — the AI tutor will read it and give you a pat on the back, a frown, or a question you hadn't thought of.

Recap

Key Takeaways

Real Python projects start small and grow feature-by-feature — never write all the code before running any of it
A README is half the project — recruiters and hiring managers read it before they read the code, sometimes instead of the code
The AI tutor is your on-demand senior code reviewer — use it liberally, push back on its answers, and learn from the dialogue

Quick Check1 / 3

You're about to start building Option B (the data analyzer). What should you do FIRST?

That closes the Python Foundations track — fifty-four lessons from your first print() to a working LLM-powered script you can hand to a recruiter. Python is the substrate; from here, every track in the curriculum will assume you can read a function signature, write a loop, debug an exception, and call an API. Next up is the SQL & Database Mastery track, because every production ML system has a database behind it — and the moment you start working with real data in the Data Foundations and Classical ML tracks, you will need to query it before you can model it.

Capstone: Ship a Real Python Project

Learning Objectives

After this lesson, you will be able to:

Plan a real project end-to-end — from a 1-paragraph problem statement to a working spec to running code
Apply everything you've learned (functions, classes, file I/O, error handling, APIs) inside a single coherent codebase
Write a README that explains the problem, your approach, and how to run it — clearly enough for a stranger to follow
Get specific, actionable feedback on your code by asking the AI tutor for a senior-engineer code review

#Pick your project

This is a real capstone, not a worked example. You'll pick one project from the four options below, build it over the next 4-8 hours (spread across as many days as you like), and submit it.

Read all four options before choosing. Pick the one that excites you most. Excitement is the only fuel that gets you through hour three of a real project.

#Option A: CLI LLM Pet Project · Beginner · ~4 hours

Skills you'll exercise: requests (or the anthropic SDK), JSON parsing, functions, dicts, file I/O for chat-history persistence.

Architecture hint

personas.json, a dict of {persona_name: system_prompt} so adding a new persona is a 2-line change
chat_history.json, which appends every user/assistant turn so the bot has memory between sessions
chat.py — the CLI entry point: picks a persona, loads history, loops on input(), calls the API, prints the reply, saves history

Stretch goals: add a --reset flag to wipe history; let the user /switch persona mid-chat; colorize the output with rich.

#Option B: Personal Data Analyzer · Intermediate · ~6 hours

Pick one dataset from your own life and build a CLI tool that loads the file, computes 5 interesting stats, and saves a report. Examples that work well:

Spotify listening history (request your data from Spotify — comes as JSON)
GitHub commit history (use the GitHub REST API or git log --pretty=format: exported to CSV)
Screen-time export from your phone
Browser history (history.sqlite on most browsers)
Fitness app data (Apple Health, Strava, Garmin)

Skills you'll exercise: file I/O, csv / json / pandas, datetime, classes to organize the analyzer, matplotlib for one chart, argparse for CLI args.

Architecture hint

analyzer.py, a DataAnalyzer class with methods load(), compute_stats(), top_n(), by_month()
report.py — formats the stats into a Markdown or plain-text report
main.py — CLI entry point parsing --input file.csv --output report.md

Stretch goals: save the chart as a PNG and embed it in the report; add a --compare flag to diff two time periods.

#Option C: Mini FastAPI Service · Advanced · ~8 hours

Skills you'll exercise: FastAPI routing, Pydantic schemas, type hints, error handling with HTTPException, JSON serialization, basic pytest coverage.

Architecture hint

main.py — FastAPI app with route handlers
models.py — Pydantic schemas (JokeIn, JokeOut, ErrorOut)
service.py — business logic, separated from routing so it's testable
tests/ — at least 3 pytest tests hitting the API via TestClient

Stretch goals: add request logging middleware; deploy it to Render or Fly.io with a public URL; write an OpenAPI client.

#Option D: Propose your own · Any difficulty

If none of the above fit you, write your own. Constraints:

Must be a single coherent Python project (not 5 disconnected scripts).
Must produce something a real user, including a non-programmer in your life, can actually use.
Must touch at least 4 skills from the prerequisite recap above.

#The build process: 4 phases

You're not going to write everything at once. You're going to build it the way professionals do: one slice at a time, running the code constantly.

#Phase 1: Plan (30 minutes)

Write a 1-paragraph spec: What does it do? Who uses it? What's the input, what's the output?
Sketch the file structure. Three to five files is right for this size of project.
List the 3-5 functions or classes you'll need. Just the names and one-line descriptions — no implementation yet.

That's it. Resist the urge to start coding. Spec first.

#Phase 2: Skeleton (1 hour)

Create the empty files.
Define every function signature with pass as the body.
Add a docstring to each function explaining what it should do when implemented.
Run python main.py (or whatever your entry point is) and verify the import graph doesn't crash. The skeleton should run silently — no logic, no output, no errors.

This phase feels pointless. It is not. A working skeleton you can extend feature by feature is what makes the difference between finishing and stalling.

#Phase 3: Implement (most of the time, ~2-5 hours)

Pick ONE function. Make it work end-to-end. Test it manually in the terminal. Move on to the next function. Repeat.

#Phase 4: Polish (1 hour)

Write the README (template below — copy/paste it).
Add error handling for the obvious failure modes: missing files, bad API keys, malformed input, empty user input.
Take a screenshot of it working, or record a 30-second screen recording. This is for your portfolio and your LinkedIn post.
Run the whole thing one more time on a clean terminal as if you were a stranger. Did anything surprise you? Fix it.

#A starter for Option A: the persona chatbot

If you picked Option A, here is a minimal skeleton to get you past Phase 2. Edit, run, extend.

pythonplayground.py · Pyodide

Input for this program

This exercise calls input(). Python here can't pause to ask you, so type the answers below before running — one value per line, in the order the program asks for them.

import json
import os
from pathlib import Path
from anthropic import Anthropic

PERSONAS_FILE = Path("personas.json")
HISTORY_FILE = Path("chat_history.json")

def load_history() -> list:
  """Load prior chat turns so the bot has memory across runs."""
  if HISTORY_FILE.exists():
      return json.loads(HISTORY_FILE.read_text())
  return []

def save_history(history: list) -> None:
  """Persist the full conversation to disk."""
  HISTORY_FILE.write_text(json.dumps(history, indent=2))

while True:
      user_msg = input("You: ").strip()
      if user_msg.lower() in {"quit", "exit"}:
          break
      if not user_msg:
          continue

history.append({"role": "assistant", "content": reply})
      save_history(history)
      print(f"\n{persona_name}: {reply}\n")

if __name__ == "__main__":
  main()

Watch Out

Don't hardcode your API key

Hardcoding the API key directly in source: client = Anthropic(api_key='sk-ant-real-secret-here')

#The README template: copy this exactly

markdown

# Project Name

> One-sentence tagline. What it does, in plain English.

## What it does

A 3-5 sentence paragraph explaining the problem you wanted to solve, who
it's for, and what the program does. Plain English. No jargon. Imagine
explaining it to a smart friend who doesn't code.

## Demo

![Screenshot of the app running](./demo.png)

(Or embed a 30-second screen recording, or a link to a deployed URL.)

## Setup

```bash
# 1. Clone the repo
git clone https://github.com/your-username/your-project.git
cd your-project

# 2. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate     # macOS / Linux
# .venv\Scripts\activate      # Windows
pip install -r requirements.txt

# 3. Set your API key (if applicable)
export ANTHROPIC_API_KEY=sk-ant-...
```

## Usage

```bash
python main.py --input data.csv --output report.md
```

Sample output:

```
=== Personal Data Analyzer ===
Loaded 1,243 rows.
Top track: "Sunset Lover" — 89 plays
Most-listened month: October 2025
Report saved to report.md
```

## How it works

A 1-paragraph architectural overview. What are the main files? What does
each one do? What's the data flow from input to output? Don't reproduce
the code — describe the *shape* of it.

## What I learned

- One specific technical lesson (e.g., "Pydantic's validation errors are
  way more useful than try/except chains.")
- A second specific lesson — ideally one you got wrong first, then fixed.
- A debugging story — the bug that took you the longest to find.
- One thing about your own process (e.g., "I shipped faster once I stopped
  trying to design the whole API before writing any of it.")

## What I'd add next

- A concrete feature you'd add with another week.
- A second feature — something a real user has asked for, or that would
  obviously improve the product.
- An infrastructure or quality improvement (tests, CI, deployment, logging).
```

The "What I learned" and "What I'd add next" sections are the ones that turn a project from "homework" into "this person thinks like an engineer." Do not skip them.

#Get an AI code review

pythonGet an AI code reviewClaude · senior-engineer review

Paste your capstone code. You'll get back a senior-engineer-style review — three concrete bugs to fix, three specific strengths, and the ONE highest-impact change that would make this resume-grade.

capstone.py1 line · 0 chars

Prefer the manual prompt? Open the AI tutor and paste this:

You are a senior Python code reviewer. I just wrote this for a Python
learning capstone. Review it as if I were applying for a junior Python
job. Tell me:

1. Three concrete bugs or risks (even if minor) — be specific, cite line
   numbers if possible.
2. Three things I did well that I should keep doing.
3. The ONE thing I should change to make this resume-grade.

Be direct. Don't be polite — be useful.

[paste my code below]

You finished. You shipped a thing. The world doesn't know yet — fix that.

Push it to a fresh public GitHub repo. New repo, clean history, good README at the top.
Add the link to your portfolio at /portfolio/python (or wherever your portfolio lives). One line: "Python capstone — built X in N hours. [link]"
Post it to LinkedIn using this structure:

I just built [X] with Python in [N] hours as my capstone project. It [does Y for Z users]. The thing that surprised me most: [one honest lesson]. Code + README here: [link]. Feedback welcome.

Don't oversell. Don't underplay. Just describe what you did and what you learned. The honesty is what makes recruiters reach out.
(Optional) Reply to the QuizBlock below with what you built — the AI tutor will read it and give you a pat on the back, a frown, or a question you hadn't thought of.

Recap

Key Takeaways

Real Python projects start small and grow feature-by-feature — never write all the code before running any of it
A README is half the project — recruiters and hiring managers read it before they read the code, sometimes instead of the code
The AI tutor is your on-demand senior code reviewer — use it liberally, push back on its answers, and learn from the dialogue

Quick Check1 / 3

You're about to start building Option B (the data analyzer). What should you do FIRST?

Capstone: Ship a Real Python Project

#Pick your project

#Option A: CLI LLM Pet Project · Beginner · ~4 hours

Architecture hint

#Option B: Personal Data Analyzer · Intermediate · ~6 hours

Architecture hint

#Option C: Mini FastAPI Service · Advanced · ~8 hours

Architecture hint

#Option D: Propose your own · Any difficulty

#The build process: 4 phases

#Phase 1: Plan (30 minutes)

#Phase 2: Skeleton (1 hour)

#Phase 3: Implement (most of the time, ~2-5 hours)

#Phase 4: Polish (1 hour)

#A starter for Option A: the persona chatbot

#The README template: copy this exactly

#Get an AI code review

#Submit and share

Your Reflection

Continue Learning

Discussion

Capstone: Ship a Real Python Project

#Pick your project

#Option A: CLI LLM Pet Project · Beginner · ~4 hours

Architecture hint

#Option B: Personal Data Analyzer · Intermediate · ~6 hours

Architecture hint

#Option C: Mini FastAPI Service · Advanced · ~8 hours

Architecture hint

#Option D: Propose your own · Any difficulty

#The build process: 4 phases

#Phase 1: Plan (30 minutes)

#Phase 2: Skeleton (1 hour)

#Phase 3: Implement (most of the time, ~2-5 hours)

#Phase 4: Polish (1 hour)

#A starter for Option A: the persona chatbot

#The README template: copy this exactly

#Get an AI code review

#Submit and share

Your Reflection

Continue Learning

Discussion