This week, we build a World Cup 2026 Tracker — a three-day project that turns a free public football API into your own personal tournament dashboard.

• Day 1: Fetch and Show the Knockout Phase

• Day 2: Bracket Printer (Terminal Art)

• Day 3: Visual Bracket Web App (Today)

View All Projects This Week

Today’s Project

Welcome to the finale — the tournament goes to the browser.

The terminal versions from Days 1 and 2 were useful, but nobody can share a terminal screenshot. Today we make a real web app: a Flask backend that serves the live match data, and a single-page HTML front-end that renders the whole 32-team knockout bracket visually, with color-coded winners, live match highlighting, and auto-refresh every 60 seconds.

Open it in your browser. Send it to a friend. Deploy it. This is the portfolio piece.

Project Task

Build a two-piece web app:

Flask backend (worldcup_web.py):

• Serves an HTML page at /

• Exposes the live match data at /api/matches as JSON

• Caches the upstream openfootball fetch (so multiple visitors don’t hammer their server)

• Handles fetch failures gracefully

Single-page frontend (templates/index.html):

• Fetches from /api/matches

• Renders the 32 knockout matches as a bracket-style grid using CSS Grid

• Highlights winners in green

• Highlights today’s matches with a bright yellow “TODAY” badge

• Dims placeholder team names (like “Winner of #74”)

• Shows scores including extra time and penalty shootouts

• Auto-refreshes every 60 seconds

This project gives you hands-on practice with Flask (routes, templates, JSON responses), CSS Grid, fetch() + async/await in JavaScript, and porting Python logic to JavaScript.

Expected Output

Running the server:

python worldcup_web.py

🏆 World Cup Bracket running at http://127.0.0.1:5000
 * Serving Flask app 'worldcup_web'
 * Running on http://127.0.0.1:5000

Open http://127.0.0.1:5000 in your browser:

The user can see up-to-date matches and their results. The match cards are clickable. Clicking them will show more information about the match in a modal:

Setup Instructions

Install one new dependency:

pip install flask

Create the project structure:

your-project/
├── worldcup_web.py          # the Flask server
└── templates/
    └── index.html           # the single-page frontend

Note we have an html file which is located inside a templates directory.

Run:

python worldcup_web.py

Then open http://127.0.0.1:5000 in your browser.

Understanding Two-Piece Web Apps

Every modern web app splits into two pieces:

1. The backend — a server that returns data (usually as JSON)

2. The frontend — HTML/CSS/JS that fetches the data and renders it

The pieces talk to each other over HTTP. Our backend has two routes:

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/matches")
def api_matches():
    data = get_matches()
    return jsonify({"ok": True, "matches": data["matches"], ...})

The first serves the HTML page (the frontend). The second serves the data (JSON). The frontend loads first, then it fetches from the second route to fill itself in.

This split scales endlessly: a single backend can serve a website, a mobile app, a CLI, and third-party integrations. Today’s tiny two-route Flask app is the exact shape of billion-dollar SaaS backends.

Understanding Flask Basics

Flask is Python’s most-loved web framework. The core is three concepts:

from flask import Flask, render_template, jsonify

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/matches")
def api_matches():
    return jsonify({"ok": True, "matches": [...]})

if __name__ == "__main__":
    app.run(debug=True, port=5000)

• Flask(__name__) — creates the app. The __name__ tells Flask where your project’s root is (for finding the templates/ folder etc).

• @app.route("/path") — decorator that registers the function below as the handler for that URL.

• render_template("index.html") — Flask looks in templates/ and returns the file’s contents. (It can also do template variables, but we don’t need that today.)

• jsonify({...}) — serializes the dict to JSON and sets the Content-Type header correctly. Never do return json.dumps(...) — always use jsonify.

Six lines is a real, working web server.

Understanding Server-Side Caching

Our backend hits openfootball’s server every time someone loads the page. If 100 people had the page open, and it polls every 60 seconds, that’s 100 requests per minute to a static JSON file. Rude.

The fix: cache the upstream response for 60 seconds in the server’s memory. Regardless of how many browsers hit us, we hit openfootball at most once a minute:

CACHE_SECONDS = 60
_cache = {"data": None, "fetched_at": 0}

def get_matches():
    now = time.time()
    if _cache["data"] is None or now - _cache["fetched_at"] > CACHE_SECONDS:
        response = requests.get(DATA_URL, timeout=10)
        response.raise_for_status()
        _cache["data"] = response.json()
        _cache["fetched_at"] = now
    return _cache["data"]

Two-key dict, one check, one write. That’s the whole cache.

The layered cache picture: each browser polls our Flask backend every 60 seconds. Our backend polls openfootball at most once per 60 seconds. Result: openfootball sees one request per minute, regardless of how many users we have. This is the exact shape of every real API service — layered caching all the way up.

Understanding CSS Grid for the Bracket

The bracket needs six columns of matches side by side. CSS Grid is born for this:

.bracket {
  display: grid;
  grid-template-columns: repeat(6, minmax(220px, 1fr));
  gap: 24px;
  overflow-x: auto;
}

Three properties:

• display: grid — this container is a grid.

• grid-template-columns: repeat(6, minmax(220px, 1fr)) — six columns, each at least 220px wide but growing to share available space equally.

• overflow-x: auto — if the viewport is too narrow, allow horizontal scroll instead of squishing.

Then each column is a flexbox stacking match cards vertically:

.round-matches {
  display: flex;
  flex-direction: column;
  justify-content: space-around;
  gap: 10px;
}

justify-content: space-around gives each match card equal breathing room — which visually approximates how bracket lines would space matches to feed into the next round. No SVG lines needed.

Understanding Fetch and Async/Await

To get data from our own backend, the frontend uses JavaScript’s fetch():

async function fetchAndRender() {
  try {
    const response = await fetch("/api/matches");
    const data = await response.json();

    if (!data.ok) {
      showError(data.error);
      return;
    }

    renderBracket(data.matches);
  } catch (err) {
    showError(err.message);
  }
}

fetch returns a Promise. await waits for it to resolve. .json() also returns a Promise (parsing the body is async), so we await that too.

Three modern-JS habits worth internalizing:

• async on the function enables await inside it.

• await in front of every Promise-returning call — the code reads sequentially even though it’s asynchronous.

• try/catch — network errors are exceptions in async code, catch them the same way as sync errors.

This is the pattern for every frontend API call. Once you have it, you can talk to any HTTP API from a browser.

Understanding Auto-Refresh with setInterval

The page should update itself when new match results come in. setInterval schedules a repeating function call:

const REFRESH_MS = 60 * 1000;   // 60 seconds

fetchAndRender();                // initial render
setInterval(fetchAndRender, REFRESH_MS);

That’s the whole auto-refresh mechanism. One line does what a whole “reload the page” workflow would.

Because our backend caches upstream fetches for 60 seconds and the frontend polls every 60 seconds, the maximum freshness delay is 120 seconds. That’s plenty for a tournament where matches take 90 minutes.

Understanding Porting Python to JavaScript

Days 1 and 2 built is_placeholder, pretty_team, winner_of, and score-formatting functions in Python. The frontend needs them all — because it’s the one drawing the cards.

Rewriting them in JavaScript is a great exercise in seeing how the languages relate:

// Python:
//   if name.startswith("W") and name[1:].isdigit():
//       return "Winner of #" + name[1:]

// JavaScript:
if (/^W\d+$/.test(name)) return "Winner of #" + name.slice(1);

re.match in Python, RegExp.test in JavaScript. name[1:] in Python, name.slice(1) in JavaScript. Same ideas, different syntax — like learning to write left-handed after a career of writing with your right.

Same for winner_of:

function winnerOf(match) {
  if (!match.score) return 0;
  const s = match.score;
  if (s.p) return s.p[0] > s.p[1] ? 1 : (s.p[1] > s.p[0] ? 2 : 0);
  if (s.et && s.et[0] !== s.et[1]) return s.et[0] > s.et[1] ? 1 : 2;
  if (s.ft[0] !== s.ft[1]) return s.ft[0] > s.ft[1] ? 1 : 2;
  return 0;
}

Same logic, JavaScript syntax. Every language has some form of if, array indexing, comparison. Once you know one language deeply, the second one is 90% translation.

Understanding Rendering a Match Card

The heart of the frontend is renderMatch(match, todayStr) — takes a match dict, returns a chunk of HTML. Built with a template literal (multi-line string with ${expression} interpolation):

function renderMatch(match, todayStr) {
  const played = !!match.score;
  const isToday = match.date === todayStr;
  const w = winnerOf(match);

  // ...build class names, score values, etc.

  return `
    <div class="${cardClasses.join(' ')}">
      <div class="match-meta">
        <span class="match-num">${num}</span>
        <span>${dateHtml}</span>
      </div>
      <div class="team">
        <span class="${t1Cls.join(' ')}">${prettyTeam(match.team1)}</span>
        <span class="${s1Cls}">${s1}</span>
      </div>
      <div class="team">
        <span class="${t2Cls.join(' ')}">${prettyTeam(match.team2)}</span>
        <span class="${s2Cls}">${s2}</span>
      </div>
    </div>
  `;
}

The ${...} slots inject dynamic values. The resulting HTML string gets stitched together with matches.map(renderMatch).join('') and injected into the DOM with element.innerHTML = ....

This is “template literal” rendering — the simplest form of client-side templating. React, Vue, Svelte add sophistication (reactive updates, components, virtual DOM) but at the core they’re doing the same thing: turn state into HTML.

Understanding the Full Data Flow

Let’s trace one match result appearing on your screen, from data source to green pixels:

1. A referee blows the final whistle in Boston. Paraguay beats Germany 4-3 on penalties.

2. A few hours later, someone updates the openfootball JSON on GitHub.

3. Within 60 seconds, our Flask cache times out; on the next visitor request it re-fetches the JSON.

4. Within another 60 seconds, every open browser tab polls /api/matches and receives the fresh data.

5. renderBracket() runs; winnerOf() returns 2 for Paraguay; renderMatch() builds a card with class="team-name winner" on Paraguay’s name.

6. element.innerHTML = ... swaps in the new HTML; CSS applies --win (green) to Paraguay’s name.

Nowhere in that pipeline is anyone manually editing anything. From “match ends” to “your bracket updates” is fully automatic. That’s the shape of every modern data-driven web app.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete, deployable World Cup Bracket Tracker:

• Day 1: Fetch from a live public API, parse JSON, print the knockout stage

• Day 2: Style the terminal output with rich — panels, colors, winner highlighting

• Day 3: Wrap it in a Flask web app with a visual bracket UI and auto-refresh

Next steps:

• Deploy it: Render or Railway hosts Flask apps for free

• Add a matchup detail modal: click a card, see scorers

• Add team logos: openfootball has a companion repo with country flags

• Add group standings: reuse Day 1 logic from the older version

• Build a mobile-first view: the CSS Grid becomes a vertical stack on small screens

• Swap Flask for FastAPI to try async

You’ve built the foundation for a real full-stack data web app. 🚀

View Code Evolution

Get the code of this project down below and compare today’s web app with Day 1’s plain-text output and Day 2’s colored terminal panels:

Read more

This week, we build a World Cup 2026 Tracker — a three-day project that turns a free public football API into your own personal tournament dashboard.

• Day 1: Fetch and Show the Knockout Phase

• Day 2: Bracket Printer (Terminal Art) (Today)

• Day 3: Visual Bracket Web App

View All Projects This Week

Today’s Project

This World Cup has been quite unexpected so far. Just yesterday, two strong teams were eliminated. We continue our world cup Python project and today we make it look like a tournament.

We will use the Python rich library which turns any Python script’s terminal output into something that could pass for a designed UI. We’ll wrap each round in a colored panel, highlight winners in green, dim upcoming placeholder matches, mark today’s matches in yellow, and add a running “played / total” counter for each round.

Same data, dramatically better presentation. The only new dependency is rich.

Project Task

Extend yesterday’s script so it:

• Wraps each knockout round in a colored rich Panel

• Uses a different color for each round (blue → cyan → magenta → yellow → gold)

• Highlights the winning team’s name in bold green

• Dims placeholder team names (like “Winner of #74”) in italic gray

• Marks today’s matches with a bright yellow “TODAY” tag instead of “vs”

• Shows a “played / total” counter as each panel’s subtitle

• Includes a header banner and a legend

This project gives you hands-on practice with the rich library — Panels, Tables, Text styling — plus a small helper for detecting winners from the score object.

Expected Output

Running the script:

python worldcup_bracket.py

Output (rendered in your terminal with actual colors):

Same data as Day 1. Vastly better presentation.

Setup Instructions

Install the new dependency:

pip install rich

rich is the only new package. It works on Windows, Mac, and Linux terminals with no configuration.

Run it:

python worldcup_bracket.py

Understanding rich

rich is a Python library for making terminal output beautiful. It handles:

• Colors and text styles

• Panels (bordered boxes)

• Tables (aligned columns)

• Progress bars, spinners, live updates

• Markdown, syntax-highlighted code, tracebacks

We’re using a small subset today: Console (for printing), Panel (the bordered boxes), Table.grid (for aligned columns), and Text (styled strings). The whole library is thousands of features deep; you can go as far as you want with it.

The pattern is:

from rich.console import Console
from rich.panel import Panel
from rich.text import Text

console = Console()
console.print(Panel(Text("Hello!", style="bold green"), title="Greeting"))

Every console.print() renders to the terminal with full styling. Regular print() still works alongside it.

Understanding rich.Text vs f-strings

Yesterday we used f-strings for alignment. rich prefers you to build Text objects instead — they carry style information separately from the raw text:

from rich.text import Text

t = Text("Argentina")
t.stylize("bold bright_green")     # winner: bright green

The style syntax is one or more space-separated tokens:

• Colors: red, green, blue, cyan, magenta, yellow, white, bright_black, gold1, and dozens more

• Attributes: bold, italic, dim, underline, strike, reverse

• Background: on black, on grey11

• Combined: "bold bright_green" = bold + green; "dim italic" = dim + italic

Style is separate from content — much cleaner than mixing ANSI escape codes into your strings.

Understanding Panels

A Panel is a bordered box with optional title and subtitle:

from rich.panel import Panel

console.print(Panel(
    "Contents go here",
    title="[bold blue]Round of 32[/]",
    subtitle="[blue]7 / 16 played[/]",
    border_style="blue",
    padding=(1, 2),
))

Two things to notice:

• The title/subtitle use inline BBCode-style markup — [bold blue] opens the style, [/] closes it. Concise for one-off text bits.

• border_style sets the color of the actual border characters.

• padding=(vertical, horizontal) controls internal whitespace: (1, 2) means one blank line top/bottom and two spaces left/right.

Panels are our workhorse today — one per round, each in a different color.

Understanding Table.grid for Alignment

Regular rich.Table renders with visible borders between rows and columns. Table.grid gives you the same alignment behavior with no borders — perfect for laying out rows inside a Panel:

from rich.table import Table

table = Table.grid(padding=(0, 1))
table.add_column(justify="left")     # match number
table.add_column(justify="left")     # date
table.add_column(justify="right")    # team1
table.add_column(justify="center")   # score / vs
table.add_column(justify="left")     # team2

table.add_row("#73", "2026-06-28", "South Africa", "0–1", "Canada")
table.add_row("#74", "2026-06-29", "Germany", "1–1 (3-4 pens)", "Paraguay")

The five columns line up automatically no matter what row content you add. Right-align for team1 + center for the score + left-align for team2 gives you that classic “team score team” look:

     South Africa  0–1     Canada
          Germany  1–1 (3-4 pens)  Paraguay

This is dramatically easier than trying to do it with f-string width specifiers, especially once rich styling gets mixed in.

Understanding Detecting the Winner

To highlight a winner, we need to know who won. Football has three ways a knockout match can end, and each hides the winner in a different score field:

def winner_of(match):
    """Return 1 if team1 won, 2 if team2 won, or 0 for a draw / unplayed."""
    if "score" not in match:
        return 0
    score = match["score"]

    # Penalty shootout: the penalty score decides it.
    if "p" in score:
        p1, p2 = score["p"]
        return 1 if p1 > p2 else 2 if p2 > p1 else 0

    # Extra time: if there's an et score AND it's not tied, that decides it.
    if "et" in score:
        g1, g2 = score["et"]
        if g1 != g2:
            return 1 if g1 > g2 else 2

    # Regulation.
    g1, g2 = score["ft"]
    if g1 != g2:
        return 1 if g1 > g2 else 2

    return 0

The order matters again: check p first, then et, then ft. A match with a penalty shootout has all three fields; if we checked ft first we’d get “tied” and never look at the shootout.

This function is small but foundational — Day 3’s web app uses the exact same logic to pick which team’s name to bold in the browser.

Understanding Detecting Placeholders

To style unresolved team names differently (dim italic), we need a way to tell “Canada” apart from “Winner of #74”. The check is the mirror image of yesterday’s pretty_team():

def is_placeholder(name):
    if name.startswith("W") and name[1:].isdigit():
        return True
    if name.startswith("L") and name[1:].isdigit():
        return True
    if len(name) == 2 and name[0].isdigit() and name[1].isalpha():
        return True
    if "/" in name:
        return True
    return False

Same patterns as yesterday, but instead of transforming the string, we’re classifying it. Same regex-free approach — just startswith, isdigit, and a couple of shape checks.

Understanding Styling One Row

The core styling function ties it all together — for each match, pick the right style for the team names, the score, and the date:

def build_match_row(match, today_str):
    num = f"#{match.get('num', '?')}"
    date_str = match.get("date", "")
    played = "score" in match
    is_today = date_str == today_str
    w = winner_of(match)

    # Match number: always bold
    num_text = Text(num, style="bold")

    # Date: yellow if today AND unplayed, plain otherwise
    date_text = Text(date_str)
    if is_today and not played:
        date_text.stylize("bold yellow")

    # Teams: green if winner, dim italic if placeholder, plain white otherwise
    t1_text = styled_team(match["team1"], is_winner=(w == 1),
                          is_placeholder_name=is_placeholder(match["team1"]))
    t2_text = styled_team(match["team2"], is_winner=(w == 2),
                          is_placeholder_name=is_placeholder(match["team2"]))

    # Score column: real result, "TODAY", or "vs"
    if played:
        score_text = Text(format_score(match["score"]), style="bold white")
    elif is_today:
        score_text = Text("TODAY", style="bold yellow")
    else:
        score_text = Text("vs", style="dim")

    return num_text, date_text, t1_text, score_text, t2_text

The function returns a tuple of Text objects — one per column. Table.grid.add_row(*result) unpacks the tuple into the table’s columns. Small, composable, easy to test.

Understanding Color-Coding by Round

Each round gets its own color, and we keep them in a list of (name, color) tuples so the display order and color mapping stay in one place:

ROUNDS = [
    ("Round of 32",            "bright_blue"),
    ("Round of 16",            "cyan"),
    ("Quarter-final",          "magenta"),
    ("Semi-final",             "yellow"),
    ("Match for third place",  "bright_black"),
    ("Final",                  "gold1"),
]

for round_name, color in ROUNDS:
    round_matches = [m for m in matches if m["round"] == round_name]
    ...
    console.print(build_round_panel(round_name, round_matches, color, today_str))

The palette goes cool-to-warm, culminating in gold for the Final. It’s a visual metaphor — the tournament heats up as it narrows. Small aesthetic choice, big effect.

Understanding Adding a Legend

At the bottom, a two-row Table.grid explains what the styles mean:

legend = Table.grid(padding=(0, 2))
legend.add_column()
legend.add_column()
legend.add_column()

legend.add_row(
    Text("Legend:", style="bold"),
    Text("winner", style="bold bright_green"),
    Text("upcoming placeholder", style="dim italic"),
)
legend.add_row(
    Text(""),
    Text("today's match", style="bold yellow"),
    Text("score / result", style="bold white"),
)
console.print(legend)

Nothing dramatic — just a small ceremonial ending that helps users decode the colors. Every good chart has a legend; every good terminal UI can too.

Understanding Everything Together

Look at what the whole script does:

1. Fetch the JSON (same as Day 1)

2. Loop through rounds in the desired order

3. For each round: filter matches, sort by match number, build a Panel containing a Table.grid

4. For each match in the round: pick styles based on who won, whether it’s today, whether teams are placeholders

5. Print each panel

6. Print a legend

That’s the entire day. rich handles all the styling and alignment work — we just describe what we want. The data logic barely changed from Day 1. All the new complexity is presentation. That’s the point: the same fetch-and-parse pipeline can power a plain print, a terminal UI, or (as we’ll see tomorrow) a web app.

Practical Use Cases

1. Terminal dashboards:

Server monitoring, deployment logs, CI/CD summaries — rich turns any script into a designed UI.

2. Interactive CLIs:

Combine rich with prompt_toolkit for full-featured terminal apps.

3. Progress and status:

rich.progress and rich.live are worth exploring — real-time-updating panels are magical.

4. Foundation for Day 3:

The same match-styling logic (winner detection, placeholder detection) drives the web app tomorrow.

Coming Tomorrow

Tomorrow we ship it. The Visual Bracket Web App wraps this whole thing in a Flask server that serves an HTML page — with a real, actual visual bracket diagram in HTML/CSS. Auto-refreshing every minute. Deployable. Shareable. This is the finale.

View Code Evolution

Compare today’s colorful bracket with yesterday’s plain-text version — and see how a few rich components (Panel, Table.grid, Text) turn a functional script into something that looks designed.

Read more

This week, we build a World Cup 2026 Tracker — a three-day project that turns a free public football API into your own personal tournament dashboard. By Friday, you’ll have a live web app showing the entire knockout bracket, updating itself as the matches play out.

Why build this? Because we’re in the World Cup right now. The Round of 32 just kicked off, and through July 19, the bracket fills in match by match. This is the perfect moment to build something that pulls live tournament data and turns it into something useful. The skills — consuming an API, parsing JSON, building UIs around external data — apply to every kind of real-world data work, from finance to weather to fitness apps.

What you’ll learn: This series teaches you HTTP API consumption with requests, JSON parsing, terminal art with rich, Flask web servers, and bridging Python data to HTML/CSS/JS frontends.

Why this matters: By Day 3, you’ll have a deployable web app showing a live, visual knockout bracket — a portfolio piece you can share with anyone who likes football.

• Day 1: Fetch and Show the Knockout Phase (Today)

• Day 2: Bracket Printer (Terminal Art)

• Day 3: Visual Bracket Web App

View All Projects This Week

Today’s Project

We start small but real: fetch live World Cup 2026 data from a free public JSON API, parse it, and print every knockout-stage match in the terminal. By the end of today you’ll be making a real HTTP request, working with real-world JSON, and seeing real match results from a tournament happening right now.

The display is intentionally simple — we’ll polish it on Day 2 with terminal art, and Day 3 turns it into a proper visual web app. Today is about the data. Once you can fetch and parse it, the rest of the week is presentation.

The Data Source

We’re using the wonderful openfootball/worldcup.json project — a free, public-domain, no-API-key-required JSON dataset of every World Cup match. It’s maintained by hand by an Austrian developer named Gerald Bauer, updated daily, and used by dozens of real projects.

The endpoint is a single URL that returns all 104 matches:

https://raw.githubusercontent.com/openfootball/worldcup.json/master/2026/worldcup.json

That’s it. No authentication, no signup, no rate limits to worry about. Hit the URL, get JSON. Perfect for learning.

A note on “live”: the data is updated by hand (usually daily), not in real time. For our purposes — building a tracker, learning APIs — that’s fine. Day 3 will auto-refresh every few minutes. For real-time scores you’d need a paid API; that’s a different project.

Project Task

Build a Python script that:

• Fetches the openfootball JSON endpoint via HTTP

• Parses the response as JSON

• Filters the match list to just the knockout-stage matches

• Sorts each round in bracket order (by match number)

• Prints them grouped by round: Round of 32 → Round of 16 → QF → SF → 3rd place → Final

• Shows the score correctly whether the match was decided in regulation, extra time, or penalties

• Renders placeholder team codes (W73, 2A) as readable text (Winner of match 73, Group A runner-up)

This project gives you hands-on practice with requests, JSON parsing, list comprehensions, sort keys, dict access patterns, and the small details that make the difference between “the data is there” and “the output is readable.”

Expected Output

Running the script:

python worldcup.py

Output:

Played matches show their full score including penalty shootouts. Future matches show placeholders that automatically resolve into real team names as the bracket fills in.

Setup Instructions

Install one dependency:

pip install requests

That’s it. Everything else is standard library.

Run it:

python worldcup.py

Understanding the Data Source

Before writing any code, look at the data. Open the URL in a browser and scroll through it. The structure is:

{
  "name": "World Cup 2026",
  "matches": [
    {
      "round": "Matchday 1",
      "date": "2026-06-11",
      "time": "13:00 UTC-6",
      "team1": "Mexico",
      "team2": "South Africa",
      "score": { "ft": [2, 0], "ht": [1, 0] },
      "goals1": [...],
      "ground": "Mexico City"
    },
    {
      "round": "Round of 32",
      "num": 73,
      "date": "2026-06-28",
      "team1": "2A",
      "team2": "2B",
      "ground": "Los Angeles (Inglewood)"
    },
    ...
  ]
}

Three things to notice for today:

• Every match has round, team1, team2. The knockout matches also have num — their match number (73-104).

• score only appears after the match is played. Future matches have no score key at all.

• Knockout matches have placeholder teams until the dependency matches resolve. "2A" means “Group A runner-up.” "W73" means “Winner of match 73.” As real matches finish, openfootball replaces those placeholders with actual team names — automatically, for free, on our side.

Understanding requests for an API

requests is Python’s go-to library for HTTP. Hitting our endpoint is two lines:

import requests

response = requests.get(DATA_URL, timeout=10)
response.raise_for_status()
data = response.json()

Three habits worth forming on day one of API work:

• Always set a timeout. Without one, a slow server can hang your script forever. 10 seconds is sensible.

• Always call raise_for_status(). It throws on 4xx/5xx responses, so you catch network failures immediately instead of crashing while parsing an HTML error page as JSON.

• response.json() is the magic call. It does json.loads(response.text) for you, returning a Python dict (or list).

That’s the entire API interaction. The hard part of API work isn’t the HTTP call — it’s everything you do with the data afterward.

Understanding Filtering by Round

The JSON has all 104 matches — group stage plus knockouts. We want just the knockout ones. A list comprehension and a fixed list of round names handles it:

KNOCKOUT_ROUNDS = [
    "Round of 32",
    "Round of 16",
    "Quarter-final",
    "Semi-final",
    "Match for third place",
    "Final",
]

for round_name in KNOCKOUT_ROUNDS:
    round_matches = [m for m in matches if m["round"] == round_name]
    # ... print them

The order of KNOCKOUT_ROUNDS defines the display order — Round of 32 first, Final last. Just by looping that list in order, we get the bracket in the right sequence. No sorting algorithm needed for the rounds themselves.

Understanding Match Numbers and Sort Order

Within a round, matches have a num field — 73, 74, 75, etc. The order of matches in the JSON isn’t guaranteed, so we sort each round’s matches by num:

round_matches.sort(key=lambda m: m.get("num", 0))

A lambda is just a small inline function — lambda m: m.get("num", 0) takes a match m and returns its num field (or 0 if missing).

Why m.get("num", 0) and not m["num"]? Because group-stage matches don’t have a num field, and using m["num"] would crash if any non-knockout match slipped through. dict.get(key, default) is the safe accessor. Use it whenever a key might not exist — it returns the default value instead of raising KeyError.

Understanding the Score Structure

This is the most interesting JSON detail of the day. Football matches can end in three ways, and openfootball encodes each one slightly differently:

# 1. Regulation: just full-time
"score": {"ft": [2, 0], "ht": [1, 0]}

# 2. Extra time: full-time was a draw, extra time decided it
"score": {"ft": [1, 1], "et": [2, 1], "ht": [0, 1]}

# 3. Penalty shootout: full-time was a draw, extra time too, decided on pens
"score": {"ft": [1, 1], "et": [1, 1], "p": [4, 3], "ht": [0, 1]}

So three keys to know:

• ft — full-time score, always present

• et — extra-time aggregate (only if the match went to extra time)

• p — penalty shootout result (only if there was a shootout)

For the knockout stage, all three matter. A 1-1 draw in regulation that ended 4-3 on penalties looks very different on the bracket than just “1-1.” So our score formatter handles all three:

def format_score(score):
    g1, g2 = score["ft"]

    if "p" in score:                       # penalty shootout
        p1, p2 = score["p"]
        if "et" in score:
            g1, g2 = score["et"]           # show the ET tie, not the FT one
        return f"{g1} — {g2} ({p1}-{p2} pens)"

    if "et" in score:                       # decided in extra time
        g1, g2 = score["et"]
        return f"{g1} — {g2} (a.e.t.)"

    return f"{g1} — {g2}"                   # regulation

The order matters: check p first, then et, then default to regulation. A penalty shootout always also has et — if we checked et first, we’d report shootouts as “extra time” results and miss the decisive penalty score.

Practical Use Cases

1. The API consumption pattern:

fetch → parse → filter → display works for weather, crypto, stocks, GitHub, anything.

2. The placeholder-resolution pattern:

APIs often return raw codes that need translation. Build a small helper, keep callers clean.

3. Tournament data in general:

The same JSON format covers Premier League, La Liga, Bundesliga, every past World Cup.

4. Foundation for the rest of the week:

Day 2 makes the display beautiful. Day 3 puts it in the browser. Same fetch + parse pipeline.

Coming Tomorrow

Tomorrow we make this look like a bracket. We’ll use the rich library to draw the actual knockout bracket diagram in your terminal — with colors, lines connecting matches across rounds, winners highlighted, and the whole thing as one cohesive visual. Same data source, way more wow.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Code Skeleton

Get the code solution here:

View Code Solution

This week, we build an Email Productivity Suite — a complete set of tools for one of the most universal time-sinks in modern life: writing and sending email.

• Day 1: Email Sender Desktop App

• Day 2: Mail Merge from CSV

• Day 3: AI Email Assistant (Gemini) (Today)

View All Projects This Week

Today’s Project

Welcome to the finale — and the most fun one.

You have an email to write. Maybe to your professor about a missed deadline. Maybe to a client whose invoice you need to chase. Maybe to your landlord about a leaky tap. You know what you want to say in two seconds. Writing it politely — picking the right tone, the right opening, the right level of firmness — takes ten minutes you don’t have.

Today we will have AI write our emails in the GUI. You just type a rough note in plain language:

“tell my professor i can’t make tomorrow’s office hours, doctor’s appointment, ask if we can meet thursday”

Click the tone — polite, firm, concise, apologetic — and Gemini rewrites it as a polished email. One more click and it sends through the same Gmail engine you built on Day 1.

This is the kind of AI tool you’ll actually use — not a demo, a real piece of your workflow.

Project Task

Build an AI Email Assistant with Tkinter and Gemini that:

• Takes a rough draft as input — any tone, any messiness

• Lets the user pick a target tone: Polite / Firm / Concise / Apologetic / Friendly

• Sends the rough draft to Gemini with a tone-specific instruction

• Displays the polished version in a separate editable text box

• Lets the user tweak the AI output before sending

• Suggests a subject line automatically based on the content

• Sends the finished email through the same send_email() function from Day 1

• Handles missing API keys, network errors, and Gmail errors gracefully

This project gives you hands-on practice with the langchain-google-genai library, prompt engineering for tone control, integrating LLM output into a real workflow, two-pane editing UIs, and capping off a multi-day project series cleanly.

Expected Output

Running the app:

python ai_email_assistant.py

That will display the app. In the app, you can write the instructions to the AI about the email and pick a tone:

Then, further down an email with subject will be generated:

Pressing “SEND EMAIL” will send out the email to the sender’s email address. Here is what I received to my the sender’s address:

Cool, isn’t it?

Setup Instructions

Step 1 — Install the AI dependency:

pip install langchain-google-genai

That’s the only new thing this week.

Step 2 — Get a Gemini API key (free, 1 minute):

1. Go to aistudio.google.com/apikey.

2. Sign in with any Google account.

3. Click Create API key.

4. Copy the key it shows you.

The free tier gives you generous daily quota — plenty for personal email rewriting.

Step 3 — Paste your API key into the script:

Open ai_email_assistant.py and find this line near the top:

GOOGLE_API_KEY = "PASTE_YOUR_KEY_HERE"

Replace PASTE_YOUR_KEY_HERE with your actual key. Save.

Security note: keeping the key directly in the code is the simplest approach for learning. For real apps, store it in an environment variable or a .env file, then read it via os.environ["GOOGLE_API_KEY"]. We use the inline approach so the project runs without extra setup.

Step 4 — Use the same Gmail App Password from Day 1.

If you already set up your App Password earlier this week, you’re done. Otherwise see Day 1 — 5-minute setup.

Run it:

python ai_email_assistant.py

Understanding LangChain + Gemini

langchain-google-genai is the glue between Python and Google’s Gemini models. The basic shape is three steps:

from langchain_google_genai import ChatGoogleGenerativeAI

llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    google_api_key=GOOGLE_API_KEY,
    temperature=0.4,        # how creative; lower = more focused
)

response = llm.invoke("Rewrite this email politely: tell my prof I'll be late")
print(response.content)

Three things to know:

• gemini-2.5-flash — Google’s fast, cheap model. Perfect for short text rewriting. The smarter gemini-3.5-flash exists too; you can swap it in any time, you just pay a small latency cost.

• temperature=0.4 — moderate creativity. 0 is fully deterministic (same input → same output every time); 1 is wildly creative. For tone rewriting, 0.3–0.5 hits the right spot: consistent voice with a bit of natural variation.

• response.content — the actual text. The full object has tokens, metadata, etc.; for our use we just want the string.

Understanding Prompt Engineering for Tone

The whole AI part of the app boils down to one well-crafted prompt template. We need Gemini to:

1. Read the user’s rough note.

2. Rewrite it as a professional email.

3. Apply the chosen tone.

4. Return only the email — no preamble, no explanation.

Here’s a template that does exactly that:

PROMPT_TEMPLATE = """You are an expert email writer. The user has a rough \
draft of an email they want to send. Rewrite it as a polished, well-structured \
email in a {tone} tone.

Rules:
- Output ONLY the email body. No preamble, no commentary, no markdown.
- Do not include a subject line - the user handles that separately.
- Keep it appropriately brief; do not pad with filler.
- Preserve every concrete detail from the rough draft.
- Sign off appropriately for the tone.

Tone: {tone}

Rough draft:
{rough_draft}

Polished email:"""

Three prompt-writing habits in this one example:

• Set the role — “You are an expert email writer” primes the model for the task.

• List explicit rules — bullet rules are dramatically more effective than vague prose at controlling output. “Output ONLY the email body” prevents the model’s tendency to add “Sure! Here’s your email:” preambles.

• Show the structure — ending with “Polished email:” tells the model what comes next is the answer. Sounds silly, works brilliantly.

The {tone} and {rough_draft} are placeholders we’ll fill at runtime — same str.format() trick from Day 2:

prompt = PROMPT_TEMPLATE.format(tone="polite", rough_draft=user_text)

Understanding Tone-Specific Variations

“Polite” and “Firm” and “Concise” each have different sweet spots. We can make the rewrite much better by giving each tone a bit of guidance:

TONES = {
    "Polite": "warm, respectful, hedged where appropriate",
    "Firm": "direct and assertive, but not aggressive; clear next steps",
    "Concise": "as short as possible while staying complete; no filler words",
    "Apologetic": "genuinely apologetic, takes ownership, offers to make it right",
    "Friendly": "warm and conversational; appropriate for someone you know well",
}

In the prompt:

prompt = PROMPT_TEMPLATE.format(
    tone=f"{tone_name} ({TONES[tone_name]})",
    rough_draft=user_text,
)

So the model sees Tone: Polite (warm, respectful, hedged where appropriate). The parenthesized hint is the real instruction — the label is just for the user. This is prompt scaffolding: giving the model enough context to do the job well, without making the user write a paragraph every time.

Understanding Subject Line Suggestions

Most rough drafts don’t include a subject — but the user needs one. We can have Gemini suggest one in the same call by asking it for a tiny JSON-shaped response:

SUBJECT_PROMPT = """Suggest a concise email subject line for this email body. \
Reply with ONLY the subject line - no quotes, no preamble.

Email body:
{body}

Subject line:"""

def suggest_subject(llm, body):
    response = llm.invoke(SUBJECT_PROMPT.format(body=body))
    return response.content.strip()

A separate small call keeps things simple — one call per output. Both are short (a few hundred tokens) so latency adds up to maybe two seconds total. Much cleaner than trying to coerce structured output from the model.

Aside: for production, you’d probably want with_structured_output (like we did in Week 19’s travel planner) and get both subject and body in one structured call. For a personal-use tool, two simple invoke calls are easier to reason about.

Understanding the Two-Pane Layout

The whole app is a top-down flow: rough on top, polished on bottom. Tkinter’s vertical stacking is perfect:

# Top pane: rough draft
tk.Label(root, text="YOUR ROUGH DRAFT").pack(anchor="w")
self.rough_text = tk.Text(root, height=6, wrap="word")
self.rough_text.pack(fill="x", padx=10)

# Tone buttons
tone_bar = tk.Frame(root)
tone_bar.pack(pady=8)
for tone in TONES:
    tk.Button(tone_bar, text=tone,
              command=lambda t=tone: self.rewrite(t)).pack(side="left", padx=4)

# Big "Rewrite" button
tk.Button(root, text="✨ REWRITE WITH AI", ...).pack(pady=4)

# Bottom pane: polished output
tk.Label(root, text="POLISHED EMAIL (edit before sending)").pack(anchor="w")
self.subject_entry = tk.Entry(root, textvariable=self.subject_var)
self.subject_entry.pack(fill="x", padx=10)
self.polished_text = tk.Text(root, height=10, wrap="word")
self.polished_text.pack(fill="both", expand=True, padx=10)

The polished pane is a regular Text widget — the user can edit it. That’s the key UX choice: AI suggests, human approves. The output isn’t locked; you’re free to fix any phrase before sending.

Understanding the Threading Question

LLM calls take 1–3 seconds. If we call llm.invoke() directly from the button handler, Tkinter freezes for that whole time — the window won’t repaint, won’t respond to clicks, looks crashed.

For a personal-use tool with quick calls, the simplest fix is root.update_idletasks() after a “Thinking...” status update, then let the call complete. The window freezes briefly but the user knows why:

self.set_status("✨ Thinking...")
self.root.update_idletasks()
result = llm.invoke(prompt)

For longer calls or a heavier app, you’d use threading.Thread and root.after() to keep the GUI responsive. For our case — a few seconds, a clear status message — the simple approach is the right tradeoff. Less code to teach, less code to break.

Understanding Reusing send_email Again

The whole point of the architecture lesson this week:

# Top of ai_email_assistant.py
from email_sender import send_email

Day 1’s send_email() ships emails from Day 1’s app, from Day 2’s mail-merge loop, and from Day 3’s AI assistant. Three completely different products, one engine. That’s what separating pure functions from UI gets you.

When the user clicks Send, we feed Gemini’s polished output into the same function:

def on_send(self):
    sender = self.from_var.get().strip()
    password = self.password_var.get()
    recipient = self.to_var.get().strip()
    subject = self.subject_var.get().strip()
    body = self.polished_text.get("1.0", "end-1c").strip()

    try:
        send_email(sender, password, recipient, subject, body)
        self.set_status(f"✓ Email sent to {recipient}")
    except smtplib.SMTPAuthenticationError:
        self.set_status("✗ Gmail authentication failed. Check your App Password.")
    except Exception as e:
        self.set_status(f"✗ Send failed: {e}")

Same shape as Day 1. Same SMTP errors. Same status updates.

Understanding the Bigger Picture

Three days of email tools. One pure send function. One templating helper. One AI rewriter.

• Day 1 built the engine.

• Day 2 wrapped it in a loop.

• Day 3 put intelligence in front of it.

Each layer adds value; none of them rewrite the layer below. That’s not a Python pattern — that’s the discipline behind every well-built software product. Today you wrote one piece of an “email-productivity-AI-assistant”; the same shape works for any AI-powered desktop app you’ll build from here.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete Email Productivity Suite:

• Day 1: Send a single email through Gmail SMTP via a desktop app

• Day 2: Send personalized emails to a CSV of recipients

• Day 3: AI-rewrite rough drafts in any tone before sending

You now have:

✅ Python email skills — smtplib, EmailMessage, Gmail SMTP, App Passwords ✅ CSV-driven personalization — DictReader, str.format(), batch processing ✅ LangChain + Gemini integration — building a real LLM-powered tool ✅ Prompt engineering — tone control, output constraints, structured prompts ✅ A reusable architecture — pure functions composed across three tools

Real-world applications:

• 📨 Personal email speed — quick drafts become professional emails in seconds

• 🎓 Student communications — emailing professors, advisors, departments

• 💼 Freelancer workflows — invoicing, follow-ups, client check-ins

• 🛠️ Automation triggers — long script finishes → script emails you the result

• 🤖 Custom AI tools — you now know how to wrap any LLM into a desktop app

Next steps:

• Add an inbox reader (IMAP) — let Gemini summarize and respond to incoming emails

• Save templates — keep your favorite rewritten emails for one-click reuse

• Multi-recipient AI batch — combine Day 2 mail merge with Day 3 AI rewriting

• Voice input — speak your rough draft, transcribe with Whisper, rewrite with Gemini

• Use keyring or python-dotenv to manage your API key and Gmail credentials safely

You’ve built a real, daily-use AI tool in three days. 🚀

View Code Evolution

Compare today’s AI assistant with Day 1’s single sender and Day 2’s mail merge — and see how the same pure send_email() function composes with templating and an LLM to produce three very different end-user tools.

Read more

This week, we build an Email Productivity Suite — a complete set of tools for one of the most universal time-sinks in modern life: writing and sending email.

• Day 1: Email Sender Desktop App

• Day 2: Mail Merge from CSV (Today)

• Day 3: AI Email Assistant (Gemini)

View All Projects This Week

Today’s Project

Yesterday we sent one email. Today we send a hundred — each personalized to its recipient.

Mail merge is the technique behind every personalized email you’ve ever received: the company has a list of names and a template (”Hi {first_name}, your order #{order_id} has shipped”), and a script fills the blanks for each row and sends. Today you build that script. Load a CSV of recipients, write your email once with {placeholder} variables, hit Send All, and watch personalized emails go out one by one.

Same send_email() function from Day 1 — wrapped in a loop with smarter UI around it.

Project Task

Build a CSV-driven mail merge tool with Tkinter that:

• Loads a CSV of recipients with at minimum an email column

• Auto-detects the other columns as available template variables

• Lets you write subject and body with {column_name} placeholders

• Shows a live preview of how the email will look for the first recipient

• Sends one personalized email per row when Send All is clicked

• Adds a polite delay between sends to avoid Gmail rate-limiting

• Reports progress per recipient (sent / failed / row count)

• Continues to the next row if one fails — never crashes mid-batch

• Logs every send with status to a scrollable log box

This project gives you hands-on practice with csv.DictReader, Python’s str.format() for templating, batch processing with error recovery, real-time progress reporting in Tkinter, and turning a single-use function into a reusable engine.

Expected Output

Running the tool:

python mail_merge.py

Here is what you will see when you run the program.

You can write an email in the GUI and use variables such as {first_name} and {course} in the email:

When you press SEND ALL, the app will pull the actual value from the respective column (i.e., first_name and course) in the CSV file for each row:

Each person in the CSV will get a personalized email. Here is the email Carol received:

Each member receives an email with their own data fetched from the CSV.

Setup Instructions

Install (nothing new):

Same as Day 1 — pure standard library (smtplib, csv, tkinter). No pip install.

Prepare a recipients CSV:

A sample students.csv is provided with this project. The format is simple:

email,first_name,course,amount
alice@example.com,Alice,Python Bootcamp,250
bob@example.com,Bob,Data Science 101,180
carol@example.com,Carol,Web Dev Foundations,200
david@example.com,David,Python Bootcamp,250

You can copy the above, paste it in an empty text file and save as students.csv.

Run the program:

python mail_merge.py

Understanding csv.DictReader

The CSV-handling workhorse for today is csv.DictReader. It reads the header row, then yields each subsequent row as a dictionary keyed by column name:

import csv

with open("students.csv", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    fieldnames = reader.fieldnames           # ['email', 'first_name', ...]
    recipients = list(reader)                # [{'email': 'alice@...', ...}, ...]

Two things to know:

• reader.fieldnames — the column headers. We’ll use these to tell the user which {variables} they can put in their template.

• list(reader) — materializes all rows into memory. Fine for hundreds of rows; for hundreds of thousands you’d iterate the reader directly.

DictReader gives us a clean shape: a list of dicts, each one perfectly ready to feed into .format(**row).

Understanding Python’s str.format with **kwargs

Templating in Python is built into the language — no Jinja, no Mustache, just str.format():

template = "Hi {first_name}, your {course} starts soon."
row = {"first_name": "Alice", "course": "Python Bootcamp"}

personalized = template.format(**row)
# "Hi Alice, your Python Bootcamp starts soon."

The **row syntax unpacks the dict into keyword arguments. So template.format(**row) is equivalent to template.format(first_name="Alice", course="Python Bootcamp", ...).

It works for any number of variables. The template grabs whichever placeholders it needs and ignores the rest. The dict can have 10 columns — your template might only use 2 of them; that’s fine.

Understanding Safe Personalization

What happens if your template has {first_name} but a CSV row is missing that column? format() raises KeyError. That’s exactly what you want for a typo — but you want it to fail cleanly for the user, not crash the script:

def personalize(template, row):
    """Fill {placeholders} in template with values from row dict."""
    try:
        return template.format(**row)
    except KeyError as e:
        raise ValueError(f"Template references {e} but the CSV has no such column.")

Wrapping in a function with a clearer error means the GUI can show “Template references ‘first_name’ but the CSV has no such column” instead of a stack trace. Errors as messages, not crashes.

Understanding the Live Preview

The live preview shows how the first recipient’s email will look — it runs the same personalize() function the batch will use:

def refresh_preview(self):
    if not self.recipients:
        self.preview_text.delete("1.0", "end")
        return

    first = self.recipients[0]
    try:
        subject = personalize(self.subject_var.get(), first)
        body = personalize(self.body_text.get("1.0", "end-1c"), first)
    except ValueError as e:
        self.preview_text.delete("1.0", "end")
        self.preview_text.insert("1.0", f"⚠️ {e}")
        return

    preview = f"To: {first['email']}\nSubject: {subject}\n\n{body}"
    self.preview_text.delete("1.0", "end")
    self.preview_text.insert("1.0", preview)

Bind it to keystrokes on the subject and body widgets:

subject_entry.bind("<KeyRelease>", lambda _e: self.refresh_preview())
self.body_text.bind("<KeyRelease>", lambda _e: self.refresh_preview())

The user types {first_name} — the preview instantly shows “Alice.” Type {first_nam} (typo) — the preview shows a clear warning before they hit Send. This is the small UX detail that separates I built a script from I built a tool.

Understanding the Send-All Loop

The batch loop wraps yesterday’s send_email() in a for loop with three additions: a delay between sends, per-row error handling, and progress logging:

import time

def send_all(self):
    sender = self.from_var.get().strip()
    password = self.password_var.get()
    subject_template = self.subject_var.get()
    body_template = self.body_text.get("1.0", "end-1c")

    successes = 0
    failures = 0
    total = len(self.recipients)

    self.log(f"Sending to {total} recipients...")

    for i, row in enumerate(self.recipients, 1):
        recipient = row.get("email", "").strip()

        try:
            subject = personalize(subject_template, row)
            body = personalize(body_template, row)
            send_email(sender, password, recipient, subject, body)
            self.log(f"  [{i}/{total}]  {recipient:<30}  →  ✓ sent")
            successes += 1
        except Exception as e:
            self.log(f"  [{i}/{total}]  {recipient:<30}  →  ✗ {e}")
            failures += 1

        time.sleep(1)   # be polite to Gmail

    self.log(f"\nDone. {successes} sent, {failures} failed.")

Three patterns to internalize:

• time.sleep(1) — one second between sends. Gmail’s free tier rate-limits at around 100/day; even at the limit, one-second pacing keeps you well under any per-minute throttle. Tomorrow’s AI version can use 2-3 seconds for extra safety.

• try/except per row — one bad recipient doesn’t stop the batch. The failure is logged; the next row goes out.

• successes and failures counters — the user sees a useful summary at the end, not a wall of green checkmarks.

Understanding Reusing send_email from Day 1

We don’t rewrite send_email. We import it:

# At the top of mail_merge.py
from email_sender import send_email

This is the architecture lesson of the week. Day 1’s send_email() was a pure function — no Tkinter, no I/O outside of the SMTP call — exactly so this would work. Day 3 will import it again.

If you wrote send_email() as a method on the Day 1 EmailSenderApp class, today’s loop would be much harder. Pure functions compose; methods on classes don’t.

Understanding the Architecture

The whole app is built on three layers:

1. send_email() — the SMTP primitive (imported from Day 1)

2. personalize() — template + dict → final string

3. send_all() — the loop that ties them together

Each layer does one thing. Each layer is reusable. Day 3’s AI assistant will reuse the same three — Gemini produces the body, personalize() fills in any placeholders, send_email() sends it. That’s the discipline that makes week-by-week projects compose.

Practical Use Cases

1. Notify a class / team / customer list:

Drop the names into a CSV, write your email once, hit Send All.

2. Send personalized invoices, certificates, receipts:

{first_name}, {amount}, {invoice_id} - one email per row.

3. Course communications:

Reminders, deadline alerts, assignment feedback — anywhere you'd otherwise BCC.

4. Event RSVPs and follow-ups:

"Hi {name}, thanks for attending {event}! Your certificate is at {link}."

5. Foundation for Day 3:

Tomorrow's AI assistant uses the same send_email() function and the same personalize() trick.

Coming Tomorrow

Tomorrow we add AI. The AI Email Assistant takes a quick rough draft — “tell my boss I’ll be out tomorrow morning, doctor’s appointment” — and Gemini rewrites it as a polished email in your chosen tone (polite / firm / concise / apologetic). One click and it’s ready to send via the same send_email() you built on Day 1.

View Code Evolution

Compare today’s mail merge tool with Day 1’s single sender — and see how a small for loop, a templating helper, and per-row error handling turn one email into a personalized hundred.

Read more

This week, we build an Email Productivity Suite — a complete set of tools for one of the most universal time-sinks in modern life: writing and sending email. By Friday, you’ll have a desktop app that sends single emails, mail-merges to a CSV list, and uses AI to rewrite rough drafts in any tone you want.

Why build this? Because email isn’t going away — AI made it easier to write but more of it gets sent. Python automation around email is one of those rare skills that pays off in every job, every side project, every freelance gig.

What you’ll learn: This series teaches you Python’s smtplib and email modules, Gmail authentication via app passwords, sending plain and HTML email, attaching files, CSV-driven personalization, and integrating LLMs into a real desktop workflow.

Why this matters: By Day 3, you’ll paste a rough message — “tell my professor I cant make tomorrow’s office hours” — and the AI rewrites it as a polite, professional email, ready to send. That’s the kind of tool you’ll actually use.

• Day 1: Email Sender Desktop App (Today)

• Day 2: Mail Merge from CSV

• Day 3: AI Email Assistant (Gemini)

View All Projects This Week

Today’s Project

We start with the foundation of everything else this week: a desktop app that sends one email. Type the recipient, subject, and body, click Send, and your email goes out via Gmail. By the end you’ll understand how Python actually talks to a mail server — the same code powers everything from cron-job notifications to 100-recipient mail merges.

This is the engine. Days 2 and 3 wrap new features around it.

Project Task

Build a Tkinter desktop email sender that:

• Provides input fields for: From (your Gmail), App Password, To, Subject, Body

• Sends the email through Gmail’s SMTP server using smtplib

• Shows clear status: connecting, authenticating, sending, success/failure

• Hides the password field with asterisks

• Validates input (no empty recipient, no missing password) before sending

• Reports detailed error messages when authentication or sending fails

• Has a “Clear” button to reset the form

• Doesn’t crash on network errors — failures are caught and reported

This project gives you hands-on practice with smtplib, the email.message module, Gmail’s STARTTLS authentication, Tkinter form layout, password fields, multi-line text widgets, and the cleanest pattern for separating GUI from logic in a desktop app.

Expected Output

Running the app:

python email_sender.py

That will open the following app in your computer. Below, I already filled in the sender email address and its app password (see further below on how to get an app password for your Gmail account). I also wrote an email.

Pressing the SEND EMAIL button will send out the email from the sender’s address to the receiver’s address. Here is what I received in my gmail account:

Setup Instructions

Step 1 — Install (no dependencies):

This entire project uses Python’s standard library — smtplib, email, tkinter. Nothing to install.

python email_sender.py

Step 2 — Create a Gmail App Password (5 minutes):

You can’t use your regular Gmail password anymore — Google requires an App Password for Python scripts since May 2025.

1. Go to myaccount.google.com and sign in.

2. Click Security in the left sidebar.

3. Under “How you sign in to Google,” enable 2-Step Verification if you haven’t already. (App passwords require it.)

4. Once 2FA is on, go directly to myaccount.google.com/apppasswords.

5. Type any name (e.g., “Python Email”) and click Create.

6. Google shows a 16-character password in a yellow box. Copy it.

7. Paste it into the App Password field in the app — no spaces, just the 16 characters.

Security note: for simplicity, this app keeps the password in the form text field, in memory only. It’s never saved to disk. A more secure setup uses keyring or environment variables — we’ll mention that briefly on Day 3.

Understanding SMTP and Gmail

SMTP — Simple Mail Transfer Protocol — is the protocol that’s moved email between servers since the 1980s. It’s still the protocol. Your script connects to Gmail’s SMTP server, authenticates, and hands over a message; Gmail does the rest.

Python’s smtplib handles the protocol:

import smtplib

with smtplib.SMTP("smtp.gmail.com", 587) as smtp:
    smtp.starttls()                          # upgrade to encrypted connection
    smtp.login("you@gmail.com", "your_app_password")
    smtp.send_message(msg)

Three terms worth knowing:

• smtp.gmail.com — Gmail’s SMTP server address.

• Port 587 — the standard “submission” port for outgoing mail.

• STARTTLS — starts the connection in plain text, then upgrades to TLS encryption. Required by Gmail.

There’s also a port 465 variant using SMTP_SSL (encrypted from the start). Both work for Gmail; we use 587/STARTTLS because it’s the most common pattern in production code.

Understanding the email.message Module

smtplib sends bytes. To build a proper email — with a Subject, From, To, and a body — we use email.message.EmailMessage:

from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "you@gmail.com"
msg["To"] = "recipient@example.com"
msg["Subject"] = "Hello"
msg.set_content("This is the email body.")

EmailMessage is the modern (Python 3.6+) way to construct emails. It handles headers, encoding, MIME types, and attachments cleanly. The older MIMEText / MIMEMultipart classes still work but feel clunky compared to this one.

Setting headers is dictionary-style (msg["Subject"] = ...); setting the body is method-style (msg.set_content(...)). That’s just a quirk of the API — once you know it, the rest is straightforward.

Understanding the Pure Send Function

We keep the email-sending logic in a pure function — no Tkinter, no GUI. It takes the fields, sends the email, and either returns or raises an exception. This makes it reusable for Days 2 and 3 and easy to test in isolation:

def send_email(sender, password, recipient, subject, body):
    msg = EmailMessage()
    msg["From"] = sender
    msg["To"] = recipient
    msg["Subject"] = subject
    msg.set_content(body)

    with smtplib.SMTP("smtp.gmail.com", 587) as smtp:
        smtp.starttls()
        smtp.login(sender, password)
        smtp.send_message(msg)

A simple, four-step function. The Tkinter app just calls it. Tomorrow’s mail-merge tool calls it in a loop. Day 3’s AI assistant calls it after the AI is done. One sending function, many surfaces around it.

Understanding Tkinter Form Layout

For a form-style UI, grid() is much cleaner than pack(). You think in rows and columns; labels go in column 0, inputs in column 1:

frame = tk.Frame(root)
frame.pack(padx=10, pady=10, fill=tk.BOTH, expand=True)

tk.Label(frame, text="From:").grid(row=0, column=0, sticky="w")
tk.Entry(frame, textvariable=self.from_var, width=50).grid(row=0, column=1, sticky="ew")

tk.Label(frame, text="To:").grid(row=1, column=0, sticky="w")
tk.Entry(frame, textvariable=self.to_var, width=50).grid(row=1, column=1, sticky="ew")

frame.columnconfigure(1, weight=1)   # input column stretches with the window

Three small details that earn their place:

• sticky="w" — labels left-align (”west”) instead of centering on their row.

• sticky="ew" — inputs stretch horizontally (”east-west”) to fill the column.

• columnconfigure(1, weight=1) — declares “column 1 gets the extra space when the window resizes.” Without this, the input column never grows.

Understanding Password Fields

Tkinter has a one-line way to hide a password as it’s typed — show="●" on an Entry:

tk.Entry(frame, textvariable=self.password_var, width=50, show="\u2022").grid(...)

\u2022 is the bullet character. ("*" works too; bullets just look cleaner.) The variable still holds the real password — show only affects what the user sees, not what’s stored.

Understanding the Body Text Widget

A single-line Entry won’t work for a multi-line email body — we need a Text widget:

self.body_text = tk.Text(frame, width=50, height=10, wrap="word")
self.body_text.grid(row=4, column=1, sticky="nsew")

# Reading the body later:
body = self.body_text.get("1.0", "end-1c")  # from line 1 char 0 to end, minus the trailing newline

Two Text-widget quirks you’ll see a lot:

• get("1.0", "end-1c") — Tkinter Text indexes use "line.column" format. "1.0" is “line 1, column 0” (the start). "end-1c" is “end minus 1 character” — that strips the trailing newline that Text always appends.

• wrap="word" — wraps lines at word boundaries instead of mid-word.

Understanding Catching SMTP Errors

The send function can fail in many ways: wrong password, bad recipient, network down, Gmail rate-limiting. smtplib raises distinct exceptions for each — we catch them specifically so we can give the user a useful message:

try:
    send_email(sender, password, to_addr, subject, body)
    self.set_status(f"\u2713 Email sent to {to_addr}")

except smtplib.SMTPAuthenticationError:
    self.set_status("\u2717 Authentication failed: check your "
                    "Gmail address and App Password.")

except smtplib.SMTPRecipientsRefused as e:
    self.set_status(f"\u2717 Recipient refused: {e}")

except smtplib.SMTPException as e:
    self.set_status(f"\u2717 Send failed: {e}")

except Exception as e:
    self.set_status(f"\u2717 Error: {e}")

Specific exceptions on top, generic exceptions on the bottom — the classic exception-handling pattern. SMTPAuthenticationError in particular is the one your users will hit most often, almost always because they pasted the App Password with spaces in it. A clear message saves them a lot of confusion.

Understanding Validation Before Send

The send button should refuse to fire when the form is incomplete. A small validation function returns the first error or None:

def validate(self):
    if not self.from_var.get().strip():    return "Please enter your Gmail address."
    if not self.password_var.get():        return "Please enter your App Password."
    if not self.to_var.get().strip():      return "Please enter a recipient."
    if not self.subject_var.get().strip(): return "Please enter a subject."
    body = self.body_text.get("1.0", "end-1c").strip()
    if not body:                           return "Please enter a message body."
    return None

Then in the send handler:

error = self.validate()
if error:
    self.set_status(f"\u2717 {error}")
    return

This is much better than letting the SMTP call fail with a cryptic error. The user sees the actual problem in plain English, before the script even tries to connect.

Understanding the Status Bar

A status bar at the bottom of the window gives the user feedback as the script runs. Three lines do it:

self.status_var = tk.StringVar(value="Ready. Fill in the form and click Send.")
tk.Label(self.root, textvariable=self.status_var, anchor="w",
         bd=1, relief="sunken", padx=8, pady=4).pack(fill="x", side="bottom")

And inside the send method, we update it at each step:

self.set_status("Connecting to smtp.gmail.com...")
self.root.update_idletasks()   # force the GUI to repaint NOW

self.set_status("Authenticating...")
self.root.update_idletasks()

# ... send ...

self.set_status(f"\u2713 Email sent to {to_addr}")

self.root.update_idletasks() is the magic ingredient. Without it, Tkinter batches GUI updates and the user sees nothing happen until the whole send_email call finishes. Calling update_idletasks() forces an immediate repaint — so the user sees “Connecting...” then “Authenticating...” then “Sending...” in real time, instead of a frozen window followed by “Done.”

Coming Tomorrow

Tomorrow we go from one email to many. The Mail Merge tool loads a CSV of recipients, lets you write the email once with placeholder variables like {first_name} and {course}, and personalizes one email per row — sending each with a polite delay between them. Same send_email() function, just a loop around it.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Code Skeleton

Get the code solution here:

View Code Solution

This week, we build an Image Toolkit with Pillow that lets you edit photos in a desktop app, watermark whole folders of images at once, and turn photos into shareable memes and collages.

• Day 1: Photo Filters Studio (Tkinter)

• Day 2: Batch Watermarker

• Day 3: Meme Generator & Collage Maker (Today)

View All Projects This Week

Today’s Project

Welcome to the finale — and the fun one. Today we build two image tools in a single app: a meme generator with the classic top+bottom Impact-font caption (white text, thick black outline) and a collage maker that arranges several photos into a single grid image.

Both are real, shareable image tools — output you’d actually post somewhere. And they reuse every Pillow skill from Days 1 and 2: image opening, text drawing, RGBA, positioning, batch handling. The lesson lands: the same fundamentals power every image tool you’ll ever build.

Project Task

Build a two-mode image studio with Tkinter and Pillow that:

Meme Mode:

• Loads an image

• Lets the user type top and bottom caption text

• Draws captions in the classic meme style (uppercase, white with black outline)

• Auto-fits the text to the image width (no clipping)

• Live preview as text changes

• Saves the finished meme

Collage Mode:

• Loads multiple images

• Lays them out in a configurable grid (2×2, 3×2, 3×3)

• Resizes each image consistently

• Adds a configurable colored border between images

• Saves the finished collage

This project gives you hands-on practice with text styling and stroke outlines, dynamic font sizing, grid layout math, the Image.paste compositing pattern, mode tabs in Tkinter, and reusing one image pipeline across two visual products.

Expected Output

Running the studio:

python meme_collage.py

Meme Mode:

The user can write two pieces of text in the GUI on the right side and the image will be updated instantly:

Collage Mode:

In collage mode, the user can select multiple images in their computer and then user the configuration settings on the right to create a collage view of those images:

Each mode is its own clean tool, sharing a preview area and Save workflow.

Setup Instructions

Install Pillow:

pip install Pillow

(One dependency, same as Days 1 and 2.)

Run it:

python meme_collage.py

For meme mode, use any image (the sample.jpg from Day 1 works great). For collage mode, you’ll want 2–9 images — drop a few photos into a folder and load them.

Understanding the Two-Mode Architecture

The app is structured around tabs: meme mode and collage mode each get their own controls and their own logic, but share the same preview area, save workflow, and font-loading helper.

class ImageStudio:
    def __init__(self, root):
        # shared state lives on self
        self.preview_image = None
        self.tk_image = None
        # ...

        self.notebook = ttk.Notebook(root)
        self.meme_tab = MemeTab(self.notebook, self)
        self.collage_tab = CollageTab(self.notebook, self)
        self.notebook.add(self.meme_tab.frame, text="Meme")
        self.notebook.add(self.collage_tab.frame, text="Collage")

Two small structural choices that matter:

• Each tab gets its own class. Meme and collage are different enough that mixing their state on one giant class gets ugly. Splitting them keeps each tool readable.

• The shared parent (self) holds the preview machinery. Both tabs call parent.set_preview(image) to update the central preview — that way the GUI bit lives in one place.

ttk.Notebook is the standard Tkinter tabbed-pane widget. Switch between Meme and Collage with a click; each tab carries its own state without stomping on the other.

Understanding the Meme Style

The classic meme look has three rules:

1. Bold sans-serif font (Impact traditionally; we use a system bold).

2. Uppercase text.

3. White fill, thick black outline — readable against any background.

Pillow’s draw.text(...) supports outlines directly via two parameters: stroke_width and stroke_fill. The whole meme caption is one call:

def draw_meme_text(draw, text, position, font, fill="white", outline="black", stroke=4):
    draw.text(
        position,
        text.upper(),
        font=font,
        fill=fill,
        stroke_width=stroke,
        stroke_fill=outline,
        anchor="mm",   # center the text at the anchor point
    )

Two parameters earn the magic:

• stroke_width=4 — pixels of outline thickness. 3 is too thin; 6 is too cartoony. Around 4 hits the sweet spot for most image sizes.

• anchor="mm" — the text is middle-horizontal, middle-vertical-anchored at the position you give it. This makes centering trivial: pass the center point of where the text should be, not its top-left corner.

Understanding Auto-Fitting Text Width

A meme caption that overruns the image looks broken. We auto-shrink the font until the rendered text fits the image width:

def fit_font_to_width(text, max_width, target_size):
    """Find the largest font size <= target that fits in max_width."""
    size = target_size
    while size > 10:
        font = load_meme_font(size)
        bbox = ImageDraw.Draw(Image.new("RGB", (10, 10))).textbbox(
            (0, 0), text.upper(), font=font, stroke_width=4
        )
        text_width = bbox[2] - bbox[0]
        if text_width <= max_width:
            return font
        size -= 4
    return load_meme_font(10)

The pattern: start at the user’s requested size and shrink in steps until the text fits. The loop only kicks in for long captions — short text gets full size, no measurement overhead.

Note we include stroke_width=4 in the measurement. The outline adds to the text’s actual width, so we have to account for it — or the loop returns a size that fits the unstroked text but overflows once outlined.

Understanding the Meme Builder

The full meme function ties everything together. Top text goes near the top, bottom text near the bottom, both center-aligned:

def make_meme(image, top_text, bottom_text, target_size=60):
    img = image.convert("RGB").copy()
    draw = ImageDraw.Draw(img)

    # Margin from each edge
    margin = max(20, img.height // 20)

    if top_text:
        font = fit_font_to_width(top_text, img.width - 2 * margin, target_size)
        bbox = draw.textbbox((0, 0), top_text.upper(), font=font, stroke_width=4)
        text_h = bbox[3] - bbox[1]
        center = (img.width // 2, margin + text_h // 2)
        draw_meme_text(draw, top_text, center, font)

    if bottom_text:
        font = fit_font_to_width(bottom_text, img.width - 2 * margin, target_size)
        bbox = draw.textbbox((0, 0), bottom_text.upper(), font=font, stroke_width=4)
        text_h = bbox[3] - bbox[1]
        center = (img.width // 2, img.height - margin - text_h // 2)
        draw_meme_text(draw, bottom_text, center, font)

    return img

The pattern repeats for top and bottom — fit the font, measure the rendered height, compute the center point, draw. Pure function, no side effects: hand it an image and some text, get back the meme. Same as Day 2’s apply_watermark — and that consistency is the point.

Understanding Grid Math for Collages

The collage problem boils down to: given N images and a grid (R rows × C columns), how big should each cell be, and where does each image go?

The cleanest approach is to fix a target cell size and compute the canvas from there, rather than the other way around:

def make_collage(images, rows, cols, border, border_color, cell_size=400):
    cell_w = cell_h = cell_size
    canvas_w = cols * cell_w + (cols + 1) * border
    canvas_h = rows * cell_h + (rows + 1) * border

    canvas = Image.new("RGB", (canvas_w, canvas_h), border_color)

    for index, img in enumerate(images[:rows * cols]):
        row = index // cols
        col = index % cols
        x = border + col * (cell_w + border)
        y = border + row * (cell_h + border)
        canvas.paste(fit_into_cell(img, cell_w, cell_h), (x, y))

    return canvas

A few moves worth understanding:

• (cols + 1) * border — there’s a border on each side and between every column. For 3 columns, that’s 4 border-widths total. Same logic vertically.

• row = index // cols, col = index % cols — integer division and modulo turn a flat list index into a 2D grid position. Image 0 → (0, 0); image 1 → (0, 1); image 3 in a 3-col grid → (1, 0). Classic pattern.

• canvas.paste(img, (x, y)) — Pillow’s basic compositing: draw img onto canvas at the given top-left corner.

Image.new("RGB", (w, h), color) creates the canvas filled with the border color, so empty space between the pasted images is automatically the right color. We never have to “draw the borders” — they’re just the parts of the canvas that don’t get pasted over.

Understanding the fit_into_cell Helper

Real photos come in different aspect ratios — landscape, portrait, square. Just resizing them all to the same dimensions distorts them. The right move is fit and center: shrink each photo to fit inside the cell preserving its aspect ratio, then center it on a square cell-sized canvas:

def fit_into_cell(img, cell_w, cell_h):
    """Resize `img` to fit in a cell_w x cell_h cell, centered, no distortion."""
    img = img.copy()
    img.thumbnail((cell_w, cell_h), Image.Resampling.LANCZOS)

    # Center it on a cell-sized canvas
    cell = Image.new("RGB", (cell_w, cell_h), (240, 240, 240))
    offset = ((cell_w - img.width) // 2, (cell_h - img.height) // 2)
    cell.paste(img, offset)
    return cell

thumbnail preserves aspect ratio; the centering math handles whatever’s left over with a light gray pad. The result: every cell is exactly cell_w × cell_h, no distortion, every photo placed sensibly. The collage layout math from above doesn’t need to care about individual photo sizes.

Understanding Saving Both Modes

Each mode runs through a Save button that triggers a save dialog and writes the current preview-equivalent image (full resolution, not the screen-shrunk version):

def save_meme(self):
    if not self.image:
        return
    final = make_meme(self.image, self.top_var.get(), self.bottom_var.get(),
                      self.size_var.get())
    path = filedialog.asksaveasfilename(defaultextension=".jpg", ...)
    if path:
        final.save(path, quality=92)

Note we rebuild the meme at full resolution before saving — the preview was a shrunken version. The user saw the layout; the save call produces the high-quality version of exactly that layout. Preview is a window onto truth, not its own truth.

Understanding the Full Picture

Three days of image work, one shape:

• Day 1 took one image and applied filters interactively.

• Day 2 took one folder and looped over it.

• Day 3 takes one image (meme) or many images (collage) and produces a single new image.

The same Pillow primitives — Image.open, copy, convert, paste, ImageDraw.Draw, ImageFont, ImageEnhance — assembled in different shapes. There’s no special trick for “memes” or “collages” — only for combining the primitives sensibly. That’s the actual lesson of the week.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete Pillow image toolkit:

• Day 1: Live photo filters and adjustments in a Tkinter studio

• Day 2: Batch-watermark whole folders with live preview

• Day 3: Meme generator and collage maker in a tabbed app

You now have:

✅ Pillow fundamentals — Image, ImageDraw, ImageFont, ImageOps, ImageEnhance, ImageFilter ✅ The PIL ↔ Tkinter bridge — ImageTk.PhotoImage, with the GC reference rule baked in ✅ Real-world habits — EXIF orientation, RGBA compositing, JPEG quality ✅ Live-preview architecture — same function powers preview and save, so what users see is what they get ✅ Multiple working tools — filters, watermarker, meme generator, collage maker

Real-world applications:

• 🎨 Social media content — branded posts, memes, collages, watermarked photos

• 📷 Photography workflow — batch process exports, add copyright, generate previews

• 🛒 E-commerce — watermark product photos at scale

• 📚 Documentation and tutorials — annotate screenshots, generate diagrams

• 🤖 Automation — feed any of these into a script that runs on every uploaded image

Next steps:

• Add a real font picker (browse local fonts)

• Support emoji and unicode characters (Pillow can do it with a unicode font)

• Add an undo stack (keep a list of past edited images)

• Build a CLI version so it’s scriptable

• Try Pillow’s ImageDraw.rounded_rectangle for fancier collage borders

You’ve built the foundation for a real image-processing pipeline. 🚀

View Code Evolution

Compare today’s two-mode studio with Day 1’s filters and Day 2’s batch watermarker — and see how the same Pillow primitives assemble into completely different tools when you change the shape of the loop around them.

Read more

This week, we build an Image Toolkit with Pillow that lets you edit photos in a desktop app, watermark whole folders of images at once, and turn photos into shareable memes and collages.

• Day 1: Photo Filters Studio (Tkinter)

• Day 2: Batch Watermarker (Today)

• Day 3: Meme Generator & Collage Maker

View All Projects This Week

Today’s Project

Yesterday we edited one photo at a time. Today we process hundreds at once.

The Batch Watermarker takes a folder of images, applies a text watermark with the position, opacity, and color you pick, and writes the watermarked copies to an output folder. Live preview while you tune the settings, then one click processes the whole batch — leaving every original untouched.

This is where image processing gets useful. Photographers protecting their work, content creators branding their screenshots, ecommerce sellers labeling product photos — the workflow is the same, and you can build it in 200 lines of Python.

Project Task

Build a batch text watermarker with Tkinter and Pillow that:

• Lets the user pick an input folder of images and an output folder

• Lets the user type the watermark text

• Lets the user choose the position: one of 5 anchor points (corners + center)

• Lets the user adjust opacity (0–100%) and font size with sliders

• Shows a live preview of the watermark on the first image in the folder

• Processes the whole folder when “Apply to All” is clicked

• Preserves EXIF orientation and original quality

• Reports progress per file and continues on errors

• Never overwrites originals — writes to a separate output folder

This project gives you hands-on practice with Pillow’s ImageDraw and ImageFont, RGBA compositing for proper transparency, working with image folders, anchor-based positioning, and turning a single-image operation into a batch pipeline.

Expected Output

Running the watermarker:

python batch_watermarker.py

Application Window:

The user can pick an input folder where the images are and an output folder to save the watermarked images.

Once the user has selected the folder the program already applies watermarks and displays the first image in the GUI.

The user can click the APPLY TO ALL button to process all images and a new output folder with the generated images will be generated. Here is a snapshot of that folder:

Setup Instructions

Install Pillow:

pip install Pillow

(Same single dependency as Day 1.)

Run it:

python batch_watermarker.py

You’ll need a folder of images to point at. To try it quickly, copy sample.jpg from Day 1 into a folder a few times — even one image works.

Understanding the Two-Step Architecture

The whole app is built around one simple split:

apply_watermark(image, settings)  →  the pure image operation
process_folder(input, output, settings)  →  the batch loop

The first function takes a single PIL image plus a dict of settings and returns a watermarked copy. The second function walks the input folder, calls the first function for each image, and saves the result.

This split is the whole point of today’s lesson. Once you have a clean single-image function, batching it is just a for loop with error handling around it. Days 1, 2, and 3 of this week all reuse the same shape: do one thing well, then loop.

Understanding RGBA Compositing

A watermark isn’t just text drawn on top of an image — it’s text with transparency. If you set opacity to 60%, that means “60% white text, 40% whatever pixel is underneath.” That’s RGBA compositing, and it’s the foundation of every transparency effect in Pillow.

The pattern:

1. Convert the photo to RGBA (so it can mix with transparent things).

2. Create a separate transparent overlay the same size as the photo.

3. Draw the text onto the overlay with an alpha channel set by opacity.

4. Composite the overlay onto the photo with Image.alpha_composite.

def apply_watermark(image, text, position, font_size, opacity, color):
    # 1. Force RGBA so compositing works
    base = image.convert("RGBA")

    # 2. Transparent overlay
    overlay = Image.new("RGBA", base.size, (0, 0, 0, 0))
    draw = ImageDraw.Draw(overlay)

    # 3. Compute the alpha (0-255) from opacity (0.0-1.0)
    fill_rgb = (255, 255, 255) if color == "white" else (0, 0, 0)
    fill_rgba = (*fill_rgb, int(opacity * 255))

    # 4. Position the text and draw it
    font = ImageFont.truetype(...)  # see below
    x, y = compute_position(text, font, base.size, position)
    draw.text((x, y), text, font=font, fill=fill_rgba)

    # 5. Composite and return
    return Image.alpha_composite(base, overlay)

The critical move is drawing the text onto a separate transparent overlay, not directly onto the photo. Drawing directly works for fully opaque text, but the moment you want partial transparency, the alpha values in fill get ignored unless the canvas itself supports alpha. The overlay does.

Understanding ImageDraw and ImageFont

ImageDraw is Pillow’s drawing API. You wrap a canvas image and call drawing methods on it:

from PIL import ImageDraw, ImageFont

draw = ImageDraw.Draw(overlay)
draw.text((50, 50), "Hello", font=font, fill=(255, 255, 255, 200))

For text, you need a font — and this is where things get a little fiddly across platforms. The cleanest approach: try a likely system font, fall back to Pillow’s built-in if it isn’t found:

def load_font(size):
    candidates = [
        "DejaVuSans-Bold.ttf",                       # Linux
        "/Library/Fonts/Arial Bold.ttf",             # macOS
        "C:/Windows/Fonts/arialbd.ttf",              # Windows
    ]
    for path in candidates:
        try:
            return ImageFont.truetype(path, size)
        except (OSError, IOError):
            continue
    # Last resort: a tiny built-in font (size is not adjustable on this one)
    return ImageFont.load_default()

The truetype paths are platform-specific, so we try a few. load_default() always works but the size is fixed — only acceptable as a fallback.

Understanding Text Measurement and Positioning

To anchor a watermark to a corner, you need to know how big the text actually is in pixels. The modern way in Pillow is textbbox:

# Measure the rendered size of the text
bbox = draw.textbbox((0, 0), text, font=font)
text_w = bbox[2] - bbox[0]
text_h = bbox[3] - bbox[1]

textbbox((x, y), text) returns (left, top, right, bottom) — the bounding box of where the text would be drawn if you called draw.text((x, y), ...). Subtract to get width and height.

With that, anchor positioning is just math:

def compute_position(text_w, text_h, img_w, img_h, position, pad=20):
    if position == "top-left":     return (pad, pad)
    if position == "top-right":    return (img_w - text_w - pad, pad)
    if position == "bottom-left":  return (pad, img_h - text_h - pad)
    if position == "bottom-right": return (img_w - text_w - pad, img_h - text_h - pad)
    if position == "center":       return ((img_w - text_w) // 2, (img_h - text_h) // 2)
    return (pad, pad)

The pad of 20 px keeps the text off the very edge — a small touch that makes a huge visual difference. Without padding, watermarks look glued to the corner; with padding, they look intentionally placed.

Understanding Folder Iteration

Listing images in a folder needs care. Folders contain hidden files, non-image files, subfolders. pathlib makes it tidy:

from pathlib import Path

IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".bmp", ".gif", ".webp"}

def list_images(folder):
    return sorted(
        p for p in Path(folder).iterdir()
        if p.is_file() and p.suffix.lower() in IMAGE_EXTS
    )

Three small choices that matter:

• Set lookup for extensions — O(1) membership and easy to extend.

• p.suffix.lower() — match .JPG as well as .jpg.

• sorted(...) — predictable order in the progress log, instead of whatever the filesystem coughs up.

Understanding Saving and Format

The watermarked image is in RGBA mode. That’s fine for PNG, but JPEG can’t store transparency. So before saving JPEG, we flatten the alpha:

def save_image(img, path):
    if path.suffix.lower() in {".jpg", ".jpeg"}:
        # Flatten to RGB so JPEG can save it
        img = img.convert("RGB")
        img.save(path, quality=92)
    else:
        img.save(path)

convert("RGB") drops the alpha channel by blending against black — fine for our case because the photo underneath has no transparent areas. (If you needed to preserve transparency with JPEG-style compression, you’d save WebP or PNG instead.)

The quality=92 is genuinely worth setting — Pillow’s JPEG default is 75, which is enough for thumbnails but visibly lossy on photos. 92 keeps the output looking essentially identical to the input.

Coming Tomorrow

Tomorrow we make things fun. The Meme Generator & Collage Maker uses today’s text drawing skills for meme captions (the classic top + bottom text in white-with-black-outline) and adds a collage builder that arranges multiple photos into a single grid image. Two image tools, one app, ready to share.

View Code Evolution

Compare today’s batch watermarker with yesterday’s filters studio and see how the single-image transformation pattern scales to whole folders with one loop and a little error handling.

Read more

This week, we build an Image Toolkit with Pillow that lets you edit photos in a desktop app, watermark whole folders of images at once, and turn photos into shareable memes and collages.

Why build this? Because image manipulation is one of the most fun and visible domains in Python. Click a button, see your photo transform — instant feedback you can’t get with text-based tools. Plus the skills transfer everywhere: any time you need to resize, watermark, filter, or generate images, this is the foundation.

What you’ll learn: This series teaches you Pillow (the modern PIL), Tkinter GUI design with image previews, color and pixel manipulation, image filters and convolutions, batch processing, EXIF orientation handling, and the classic bridges between PIL and Tkinter.

Why this matters: By Day 3, you’ll have built a meme generator and collage maker that produces images you’d actually post. That’s portfolio-level fun.

• Day 1: Photo Filters Studio (Tkinter) (Today)

• Day 2: Batch Watermarker

• Day 3: Meme Generator & Collage Maker

View All Projects This Week

Today’s Project

We start with the visual heart of any image toolkit: a filter studio. Load a photo, see it on screen, click filter buttons or drag sliders, watch the image transform in real time, and save the result. By the end you’ll have a polished little Photoshop-lite — and the Pillow fundamentals to do anything image-related in Python.

The classic six one-click filters (Grayscale, Sepia, Blur, Sharpen, Edge Detect, Invert) plus three live sliders (Brightness, Contrast, Saturation). Reset returns to the original. Save writes a new file — your original is never touched.

Project Task

Build a photo filter desktop app with Tkinter and Pillow that:

• Loads an image via a file dialog (JPG, PNG, etc.)

• Displays the image in a preview area, resized to fit

• Correctly handles phone-photo rotation (EXIF orientation)

• Applies one-click filters: Grayscale, Sepia, Blur, Sharpen, Edge Detect, Invert

• Provides live sliders for Brightness, Contrast, and Saturation

• Re-renders the preview every time the user changes something

• Has a Reset button to return to the original

• Saves the edited image as a new file (Save As…)

• Never modifies the original — every edit happens on a copy

This project gives you hands-on practice with Pillow’s Image, ImageFilter, ImageEnhance, and ImageOps modules, Tkinter file dialogs, scales/sliders, the ImageTk bridge for previewing PIL images in a GUI, and the small architecture choices that keep an image editor sane.

Expected Output

Running the app:

python photo_filters.py

Application Window:

Here is a snapshot of how the finished app looks like:

Setup Instructions

Install Pillow:

pip install Pillow

That’s it — Tkinter ships with Python. (On Linux: sudo apt-get install python3-tk if it isn’t already there.)

Get a test image:

A sample.jpg is provided below — a colorful generated scene that shows off every filter beautifully. You can also use any photo from your computer.

Run the app:

python photo_filters.py

Understanding the Image-Editing Architecture

Before any code, the architecture matters. There are three images alive at all times:

self.original   →  The image as loaded from disk. NEVER touched again.
self.edited     →  The current edited version. This is what gets saved.
self.preview    →  A small, screen-sized copy of `edited` for display only.

Two rules fall out of this:

1. Filters and slider changes modify edited — they never touch original.

2. Every change is followed by a refresh_preview() — which creates a fresh preview from edited and updates the GUI.

Reset is then trivial: self.edited = self.original.copy() — and refresh. This separation prevents the most common bugs in image editors (irreversible damage, slow re-renders, getting “stuck” on a filter).

Understanding Pillow Basics

Pillow’s central object is Image. Opening, copying, and saving look like this:

from PIL import Image

img = Image.open("sample.jpg")   # lazy load — actual pixels read on demand
edited = img.copy()              # always work on a copy
edited.save("output.jpg")        # save anywhere with any supported extension

Three habits worth forming on day one:

• Always .copy() before editing. Pillow’s filters often return new images, but it’s safer to think of the original as immutable.

• Don’t worry about format on open. Pillow detects JPG/PNG/BMP/GIF/WebP/HEIC automatically.

• The format on save is taken from the extension — output.png writes PNG, output.jpg writes JPEG.

Understanding EXIF Orientation

Here’s a real-world trap: photos taken on a phone often look correct in Photos but appear rotated 90° when opened with Pillow. That’s because the camera saves the image in its native sensor orientation and stores the intended rotation as EXIF metadata — and Pillow doesn’t apply it automatically.

The fix is one line:

from PIL import ImageOps

img = Image.open("photo.jpg")
img = ImageOps.exif_transpose(img)   # apply the EXIF rotation

exif_transpose reads the EXIF orientation tag and physically rotates/flips the image to match what the user expects. Without it, your “perfectly working” app will mysteriously fail on the first phone selfie someone tries. Call it once, right after opening — done.

Understanding ImageTk: PIL → Tkinter Bridge

Tkinter’s widgets can’t display a PIL Image directly. The bridge is ImageTk.PhotoImage, which wraps a PIL image into a Tkinter-compatible image object:

from PIL import ImageTk

self.tk_image = ImageTk.PhotoImage(self.preview)
self.preview_label.config(image=self.tk_image)

The classic gotcha: if you don’t keep a reference to self.tk_image, Python garbage-collects it and the image vanishes from the screen with no error. Always store it on self. — never as a local variable inside a method.

This is the #1 most common “my image won’t show” bug in Pillow+Tkinter code. Now you’ll never write it.

Understanding Resizing for Preview

A 4000×3000 photo can’t be shown at full size — and resizing on every slider tick would be sluggish. The pattern: resize once, when the image changes, to a screen-friendly version.

Pillow’s thumbnail() method resizes in place and preserves aspect ratio:

preview = self.edited.copy()
preview.thumbnail((600, 600), Image.Resampling.LANCZOS)
self.preview = preview

Two details that matter:

• thumbnail is in-place. It doesn’t return a new image — it modifies the one you call it on. So we copy() first.

• Image.Resampling.LANCZOS is the modern constant for the high-quality downsampling filter. Older code uses Image.LANCZOS (deprecated) or Image.ANTIALIAS (removed). LANCZOS is the right choice for shrinking photos.

Understanding ImageFilter: One-Click Filters

For Blur, Sharpen, and Edge Detect, Pillow ships built-in convolution kernels in ImageFilter:

from PIL import ImageFilter

self.edited = self.edited.filter(ImageFilter.BLUR)
self.edited = self.edited.filter(ImageFilter.SHARPEN)
self.edited = self.edited.filter(ImageFilter.FIND_EDGES)

A “convolution” is just: for each pixel, look at its neighbors, compute a weighted average. Blur averages neighbors. Sharpen subtracts a blurred version from the original. Edge detect amplifies differences between neighbors. You don’t need to write the math — ImageFilter has clean, named presets.

Understanding ImageOps: Grayscale and Invert

For pure color transformations, ImageOps is the right toolbox:

from PIL import ImageOps

self.edited = ImageOps.grayscale(self.edited).convert("RGB")
self.edited = ImageOps.invert(self.edited)

A subtlety with grayscale: ImageOps.grayscale returns a single-channel (”L” mode) image. Converting back to “RGB” keeps the rest of the pipeline happy — later filters and the ImageTk display expect 3-channel images.

invert simply flips every pixel value (255 − v), giving you that classic film-negative look.

Understanding Sepia: Custom Per-Channel Math

Sepia isn’t built in — and that’s a good thing, because it’s the perfect excuse to teach per-pixel/per-channel manipulation. The standard sepia formula transforms each pixel’s RGB values:

new_R = 0.393·R + 0.769·G + 0.189·B
new_G = 0.349·R + 0.686·G + 0.168·B
new_B = 0.272·R + 0.534·G + 0.131·B

Implemented in Pillow:

def apply_sepia(img):
    img = img.convert("RGB")
    pixels = img.load()         # an indexable pixel grid

    for y in range(img.height):
        for x in range(img.width):
            r, g, b = pixels[x, y]
            tr = int(0.393 * r + 0.769 * g + 0.189 * b)
            tg = int(0.349 * r + 0.686 * g + 0.168 * b)
            tb = int(0.272 * r + 0.534 * g + 0.131 * b)
            pixels[x, y] = (min(tr, 255), min(tg, 255), min(tb, 255))

    return img

img.load() returns a pixel-access object you can read and assign with pixels[x, y]. The min(..., 255) clamps values that overflow the 0–255 range. Slow for huge images but perfectly fine for the screen-sized previews we’re editing.

Aside: for large images and production code, you’d use numpy or Image.point() for vectorized math. But the pixel loop is the canonical way to teach what every image filter is doing under the hood, so we use it here. Worth the few seconds.

Understanding ImageEnhance: Adjustable Effects

Brightness, Contrast, and Saturation aren’t on/off filters — the user dials them. That’s what ImageEnhance is for:

from PIL import ImageEnhance

enhancer = ImageEnhance.Brightness(self.edited)
self.edited = enhancer.enhance(1.4)   # 1.0 = unchanged; >1 brighter, <1 darker

The number is a factor, not an amount:

• 1.0 — leave as is

• 1.5 — 50% brighter / more contrast / more saturated

• 0.5 — 50% darker / flatter / desaturated

• 0.0 — completely black / no contrast / fully grayscale

This factor pattern is uniform across Brightness, Contrast, Color (saturation), and Sharpness. Once you know one, you know all four.

Understanding the Slider Refresh Pattern

Sliders fire continuously as the user drags. To keep the UI snappy, each slider re-applies all three enhancements from the original, every time:

def update_adjustments(self, _event=None):
    img = self.original_for_adjust.copy()

    img = ImageEnhance.Brightness(img).enhance(self.brightness_var.get())
    img = ImageEnhance.Contrast(img).enhance(self.contrast_var.get())
    img = ImageEnhance.Color(img).enhance(self.saturation_var.get())

    self.edited = img
    self.refresh_preview()

The key choice: we start each update from self.original_for_adjust, a snapshot taken when the user last clicked a filter. That way the sliders work on top of “grayscale”, “sepia”, etc., but moving a slider doesn’t accumulate enhancements every frame (which would amplify them out of control).

This snapshot-based pattern is the small architectural trick that makes the studio feel like a real editor instead of a glitchy demo.

Understanding Saving

Pillow infers the output format from the file extension:

def save_as(self):
    path = filedialog.asksaveasfilename(
        defaultextension=".jpg",
        filetypes=[("JPEG", "*.jpg *.jpeg"),
                   ("PNG",  "*.png"),
                   ("All",  "*.*")],
    )
    if not path:
        return
    self.edited.save(path)

Two important details:

• JPEG can’t store transparency. If the user has applied filters that introduce an alpha channel (rare here, but possible), save to PNG. Otherwise force RGB before saving JPEG: self.edited.convert("RGB").save(path).

• JPEG quality defaults to 75. For photos worth sharing, add quality=92 to the save call.

Our app saves whatever PIL deems best for the extension, which works for the 95% case.

Coming Tomorrow

Tomorrow we go from one photo to a whole folder. The Batch Watermarker adds a text or logo watermark to every image in a folder, with position controls, opacity, and a live preview — turning today’s manual workflow into a one-click batch operation.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Code Skeleton

Get the code solution here:

View Code Solution

This week, we build a Web Scraping with BeautifulSoup suite that extracts a complete product catalog from a real website, scales up to thousands of items across many pages, and turns the scraped data into a searchable mini-database.

• Day 1: Scrape a Single Page

• Day 2: Multi-Page Scraping with Pagination

• Day 3: Search & Analyze the Scraped Data (Today)

View All Projects This Week

Today’s Project

Welcome to the finale. You have a dataset of 1,000 scraped books. Now what? Now you query it. Today we turn the CSV into an interactive command-line search engine — keyword search, filters by category, price, and rating, sorting, and on-demand statistics. The scraping pipeline becomes a real tool you can use.

This is what makes scraping worth doing. Data sitting in a CSV is just rows. The same data behind a query interface becomes a mini-database — yours to ask questions of.

Project Task

Build an interactive book search and analysis tool that:

• Loads all_books.csv from Day 2 into a pandas DataFrame

• Offers a friendly REPL — type a command, see results

• Supports keyword search across titles and descriptions

• Filters by category, price range, rating, and stock status

• Combines filters (category=Fiction min_price=20 rating>=4)

• Sorts results by any field (sort=price desc)

• Shows summary statistics on the full catalog or any filter

• Exports the current view to a CSV

• Has a clear help command and gracefully handles bad input

This project gives you hands-on practice with pandas filtering, boolean masks, string matching, building a small CLI loop, parsing command arguments, and turning a dataset into a tool people can actually use.

Expected Output

Running the tool:

python search_books.py

Interactive session:

The user can interact with the program in the terminal. All the text in red color are commands the user has submitted:

You drop a search command and your dataset answers. Combine filters and it slices in real time. That’s a tool.

Setup Instructions

Install pandas:

pip install pandas

(You also need all_books.csv — the output of Day 2. If you haven’t run that yet, run it first, or use the sample file provided below)

Download all_books.csv

Run the program:

python search_books.py

The tool drops you into an interactive prompt. Type help to see the commands; type quit to exit.

Understanding the REPL Loop

A REPL — Read, Evaluate, Print, Loop — is just a while loop around input() and a dispatch on what the user typed. It’s the simplest way to build an interactive tool, and it suits this kind of dataset exploration perfectly:

def run_repl(df):
    current = df  # the current "view" - starts as the whole dataset

    while True:
        line = input("> ").strip()
        if not line:
            continue
        if line == "quit":
            break

        # parse the command and dispatch
        current = handle_command(line, df, current)

Three habits worth noticing:

• An empty line just continues — common enough to handle explicitly.

• The user typed string is .strip()ped — trailing whitespace from a paste shouldn’t break commands.

• current holds the filtered view, separate from df (the full catalog) — so reset always has the full data to return to.

Understanding Command Parsing

Each command starts with a word (search, filter, sort, stats...) followed by arguments. The simplest parse: split on whitespace, take the first token as the command name:

def handle_command(line, df, current):
    parts = line.split()
    cmd = parts[0].lower()
    args = parts[1:]

    if cmd == "search":
        return command_search(current, " ".join(args))
    if cmd == "filter":
        return command_filter(df, args)
    if cmd == "stats":
        command_stats(current)
        return current
    # ...

Each command gets its own function. command_search and command_filter return the new view (so the REPL can update current); command_stats just prints and returns the view unchanged. This keeps the dispatch readable — each command does one thing in one place.

Understanding pandas String Search

The search command should match across titles and descriptions, case-insensitively. pandas’ .str.contains() does the heavy lifting:

def command_search(df, query):
    if not query:
        print("  Usage: search <keyword>")
        return df

    title_match = df["title"].str.contains(query, case=False, na=False)
    desc_match = df["description"].str.contains(query, case=False, na=False)

    matches = df[title_match | desc_match]
    show_results(matches, f"Found {len(matches)} matches for '{query}'")
    return matches

A few important details:

• case=False — case-insensitive matching. "python" finds "Python".

• na=False — treats missing values as “no match” instead of NaN. Without it, you get errors when the column has any blanks.

• | — boolean OR between the two masks. A book matches if either the title or the description contains the keyword.

The result is a new DataFrame — a filtered view of the catalog — that becomes the new current. The next command operates on those matches.

Understanding Boolean Masks

Filtering in pandas is built on boolean masks: a column of True/False the same length as the DataFrame, used to keep only the True rows.

# Books over £30
mask = df["price"] >= 30
expensive = df[mask]

# Books over £30 AND rated 4+
mask = (df["price"] >= 30) & (df["rating"] >= 4)
expensive_and_good = df[mask]

Two non-obvious rules every pandas user hits:

• Use & and |, not and and or. The Python keywords don’t work on column-level booleans.

• Wrap each condition in parentheses. & has higher precedence than >=, so without parens the order is wrong and you get errors.

(condition) & (condition) & (condition) is how every multi-filter query in pandas looks. Get used to it.

Understanding the Filter Command

The filter command takes key-value pairs like category=Fiction min_price=20 rating>=4. We parse each piece, build a list of conditions, then combine them:

def command_filter(df, args):
    mask = pd.Series(True, index=df.index)   # start: keep everything
    applied = []

    for arg in args:
        if arg.startswith("category="):
            value = arg.split("=", 1)[1].lower()
            mask &= df["category"].str.lower().str.contains(value, na=False)
            applied.append(f"category={value}")

        elif arg.startswith("min_price="):
            value = float(arg.split("=", 1)[1])
            mask &= df["price"] >= value
            applied.append(f"price>={value}")

        elif arg.startswith("max_price="):
            value = float(arg.split("=", 1)[1])
            mask &= df["price"] <= value
            applied.append(f"price<={value}")

        elif arg.startswith("rating>="):
            value = int(arg.split("=", 1)[1])
            mask &= df["rating"] >= value
            applied.append(f"rating>={value}")

    result = df[mask]
    print(f"  Filter applied: {', '.join(applied)}")
    show_results(result, f"{len(result)} books match.")
    return result

Two patterns worth taking away:

• Build masks incrementally with &= — starting from True everywhere, each condition narrows the result. Whether the user passes one filter or four, the same loop handles it.

• Always re-filter from the full catalog, not the current view. That way filter category=Fiction replaces the previous filter rather than narrowing within it — usually what you actually want.

Understanding the Sort Command

sort price desc reorders the current view. The parse picks up the column and direction:

def command_sort(df, args):
    if not args:
        print("  Usage: sort <field> [asc|desc]")
        return df

    field = args[0]
    ascending = not (len(args) > 1 and args[1].lower() == "desc")

    if field not in df.columns:
        print(f"  Unknown field: {field}")
        return df

    sorted_df = df.sort_values(field, ascending=ascending).head(10)
    direction = "ascending" if ascending else "descending"
    print(f"  Sorted by {field} ({direction}). Showing top 10:")
    show_results(sorted_df, "")
    return df  # return original; don't permanently sort the view

A subtlety: sort should display the sorted top-10 but not change the filter state. So we show the sorted view, but return the unsorted current view. The user expects “show me the top by price” to be a view, not a state change — the next filter shouldn’t be operating on a sliced sorted list.

Understanding Formatting Aligned Output

A search result is just a DataFrame — but print(df) looks ugly. We format each row manually so titles align, prices line up by the decimal, and ratings use stars:

def show_results(df, header_message):
    if header_message:
        print(f"\n  {header_message}")
    if df.empty:
        print("  (no results)")
        return

    print()
    print(f"    {'Title':<40} {'Category':<18} {'Price':>8} {'Rating':>10}")
    print("    " + "─" * 80)

    for _, row in df.head(20).iterrows():
        title = row["title"]
        if len(title) > 40:
            title = title[:37] + "..."
        stars = "★" * int(row["rating"])
        print(f"    {title:<40} {row['category']:<18} "
              f"£{row['price']:>6.2f}   {stars:>8}")

.head(20) caps the output — nobody scrolls through 1,000 rows in a terminal. The column widths (:<40, :<18, :>8) and right-aligned price with two decimals (>6.2f) make the table read like a real product, not raw data.

Understanding the Stats Command

stats runs on the current view, so the same command answers both “stats for the full catalog” and “stats for what I just filtered.” It’s all pandas aggregation:

def command_stats(df):
    if df.empty:
        print("  No books in current view.")
        return

    print(f"\n  Books:            {len(df)}")
    print(f"  Categories:       {df['category'].nunique()}")
    print(f"  Average price:    £{df['price'].mean():.2f}")
    print(f"  Price range:      £{df['price'].min():.2f} – £{df['price'].max():.2f}")
    print(f"  Avg rating:       {df['rating'].mean():.2f} / 5")
    in_stock = (df["stock_count"] > 0).sum()
    print(f"  In stock:         {in_stock} ({in_stock / len(df) * 100:.0f}%)")

    print("\n  Rating breakdown:")
    for rating in range(1, 6):
        count = (df["rating"] == rating).sum()
        stars = "★" * rating
        print(f"    {stars:<13} {count:>3}")

    print("\n  Top 5 categories by book count:")
    top = df["category"].value_counts().head(5)
    for cat, count in top.items():
        print(f"    {cat:<22} {count:>3}")

The reusable trick: df['category'].value_counts() — counts how often each value appears, sorted descending, in one line. It’s the fastest way to build a “top categories” or “top X” list from any column.

Understanding the Export Command

save results.csv writes the current view to a file. One line:

def command_save(df, args):
    if not args:
        print("  Usage: save <filename>")
        return df
    path = args[0]
    df.to_csv(path, index=False)
    print(f"  ✓ Exported {len(df)} books to {path}")
    return df

This is the closing of the loop: scrape → enrich → query → export the answer. The user can take their filtered subset into pandas, Excel, or another tool. The tool becomes a gateway, not just an endpoint.

Understanding Graceful Error Handling

Users mistype things. A REPL that crashes on a typo is unusable, so each command wraps its risky parts in try/except:

try:
    value = float(arg.split("=", 1)[1])
except ValueError:
    print(f"  Could not parse: {arg}")
    continue

The unknown-command fallback is just as important — help is a single press away, and bad input is just a printed message:

print(f"  Unknown command: {cmd}. Type 'help' for the list.")

Quiet, clear, forgiving. A tool you’d actually use.

Understanding Why This Is the Right Finale

Look at the three days together:

• Day 1 taught you to extract from one page.

• Day 2 taught you to scale across many pages with pagination and detail-page enrichment.

• Day 3 taught you to use the result — turning raw scraped data into answers.

The arc matters: scraping by itself isn’t valuable, it’s the dataset and what you do with it that matters. Every real scraping project ends with a query interface, a dashboard, an analysis — something that turns rows into decisions. Today’s REPL is the smallest, simplest version of that, and it makes the whole week click into place.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete web scraping pipeline:

• Day 1: Extract structured data from a single web page

• Day 2: Scale across pagination + detail pages, with polite delays

• Day 3: Turn the scraped catalog into an interactive search tool

You now have:

✅ Scraping fundamentals — requests, BeautifulSoup, CSS class selection, attributes ✅ Pagination and multi-level scraping — listing pages + detail pages, combined cleanly ✅ Polite scraping habits — User-Agent, timeouts, delays, error handling ✅ Querying skills with pandas — boolean masks, string search, sorting, aggregation ✅ A real tool — your scraped data, queryable in real time

Next steps:

• Add a charts module: matplotlib distribution plots for price and rating

• Persist the dataset to SQLite for fast queries on larger catalogs

• Build a Streamlit version of the query interface

• Add a watcher: nightly rescrape, diff against the previous CSV

• Handle login-required sites with requests.Session

You’ve built the foundation for a real scraping-and-analysis pipeline. 🚀

View Code Evolution

Compare today’s query tool with Day 1’s single-page scraper and Day 2’s full-catalog scraper — and see how a clean three-step pipeline (extract → scale → query) is the shape of every real scraping project.

Read more

This week, we build a Web Scraping with BeautifulSoup suite that extracts a complete product catalog from a real website, scales up to thousands of items across many pages, and turns the scraped data into a searchable mini-database.

• Day 1: Scrape a Single Page

• Day 2: Multi-Page Scraping with Pagination (Today)

• Day 3: Search & Analyze the Scraped Data

View All Projects This Week

Today’s Project

Yesterday we scraped 20 books from one page. Today we scrape 1,000 books from 50 pages — the full catalog of books.toscrape.com. Then we go deeper: for each book, we also visit its detail page to pull richer information you can’t get from the listing — the exact UPC, real stock count, full description, and category.

This is what a real scraper looks like: it follows links, scales across pages, and handles failures politely. By the end of today, you’ll have a single CSV holding every book on the site, ready for Day 3’s search tool.

Project Task

Build a multi-page book scraper that:

• Scrapes every book across all 50 catalog pages

• Detects the “next page” link to follow pagination automatically

• Visits each book’s detail page to pull richer fields (UPC, stock count, description, category)

• Adds a polite delay between requests

• Shows clear progress (page X of Y, book X of Y)

• Continues running if one page or detail page fails

• Saves everything to a single CSV

• Reports a final summary with counts and totals

This project gives you hands-on practice with pagination, two-level scraping (listing → detail page), polite rate limiting, robust error handling, progress reporting, and combining data from multiple HTTP requests — the techniques behind every production-grade scraper.

Expected Output

Running the full-catalog scraper:

python scrape_all_books.py

Console Output:

The script will run and visit different pages (50 in total) of the books.toscrape.com website and print out info for each book in the terminal:

Generated all_books.csv:

In addition to being printed in the terminal, the data will also be saved in a CSV file. Here is a snapshot of the file:

We will have 1,000 rows, 9 columns, every book on the site. Ready for tomorrow’s search tool.

Setup Instructions

Install Required Packages:

pip install requests beautifulsoup4

(Same as Day 1 — no new dependencies.)

Run it:

python scrape_all_books.py

The full run takes roughly 5-10 minutes depending on your internet — that’s 50 listing pages + 1,000 detail pages = 1,050 requests with a 0.2 second delay between each. The script prints progress so you’ll know it’s working.

Tip: if you just want to see it work without waiting, set MAX_PAGES = 3 near the top of the script for a quick three-page test.

Understanding Pagination

The first scaling problem is finding all the pages. We could hardcode page-1.html through page-50.html, but that breaks the moment the site adds page 51. The robust way is to let the page tell us where to go next.

Look at the bottom of any catalog page and you’ll find:

<li class="next">
  <a href="page-2.html">next</a>
</li>

So our strategy is: scrape the current page, look for <li class="next">, follow it. When that link doesn’t exist, we’re done.

def find_next_url(soup, current_url):
    """Return the absolute URL of the next page, or None if this is the last."""
    next_li = soup.find("li", class_="next")
    if next_li is None:
        return None  # we've reached the end of the catalog
    next_href = next_li.find("a")["href"]
    return urljoin(current_url, next_href)

That urljoin(current_url, ...) is doing real work: pages 2 through 50 use relative links like page-3.html, and urljoin resolves each one against the current page’s URL. The result is always a correct absolute URL.

Understanding the Main Pagination Loop

With find_next_url in hand, the main scrape becomes a small while loop:

url = BASE_URL
page_number = 0
all_books = []

while url:
    page_number += 1
    print(f"Page {page_number}:  {url}")

    html = fetch_page(url)
    if html is None:
        break  # can't fetch this page, stop the run

    soup = BeautifulSoup(html, "html.parser")
    books = scrape_listing_page(soup)
    all_books.extend(books)

    url = find_next_url(soup, url)   # None when we've reached the end
    time.sleep(REQUEST_DELAY)

The whole loop reads in plain English: fetch this page, extract its books, find the next URL, sleep, repeat. When find_next_url returns None, the loop ends naturally. No page counting, no hardcoded limit, no fragility.

Understanding Polite Scraping

Hitting a server with 1,050 requests as fast as Python can send them is rude — and a great way to get rate-limited or banned. The fix is a small delay between requests:

import time

REQUEST_DELAY = 0.2   # seconds between requests

# ...inside the loop, after each request:
time.sleep(REQUEST_DELAY)

0.2 seconds is invisible to you but a huge break for the server — five requests per second is gentle for any well-running site. The fact that books.toscrape.com explicitly invites scraping doesn’t change the principle: every scraper you write should pause between requests. The habit matters more than this particular site’s tolerance.

Understanding Two-Level Scraping

A listing page tells you a book exists. The detail page tells you everything about it — the UPC, the precise stock count, the full description, the category. To get those, we visit each book’s detail URL.

The pattern is two-level: scrape the listing, then for each book in that listing, fetch and scrape its detail page.

def enrich_with_details(book):
    """Fetch the book's detail page and add the extra fields to its dict."""
    html = fetch_page(book["url"])
    if html is None:
        # detail fetch failed; keep the listing data, add empty extras
        book.update(stock_count=None, category=None, upc=None, description=None)
        return book

    soup = BeautifulSoup(html, "html.parser")
    book["upc"] = extract_upc(soup)
    book["stock_count"] = extract_stock_count(soup)
    book["category"] = extract_category(soup)
    book["description"] = extract_description(soup)
    return book

The function takes a book dict (from the listing scrape) and returns the same dict with the extra fields added. This composes cleanly — listing data and detail data end up in one place.

Understanding find_next_sibling

find_next_sibling("p") is worth a closer look — it’s the move for “find me the next paragraph after this element.” That’s how the description is structured on the site: a header div followed by the description paragraph at the same level.

header = soup.find("div", id="product_description")
description_p = header.find_next_sibling("p")

This pattern shows up constantly in scraping when content is logically related but lives in separate tags. Sibling navigation lets you say “the thing right after this one,” without having to know its position in the document. You’ll reach for it again and again.

Understanding Saving the Combined Data

The output schema is the union of listing data and detail data — nine columns total:

FIELDNAMES = [
    "title", "price", "rating", "availability",
    "stock_count", "category", "upc", "description", "url",
]

with open("all_books.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=FIELDNAMES)
    writer.writeheader()
    writer.writerows(all_books)

Because every book is a dict with the same keys, DictWriter aligns the columns correctly even when a few rows have empty description fields. The result is a single, clean CSV — 1,001 lines including the header — that becomes the input for Day 3.

Coming Tomorrow

Tomorrow we put the dataset to work. The Search & Analyze tool takes all_books.csv and turns it into a query interface: search by title or keyword, filter by category, price range, and rating, and generate summary statistics — average prices per category, distribution of ratings, top-N by any field. Your scraped data becomes a small but real, useful database.

View Code Evolution

Compare today’s full-catalog scraper with yesterday’s single-page version and see how a small pagination loop and a detail-page step scale 20 books into 1,000 — without rewriting the extraction logic.

Read more

This week, we build a Web Scraping with BeautifulSoup suite that extracts a complete product catalog from a real website, scales up to thousands of items across many pages, and turns the scraped data into a searchable mini-database.

Why build this? Because web scraping is one of the most genuinely useful Python skills. Data that’s locked inside a website becomes yours — to analyze, search, compare, or feed into other tools. Every analyst, data scientist, and automation engineer needs this skill.

What you’ll learn: This series teaches you HTTP requests, HTML parsing with BeautifulSoup, CSS selectors, handling lists of repeated elements, pagination, polite scraping with delays, structured data extraction, and querying the result.

Why this matters: By Day 3, you’ll have scraped a complete catalog of 1,000 books and built a tool to search and analyze them. That’s a real, portfolio-worthy project — and the techniques transfer directly to scraping any catalog-style site.

• Day 1: Scrape a Single Page (Today)

• Day 2: Multi-Page Scraping with Pagination

• Day 3: Search & Analyze the Scraped Data

View All Projects This Week

Today’s Project

Today you learn the fundamentals: fetching a web page, parsing it with BeautifulSoup, and extracting structured data from a list of repeated items.

The target is books.toscrape.com — a real, public site explicitly built for scraping practice. It’s the official sandbox of the Python scraping community. Today’s mission: scrape every book on the homepage (20 books), capture each one’s title, price, rating, and availability, and save the result as a clean CSV.

By the end, you’ll understand how every catalog-style scraper works — because the pattern is the same whether you’re scraping books, products, jobs, real estate, or any other list of repeated items.

Project Task

Build a single-page book scraper that:

• Fetches the books.toscrape.com homepage with requests

• Sets a polite User-Agent header to identify your script

• Parses the HTML with BeautifulSoup

• Finds every book card on the page

• For each book, extracts:

  • Full title (from the link’s title attribute, not the truncated text)

  • Price as a real number (no £ symbol)

  • Star rating as an integer (1–5)

  • Stock availability (in stock / out of stock)

  • Link to the book’s detail page

• Reports progress as it works

• Saves all books to a CSV with proper column types

This project gives you hands-on practice with requests, BeautifulSoup, CSS class selection, attribute access, text cleanup, and writing structured data to CSV — the core of every web scraper.

Expected Output

Running the scraper:

python scrape_books.py

Console Output:

Generated books.csv:

Real prices as numbers, ratings as integers, links absolute — ready for analysis without further cleanup.

Setup Instructions

Install Required Packages:

pip install requests beautifulsoup4

That’s it — two libraries. requests fetches the page, beautifulsoup4 parses it.

Run it:

python scrape_books.py

The script reads from the live site and writes books.csv next to itself.

Understanding the Target Site

Before writing any code, always look at the page in your browser. Open https://books.toscrape.com/ and right-click any book → “Inspect Element.”

You’ll see that every book on the page is wrapped in an <article> tag with the class product_pod:

<article class="product_pod">
  <div class="image_container">
    <a href="catalogue/a-light-in-the-attic_1000/index.html">
      <img src="..." alt="A Light in the Attic">
    </a>
  </div>
  <p class="star-rating Three"></p>
  <h3>
    <a href="catalogue/a-light-in-the-attic_1000/index.html"
       title="A Light in the Attic">A Light in the ...</a>
  </h3>
  <div class="product_price">
    <p class="price_color">£51.77</p>
    <p class="instock availability"> In stock </p>
  </div>
</article>

This structure is the whole game. Every scraper boils down to: find the repeated container, then pluck specific fields out of each one. The HTML inspector tells you the class names and tags to target — that’s how you know what to put in your code.

Understanding requests and Headers

Scraping starts with downloading the page. requests.get() does the heavy lifting:

import requests

url = "https://books.toscrape.com/"
headers = {"User-Agent": "Mozilla/5.0 (Python Scraper)"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()      # blow up clearly if the page didn't load

html = response.text

Three habits worth forming from day one:

• Always set a User-Agent. Many sites block the default python-requests/... UA. A real-looking string makes your scraper a polite, well-behaved visitor.

• Always set a timeout. Without one, a slow or unresponsive server can hang your script forever. Ten seconds is sensible for most pages.

• Call raise_for_status(). It throws an exception on 4xx/5xx responses, so you catch bad pages immediately instead of trying to parse an error page.

Understanding BeautifulSoup

BeautifulSoup turns HTML text into a tree you can search. You hand it the raw HTML and a parser name:

from bs4 import BeautifulSoup

soup = BeautifulSoup(html, "html.parser")

The two most-used methods:

• soup.find(tag, class_="...") — returns the first matching element (or None).

• soup.find_all(tag, class_="...") — returns a list of every matching element.

Note the class_ with the trailing underscore — class is a reserved word in Python, so BeautifulSoup uses class_ for matching on CSS classes. It catches everyone the first time.

Understanding find_all for Repeated Items

The first real scraping move is grabbing every book card on the page. We saw each one is an <article class="product_pod">, so:

book_cards = soup.find_all("article", class_="product_pod")

print(f"Found {len(book_cards)} books")
# Found 20 books

find_all returns a list — we now iterate through it and extract from each card individually. This is the heart of catalog scraping: find the repeating container with find_all, then operate on each one in a loop.

Understanding Field Extraction

Inside each <article>, we pull out the four fields. Each one is its own little trick:

Title — from the <a> tag inside the <h3>. The visible link text is truncated (”A Light in the …”), but the full title is in the title attribute:

title_link = card.find("h3").find("a")
title = title_link["title"]           # "A Light in the Attic"  (the full one)

Price — inside <p class="price_color">, including the £ symbol. We extract the text, strip the symbol, convert to a float:

price_text = card.find("p", class_="price_color").get_text()
price = float(price_text.replace("£", "").strip())

Rating — in the class name of <p class="star-rating Three">. The number is encoded as a word:

rating_tag = card.find("p", class_="star-rating")
rating_word = rating_tag["class"][1]       # ["star-rating", "Three"] -> "Three"
rating = RATING_MAP[rating_word]           # {"One":1, "Two":2, ...}

Availability — inside <p class="instock availability">. The text has leading/trailing whitespace:

availability = card.find("p", class_="instock availability").get_text(strip=True)
# "In stock"

Each extraction is two or three lines, but together they capture everything we need. The pattern is always the same: locate, extract, clean.

Understanding Why title= Beats the Link Text

You might be tempted to use the visible text — title_link.get_text() — for the title. Don’t. The visible text is deliberately truncated: “A Light in the …” instead of “A Light in the Attic.”

The full title lives in the title attribute of the same link. Why? Because that’s what websites use to show a tooltip when you hover. The HTML stores the real value there even when the visible text is shortened for layout.

Lesson: when scraping, the visible text isn’t always the data you want. Inspect the HTML, find the cleanest source, and use that. Attribute values (title, data-*, value, href) often hold the real, untruncated information.

Understanding Resolving Relative URLs

The href on each book is relative: catalogue/a-light-in-the-attic_1000/index.html. To save a useful link, we need the absolute URL. urllib.parse.urljoin handles this correctly even when the page has a base path:

from urllib.parse import urljoin

base_url = "https://books.toscrape.com/"
relative = card.find("h3").find("a")["href"]

absolute = urljoin(base_url, relative)
# 'https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html'

Manual string concatenation breaks on edge cases. urljoin always produces a correct URL — use it without thinking about it.

Understanding Saving to CSV

We could use pandas, but the standard library’s csv module is perfect for clean, structured data:

import csv

with open("books.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=["title", "price", "rating",
                                            "availability", "url"])
    writer.writeheader()
    writer.writerows(books)

Two pieces of CSV trivia worth knowing:

• newline="" — without this, the csv module sometimes writes blank lines between rows on Windows. Always include it.

• encoding="utf-8" — book titles can include accented characters, em-dashes, smart quotes. UTF-8 handles them all; the default encoding doesn’t on every OS.

DictWriter is the natural match for our extracted books — each book is already a dict with the right keys.

Understanding Polite Scraping

books.toscrape.com explicitly invites scraping (”We love being scraped!”), so today’s single fetch is fine. But the habits start now: identify yourself in the User-Agent, set a timeout, and check raise_for_status. Tomorrow when we hit 50 pages in a row, we’ll add a delay between requests too — but that’s a Day 2 detail. Today: one polite request, gracefully handled.

Practical Use Cases

1. Catalog extraction:

The same pattern (find_all the cards, extract per card) scrapes any e-commerce listing page.

2. Job listings:

Sites like Indeed and Remote OK use repeated cards just like book listings.

3. Real-estate aggregation:

Pull property cards from a listing page — same logic, different selectors.

4. Research and data collection:

Academic papers, datasets, contest leaderboards — catalog patterns are everywhere.

5. Foundation for Day 2:

Once you can scrape one page, scaling to many is just a loop with pagination.

Coming Tomorrow

Tomorrow we go from 20 books to 1,000. You’ll follow the “next page” link, scrape all 50 pages of the catalog, and add detail-page scraping for richer data — UPC, exact stock count, full description, and category. We also add polite delays between requests because real scrapers don’t hammer servers.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Skeleton

Get the code solution here:

View Code Solution

This week, we build a CSV Sales Toolkit that cleans messy data, generates insightful reports, and processes whole folders of files at once — the exact workflow of real data work.

• Day 1: Visual CSV Cleaner

• Day 2: Sales Analyzer & Report

• Day 3: Batch CSV Processor (Today)

View All Projects This Week

Today’s Project

Welcome to the finale. You have a cleaner and an analyzer. Today they grow up. Instead of working on one file at a time, today’s tool points at a folder of monthly sales CSVs, cleans every one, combines them all into a single dataset, and produces a consolidated multi-month report — with per-month comparisons, growth percentages, and a full-period summary.

This is the moment your script becomes a tool someone could automate. Drop a new month’s file into the folder, run the script, get the updated report. That’s how real data work scales.

Project Task

Build a batch CSV processor that:

• Discovers every CSV in a designated folder automatically

• Cleans each file using the Day 1 cleaning pipeline

• Reports the result of each file (rows, missing values fixed)

• Continues to the next file if one fails, instead of crashing

• Merges all cleaned data into a single combined DataFrame

• Runs the Day 2 analysis on the combined data

• Adds per-month aggregates (revenue per month, month-over-month change)

• Identifies the best month, top product overall, and trends

• Saves both the combined CSV and the consolidated report

• Prints a progress summary as it works

This project gives you hands-on practice with pathlib for folder scanning, batch file handling, robust error handling, pd.concat for combining DataFrames, time-grouped aggregations with dt.to_period, and turning your earlier scripts into reusable functions.

Expected Output

Folder structure before running:

monthly_sales/
├── sales_2026_01.csv     (30 orders, messy)
├── sales_2026_02.csv     (25 orders, messy)
├── sales_2026_03.csv     (27 orders, messy)
└── sales_2026_04.csv     (28 orders, messy)

Running the processor:

python batch_process.py

Console Output:

You drop a fifth month into the folder next quarter — and rerunning produces an updated five-month report with no changes to the code. That’s the win.

Setup Instructions

Install pandas:

pip install pandas

Get the data files:

Download the monthly_sales/ folder:

Download

It contains four monthly CSVs. Place the folder next to your script.

Run it:

python batch_process.py

The script reads every CSV in monthly_sales/ and writes two new files: all_sales_clean.csv (the merged clean data) and consolidated_report.txt (the report).

Understanding Folder Scanning with pathlib

The first batch trick is finding the files automatically. We don’t hardcode filenames — we ask the folder what’s in it. pathlib makes this elegant:

from pathlib import Path

folder = Path("monthly_sales")
csv_files = sorted(folder.glob("*.csv"))

print(f"Found {len(csv_files)} CSV files")
for path in csv_files:
    print(f"  {path.name}")

Three things to know:

• Path("monthly_sales") — pathlib’s modern, OS-aware way to point at a folder.

• .glob("*.csv") — returns every file matching the pattern.

• sorted(...) — files come back in filesystem order, which can vary. Sorting alphabetically gives you predictable chronological order when filenames include dates.

Adding a new monthly file later is now a non-event. The script discovers it automatically.

Understanding Reusable Cleaning Functions

We need the Day 1 cleaning logic — but as a function, not a GUI button. So we lift it into a standalone helper:

TEXT_COLUMNS = ["customer_name", "product", "category", "status"]

def clean_dataframe(df):
    """Apply every cleaning step from Day 1 and return the result."""
    for col in TEXT_COLUMNS:
        df[col] = df[col].astype(str).str.strip()

    df["category"] = df["category"].str.title()
    df["status"] = df["status"].str.lower()

    df["unit_price"] = (
        df["unit_price"].astype(str)
        .str.replace("$", "", regex=False)
        .str.replace(",", "", regex=False)
    )
    df["unit_price"] = pd.to_numeric(df["unit_price"], errors="coerce")

    df["quantity"] = pd.to_numeric(df["quantity"], errors="coerce")
    df["quantity"] = df["quantity"].fillna(1).astype(int)

    category_avg = df.groupby("category")["unit_price"].transform("mean")
    df["unit_price"] = df["unit_price"].fillna(category_avg).round(2)

    df["total_price"] = (df["quantity"] * df["unit_price"]).round(2)

    return df

This is the same logic as Day 1, packaged so it can be called over and over. That’s the broader lesson: a function you wrote for one file works for a thousand, the moment you stop hardcoding the data and start passing it as an argument.

Understanding the Batch Loop

The heart of batch processing is the loop. For each file: load, clean, collect. The key habit is defensive error handling — one bad file should not destroy the entire run:

cleaned_dfs = []
failures = []

for i, path in enumerate(csv_files, 1):
    try:
        df = pd.read_csv(path)
        df = clean_dataframe(df)
        cleaned_dfs.append(df)
        print(f"  [{i}/{len(csv_files)}] {path.name}   ✓  {len(df)} rows cleaned")
    except Exception as e:
        failures.append((path.name, str(e)))
        print(f"  [{i}/{len(csv_files)}] {path.name}   ✗  {e}")

Two important moves:

• try/except around each file — if one CSV is corrupt or has unexpected columns, the loop logs the failure and continues. The other files still process.

• failures list — collecting errors instead of letting them kill the script means you get a complete picture of what happened, even when some files broke.

A batch tool that crashes on the third file out of fifty is barely better than running them manually. Robustness is the feature.

Understanding pd.concat for Merging

After cleaning, we combine the per-file DataFrames into one. pd.concat is the tool:

combined = pd.concat(cleaned_dfs, ignore_index=True)
combined.to_csv("all_sales_clean.csv", index=False)

pd.concat stacks DataFrames vertically — row after row — as long as they share columns. ignore_index=True is important: without it, you keep each file’s original row indexes (0, 1, 2... then 0, 1, 2... again). With it, you get a single fresh sequence — much easier to work with.

The merged file is also a deliverable. Now you have a single clean CSV holding every month’s data, ready for any future analysis.

Understanding Period Grouping

The headline new capability today is monthly comparisons. With the merged data, we can group by month using pandas’ time-period feature:

combined["order_date"] = pd.to_datetime(combined["order_date"])

monthly = (
    completed.assign(month=completed["order_date"].dt.to_period("M"))
    .groupby("month")
    .agg(
        orders=("order_id", "count"),
        revenue=("total_price", "sum"),
    )
)

Two new ideas here:

• .dt.to_period("M") — converts a date like 2026-01-15 into the period 2026-01. Every date in January becomes the same period, which is exactly what you need to group by month.

• .agg(name=(column, function), ...) — the named-aggregation form of agg. You get to name each output column and pick what it’s computed from, in one clean call. Much more readable than the older positional form.

The result is a small DataFrame with one row per month, ready to compare.

Understanding Month-over-Month Change

A monthly total tells you what happened. A month-over-month change tells you the direction. Pandas’ pct_change() makes this a one-liner:

monthly["change"] = monthly["revenue"].pct_change() * 100
# Output:
# 2026-01     —      (first month, no prior to compare to)
# 2026-02   -2.7%
# 2026-03  +15.3%
# 2026-04   +5.9%

pct_change() returns the percentage change between each row and the one before it. The first row gets NaN — there’s no earlier value to compare to — which we display as an em-dash.

This single column turns a list of monthly revenues into a story: “Dipped in Feb, surged 15% in March, and kept climbing.” That’s the kind of sentence reports are supposed to enable.

Understanding Formatting the Monthly Table

The monthly section needs careful column alignment to look like a real report:

lines.append("  Month        Orders   Revenue       Change")
lines.append("  " + "-" * 48)

for month, row in monthly.iterrows():
    change = row["change"]
    if pd.isna(change):
        change_str = "    —"            # first month, nothing to compare to
    else:
        sign = "+" if change >= 0 else ""
        change_str = f"{sign}{change:.1f}%"

    lines.append(
        f"  {str(month):<10}"
        f"  {int(row['orders']):>4}"
        f"     ${row['revenue']:>8,.2f}"
        f"   {change_str:>6}"
    )

A few details earn their place:

• pd.isna(change) — the safe way to check for missing values. (change == NaN always returns False — never use == for NaN.)

• "+" if change >= 0 else "" — manually prepending + makes positive numbers visually distinct from negative ones at a glance.

• {...:<10} / {...:>4} / {...:>8,.2f} — left- and right-alignment with widths. The column headers and the data rows use the same widths, so everything lines up.

These small touches turn raw numbers into a table that reads like something from a real product.

Understanding Why This Architecture Works

Look at the three days side by side:

• Day 1 built a clean_dataframe workflow inside a GUI.

• Day 2 built build_report from clean data.

• Day 3 wraps both in a loop over a folder.

Each layer was rewritten exactly once: when its job changed. The cleaning logic didn’t change today — we just call it in a loop. The reporting structure didn’t change much either — we added monthly comparisons. Most of today’s code is glue: scanning a folder, iterating, concatenating, formatting. That’s a real pattern for building software: solve one case well, then loop the solution.

Practical Use Cases

1. Monthly business reporting:

Drop each new month's export into the folder, rerun, get an updated report — forever.

2. Year-end consolidation:

Process 12 monthly files into one yearly summary, with month-over-month growth.

3. Multi-source data merging:

Combine exports from different stores, regions, or systems into one analysis.

4. Building data pipelines:

The pattern (discover → clean → merge → analyze) is the skeleton of every ETL job.

5. Automated jobs:

Schedule this script and it generates fresh reports nightly without supervision.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete CSV Sales Toolkit.

• Day 1: Visual CSV cleaner — fixes real-world data mess with a click

• Day 2: Sales analyzer — turns clean data into business insights

• Day 3: Batch processor — scales the whole pipeline to a folder of files

You now have:

✅ Data cleaning skills — whitespace, casing, types, missing values, the real toolkit ✅ Aggregation skills — groupby, agg, pct_change, period grouping ✅ Batch processing skills — pathlib, looped error handling, pd.concat ✅ Report formatting skills — alignment, currency, percent, multi-section output ✅ A clean architecture — three layers, reused not rewritten

Real-world applications:

• 📊 Sales and finance reporting — exactly the workflow this teaches

• 🧾 Receipt or invoice consolidation — batch-clean and merge

• 🏷️ Inventory analysis — same patterns apply to product/stock data

• 📈 Marketing reporting — clean campaign exports, aggregate, compare

• 🤖 Personal automation — turn a 30-minute manual job into a 10-second script

Next steps:

• Add charts: matplotlib bar/line plots embedded in a PDF report

• Make it incremental: detect new files and only process those

• Schedule it: run nightly with cron, send the report by email

• Add forecasting: use the monthly trend to predict next month

• Database storage: write the cleaned merged data into SQLite for queries

You’ve built the foundation for a real data automation pipeline.

View Code Evolution

Compare today’s batch processor with the Day 1 cleaner and Day 2 analyzer — and see how a folder loop, robust error handling, and one good architecture turn a small script into a tool that scales.

Read more

This week, we build a CSV Sales Toolkit that cleans messy data, generates insightful reports, and processes whole folders of files at once — the exact workflow of real data work.

• Day 1: Visual CSV Cleaner

• Day 2: Sales Analyzer & Report (Today)

• Day 3: Batch CSV Processor

View All Projects This Week

Today’s Project

Yesterday we cleaned the data. Today we make it talk. Clean data is only useful if it tells you something — so today we build a Sales Analyzer that takes orders_clean.csv and computes the numbers a business actually cares about: total revenue, best-selling products, revenue by category, daily trends, and average order value.

The result is a formatted text report you can read at a glance or email to someone — turning a spreadsheet of rows into actual answers.

Project Task

Build a sales analyzer that:

• Loads the cleaned orders CSV from Day 1

• Separates completed orders from cancelled ones

• Calculates headline metrics: total revenue, order count, average order value

• Finds the best-selling products (by quantity and by revenue)

• Breaks revenue down by category

• Computes a daily sales trend

• Calculates the cancellation rate

• Formats everything into a clean, readable report

• Saves the report to a text file

This project gives you hands-on practice with pandas aggregation, groupby, sorting, filtering, and turning raw numbers into a formatted business report — the analysis half of real data work.

Expected Output

Running the analyzer:

python analyze_sales.py

Console Output (and saved report):

The same text is printed to the console and saved as sales_report.txt — readable, shareable, done.

Setup Instructions

Install pandas:

pip install pandas

Get the data file:

You need orders_clean.csv — the output of Day 1. Run the Day 1 cleaner first, or use the cleaned file provided below:

Download orders_clean.csv

Place the orders_clean.csv file in the same folder as the script.

Run the Python script:

python analyze_sales.py

The script reads orders_clean.csv and writes sales_report.txt.

Understanding Why Clean Data Matters Here

Day 1 wasn’t busywork — today is where it pays off. Every calculation below depends on the cleaning:

• Total revenue sums total_price — only possible because prices are real numbers, not $12.99 text.

• Revenue by category groups by category — only gives 3 groups because we standardized the capitalization.

• Completed vs. cancelled filters on status — only works because we made the status values consistent.

Analysis on dirty data produces confidently wrong answers. That’s worse than no answer. Clean first, analyze second — always.

Understanding Loading and Filtering

We start by loading the clean CSV and splitting it by status. Most metrics should count completed orders only — a cancelled order earned no revenue:

import pandas as pd

df = pd.read_csv("orders_clean.csv")

# Split by status
completed = df[df["status"] == "completed"]
cancelled = df[df["status"] == "cancelled"]

df[df["status"] == "completed"] is boolean filtering — the inner part builds a column of True/False, and the outer part keeps only the True rows. This is the single most common pandas operation, and it’s how we make sure cancelled orders don’t inflate revenue.

Understanding Headline Metrics

The top-level numbers are simple aggregations on the completed orders:

total_revenue = completed["total_price"].sum()
order_count = len(completed)
items_sold = completed["quantity"].sum()

# Average order value — guard against dividing by zero
average_order = total_revenue / order_count if order_count else 0

# Cancellation rate as a percentage
cancellation_rate = len(cancelled) / len(df) * 100

Each metric is one line. .sum() adds a column, len() counts rows. The only subtlety is guarding the division — if order_count else 0 prevents a crash if there are no completed orders. Defensive arithmetic like this is what separates a script that works on your data from one that works on any data.

Understanding groupby for Category Revenue

To break revenue down by category, we use groupby — pandas’ tool for “split into groups, then calculate per group”:

category_revenue = (
    completed.groupby("category")["total_price"]
    .sum()
    .sort_values(ascending=False)
)

Read it as a pipeline:

1. groupby("category") — split the rows into one group per category.

2. ["total_price"] — we only care about the price column.

3. .sum() — total it within each group.

4. .sort_values(ascending=False) — order the result, biggest first.

The result is a Series: category names on the left, total revenue on the right. This four-step pattern — group, select, aggregate, sort — is the backbone of nearly every report you’ll ever write.

Understanding Top Products

“Best-selling” has two meanings, and a good report shows both. Some products sell in high volume; others bring in more money. Same groupby pattern, different column:

# By revenue — which products earn the most money
top_by_revenue = (
    completed.groupby("product")["total_price"]
    .sum()
    .sort_values(ascending=False)
    .head(5)
)

# By quantity — which products sell the most units
top_by_quantity = (
    completed.groupby("product")["quantity"]
    .sum()
    .sort_values(ascending=False)
    .head(5)
)

.head(5) keeps only the top five after sorting. Showing both lists is genuinely useful: a cheap product can top the quantity list while barely registering on revenue — that contrast is an insight, not just a number.

Understanding the Daily Trend

To see sales over time, we group by date. The order_date column is text, so we convert it to real dates first — that makes it sort chronologically and behave correctly:

completed = completed.copy()
completed["order_date"] = pd.to_datetime(completed["order_date"])

daily_sales = (
    completed.groupby("order_date")["total_price"]
    .sum()
    .sort_index()
)

# The single best day
best_day = daily_sales.idxmax()       # the date with the highest total
best_amount = daily_sales.max()        # that highest total

Two new tools here:

• pd.to_datetime turns date text into real date objects, so 2026-01-09 sorts after 2026-01-08, not alphabetically.

• .idxmax() returns the index label of the maximum value — here, the date of the best day — while .max() returns the value itself. The pair answers “what was the best day, and how good was it?”

Note the .copy() — when you take a filtered slice of a DataFrame and then modify it, pandas warns you. .copy() makes a clean, independent copy so the modification is unambiguous and warning-free.

Understanding Formatting the Report

Raw numbers aren’t a report — formatting makes them readable. Python’s f-strings give you fine control over alignment and number display:

# Currency: 2 decimals, comma thousands separator
print(f"  Total revenue:  ${total_revenue:,.2f}")
# -> "  Total revenue:  $986.40"

# Percentage: 1 decimal place
print(f"  Cancellation rate:  {cancellation_rate:.1f}%")
# -> "  Cancellation rate:  20.0%"

# Aligned columns: pad the name to a fixed width
for product, revenue in top_by_revenue.items():
    print(f"  {product:<20} ${revenue:>9,.2f}")

The format codes earn their keep:

• :,.2f — comma thousands separator, exactly 2 decimals (money).

• :.1f — 1 decimal place (percentages).

• :<20 — left-align in a 20-character space (product names line up).

• :>9 — right-align in a 9-character space (numbers line up by the decimal).

Aligned columns are the difference between a report that looks professional and one that looks like a data dump.

Understanding Building Report Sections

Rather than print scattered everywhere, we build the report as a list of text lines, then join it once at the end. This way the same text goes to both the console and the file:

def build_report(df):
    lines = []
    lines.append("=" * 80)
    lines.append("SALES ANALYSIS REPORT")
    lines.append("=" * 80)
    lines.append("")
    # ... append every section ...
    return "\n".join(lines)

Collecting lines in a list and "\n".join()-ing them at the end is cleaner than dozens of print calls. You build the report once, as a string — then you can print it, save it, or both, with no duplication.

Understanding Saving the Report

Writing the finished report to a text file is a few lines with a with block:

report_text = build_report(df)

print(report_text)                       # show it on screen

with open("sales_report.txt", "w") as f: # and save it to a file
    f.write(report_text)

The with open(...) block handles the file safely — it’s automatically closed even if something goes wrong. Because build_report returned one string, sending it to both the screen and the file is trivial. A .txt report is something a non-technical person can open, read, and forward — which is often the whole point of doing the analysis.

Practical Use Cases

1. Weekly or monthly sales summaries:

Run the analyzer on the latest data, get a report ready to send to your team.

2. Spotting your best products:

The revenue vs. quantity lists reveal which products to promote or restock.

3. Tracking cancellation problems:

A rising cancellation rate is an early warning worth watching.

4. Finding peak sales days:

The daily trend shows when customers buy — useful for planning promotions.

5. Foundation for Day 3:

Tomorrow we run this analysis across a whole folder of monthly files at once.

Coming Tomorrow

Tomorrow is the finale: the Batch CSV Processor. Instead of one file, you’ll point the tool at a folder of monthly sales CSVs — it cleans every one, analyzes them all, merges the data, and produces a single consolidated multi-month report. Real batch processing.

View Code Evolution

Compare today’s analyzer with yesterday’s cleaner and see how clean, typed data turns directly into meaningful business metrics.

Read more

This week, we build a CSV Sales Toolkit that cleans messy data, generates insightful reports, and processes whole folders of files at once — the exact workflow of real data work.

Why build this? Because real-world data is always messy. Inconsistent capitalization, stray whitespace, dollar signs in number columns, missing values — every dataset has them. The ability to reliably clean data is one of the most practical skills in all of Python.

What you’ll learn: This series teaches you data cleaning, type conversion, missing-value handling, aggregation and reporting, and batch file processing — the core skills behind data analysis and automation.

Why this matters: By Day 3, you’ll have a tool that points at a folder of monthly sales files, cleans every one, and produces a single consolidated business report. That’s a genuinely useful piece of software.

• Day 1: Visual CSV Cleaner (Today)

• Day 2: Sales Analyzer & Report

• Day 3: Batch CSV Processor

View All Projects This Week

Today’s Project

We start at the foundation of all data work: cleaning. But instead of a script that runs and prints text, we’re building a visual desktop app. You load a messy CSV, see it in a table, click a button, and watch the data transform — bad values fixed, missing cells filled, all in front of you.

The input file looks fine at a glance. But it has stray whitespace, three different spellings of “Electronics,” dollar signs stuck in the price column, and missing values. Today you build a tool that fixes all of it — and shows you the difference.

Project Task

Build a visual CSV cleaner with Tkinter that:

• Loads a raw orders CSV and displays it in a table (Treeview)

• Shows a “before” view of the messy data

• Cleans the data on a button click:

  • Strips whitespace from text columns

  • Standardizes category names to Title Case

  • Standardizes order status to lowercase

  • Removes $ signs and converts prices to numbers

  • Converts quantity to whole numbers

  • Fills missing values sensibly

  • Adds a calculated total_price column

• Displays the cleaned “after” data in the same table

• Shows a status log of exactly what was cleaned

• Saves the cleaned data to a new CSV via a Save button

This project gives you hands-on practice with pandas data cleaning, Tkinter GUIs, the Treeview table widget, and connecting a data pipeline to a visual interface — a practical mix of data and app-building skills.

Expected Output

Running the app:

python csv_cleaner.py

Application Window:

Running the code will produce this desktop app. Here we have already loaded the orders_raw.csv file which you can download here:

After clicking “Clean Data” we see this:

Watch the table change in place: electronics becomes Electronics, $12.99 becomes 12.99, the empty quantity in row 1004 fills with 1, and a new total_price column appears.

Setup Instructions

Install pandas:

pip install pandas

Tkinter ships with Python — nothing else to install.

Get the data file:

Download orders_raw.csv (provided with this project) and keep it handy — you’ll load it from inside the app.

Download CSV

Run the .py program:

python csv_cleaner.py

Understanding the Messy Data

Before building anything, look at orders_raw.csv. These are the six problems hiding in it:

1. Whitespace — " Alice Johnson" and "Bob Smith " have stray spaces.

2. Inconsistent categories — Electronics, electronics, ELECTRONICS are the same category spelled three ways.

3. Inconsistent status — completed, Completed, COMPLETED — same problem.

4. Currency symbols — some prices are $12.99 (text!) instead of 12.99 (a number).

5. Missing quantities — a few quantity cells are empty.

6. Missing prices — a few unit_price cells are empty.

Each one breaks analysis later. Sum revenue and $12.99 crashes the math. Group by category and you get six groups instead of three. Cleaning is what makes analysis possible.

Understanding the App Structure

We organize the whole app as a class. The class holds the DataFrame as self.df, so every method — load, clean, save — works on the same shared data:

import tkinter as tk
from tkinter import ttk, filedialog
import pandas as pd

class CSVCleanerApp:
    def __init__(self, root):
        self.root = root
        self.df = None          # the DataFrame, shared across all methods
        self.build_ui()

    def build_ui(self):
        # buttons, table, status log go here
        ...

self.df starts as None (nothing loaded yet). load_csv() fills it, clean_data() transforms it, save_csv() writes it out. Storing the data on self is what lets separate button clicks act on one shared dataset.

Understanding the Treeview Table

Tkinter’s ttk.Treeview is the widget for showing tabular data — rows and columns, like a spreadsheet:

# Create the table
self.tree = ttk.Treeview(self.root, show="headings")

# Define which columns exist
self.tree["columns"] = ("order_id", "customer_name", "product")

# Set the header text for each column
for col in self.tree["columns"]:
    self.tree.heading(col, text=col)
    self.tree.column(col, width=120)

# Add a row of data
self.tree.insert("", "end", values=(1001, "Alice Johnson", "Wireless Mouse"))

Three ideas:

• show="headings" hides Treeview’s default empty first column — you almost always want this.

• .heading() sets the visible column title; .column() sets its width.

• .insert("", "end", values=(...)) adds one row; the tuple of values fills the columns left to right.

Understanding Displaying a DataFrame

The table widget doesn’t know about pandas — so we need a function that takes any DataFrame and renders it into the Treeview. The pattern is: clear the table, set up the columns, then add every row.

def show_dataframe(self, df):
    # 1. Clear any existing rows
    self.tree.delete(*self.tree.get_children())

    # 2. Set the columns to match the DataFrame
    self.tree["columns"] = list(df.columns)
    for col in df.columns:
        self.tree.heading(col, text=col)
        self.tree.column(col, width=110)

    # 3. Add every row from the DataFrame
    for _, row in df.iterrows():
        self.tree.insert("", "end", values=list(row))

This one function is reused for both the before and after views. Load the messy data — call show_dataframe. Clean it — call show_dataframe again. The table just re-renders whatever DataFrame you hand it.

Understanding Loading a File

The “Load CSV” button opens a file picker with filedialog, then reads the chosen file:

from tkinter import filedialog

def load_csv(self):
    path = filedialog.askopenfilename(
        title="Select a CSV file",
        filetypes=[("CSV files", "*.csv")]
    )
    if not path:          # user clicked Cancel
        return

    self.df = pd.read_csv(path)
    self.show_dataframe(self.df)
    self.log(f"Loaded {path} — {len(self.df)} rows, {len(self.df.columns)} columns")

filedialog.askopenfilename returns the selected path as a string — or an empty string if the user cancels, which is why we check if not path. Once loaded, we show the data and log what happened.

Understanding the Cleaning Pipeline

The cleaning logic is pure pandas — the same regardless of GUI or CLI. We break it into one method per problem, all called by clean_data():

def clean_data(self):
    if self.df is None:
        self.log("Load a CSV first!")
        return

    df = self.df

    # --- Strip whitespace from text columns ---
    text_cols = ["customer_name", "product", "category", "status"]
    for col in text_cols:
        df[col] = df[col].astype(str).str.strip()

    # --- Standardize capitalization ---
    df["category"] = df["category"].str.title()   # electronics -> Electronics
    df["status"] = df["status"].str.lower()        # COMPLETED -> completed

    # --- Fix the price column ---
    df["unit_price"] = df["unit_price"].astype(str).str.replace("$", "", regex=False)
    df["unit_price"] = pd.to_numeric(df["unit_price"], errors="coerce")

    # ... (quantity, missing values, total_price) ...

    self.df = df
    self.show_dataframe(self.df)

The key tools:

• .str.strip() / .str.title() / .str.lower() — string operations applied to a whole column via the .str accessor.

• .str.replace("$", "", regex=False) — strips the dollar sign so the text can become a number.

• pd.to_numeric(..., errors="coerce") — converts text to numbers; anything unconvertible becomes NaN (missing) instead of crashing.

Understanding Missing Value Handling

After converting types, some cells are missing. For sales data we fill rather than drop — dropping rows loses real orders.

Missing quantity → fill with 1 (an order existed, so at least one item):

df["quantity"] = pd.to_numeric(df["quantity"], errors="coerce")
df["quantity"] = df["quantity"].fillna(1).astype(int)

Missing unit_price → fill with that category’s average price (a flat number would distort things — a missing webcam price shouldn’t become $5):

category_avg = df.groupby("category")["unit_price"].transform("mean")
df["unit_price"] = df["unit_price"].fillna(category_avg).round(2)

groupby(...).transform("mean") computes each category’s average and aligns it to every row, so each gap is filled with its own category’s average. “Handle missing values” always means think about what the right value is.

Understanding the Calculated Column

Clean, properly-typed data lets you derive new information. Total price is just quantity × unit price — one line, now that both columns are real numbers:

df["total_price"] = (df["quantity"] * df["unit_price"]).round(2)

This is the payoff of cleaning. If unit_price were still text with dollar signs, this multiplication would fail outright.

Understanding the Status Log

A good tool tells the user what it did. We add a scrolling text box at the bottom and append a line for each action:

from tkinter import scrolledtext

# In build_ui:
self.status_log = scrolledtext.ScrolledText(self.root, height=6)

def log(self, message):
    self.status_log.insert(tk.END, message + "\n")
    self.status_log.see(tk.END)   # auto-scroll to the newest line

Each cleaning step calls self.log(...). The user gets a running history — “stripped whitespace,” “filled 3 missing quantities” — instead of changes happening invisibly.

Understanding Saving the Result

The “Save Clean CSV” button uses a save dialog and writes the DataFrame out:

def save_csv(self):
    if self.df is None:
        self.log("Nothing to save — load and clean a file first.")
        return

    path = filedialog.asksaveasfilename(
        defaultextension=".csv",
        filetypes=[("CSV files", "*.csv")]
    )
    if not path:
        return

    self.df.to_csv(path, index=False)
    self.log(f"Saved clean data to {path}")

asksaveasfilename lets the user choose where to save. index=False in to_csv is important — without it, pandas writes its internal row numbers as a junk extra column.

Practical Use Cases

1. Cleaning exported reports:

E-commerce, accounting, and CRM exports are notoriously messy — clean them on arrival.

2. A reusable cleaning tool:

Build it once, then clean any sales CSV by loading it into the app.

3. Visual data inspection:

Seeing the table before and after catches problems a script would hide.

4. Non-technical users:

A GUI means colleagues can clean data without touching code.

5. Foundation for Day 2:

Tomorrow's analyzer needs clean, typed data — this app produces exactly that.

Coming Tomorrow

Tomorrow we put the clean data to work. The Sales Analyzer takes orders_clean.csv and computes real business insights — revenue by category, best-selling products, daily trends, average order value — and generates a formatted summary report.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Code Skeleton

Get the code solution here:

View Code Solution

This week, we build an AI Travel Itinerary Planner that turns a destination into a beautiful, interactive map you can explore and share — perfect for trip planning!

• Day 1: Interactive Trip Map with Folium

• Day 2: AI Itinerary Generator with Gemini

• Day 3: Travel Planner Web App (Today)

View All Projects This Week

Today’s Project

Welcome to the finale! We have a map engine and an AI itinerary generator. Today we wrap both in a real web app. No more editing variables in a script — users open a page, type a destination, pick the trip length, list their interests, and click a button. The AI plans the trip and the interactive map renders right on the page, ready to download and share.

We’re using Streamlit, so the whole app is pure Python — no HTML, CSS, or JavaScript.

Project Task

Build a travel planner web app that:

• Provides a clean web interface (destination, days, interests inputs)

• Generates the itinerary with Gemini when the user clicks a button

• Renders the interactive Folium map directly in the page

• Shows the itinerary as a readable day-by-day breakdown

• Lets users download the map as a standalone HTML file

• Uses session state so the map persists across interactions

• Shows loading spinners and friendly error messages

• Reuses the Day 2 AI engine and the Day 1 map engine unchanged

This project gives you hands-on practice with Streamlit, web app layout, session state, embedding interactive components, file downloads, and turning a script into a shareable product — essential skills for building and publishing data apps.

Expected Output

Running the web app:

streamlit run travel_app.py

A browser opens automatically at http://localhost:8501 and the user can set the preferences for their trip:

After they click “Generate Trip” they see their itinerary in an interactive map:

Setup Instructions

Install Required Packages:

pip install streamlit streamlit-folium langchain langchain-google-genai folium

Add Your Google API Key:

Open travel_app.py and paste your key into the GOOGLE_API_KEY line near the top:

GOOGLE_API_KEY = "your-key-here"

(Get a free key at Google AI Studio.)

Run the app:

streamlit run travel_app.py

Your browser opens automatically. To stop the app, press Ctrl+C in the terminal.

Security note: For simplicity, this project keeps the API key as a plain string in the script. That’s fine for learning and personal use, but if you share your code or push it to GitHub, your key would be exposed. The safer approach is to store the key in a .env file and load it with the python-dotenv package, or — for a deployed Streamlit app — use Streamlit’s built-in secrets management. Both keep secrets out of your source code.

Understanding Streamlit

Streamlit turns a Python script into a web app. There’s no routing, no HTML templates, no frontend code — you call functions, and Streamlit renders widgets.

import streamlit as st

st.title("My App")                      # a heading
name = st.text_input("Your name")        # an input box
if st.button("Greet"):                   # a button
    st.write(f"Hello, {name}!")          # output text

The mental model that matters: Streamlit re-runs your entire script top to bottom every time the user interacts with anything. Click a button, move a slider, type in a box — the whole script runs again. That’s simple and predictable, but it has one big consequence we have to design around (see session state below).

Understanding the App Layout

We split the screen into a sidebar for inputs and a main area for the map. st.sidebar puts widgets on the left:

import streamlit as st

st.set_page_config(page_title="AI Travel Planner", page_icon="✈️", layout="wide")

st.title("✈️ AI Travel Itinerary Planner")
st.caption("Describe your trip and get an interactive map in seconds.")

# --- Sidebar inputs ---
with st.sidebar:
    st.header("Plan your trip")
    destination = st.text_input("Destination", value="Rome")
    days = st.slider("Trip length (days)", min_value=1, max_value=7, value=3)
    interests = st.text_area("Your interests", value="food, history, art")
    generate = st.button("Generate Trip", type="primary")

layout="wide" gives the map room to breathe. st.slider is a natural fit for trip length — bounded, no invalid input possible. type="primary" makes the button stand out.

Understanding the Download Button

A shareable map should be downloadable. Streamlit’s st.download_button lets users save a file — and Folium can render a map to an HTML string in memory with get_root().render():

def map_to_html(trip_map):
    """Render the Folium map to a standalone HTML string."""
    return trip_map.get_root().render()

st.download_button(
    label="📥 Download Map as HTML",
    data=map_to_html(st.session_state.trip_map),
    file_name="my_trip.html",
    mime="text/html",
)

No temp files, no disk writes — the HTML is generated in memory and streamed straight to the user’s browser as a download. The file they get is the same standalone map from Days 1 and 2.

Understanding the Itinerary Display

Below the map, we show the trip as readable text. We group stops by day and use an emoji per category for a friendly touch:

CATEGORY_EMOJI = {
    "food": "🍴",
    "sightseeing": "📷",
    "hotel": "🛏️",
    "activity": "⭐",
    "transport": "✈️",
}

def show_itinerary(itinerary):
    st.subheader("Your Itinerary")
    stops = itinerary_to_stops(itinerary)

    for day in get_days(stops):
        st.markdown(f"**Day {day}**")
        for stop in get_stops_for_day(stops, day):
            emoji = CATEGORY_EMOJI.get(stop["category"], "📍")
            st.markdown(f"{emoji} **{stop['name']}** — {stop['description']}")

st.markdown renders bold text and emoji cleanly. The same get_days and get_stops_for_day helpers from Day 1 organize the output — more reuse of code we already trust.

Understanding the Full Picture

Look at how the three days fit together:

• Day 1 built build_trip_map() — takes stop dicts, returns an interactive map.

• Day 2 built generate_itinerary() and itinerary_to_stops() — turns plain English into stop dicts via Gemini.

• Day 3 added only the web layer — Streamlit widgets, session state, st_folium, a download button.

The map engine and the AI engine were never rewritten. Day 3’s job was purely to wrap them in an interface. That’s the mark of well-structured code: each layer has one job, and new layers build on top without disturbing what’s below.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete AI-powered travel planning web app!

• Day 1: Interactive map engine with Folium

• Day 2: AI itinerary generation with Gemini + LangChain v1

• Day 3: A real web app that ties it together

You now have:

✅ Interactive maps — color-coded, route-drawn, popup-rich ✅ AI itinerary generation — plain English in, structured trip out ✅ A real web interface — no script editing required ✅ Downloadable, shareable maps — standalone HTML ✅ Clean architecture — layered engine, AI, and UI

Real-world applications:

• Personal trip planning — your own travel tool

• Travel blogs — let readers generate and explore routes

• Travel agencies — rapid first-draft itineraries for clients

• Portfolio project — AI + maps + web app in one

• A product starting point — add accounts, saved trips, bookings

Next steps:

• Deploy it free on Streamlit Community Cloud so anyone can use it

• Let users edit or reorder stops before downloading

• Add hotel and restaurant suggestions with booking links

• Support multi-city trips

• Add trip cost estimates

You’ve built the foundation for a real travel-tech product! 🚀

View Code Evolution

Compare today’s web app with the Day 2 generator and the Day 1 map engine — and see how a clean, layered design lets you add a whole new interface without touching the code beneath it.

Read more

This week, we build an AI Travel Itinerary Planner that turns a destination into a beautiful, interactive map you can explore and share — perfect for trip planning!

• Day 1: Interactive Trip Map with Folium

• Day 2: AI Itinerary Generator with Gemini (Today)

• Day 3: Travel Planner Web App

View All Projects This Week

Today’s Project

Yesterday we built the map engine and hand-fed it a Lisbon itinerary. Today the AI writes the itinerary for us. You describe a trip in plain English — “4 days in Rome, I love food and ancient history” — and Gemini, through LangChain v1, returns a fully structured itinerary with coordinates baked in. That output drops straight into yesterday’s map code, unchanged.

This is the payoff of Day 1’s design: because we built a stable data shape first, the AI just has to fill it.

Project Task

Build an AI itinerary generator that:

• Takes a plain-English trip request (destination, days, interests)

• Uses LangChain v1 + Gemini to generate a structured itinerary

• Returns each stop with name, day, lat, lon, category, and description

• Uses Pydantic models so the AI output is validated and type-safe

• Uses with_structured_output() — no manual JSON parsing

• Feeds the AI itinerary into the Day 1 Folium map engine

• Handles API errors and missing keys gracefully

• Saves the finished map as a shareable HTML file

This project gives you hands-on practice with LangChain v1, the Gemini API, structured AI output, Pydantic schema validation, and connecting an AI layer to a visualization layer — essential skills for AI-powered applications.

Expected Output

Running the AI generator:

python ai_trip_map.py

Console Output:
The user can define their trip preferences in the terminal and the program will print out an itinerary:

After that runs an HTML file will be created which can be opened in the browser. It will contain the itinerary with interactive map pins:

Setup Instructions

Install Required Packages:

pip install langchain langchain-google-genai folium

Get Your Google API Key:

1. Go to Google AI Studio

2. Click “Create API Key” and copy it

3. Assign the key to the GOOGLE_API_KEY variable as a string in the code.

Run it:

python ai_trip_map.py

Understanding Structured Output

The hardest part of using an LLM in real code is that it returns text. Free-form text is unreliable — you’d be writing fragile parsers and praying the model uses the right quote style.

LangChain’s with_structured_output() solves this. You define the shape you want as a Pydantic model, and the AI is constrained to return exactly that shape — already parsed into Python objects:

from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI

class Person(BaseModel):
    name: str
    age: int

llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash")
structured_llm = llm.with_structured_output(Person)

result = structured_llm.invoke("Tell me about a person named Alice, age 30")
# result is a Person object: Person(name='Alice', age=30)

No JSON parsing. No string cleanup. You get a typed object, and if the AI returns something malformed, Pydantic raises a clear error instead of silently corrupting your data.

Understanding the Pydantic Schema

We need the AI to return the exact data shape our Day 1 map expects. So we describe it as Pydantic models — one for a single stop, one for the whole itinerary:

from pydantic import BaseModel, Field

class Stop(BaseModel):
    """A single stop on the trip."""
    name: str = Field(description="Name of the place")
    day: int = Field(description="Which day of the trip this stop is on")
    lat: float = Field(description="Latitude coordinate")
    lon: float = Field(description="Longitude coordinate")
    category: str = Field(description="One of: food, sightseeing, hotel, activity, transport")
    description: str = Field(description="One-sentence description of the stop")

class Itinerary(BaseModel):
    """A complete multi-day travel itinerary."""
    trip_title: str = Field(description="A short title for the trip")
    stops: list[Stop] = Field(description="All stops across all days, in visiting order")

Why the Field(description=...) matters: those descriptions aren’t just documentation. LangChain sends them to the model as part of the schema. They’re how you tell the AI “category must be one of these five values” or “give me one sentence, not a paragraph.” Good field descriptions are effectively prompt engineering.

Understanding the LangChain v1 + Gemini Setup

LangChain v1 keeps the model setup clean. You create the chat model, then attach the schema:

import os
from langchain_google_genai import ChatGoogleGenerativeAI

def build_ai():
    llm = ChatGoogleGenerativeAI(
        model="gemini-2.5-flash",
        google_api_key=os.getenv("GOOGLE_API_KEY"),
        temperature=0.7,  # a little creativity for varied suggestions
    )
    # Constrain every response to the Itinerary schema
    return llm.with_structured_output(Itinerary)

temperature=0.7 is a deliberate choice: trip planning benefits from variety, so we don’t want the near-deterministic 0 you’d use for data extraction. The structured-output constraint still guarantees the shape — temperature only affects the content.

Understanding the Prompt

Even with structured output, the prompt still matters — it’s where you give the AI its instructions and quality bar:

def build_prompt(destination, days, interests):
    return f"""You are an expert travel planner.

Create a {days}-day travel itinerary for {destination}.
The traveler is interested in: {interests}.

Requirements:
- Plan exactly 3 stops per day.
- Spread stops geographically so each day is walkable where possible.
- Include a mix of categories, with at least one food stop per day.
- Use real, well-known places with accurate latitude and longitude.
- Keep each description to a single vivid sentence.
- Order stops within each day in a sensible visiting sequence.
"""

Notice we ask for accurate latitude and longitude directly. Gemini knows the coordinates of famous landmarks well, so for a travel planner this is reliable enough — and it keeps the project to a single API call with no separate geocoding service.

Understanding the AI-to-Map Handoff

Here’s where Day 1’s design pays off. The AI returns an Itinerary object full of Stop objects. Our map engine expects a list of plain dicts. One small conversion bridges them:

def itinerary_to_stops(itinerary):
    """Convert the AI's Pydantic Itinerary into the dict list the map expects."""
    return [
        {
            "name": stop.name,
            "day": stop.day,
            "lat": stop.lat,
            "lon": stop.lon,
            "category": stop.category,
            "description": stop.description,
        }
        for stop in itinerary.stops
    ]

After this, every map function from Day 1 works untouched — build_trip_map, add_day_to_map, fit_map_to_stops, all of it. The AI is just a new data source plugged into a finished engine.

Understanding Error Handling

AI calls fail in ways normal code doesn’t — missing keys, rate limits, network drops. A travel app shouldn’t crash on any of them:

def generate_itinerary(ai, destination, days, interests):
    if not os.getenv("GOOGLE_API_KEY"):
        print("✗ No GOOGLE_API_KEY found. Set it as an environment variable.")
        return None

    prompt = build_prompt(destination, days, interests)

    try:
        return ai.invoke(prompt)
    except Exception as e:
        print(f"✗ Itinerary generation failed: {e}")
        return None

The check for the missing key happens before the call — a fast, friendly failure. The try/except catches everything else and reports it instead of dumping a stack trace.

Understanding Why Pydantic Validation Helps

Read more

This week, we build an AI Travel Itinerary Planner that turns a destination into a beautiful, interactive map you can explore and share — perfect for trip planning!

Why build this? Because planning a trip means juggling places, routes, and notes across a dozen browser tabs. You’ll build a tool that puts everything on one interactive map — and by Day 3, an AI generates the whole itinerary for you.

What you’ll learn: Interactive map creation, geographic data visualization, AI-powered content generation, and building shareable web apps — essential skills for location-based applications.

Why users love this: Type a city, get a gorgeous map with every stop pinned, routes drawn, and tips in every popup. It feels like a real travel product.

• Day 1: Interactive Trip Map with Folium (Today)

• Day 2: AI Itinerary Generator with Gemini

• Day 3: Travel Planner Web App

View All Projects This Week

Today’s Project

We’re starting with the map engine — the visual heart of the whole project. No AI yet. Today you master Folium: take a structured trip itinerary and turn it into a rich, interactive HTML map with color-coded day markers, drawn routes, detailed popups, and professional touches like a minimap and fullscreen mode.

By the end, you’ll have a real interactive map you can open in any browser and share. On Day 2, the AI will generate the data you’re hand-feeding it today.

Project Task

Build an interactive trip map generator that:

• Takes a structured multi-day itinerary (list of stops with name, day, coordinates, description, category)

• Plots every stop as a marker on a Folium map

• Color-codes markers by day (Day 1 = blue, Day 2 = green, etc.)

• Uses category-based icons (food, sightseeing, hotel, activity)

• Draws a route line connecting stops in order, per day

• Rich HTML popups with stop name, description, and category

• Auto-centers and auto-zooms to fit all stops

• Adds a minimap, fullscreen button, and layer control

• Saves the result as a standalone, shareable HTML file

This project gives you hands-on practice with Folium, interactive maps, geographic visualization, HTML generation, and structured data handling — essential skills for location-based applications.

Expected Output

Running the map generator:

python trip_map.py

Running the script will generate an HTML file which can be opened in the browser:

Setup Instructions

Install Required Package:

pip install folium

That’s it — one dependency. Folium generates the map as HTML; no server needed.

Run it:

python trip_map.py

Then open trip_map.html in any browser.

Understanding the Itinerary Data Structure

Before drawing anything, we need a clean data structure. Each stop is a dictionary, and the trip is a list of them:

itinerary = [
    {
        "name": "Time Out Market",
        "day": 1,
        "lat": 38.7067,
        "lon": -9.1459,
        "category": "food",
        "description": "Historic food hall with dozens of local vendors."
    },
    {
        "name": "São Jorge Castle",
        "day": 1,
        "lat": 38.7139,
        "lon": -9.1335,
        "category": "sightseeing",
        "description": "Moorish castle with panoramic views over the city."
    },
    # ... more stops
]

Why this structure?

It is flat, predictable, and easy to generate. On Day 2, Gemini will return exactly this shape as JSON — so the map code you write today works unchanged when the AI takes over. That is the whole point of starting with the map: you build a stable target, then plug the AI into it.

Understanding Folium Basics

Folium is a Python wrapper around Leaflet.js. You build a map in Python, and it writes the HTML/JavaScript for you.

import folium

# Create a map centered on a location
m = folium.Map(location=[38.7223, -9.1393], zoom_start=13)

# Add a marker
folium.Marker(
    location=[38.7067, -9.1459],
    popup="Time Out Market",
    tooltip="Click for details"
).add_to(m)

# Save to HTML
m.save("map.html")

Three core ideas:

• The map object (folium.Map) is the canvas — everything gets added to it.

• Elements (markers, lines, layers) are created, then attached with .add_to(m).

• .save() writes a complete, standalone HTML file — no server, no dependencies for the viewer.

Understanding Color-Coded Day Markers

To make a multi-day trip readable, each day gets its own color. Folium markers accept an Icon with a color and an icon glyph:

DAY_COLORS = ["blue", "green", "purple", "orange", "red", "darkblue"]

def get_day_color(day_number):
    # Day 1 -> index 0, wraps around for long trips
    return DAY_COLORS[(day_number - 1) % len(DAY_COLORS)]

folium.Marker(
    location=[stop["lat"], stop["lon"]],
    icon=folium.Icon(color=get_day_color(stop["day"]), icon="cutlery", prefix="fa")
).add_to(m)

Why prefix="fa"? It tells Folium to use Font Awesome icons, which gives you a much larger glyph library (cutlery, camera, bed, etc.) than the default set.

Understanding Category Icons

Color tells you which day. The icon glyph tells you what kind of stop it is. A simple dictionary maps categories to Font Awesome icons:

CATEGORY_ICONS = {
    "food": "cutlery",
    "sightseeing": "camera",
    "hotel": "bed",
    "activity": "star",
    "transport": "plane",
}

def get_category_icon(category):
    # Fallback to a generic marker if the category is unknown
    return CATEGORY_ICONS.get(category, "info-sign")

Now a blue cutlery marker reads instantly as “Day 1 food stop.” This visual encoding is what separates a real map from a pile of identical pins.

Understanding Rich HTML Popups

A popup can be plain text — or it can be styled HTML. Folium accepts an HTML string, so you can build a proper info card:

def build_popup_html(stop):
    return f"""
    <div style="width: 220px; font-family: sans-serif;">
        <h4 style="margin: 0 0 6px 0;">{stop['name']}</h4>
        <hr style="margin: 4px 0;">
        <p style="margin: 4px 0;"><b>{stop['category'].title()}</b> · Day {stop['day']}</p>
        <p style="margin: 4px 0; color: #444;">{stop['description']}</p>
    </div>
    """

popup = folium.Popup(build_popup_html(stop), max_width=250)
folium.Marker(location=[stop["lat"], stop["lon"]], popup=popup).add_to(m)

Key detail: wrap the HTML in folium.Popup(..., max_width=250). Without max_width, long descriptions render as one ugly unwrapped line. The <div> with a fixed width keeps every popup tidy.

Understanding Route Lines with PolyLine

To connect the stops of a day in order, use folium.PolyLine — it draws a line through a list of coordinates:

def draw_day_route(day_stops, color, map_obj):
    # day_stops must already be in visiting order
    coordinates = [[stop["lat"], stop["lon"]] for stop in day_stops]

    folium.PolyLine(
        locations=coordinates,
        color=color,
        weight=4,
        opacity=0.7,
        dash_array="8"  # dashed line looks like a travel route
    ).add_to(map_obj)

We draw one PolyLine per day, using that day’s color. The result: three colored, dashed routes that show the flow of each day, not one tangled line across the whole trip.

Understanding Auto-Centering and Auto-Zoom

Hardcoding location and zoom_start breaks the moment the trip changes. Instead, let the data decide the view with fit_bounds:

def fit_map_to_stops(map_obj, itinerary):
    lats = [stop["lat"] for stop in itinerary]
    lons = [stop["lon"] for stop in itinerary]

    # Bounding box: [[south, west], [north, east]]
    south_west = [min(lats), min(lons)]
    north_east = [max(lats), max(lons)]

    map_obj.fit_bounds([south_west, north_east])

fit_bounds computes the zoom and center so every stop is visible with a little padding. Now the map works for a walkable city or a sprawling road trip without any manual tuning — which matters on Day 2, when the AI generates unpredictable destinations.

Understanding LayerControl and FeatureGroups

To toggle days on and off, each day goes into its own FeatureGroup. A LayerControl then renders the checkboxes:

day_group = folium.FeatureGroup(name="Day 1 — Historic Center")

# add that day's markers and route to the group instead of the map
marker.add_to(day_group)

day_group.add_to(map_obj)

# add this LAST, after all groups exist
folium.LayerControl(collapsed=False).add_to(map_obj)

Order matters: add LayerControl after every FeatureGroup, or some layers won’t appear in the control.

Understanding Map Plugins

Folium ships plugins that add real polish in one line each:

from folium.plugins import MiniMap, Fullscreen

# Small overview map in the corner
MiniMap(toggle_display=True).add_to(m)

# Fullscreen button
Fullscreen().add_to(m)

The MiniMap helps users keep their bearings when zoomed in; Fullscreen makes the shared HTML feel like a proper app. Small additions, big difference in perceived quality.

Practical Use Cases

1. Personal trip planning:

Hand-build your itinerary, get one map with every stop, route, and note.

2. Sharing plans with travel companions:

Send the HTML file — they open it, no install, fully interactive.

3. Travel blogs and guides:

Embed the map in a post so readers can explore the route themselves.

4. Tour and event planning:

Color-code by day or group, drop notes in popups, share one link.

5. Foundation for Day 2:

The exact data shape Gemini will return — the map is ready before the AI exists.

Coming Tomorrow

Tomorrow we add the AI. Instead of hand-writing the itinerary, you’ll describe a trip in plain English (”3 days in Lisbon, I love food and history”) and Gemini — via LangChain v1 — generates the full structured itinerary, coordinates included, ready to drop straight into today’s map engine.

Skeleton and Solution

Below you will find both a downloadable skeleton.py file to help you code the project with comment guides and the downloadable solution.py file containing the correct solution.

Get the code skeleton here:

View Code Skeleton

Get the code solution here:

View Code Solution

This week, we build a Workout Tracker Suite that helps you log lifts, visualize progress, and optimize your training — perfect for anyone serious about strength training!

• Day 1: Barbell Plate Calculator (Tkinter GUI)

• Day 2: Workout Logger with Live Charts

• Day 3: Complete Workout Dashboard (Today)

View All Projects This Week

Today’s Project

Welcome to the finale! We’ve built a plate calculator and workout logger. Today we’re creating a complete training dashboard with templates, 1RM calculator, strength standards, and session timers!

You’ll have a professional-grade workout tracking system that rivals commercial fitness apps!

Project Task

Create a complete workout dashboard with:

• Workout templates (Push/Pull/Legs, Upper/Lower, Full Body)

• 1RM (one-rep max) calculator with multiple formulas

• Strength standards comparison (beginner/intermediate/advanced)

• Session timer with rest period alerts

• Progressive overload recommendations

• Volume tracking with periodization suggestions

• Export workout reports as text files

• Enhanced charts with volume and intensity trends

• All Day 1 & 2 features integrated

This project gives you hands-on practice with advanced GUI design, mathematical formulas, timer functionality, template systems, data analysis, and building production-ready fitness applications — essential skills for complete software solutions!

Expected Output

We have gone one step further in this version of the GUI and added tabs. This is a major milestone because it demonstrates one of the most popular techniques to organize a GUI when we are adding more features in the app. With tabs we can organize the various functionalities of the apps as you can see below:

For example, we have now moved the weight progress to a new “Analytics” tab:

And we have also added other tabs as it can be seen in the screenshots.

Setup Instructions

Install Required Packages:

pip install matplotlib pandas

Run the dashboard:

python workout_dashboard.py

All features ready to use:

• No additional setup needed

• Data persists in CSV files

• Templates saved as JSON

• Reports export as TXT files

Understanding 1RM Calculations

What is 1RM?

Your one-rep max - the maximum weight you can lift for exactly one rep.

Why calculate it?

• Design training programs (% of 1RM)

• Track true strength gains

• Compare against standards

• Set realistic goals

Common formulas:

1. Epley Formula:

1RM = weight × (1 + reps/30)

# Example: 225 lbs × 8 reps
1RM = 225 × (1 + 8/30)
1RM = 225 × 1.267
1RM = 285 lbs

2. Brzycki Formula:

1RM = weight × (36 / (37 - reps))

# Example: 225 lbs × 8 reps
1RM = 225 × (36 / (37 - 8))
1RM = 225 × (36 / 29)
1RM = 279 lbs

3. Lander Formula:

1RM = (100 × weight) / (101.3 - 2.67123 × reps)

# Example: 225 lbs × 8 reps
1RM = (100 × 225) / (101.3 - 2.67123 × 8)
1RM = 22500 / 79.93
1RM = 281 lbs

Our implementation:

def calculate_1rm(weight, reps):
    # Epley
    epley = weight * (1 + reps/30)
    
    # Brzycki
    brzycki = weight * (36 / (37 - reps))
    
    # Lander
    lander = (100 * weight) / (101.3 - 2.67123 * reps)
    
    # Lombardi
    lombardi = weight * (reps ** 0.10)
    
    # Average
    average = (epley + brzycki + lander + lombardi) / 4
    
    return {
        'epley': round(epley, 1),
        'brzycki': round(brzycki, 1),
        'lander': round(lander, 1),
        'lombardi': round(lombardi, 1),
        'average': round(average, 1)
    }

Understanding Strength Standards

What are strength standards?

Benchmarks for comparing your lifts to typical progression levels.

Standard categories:

STRENGTH_STANDARDS = {
    'Bench Press': {
        'Beginner': 0.75,      # 0.75× bodyweight
        'Novice': 1.0,         # 1.0× bodyweight
        'Intermediate': 1.25,  # 1.25× bodyweight
        'Advanced': 1.5,       # 1.5× bodyweight
        'Elite': 1.75,         # 1.75× bodyweight
    },
    'Squat': {
        'Beginner': 1.0,
        'Novice': 1.5,
        'Intermediate': 2.0,
        'Advanced': 2.5,
        'Elite': 3.0,
    },
    'Deadlift': {
        'Beginner': 1.25,
        'Novice': 1.75,
        'Intermediate': 2.25,
        'Advanced': 2.75,
        'Elite': 3.25,
    }
}

Understanding Workout Templates

What are templates?

Pre-designed workout programs with exercises, sets, reps, and rest times.

Common splits:

Push/Pull/Legs (PPL):

TEMPLATES = {
    'Push': [
        {'exercise': 'Bench Press', 'sets': 4, 'reps': 8, 'rest': 180},
        {'exercise': 'Overhead Press', 'sets': 3, 'reps': 10, 'rest': 120},
        {'exercise': 'Incline DB Press', 'sets': 3, 'reps': 12, 'rest': 90},
        {'exercise': 'Lateral Raises', 'sets': 3, 'reps': 15, 'rest': 60},
        {'exercise': 'Tricep Extensions', 'sets': 3, 'reps': 12, 'rest': 60},
    ],
    'Pull': [
        {'exercise': 'Deadlift', 'sets': 3, 'reps': 5, 'rest': 180},
        {'exercise': 'Pull-ups', 'sets': 3, 'reps': 10, 'rest': 120},
        {'exercise': 'Barbell Row', 'sets': 4, 'reps': 8, 'rest': 120},
        {'exercise': 'Face Pulls', 'sets': 3, 'reps': 15, 'rest': 60},
        {'exercise': 'Bicep Curls', 'sets': 3, 'reps': 12, 'rest': 60},
    ],
    'Legs': [
        {'exercise': 'Squat', 'sets': 4, 'reps': 6, 'rest': 180},
        {'exercise': 'Romanian Deadlift', 'sets': 3, 'reps': 10, 'rest': 120},
        {'exercise': 'Leg Press', 'sets': 3, 'reps': 12, 'rest': 90},
        {'exercise': 'Leg Curls', 'sets': 3, 'reps': 15, 'rest': 60},
        {'exercise': 'Calf Raises', 'sets': 4, 'reps': 20, 'rest': 60},
    ]
}

Loading a template:

def load_template(template_name):
    exercises = TEMPLATES[template_name]
    
    print(f"\n{template_name.upper()} DAY:")
    for i, ex in enumerate(exercises, 1):
        print(f"{i}. {ex['exercise']}")
        print(f"   {ex['sets']}×{ex['reps']}")
        print(f"   Rest: {ex['rest']}s")

We also have other features such as the timer which the user can use to time your workout sessions.

What You’ve Accomplished This Week

🎉 Congratulations! You’ve built a complete workout tracking system!

• Day 1: Visual plate calculator

• Day 2: Workout logger with charts

• Day 3: Complete training dashboard

You now have:

✅ Plate calculator - Visual barbell loading
✅ Workout logging - Track all exercises
✅ Progress charts - See gains visualized
✅ 1RM calculator - Multiple formulas
✅ Strength standards - Compare your lifts
✅ Workout templates - Pre-built programs
✅ Session timers - Track workout & rest
✅ Analytics - Volume & intensity trends
✅ Export reports - Share your progress
✅ Professional GUI - Tabbed interface

Next steps:

• Add exercise video library

• Integrate with fitness trackers

• Build mobile version

• Add nutrition tracking

• Social features (share workouts)

• Online coaching integration

You’ve built the foundation for a complete fitness platform! 🚀

View Code Evolution

Compare today’s complete dashboard with earlier versions and see the full progression from simple calculator → logger → complete system!

Read more

This week, we build a Workout Tracker Suite that helps you log lifts, visualize progress, and optimize your training — perfect for anyone serious about strength training!

• Day 1: Barbell Plate Calculator (Tkinter GUI)

• Day 2: Workout Logger with Live Charts (Today)

• Day 3: Complete Workout Dashboard

View All Projects This Week

Today’s Project

Yesterday we built a plate calculator. Today we’re adding workout logging with live progress charts! Log your sets, track your PRs, and see your strength gains visualized in real-time!

You’ll enhance the app into a complete training tracker with embedded matplotlib charts!

Project Task

Enhance the plate calculator with workout logging:

• Log exercises with sets, reps, weight, and RPE

• Save workouts to CSV with timestamps

• Live progress chart showing weight over time

• Personal records (PR) tracker

• Exercise history viewer

• Volume calculations (sets × reps × weight)

• Filter by exercise and date range

• Embedded matplotlib charts in Tkinter

• All Day 1 features still work

This project gives you hands-on practice with CSV data storage, pandas data analysis, matplotlib integration in Tkinter, data visualization, progressive overload tracking, and building data-driven fitness tools — essential skills for analytics applications!

Expected Output

Running the enhanced workout logger:

python workout_logger.py

Log a workout:

In this version the user can log in a workout such as bench press, squat, etc. These can be chosen from the drop down list:

After some days, you will see a weight progress at the bottom part of the GUI showing how your weights have changed over time:

CSV file generated:

Every time you log in a workout, the data are saved in a local workouts.csv file. For the example demonstrated above, here is how the file looks like:

date,time,exercise,sets,reps,weight,rpe,volume
2026-05-13,14:30:00,Bench Press,3,8,225,8,5400
2026-05-13,14:45:00,Squat,4,6,315,9,7560
2026-05-13,15:00:00,Deadlift,3,5,405,9,6075
2026-05-10,15:15:00,Bench Press,4,6,215,7,5160
2026-05-10,15:30:00,Squat,3,8,295,8,7080

Setup Instructions

Install Required Package:

pip install matplotlib pandas

Run the logger:

python workout_logger.py

Data storage:

• Workouts saved to workouts.csv automatically

• PRs tracked automatically

• Charts update in real-time

Understanding CSV Workout Storage

Why CSV for workouts?

Read more