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

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!

Why build this? Because tracking workouts manually is tedious, and most apps are overcomplicated. You’ll create tools that solve real problems: calculating plates, logging progress, and seeing gains visualized!

What you’ll learn: This series teaches you GUI development, data visualization, mathematical calculations, user interface design, and building practical fitness tools — essential skills for desktop applications!

Why users love this: A plate calculator that shows exactly what your barbell looks like? Instant dopamine! By Day 3, you’ll have a complete training dashboard that tracks every lift and shows your progress charts in real-time!

• Day 1: Barbell Plate Calculator (Tkinter GUI) (Today)

• Day 2: Workout Logger with Live Charts

• Day 3: Complete Workout Dashboard

View All Projects This Week

Today’s Project

We’re starting with something immediately satisfying: a visual plate calculator that shows you exactly how to load your barbell! No more mental math at the gym!

You’ll build a beautiful GUI that calculates the optimal plate combination and displays your loaded barbell visually!

Project Task

Create a barbell plate calculator with:

• Target weight input (kg or lbs)

• Visual barbell display showing loaded plates

• Optimal plate combination calculator

• Common lift presets (45/135, 60/185, 100/225, etc.)

• Support for standard plate sets (45, 35, 25, 10, 5, 2.5)

• Bar weight selection (20kg/45lbs standard, women’s bar, specialty bars)

• Save favorite lifts

• Clean, intuitive Tkinter interface

• Color-coded plates by weight

• Real-time updates as you type

This project gives you hands-on practice with Tkinter GUI, canvas drawing, mathematical optimization, event handling, and building visual tools — essential skills for desktop applications!

Expected Output

The app runs on the desktop. It lets the user to set the target weight. Based on that, the visual is instantly updated with the correct number of plates and their weights for the target weight:

The user can also press the “Save Current” button to save a configuration and load it later.

Setup Instructions

No installations needed!

Uses Python standard library only (Tkinter is built-in):

python plate_calculator.py

Understanding Plate Calculation Algorithm

The Challenge:

Given a target weight, find the minimum number of plates to load on each side.

Standard plate sets:

Pounds (lbs):

• 45 lbs (red) - biggest

• 35 lbs (yellow)

• 25 lbs (green)

• 10 lbs (white)

• 5 lbs (blue)

• 2.5 lbs (small red)

Kilograms (kg):

• 25 kg (red)

• 20 kg (blue)

• 15 kg (yellow)

• 10 kg (green)

• 5 kg (white)

• 2.5 kg (small red)

• 1.25 kg (small blue)

Algorithm (Greedy approach):

def calculate_plates(target_weight, bar_weight, plates):
    # Weight needed on plates (both sides)
    plates_weight = target_weight - bar_weight
    
    # Weight per side
    weight_per_side = plates_weight / 2
    
    # Greedy algorithm: largest plates first
    plates_needed = []
    remaining = weight_per_side
    
    for plate in sorted(plates, reverse=True):
        count = int(remaining / plate)
        if count > 0:
            plates_needed.append((plate, count))
            remaining -= plate * count
    
    return plates_needed

# Example
target = 225  # lbs
bar = 45      # lbs
plates = [45, 35, 25, 10, 5, 2.5]

result = calculate_plates(target, bar, plates)
# [(45, 1), (25, 1), (10, 1), (5, 1)]
# = 1×45 + 1×25 + 1×10 + 1×5 = 85 lbs per side
# = 85 × 2 + 45 bar = 215 lbs... wait, that's not 225!

Problem: Rounding!

225 - 45 = 180 lbs plates / 2 = 90 lbs per side

But 1×45 + 1×25 + 1×10 + 1×5 = 85 lbs per side (10 lbs short!)

Solution: Round to nearest 5 lbs (smallest plate × 2)

def calculate_plates(target, bar, plates):
    # Round to nearest achievable weight
    smallest_increment = min(plates) * 2  # 2.5 × 2 = 5 lbs
    target = round(target / smallest_increment) * smallest_increment
    
    weight_per_side = (target - bar) / 2
    
    # ... rest of algorithm

Understanding Tkinter Canvas Drawing

Why Canvas?

Tkinter Canvas lets us draw custom graphics:

import tkinter as tk

root = tk.Tk()
canvas = tk.Canvas(root, width=800, height=200, bg='white')
canvas.pack()

# Draw rectangle (plate)
canvas.create_rectangle(100, 50, 150, 150, fill='red', outline='black')

# Draw circle
canvas.create_oval(300, 75, 350, 125, fill='blue')

# Draw line (barbell)
canvas.create_line(50, 100, 750, 100, fill='gray', width=10)

# Draw text
canvas.create_text(400, 50, text="225 lbs", font=('Arial', 16, 'bold'))

root.mainloop()

Our barbell drawing:

def draw_barbell(canvas, plates_per_side):
    canvas.delete('all')  # Clear previous
    
    # Bar dimensions
    bar_length = 600
    bar_x_start = 100
    bar_y = 100
    
    # Draw bar
    canvas.create_line(
        bar_x_start, bar_y,
        bar_x_start + bar_length, bar_y,
        fill='gray', width=15
    )
    
    # Draw plates on left side
    x_offset = bar_x_start - 10
    for plate_weight, count in plates_per_side:
        for _ in range(count):
            color = get_plate_color(plate_weight)
            width = get_plate_width(plate_weight)
            height = get_plate_height(plate_weight)
            
            # Draw plate
            canvas.create_rectangle(
                x_offset - width, bar_y - height/2,
                x_offset, bar_y + height/2,
                fill=color, outline='black', width=2
            )
            
            # Label
            canvas.create_text(
                x_offset - width/2, bar_y - height/2 - 15,
                text=str(plate_weight), font=('Arial', 10, 'bold')
            )
            
            x_offset -= width + 5
    
    # Mirror for right side
    # ...

Understanding Saved Lifts

Persistence with JSON:

import json
from pathlib import Path

SAVED_LIFTS_FILE = 'saved_lifts.json'

def save_lift(name, weight, unit):
    # Load existing
    if Path(SAVED_LIFTS_FILE).exists():
        with open(SAVED_LIFTS_FILE, 'r') as f:
            lifts = json.load(f)
    else:
        lifts = {}
    
    # Add new
    lifts[name] = {'weight': weight, 'unit': unit}
    
    # Save
    with open(SAVED_LIFTS_FILE, 'w') as f:
        json.dump(lifts, f, indent=2)

def load_lifts():
    if Path(SAVED_LIFTS_FILE).exists():
        with open(SAVED_LIFTS_FILE, 'r') as f:
            return json.load(f)
    return {}

# Usage
save_lift('Squat', 315, 'lbs')
save_lift('Bench', 225, 'lbs')

lifts = load_lifts()
# {'Squat': {'weight': 315, 'unit': 'lbs'}, ...}

Practical Use Cases

1. Pre-planning workouts:

Before gym: Check what plates you need
At gym: Load bar exactly right, no confusion

2. Progressive overload:

Current: 225 lbs
Next week: 230 lbs
Calculator: Shows you need 2.5 lb plates!

3. Home gym setup:

See which plates you use most
Buy optimal plate set
Avoid buying unnecessary weights

4. Teaching form:

Show beginners what "135" looks like
Visual reference for proper loading
Safety check before lifting

5. Multiple lifters:

Save each person's working weights
Quick load for different people
No mental math during workout

Coming Tomorrow

Tomorrow we’re adding workout logging with live progress charts! Log your sets/reps/weight and see your strength gains visualized in real-time. The plate calculator becomes part of a complete training tool!

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-Powered Daily Journal that writes markdown entries, analyzes your mood with AI, and visualizes your emotional patterns over time!

• Day 1: Markdown Journal Writer

• Day 2: AI Mood & Theme Analyzer

• Day 3: Insights Dashboard (Today)

View All Projects This Week

Today’s Project

Welcome to the finale! We’ve built a journal with AI analysis. Today we’re creating a beautiful Streamlit dashboard with mood charts, word clouds, and AI-generated monthly summaries!

You’ll visualize your emotional journey and discover patterns you never noticed!

Project Task

Create a Streamlit insights dashboard with:

• Mood-over-time line chart (interactive with Plotly)

• Word cloud from all journal entries

• Monthly summary cards (AI-generated)

• Theme frequency chart

• Entry statistics and streaks

• Filter by date range

• Export insights as PDF

• Beautiful, intuitive interface

This project gives you hands-on practice with Streamlit, data visualization, Plotly charts, word clouds, dashboard design, and building data-driven applications — essential skills for analytics and insight tools!

Expected Output

Running the dashboard:

streamlit run dashboard.py

Browser opens with dashboard showing your mood in a graph:

Scrolling down the webpage you will find the score for the average mood, a word cloud showing the most used words in your journal, and the top themes you have written about:

Setup Instructions

Install Required Packages:

pip install streamlit plotly wordcloud langchain-google-genai

Set Google API Key:

export GOOGLE_API_KEY="your-key-here"

Run the dashboard:

streamlit run dashboard.py

Browser automatically opens to

http://localhost:8501

Make sure you have some jornal entries in the same directory with the dashboard.py file. Here are some sample files you can use:

Download Data

Understanding Streamlit Layout

Dashboard structure:

Read more

This week, we build an AI-Powered Daily Journal that writes markdown entries, analyzes your mood with AI, and visualizes your emotional patterns over time!

• Day 1: Markdown Journal Writer

• Day 2: AI Mood & Theme Analyzer (Today)

• Day 3: Insights Dashboard

View All Projects This Week

Today’s Project

Yesterday we built a markdown journal. Today we’re adding AI-powered analysis — Gemini reads each entry, scores your mood from -1 (negative) to +1 (positive), and extracts 3-5 recurring themes!

All analysis is cached as JSON metadata, so re-running is instant and free!

Project Task

Enhance the journal with AI analysis that:

• New review command analyzes entries

• Uses Gemini to score mood (-1 to 1 scale)

• Extracts 3-5 recurring themes per entry

• Caches analysis as JSON metadata files

• Re-runs are instant (reads from cache)

• Shows mood trends over time

• Lists most common themes across all entries

• Clean output with mood emoji indicators

• All Day 1 features still work

This project gives you hands-on practice with AI analysis, sentiment analysis, theme extraction, JSON caching, metadata management, and building intelligent tools — essential skills for AI-powered applications!

Expected Output

Analyzing entries for the first time:

python journal.py review

Console Output:

Setup Instructions

Install Required Package:

pip install langchain-google-genai

Get Your Google API Key:

1. Go to Google AI Studio

2. Click “Create API Key”

3. Copy your key

4. Set environment variable:

# Mac/Linux
export GOOGLE_API_KEY="your-key-here"

# Windows (PowerShell)
$env:GOOGLE_API_KEY="your-key-here"

Or edit the script:

This is a simpler method to provide the API key, but less secure.

GOOGLE_API_KEY = "your-key-here"  # Paste your key

Run analysis:

python journal.py review

Understanding AI Mood Analysis

What is mood scoring?

The AI reads your entry and assigns a score from -1 to 1:

 1.0  Very positive   😄  Joyful, excited, grateful, accomplished
 0.5  Positive        🙂  Happy, content, optimistic
 0.0  Neutral         😐  Balanced, matter-of-fact
-0.5  Negative        😔  Sad, frustrated, disappointed
-1.0  Very negative   😢  Devastated, hopeless, extremely upset

How it works:

Read more

This week, we build an AI-Powered Daily Journal that writes markdown entries, analyzes your mood with AI, and visualizes your emotional patterns over time!

Why build this? Because journaling is powerful for mental clarity and self-reflection. You’ll create a tool that not only stores your thoughts but also uses AI to understand them and show you patterns you might miss!

What you’ll learn: This series teaches you file-based data storage, markdown formatting, CLI tool development, AI sentiment analysis, data visualization, and building applications that provide real insights — essential skills for personal productivity tools!

Why users love this: A journal that understands you! By Day 3, you’ll have mood charts, word clouds, and AI-generated summaries showing your emotional journey and recurring themes. It’s like having a therapist and data analyst in one!

• Day 1: Markdown Journal Writer (Today)

• Day 2: AI Mood & Theme Analyzer

• Day 3: Insights Dashboard

View All Projects This Week

Today’s Project

We’re starting with the foundation: a command-line journal that greets you with randomized reflection prompts, saves entries as dated markdown files, and lets you search through your past thoughts! We will not use AI today yet.

You’ll learn file-based storage, markdown formatting, and building a clean CLI for daily use!

Project Task

Create a markdown journal system that:

• Date-based entries (one file per day: YYYY-MM-DD.md)

• Stores entries in journal/ folder

• Randomized reflection prompts

• Commands: new, list, search, open

• Markdown formatting for entries

• Timestamp each entry

• Clean CLI interface with argparse

• Search through past entries

• Open entries in your editor

This project gives you hands-on practice with file organization, markdown formatting, command-line tools, argparse, pathlib, datetime handling, and building daily-use tools — essential skills for productivity applications!

Expected Output

Creating a new journal entry:

python journal.py new

Console Output:

Generated file: journal/2026-05-12.md

# Friday, April 26, 2026

## 📝 Entry 1 - 10:30 AM

**Prompt:** What's one small thing that brought you joy today?

Had a great coffee this morning at the new cafe downtown.
The barista remembered my order - made me feel like a regular.
Spent the afternoon coding a new project. Made real progress!
Feeling accomplished and energized.

---

Listing all entries:

python journal.py list

Output:

Searching entries:

python journal.py search "coffee"

Output:

Opening a specific entry:

python journal.py open 2026-04-26

Output:

Setup Instructions

No installations needed!

Uses Python standard library only:

python journal.py new

The journal creates:

• journal/ folder (auto-created on first use)

• One .md file per day (e.g., 2026-05-12.md)

• Each file contains all entries for that day

Understanding File-Based Journaling

Why file-based?

✅ Simple - Just markdown files, no database
✅ Portable - Copy your journal/ folder anywhere
✅ Human-readable - Open files in any text editor
✅ Git-friendly - Version control your thoughts
✅ Privacy - Files stay on your computer
✅ Future-proof - Markdown will always be readable

File structure:

your-project/
├── journal.py
└── journal/
    ├── 2026-04-26.md
    ├── 2026-04-25.md
    ├── 2026-04-24.md
    └── ...

Why YYYY-MM-DD format?

Putting the year before is usually better in programming and working with files:

2026-04-26.md  ✅ Sorts chronologically
26-04-2026.md  ❌ Sorts incorrectly
april-26.md    ❌ No year, doesn't sort

Understanding pathlib

Modern file handling with pathlib:

from pathlib import Path

# Create journal directory
journal_dir = Path("journal")
journal_dir.mkdir(exist_ok=True)  # Create if doesn't exist

# Build file path
date_str = "2026-04-26"
file_path = journal_dir / f"{date_str}.md"
# Result: journal/2026-04-26.md

# Check if file exists
if file_path.exists():
    print("Entry already exists!")

# Read file
content = file_path.read_text()

# Write file
file_path.write_text(content)

# List all journal files
entries = sorted(journal_dir.glob("*.md"))

Why pathlib over os.path?

# OLD way (os.path)
import os
path = os.path.join("journal", date_str + ".md")

# NEW way (pathlib)
from pathlib import Path
path = Path("journal") / f"{date_str}.md"

✅ Cleaner syntax - / operator joins paths
✅ Object-oriented - Methods like .exists(), .read_text()
✅ Cross-platform - Handles Windows/Mac/Linux differences

Understanding argparse for CLI

Building a professional CLI:

import argparse

parser = argparse.ArgumentParser(description="AI Daily Journal")

# Add subcommands
subparsers = parser.add_subparsers(dest='command')

# 'new' command
new_parser = subparsers.add_parser('new', help='Create new entry')

# 'list' command
list_parser = subparsers.add_parser('list', help='List all entries')
list_parser.add_argument('--all', action='store_true', help='Show all entries')

# 'search' command
search_parser = subparsers.add_parser('search', help='Search entries')
search_parser.add_argument('query', help='Search term')

# 'open' command
open_parser = subparsers.add_parser('open', help='Open entry')
open_parser.add_argument('date', help='Date (YYYY-MM-DD)')

# Parse arguments
args = parser.parse_args()

if args.command == 'new':
    create_entry()
elif args.command == 'list':
    list_entries(show_all=args.all)
elif args.command == 'search':
    search_entries(args.query)
elif args.command == 'open':
    open_entry(args.date)

Result:

python journal.py new              # Create entry
python journal.py list             # List recent
python journal.py list --all       # List all
python journal.py search "coffee"  # Search
python journal.py open 2026-04-26  # Open

Understanding Reflection Prompts

Why prompts?

Random prompts help you:

• Break through writer’s block

• Explore different aspects of your day

• Maintain variety in entries

• Discover new insights

Our prompt bank:

REFLECTION_PROMPTS = [
    "What's one small thing that brought you joy today?",
    "What challenged you today, and what did you learn from it?",
    "What are you grateful for right now?",
    "What's on your mind that you need to get out?",
    "What progress did you make today, no matter how small?",
    "What would you do differently if you could redo today?",
    "Who or what inspired you today?",
    "What's something you're looking forward to?",
    "What did you do today that aligned with your values?",
    "What's one thing you want to remember about today?"
]

Selecting a random prompt:

import random

prompt = random.choice(REFLECTION_PROMPTS)
print(f"💭 Reflection Prompt:\n\"{prompt}\"")

Understanding Markdown Formatting

Why markdown for journals?

✅ Readable - Plain text with simple formatting
✅ Portable - Works everywhere
✅ Structured - Headers, lists, emphasis
✅ Future-proof - Never becomes obsolete

Our entry structure:

# Friday, April 26, 2026          ← Day header

## 📝 Entry 1 - 10:30 AM          ← Entry header

**Prompt:** What brought you joy? ← Prompt (bold)

Entry text goes here...           ← User's writing
Multiple paragraphs supported.

---                               ← Separator

Markdown elements we use:

# H1 Header          → Day title
## H2 Header         → Entry number
**bold**            → Prompt label
---                 → Horizontal rule (separator)

Understanding Entry Metadata

What we track:

entry_data = {
    'date': '2026-04-26',
    'day_name': 'Friday',
    'entry_number': 1,
    'timestamp': '10:30 AM',
    'prompt': 'What brought you joy today?',
    'content': '...',
    'word_count': 32,
    'char_count': 189
}

Why track this:

• Know how many entries per day

• See when you journal (morning/evening patterns)

• Track writing volume over time

• Tomorrow: AI will analyze this data!

Practical Use Cases

1. Daily reflection:

# Every morning
python journal.py new
# Write about yesterday, plan for today

2. Gratitude practice:

# Focus on positive moments
python journal.py new
# Prompt guides you to find joy

3. Problem processing:

# When stressed or confused
python journal.py new
# Writing clarifies thoughts

4. Review patterns:

# Look back at your month
python journal.py list
# See frequency and themes

5. Find specific memories:

# Remember that conversation?
python journal.py search "conversation"
# Find when you wrote about it

Coming Tomorrow

Tomorrow we’re adding AI mood and theme analysis with Gemini! The AI will read each entry, score your mood from -1 (negative) to +1 (positive), and extract 3-5 recurring themes. All cached as JSON so re-runs are free!

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 Desktop Notification System that displays toast notifications, schedules reminders, and manages alerts — perfect for building productivity tools!

• Day 1: Simple Desktop Notifications

• Day 2: Scheduled Notifications & Timers

• Day 3: Smart Notification Manager with Persistence (Today)

View All Projects This Week

Today’s Project

Welcome to the finale! We’ve built notifications and timers. Today we’re creating a complete notification management system with saved reminders, templates, and a persistent scheduler that remembers everything!

You’ll build a manager that saves your notifications, loads them on startup, and runs multiple scheduled reminders simultaneously!

Project Task

Create a complete notification management system with:

• Save notifications to JSON file

• Load saved notifications on startup

• Manage multiple scheduled notifications

• Create reusable notification templates

• List all active/scheduled notifications

• Cancel specific notifications

• Edit and update notifications

• Persistent storage between sessions

• Clean command-line interface

This project gives you hands-on practice with JSON persistence, data management, state tracking, CRUD operations, and building production-ready tools — essential skills for real-world applications!

Expected Output

Running the notification manager:

python solution.py

Console Output:

First you need to set up a scheduled notification in the terminal. Notice that we are also creating a template out of it.

Then, the notification will trigger as a native desktop notification:

Saved JSON file: notifications_data.json

{
  "notifications": [
    {
      "id": "notif_001",
      "title": "Team Meeting",
      "message": "Weekly sync starts now",
      "type": "scheduled",
      "time": "14:00",
      "status": "active",
      "created_at": "2026-04-26T10:15:00",
      "template_name": "Weekly Team Meeting"
    },
    {
      "id": "notif_002",
      "title": "Hydration Reminder",
      "message": "Time to drink water!",
      "type": "recurring",
      "interval_minutes": 60,
      "status": "active",
      "created_at": "2026-04-26T10:20:00",
      "template_name": "Hydration Reminder"
    }
  ],
  "templates": [
    {
      "name": "Daily Standup",
      "type": "scheduled",
      "time": "09:30",
      "title": "Daily Standup",
      "message": "Morning team sync",
      "use_count": 15
    },
    {
      "name": "Hydration Reminder",
      "type": "recurring",
      "interval_minutes": 60,
      "title": "Hydration Reminder",
      "message": "Time to drink water!",
      "use_count": 5
    }
  ]
}

Setup Instructions

No new installations needed!

Same setup as Days 1 & 2:

macOS:

python solution.py

Windows:

pip install win10toast  # If not already installed
python solution.py

Linux:

python solution.py

Data file:

• Creates notifications_data.json automatically

• Loads on startup

• Saves on exit or after changes

Understanding Data Persistence

Why persist data?

Without persistence:

• ❌ All notifications lost when program closes

• ❌ Must recreate reminders every time

• ❌ Can’t track notification history

With persistence:

• ✅ Notifications survive program restarts

• ✅ Templates saved for reuse

• ✅ History of completed notifications

• ✅ Resume where you left off

Our approach:

# On startup
def load():
    with open('notifications_data.json', 'r') as f:
        data = json.load(f)
    return data

# On exit or after changes
def save():
    with open('notifications_data.json', 'w') as f:
        json.dump(data, f, indent=2)

Understanding the Data Structure

notifications_data.json structure:

{
  "notifications": [
    {
      "id": "notif_001",           // Unique identifier
      "title": "Meeting",          // Notification title
      "message": "Team sync",      // Notification message
      "type": "scheduled",         // Type: scheduled/recurring/instant
      "time": "14:00",            // For scheduled notifications
      "interval_minutes": 60,      // For recurring notifications
      "status": "active",          // Status: active/completed/cancelled
      "created_at": "2026-04-26T10:15:00",
      "template_name": "Weekly Meeting"  // Optional
    }
  ],
  "templates": [
    {
      "name": "Daily Standup",     // Template name
      "type": "scheduled",         // Template type
      "time": "09:30",            // Template time
      "title": "Daily Standup",    // Default title
      "message": "Morning sync",   // Default message
      "use_count": 15             // Usage tracking
    }
  ]
}

Key fields:

• id - Unique identifier (e.g., notif_001)

• type - scheduled, recurring, instant, countdown

• status - active, completed, cancelled

• created_at - When notification was created

• template_name - Links to template (optional)

Understanding Notification States

Notification lifecycle:

Created → Active → Completed
           ↓
       Cancelled

State definitions:

Active:

• Scheduled in the future

• Currently recurring

• Waiting to be sent

Completed:

• Already sent

• Countdown finished

• One-time notification done

Cancelled:

• User manually cancelled

• Removed before sending

State transitions:

# Create notification
notification['status'] = 'active'

# Send notification
notification['status'] = 'completed'
notification['completed_at'] = datetime.now().isoformat()

# Cancel notification
notification['status'] = 'cancelled'
notification['cancelled_at'] = datetime.now().isoformat()

Understanding Templates

What are templates?

Templates are saved notification configurations you can reuse:

# Template
{
  "name": "Daily Standup",
  "type": "scheduled",
  "time": "09:30",
  "title": "Daily Standup",
  "message": "Morning team sync"
}

# Create from template
notification = create_from_template("Daily Standup")
# Automatically fills in all fields

Template benefits:

✅ Consistency - Same notification every time
✅ Speed - One click instead of typing
✅ Tracking - See which templates are most used
✅ Reusability - Use same reminder daily/weekly

Common templates:

• Daily standup (9:30 AM)

• Lunch break (12:00 PM)

• End of workday (5:00 PM)

• Hydration reminder (every 1 hour)

• Pomodoro session (25 minute timer)

Understanding Notification IDs

Why unique IDs?

Need a way to identify specific notifications:

# Without IDs - ambiguous!
cancel_notification("Team Meeting")  # Which one?

# With IDs - precise!
cancel_notification("notif_001")  # Exact notification

ID generation:

def generate_id(self):
    # Get highest existing ID number
    existing_ids = [n['id'] for n in self.notifications]
    
    if not existing_ids:
        return "notif_001"
    
    # Extract numbers and increment
    numbers = [int(id.split('_')[1]) for id in existing_ids]
    next_num = max(numbers) + 1
    
    return f"notif_{next_num:03d}"

Understanding Multi-Notification Management

Managing multiple scheduled notifications:

# Track all active threads
active_threads = []

# Start notification 1
thread1 = threading.Thread(target=send_later, args=("notif_001",))
thread1.start()
active_threads.append(thread1)

# Start notification 2
thread2 = threading.Thread(target=send_later, args=("notif_002",))
thread2.start()
active_threads.append(thread2)

# Both running simultaneously!

Cancelling specific notifications:

# Each thread has reference to notification ID
# Store stop flags in dictionary

stop_flags = {}

def send_later(notif_id):
    while not stop_flags.get(notif_id, False):
        # Wait and check if cancelled
        time.sleep(1)
    
    # Send notification
    send_notification(...)

# To cancel
stop_flags[notif_id] = True

Understanding Auto-Reload on Startup

Resume notifications on startup:

def load_and_schedule(self):
    # Load from JSON
    data = self.load_data()
    
    # Find active scheduled notifications
    for notif in data['notifications']:
        if notif['status'] == 'active':
            if notif['type'] == 'scheduled':
                # Reschedule if time hasn't passed
                self._reschedule_notification(notif)
            elif notif['type'] == 'recurring':
                # Restart recurring reminder
                self._restart_recurring(notif)

What gets rescheduled:

✅ Scheduled notifications - If time is in future
✅ Recurring reminders - Always restart
❌ Completed notifications - Already sent
❌ Past scheduled times - Mark as missed

What You’ve Accomplished This Week

• Day 1: Desktop notifications with cross-platform support

• Day 2: Scheduling, timers, and Pomodoro

• Day 3: Persistence, templates, and full management

You now have:

✅ Cross-platform notifications - Works on Mac, Windows, Linux
✅ Flexible scheduling - Instant, scheduled, recurring, countdown
✅ Persistent storage - Survives program restarts
✅ Template system - Reusable notification configs
✅ Full management - Create, list, cancel, edit
✅ Production-ready - Clean code, error handling, JSON storage

View Code Evolution

Compare today’s full management system with earlier versions and see how we evolved from simple notifications → scheduling → complete persistence.

Read more

This week, we build a Desktop Notification System that displays toast notifications, schedules reminders, and manages alerts — perfect for building productivity tools!

• Day 1: Simple Desktop Notifications

• Day 2: Scheduled Notifications & Timers (Today)

• Day 3: Smart Notification Manager with Persistence

View All Projects This Week

Today’s Project

Yesterday we built basic notifications. Today we’re adding time-based features — schedule notifications for specific times, create countdown timers, and build a Pomodoro work timer!

You’ll learn scheduling, time calculations, threading, and building productivity tools that notify you at the right moment!

Project Task

Enhance the notification system with time-based features:

• Schedule notifications for specific times

• Countdown timers with notifications

• Recurring reminders (every X minutes)

• Pomodoro timer (25 min work + 5 min break)

• Time parsing (natural language like “5pm”, “30 minutes”)

• Background task scheduling

• Visual countdown display

• All Day 1 features still work

This project gives you hands-on practice with scheduling, datetime parsing, threading, timers, background tasks, and building productivity tools — essential skills for automation and time-based applications!

Expected Output

Running the enhanced notification system:

python solution.py

Console Output:

Here is what the user sees in the console when running the program:

In the interaction above the user has chosen to use the Pomodoro feature. After 25 minutes have elapsed, the user will get a native desktop notification:

After some minutes, another focus session will start.

Setup Instructions

No new installations needed!

Same setup as Day 1:

macOS:

python solution.py

Windows:

pip install win10toast  # If not already installed
python solution.py

Linux:

python solution.py

Understanding Time-Based Scheduling

Three types of scheduling:

1. Absolute time (schedule_at):

# Notify at 3:00 PM today
scheduler.schedule_at("15:00", "Meeting", "Daily standup")

2. Relative time (countdown):

# Notify in 25 minutes
scheduler.countdown_timer(25, "Timer Done", "Break time!")

3. Recurring (repeating):

# Notify every 30 minutes
scheduler.recurring_reminder(30, "Reminder", "Drink water")

Understanding Datetime Parsing

Converting user input to datetime objects:

from datetime import datetime, timedelta

# Parse "15:00" to today at 3 PM
def parse_time(time_str):
    # Split "15:00" into hours and minutes
    hours, minutes = map(int, time_str.split(':'))
    
    # Get today's date
    now = datetime.now()
    
    # Combine with specified time
    scheduled_time = now.replace(hour=hours, minute=minutes, second=0)
    
    # If time already passed today, schedule for tomorrow
    if scheduled_time < now:
        scheduled_time += timedelta(days=1)
    
    return scheduled_time

Calculating time until notification:

# How long until 3 PM?
now = datetime.now()
scheduled_time = parse_time("15:00")

time_diff = scheduled_time - now

# Convert to readable format
hours = time_diff.seconds // 3600
minutes = (time_diff.seconds % 3600) // 60

print(f"Time until notification: {hours} hours {minutes} minutes")

Understanding Threading for Background Tasks

Why threading?

Without threading, your program blocks while waiting:

# BAD - Program freezes for 25 minutes!
time.sleep(25 * 60)
send_notification("Timer Done", "Break time!")
# User can't do anything else during wait

With threading, program stays responsive:

import threading

def timer_thread(minutes):
    time.sleep(minutes * 60)
    send_notification("Timer Done", "Break time!")

# Start timer in background
thread = threading.Thread(target=timer_thread, args=(25,))
thread.start()

# Program continues - user can start another timer!

Our approach:

def countdown_timer(self, minutes, title, message):
    # Create background thread
    thread = threading.Thread(
        target=self._run_countdown,
        args=(minutes, title, message)
    )
    thread.daemon = True  # Thread dies when main program exits
    thread.start()

Understanding the Pomodoro Technique

What is Pomodoro?

A productivity method that uses timed work sessions with breaks:

1. Work for 25 minutes (focused)

2. Break for 5 minutes (short)

3. Repeat 4 times

4. Long break 15-30 minutes

Our implementation:

def start_pomodoro(self, sessions=4):
    for i in range(sessions):
        # Work session
        print(f"🍅 Work Session {i+1}/{sessions}")
        self.countdown_timer(25, "Work Complete", "Time for a break!")
        
        # Short break (except after last session)
        if i < sessions - 1:
            print("☕ Break Time")
            self.countdown_timer(5, "Break Over", "Back to work!")

Why it works:

• ✅ Maintains focus with time limits

• ✅ Prevents burnout with regular breaks

• ✅ Creates rhythm and routine

• ✅ Notifications keep you on track

Understanding Countdown Display

Live countdown in terminal:

import time

def show_countdown(minutes):
    total_seconds = minutes * 60
    
    for remaining in range(total_seconds, 0, -60):
        mins = remaining // 60
        secs = remaining % 60
        
        # Display with carriage return (overwrites line)
        print(f"\r⏱️  Time remaining: {mins}:{secs:02d}", end='', flush=True)
        
        time.sleep(60)  # Wait 1 minute
    
    print("\n🔔 Timer complete!")

Key techniques:

• \r - Carriage return (moves cursor to start of line)

• end='' - Don’t print newline

• flush=True - Force immediate output

• Result: Counter updates in place instead of printing new lines

Understanding Recurring Reminders

How recurring reminders work:

def recurring_reminder(self, interval_minutes, title, message):
    while True:
        # Wait for interval
        time.sleep(interval_minutes * 60)
        
        # Send reminder
        self.send_notification(title, message)
        
        # Calculate next reminder time
        next_time = datetime.now() + timedelta(minutes=interval_minutes)
        print(f"Next reminder: {next_time.strftime('%I:%M %p')}")

Stopping recurring reminders:

# Use Ctrl+C to stop
try:
    recurring_reminder(30, "Break", "Take a break!")
except KeyboardInterrupt:
    print("\nRecurring reminder stopped.")

Practical Use Cases

1. Meeting reminders:

# Remind 15 minutes before 2 PM meeting
scheduler.schedule_at("13:45", "Meeting Soon", "Team sync at 2 PM")

2. Pomodoro work sessions:

# Deep work with automatic breaks
scheduler.start_pomodoro(sessions=4)

3. Hydration reminders:

# Drink water every hour
scheduler.recurring_reminder(60, "Hydration", "Drink some water!")

4. Cooking timers:

# Pasta cooking timer
scheduler.countdown_timer(10, "Pasta Ready", "Time to drain the pasta!")

5. Long-running script notifications:

# Start training ML model
train_model()  # Takes 3 hours

# Schedule notification for when it should be done
scheduler.countdown_timer(180, "Training Complete", "Model training finished!")

Coming Tomorrow

Tomorrow we’re building a Smart Notification Manager with persistence — save your scheduled notifications, create notification templates, manage multiple reminders, and run everything from the system tray!

View Code Evolution

Compare today’s scheduler-enhanced system with yesterday’s basic notifications and see how we added time-based features.

Read more

This week, we build a Desktop Notification System that displays toast notifications, schedules reminders, and manages alerts — perfect for building productivity tools!

Why build this? Because notifications are everywhere — apps, websites, productivity tools. You’ll learn how to create professional desktop alerts that grab attention at the right moment!

What you’ll learn: This series teaches you desktop notifications, system tray integration, scheduling, time-based triggers, persistence, and building tools that run in the background — essential skills for automation and productivity apps!

Why users love this: Create reminders that actually work! No more forgetting tasks or missing deadlines. By Day 3, you’ll have a smart notification manager running silently in your system tray!

• Day 1: Simple Desktop Notifications (Today)

• Day 2: Scheduled Notifications & Timers

• Day 3: Smart Notification Manager with Persistence

View All Projects This Week

Today’s Project

We’re starting with the foundation: a simple notification system that displays desktop toast notifications with custom messages, titles, and durations!

You’ll learn how to trigger system notifications from Python using native OS capabilities — no complex dependencies!

Project Task

Create a desktop notification system that:

• Displays toast notifications on Windows/Mac/Linux

• Custom title and message

• Adjustable duration (how long it shows)

• Multiple notification types (info, warning, success, error)

• Simple command-line interface

• Cross-platform compatibility

• Uses native OS notification systems

• No complex dependencies

This project gives you hands-on practice with desktop notifications, system integration, cross-platform development, user alerts, and building tools that interact with the operating system — essential for automation and productivity apps!

Expected Output

Running the notification tool:

python solution.py

Console Output:

That would trigger a notification on your computer:

Setup Instructions

Install Required Packages:

macOS and Linux (no installation needed!)

Windows:

pip install win10toast

Platform support:

• ✅ macOS - Native notification center via osascript

• ✅ Windows 10/11 - Native toast notifications via win10toast

• ✅ Linux - Native notifications via notify-send

Understanding Desktop Notifications

What are desktop notifications?

Desktop notifications (also called “toast notifications”) are small popup messages that appear on your screen to alert you about events, updates, or reminders.

Common uses:

• Email notifications

• Chat messages

• Reminders and alarms

• Task completions

• System alerts

• Download completions

How they work:

Your Python Script → Native OS API → Desktop Notification

Example flow:

# 1. Your code
notifier.send_notification("Download Complete", "file.zip is ready!")

# 2. Platform detection
# macOS: Uses osascript
# Windows: Uses win10toast
# Linux: Uses notify-send

# 3. OS displays notification
# User sees popup on screen

Understanding Cross-Platform Notifications

Why we detect the platform:

Different operating systems have different notification systems. Our code automatically detects your OS and uses the right method!

macOS approach:

# Uses AppleScript via osascript command
osascript -e 'display notification "message" with title "title"'

Windows approach:

# Uses Windows Toast Notification API
from win10toast import ToastNotifier
toaster = ToastNotifier()
toaster.show_toast("Title", "Message")

Linux approach:

# Uses notify-send (part of libnotify)
notify-send "Title" "Message" -t 5000

Our unified approach:

def send_notification(self, title, message, duration=5):
    if self.platform == "Darwin":  # macOS
        self._send_macos_notification(title, message)
    elif self.platform == "Windows":
        self._send_windows_notification(title, message, duration)
    elif self.platform == "Linux":
        self._send_linux_notification(title, message, duration)

Benefits:

• ✅ Same code works everywhere

• ✅ No complex dependencies

• ✅ Uses native OS features

• ✅ Looks native on each platform

Understanding Notification Parameters

Title:

• Short, attention-grabbing text

• Appears in bold at the top

• Keep under 50 characters

• Example: “Download Complete”, “New Message”, “Reminder”

Message:

• Main notification content

• Can be longer (up to 200 characters recommended)

• Should be clear and actionable

• Example: “Your file download.zip is ready to use”

Duration:

• How long notification stays on screen (seconds)

• Default: 5-10 seconds

• Short messages: 5 seconds

• Important messages: 10+ seconds

• Note: macOS ignores duration and uses system default

App Name:

• Identifies which app sent the notification

• Appears at bottom of notification

• Example: “Python Notifier”, “My Reminder App”

Understanding Notification Types

We implement different notification types with emoji indicators:

1. Info Notification (ℹ️):

notifier.send_info(
    title="Information",
    message="This is an informational message"
)
# Displays: ℹ️ Information

2. Success Notification (✅):

notifier.send_success(
    title="Success!",
    message="Operation completed successfully"
)
# Displays: ✅ Success!

3. Urgent Notification (⚠️):

notifier.send_urgent(
    title="Warning",
    message="Action required!"
)
# Displays: ⚠️ Warning

4. Error Notification (❌):

notifier.send_error(
    title="Error",
    message="Something went wrong"
)
# Displays: ❌ Error

Why emojis?

• ✅ Universal visual indicators

• ✅ Work on all platforms

• ✅ No icon files needed

• ✅ Instant recognition

Practical Use Cases

1. Long-running scripts:

# Scraping script
scraper.run()  # Takes 30 minutes

# Notify when done
notifier.send_success(
    "Scraping Complete",
    "Collected 1,500 quotes successfully!"
)

2. File downloads:

download_file(url)

notifier.send_notification(
    "Download Complete",
    f"{filename} is ready!"
)

3. Task reminders:

notifier.send_notification(
    "Break Time!",
    "You've been working for 1 hour. Take a 5-minute break."
)

4. System monitoring:

if disk_space < 10:
    notifier.send_urgent(
        "Low Disk Space",
        f"Only {disk_space}% remaining!"
    )

5. Build/test completions:

run_tests()

if all_passed:
    notifier.send_success("Tests Passed", "All 47 tests passed!")
else:
    notifier.send_error("Tests Failed", f"{failed_count} tests failed")

Coming Tomorrow

Tomorrow we’re adding scheduled notifications and timers — set reminders for specific times, create countdown timers, and build a Pomodoro-style work timer with automatic notifications!

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 learn Object-Oriented Programming (OOP) by building a web scraper that evolves from functions to classes to inheritance.

• Day 1: Quote Scraper with Functions

• Day 2: Refactoring to Classes

• Day 3: Adding Inheritance & Multiple Scrapers (Today)

View All Projects This Week

Today’s Project

Welcome to the finale! Yesterday we refactored to classes. Today we’re taking it further with inheritance — creating a base Scraper class and two specialized scrapers that inherit from it!

You’ll build QuoteScraper and AuthorScraper — both share common scraping logic but extract different data. This is how professional code reuses functionality!

Project Task

Create a scraping system with inheritance that:

• Base Scraper class with common scraping logic

• QuoteScraper inherits from Scraper (extracts quotes)

• AuthorScraper inherits from Scraper (extracts authors)

• Shared methods in base class (fetch, scrape, save)

• Specialized parsing in each subclass

• Both scrapers work independently

• Demonstrates clean code reuse

This project gives you hands-on practice with inheritance, base classes, method overriding, code reuse, and OOP design — essential skills for building maintainable applications!

Expected Output

Running the scraper:

python solution.py

Console Output:

The scraper scrapes quotes like in Day 2 but in addition, it also scrapes other data such as authors:

Setup Instructions

Install Required Packages:

pip install requests beautifulsoup4

Run the scrit:

python solution.py

Understanding Inheritance

What is inheritance?

Inheritance lets you create a base class with common functionality, then create child classes that inherit and extend that functionality.

Our hierarchy:

        Scraper (Base Class)
           ↑
           |
    ┌──────┴──────┐
    |             |
QuoteScraper  AuthorScraper

Before inheritance (repetitive):

class QuoteScraper:
    def fetch_page(self, url):
        # Fetching logic
        pass
    
    def scrape(self):
        # Pagination logic
        pass
    
    def parse_quotes(self, html):
        # Different!
        pass

class AuthorScraper:
    def fetch_page(self, url):
        # DUPLICATE CODE!
        pass
    
    def scrape(self):
        # DUPLICATE CODE!
        pass
    
    def parse_authors(self, html):
        # Different!
        pass

After inheritance (clean):

class Scraper:
    """Base class - write once, use everywhere"""
    def fetch_page(self, url):
        # Common code
        pass
    
    def scrape(self):
        # Common code
        pass

class QuoteScraper(Scraper):
    """Inherits fetch_page and scrape"""
    def parse_data(self, html):
        # Only write the unique part
        pass

class AuthorScraper(Scraper):
    """Also inherits fetch_page and scrape"""
    def parse_data(self, html):
        # Only write the unique part
        pass

Understanding the Base Scraper Class

The base class contains what’s shared:

class Scraper:
    """Base scraper with common functionality"""
    
    def __init__(self, base_url, max_pages=3):
        self.base_url = base_url
        self.max_pages = max_pages
        self.data = []
    
    def fetch_page(self, url):
        """Fetch HTML - same for all scrapers"""
        response = requests.get(url)
        return response.text
    
    def scrape(self):
        """Scrape pages - same logic for all scrapers"""
        for page_num in range(1, self.max_pages + 1):
            url = f"{self.base_url}/page/{page_num}/"
            html = self.fetch_page(url)
            
            # Call parse_data (implemented by child)
            data = self.parse_data(html)
            
            self.data.extend(data)
    
    def save_to_json(self, filename):
        """Save data - same for all scrapers"""
        with open(filename, 'w') as f:
            json.dump(self.data, f)
    
    def parse_data(self, html):
        """Must be implemented by child classes"""
        raise NotImplementedError("Child must implement parse_data()")

Key points:

✅ fetch_page() - All scrapers fetch HTML the same way
✅ scrape() - All scrapers loop through pages the same way
✅ save_to_json() - All scrapers save files the same way
✅ parse_data() - Each child implements differently

Understanding Child Classes

QuoteScraper - extracts quotes:

class QuoteScraper(Scraper):
    """Inherits from Scraper"""
    
    def __init__(self, base_url, tags_filter, max_pages=3):
        super().__init__(base_url, max_pages)  # Call parent init
        self.tags_filter = tags_filter
    
    def parse_data(self, html):
        """Parse quotes - unique to this scraper"""
        soup = BeautifulSoup(html, 'html.parser')
        quotes = soup.find_all('div', class_='quote')
        
        results = []
        for quote in quotes:
            text = quote.find('span', class_='text').text
            author = quote.find('small', class_='author').text
            tags = [tag.text for tag in quote.find_all('a', class_='tag')]
            
            # Filter by tags
            if any(tag in self.tags_filter for tag in tags):
                results.append({
                    'text': text,
                    'author': author,
                    'tags': tags
                })
        
        return results

AuthorScraper - counts authors:

class AuthorScraper(Scraper):
    """Also inherits from Scraper"""
    
    def parse_data(self, html):
        """Parse authors - unique to this scraper"""
        soup = BeautifulSoup(html, 'html.parser')
        authors = soup.find_all('small', class_='author')
        
        # Just return author names
        return [author.text for author in authors]

What they inherit:

• ✅ fetch_page() from Scraper

• ✅ scrape() from Scraper

• ✅ save_to_json() from Scraper

What they implement:

• 🆕 parse_data() - unique to each scraper

Understanding super()

super() calls the parent class:

class QuoteScraper(Scraper):
    def __init__(self, base_url, tags_filter, max_pages=3):
        # Call parent's __init__ first
        super().__init__(base_url, max_pages)
        
        # Then add child-specific attributes
        self.tags_filter = tags_filter

What happens:

scraper = QuoteScraper("http://example.com", ['life'], max_pages=3)

# Step 1: super().__init__(base_url, max_pages)
#   → self.base_url = "http://example.com"
#   → self.max_pages = 3
#   → self.data = []

# Step 2: Child __init__ continues
#   → self.tags_filter = ['life']

# Result: All attributes set!

Why Inheritance Matters

What we gain:

1. Write once, use everywhere:

# fetch_page() written ONCE in Scraper
# Both QuoteScraper and AuthorScraper use it

2. Easy to add new scrapers:

class TagScraper(Scraper):
    def parse_data(self, html):
        # Only implement the unique part!
        # Everything else inherited
        pass

3. Fix bugs in one place:

# Bug in fetch_page()?
# Fix it in Scraper class
# All children benefit automatically!

4. Consistent behavior:

# All scrapers fetch pages the same way
# All scrapers handle pagination the same way
# All scrapers save files the same way

Code Comparison: Day 2 vs Day 3

Day 2 (Single QuoteScraper class):

• ✅ Better than functions

• ❌ Can’t reuse for other scrapers

• ❌ Would duplicate code for AuthorScraper

Day 3 (Inheritance):

• ✅ Base class holds common code

• ✅ Easy to add new scrapers

• ✅ No code duplication

• ✅ Fix once, benefit everywhere

What You’ve Accomplished This Week

🎉 Congratulations! You’ve completed the OOP journey!

• Day 1: Functions - Simple and procedural

• Day 2: Classes - Organized with encapsulation

• Day 3: Inheritance - Reusable and scalable

You now understand:

✅ Functions → Small, independent tasks
✅ Classes → Grouping related data and behavior
✅ Inheritance → Sharing code across similar classes

This is how professional Python is written!

Real-world examples of inheritance:

• Games: Character → Player, Enemy, NPC

• Web frameworks: View → ListView, DetailView, CreateView

• ML models: Model → LinearRegression, DecisionTree, NeuralNetwork

• Data processing: FileReader → CSVReader, JSONReader, XMLReader

You’ve mastered the fundamentals of OOP! 🚀

View Code Evolution

Compare today’s inheritance-based system with earlier versions and see how we evolved from functions → classes → inheritance for maximum code reuse.

Read more

This week, we learn Object-Oriented Programming (OOP) by building a web scraper that evolves from functions to classes to inheritance.

• Day 1: Quote Scraper with Functions

• Day 2: Refactoring to Classes (Today)

• Day 3: Adding Inheritance & Multiple Scrapers

View All Projects This Week

Today’s Project

Yesterday we built a quote scraper using only functions. Today we’re refactoring the exact same scraper using classes!

You’ll see the same functionality, but organized as a QuoteScraper class. This is your “aha moment” for understanding why and when to use classes instead of functions!

Project Task

Refactor yesterday’s scraper into a class-based design that:

• Same functionality as Day 1 (scrape, filter, save)

• Organized as a QuoteScraper class

• Instance variables store configuration and state

• Methods replace standalone functions

• Cleaner data flow with self

• Easier to extend and maintain

• Same output as Day 1

This project gives you hands-on practice with class design, instance variables, methods, self keyword, refactoring, and object-oriented thinking — the foundation of professional Python code!

Expected Output

Running the scraper:

python solution.py

Console Output:

The output is the same as the output of Day 1. We get the quotes displayed. So, the behavior of the program does not change. It is only the code that changes:

Setup Instructions

Install Required Packages:

pip install requests beautifulsoup4

Same packages as Day 1!

Run the scraper:

python solution.py

Same output as Day 1, but now it’s organized as a class!

Understanding Classes vs Functions

Yesterday (Functions):

# Pass data between functions
html = fetch_page(url)
quotes = parse_quotes(html)
filtered = filter_by_tags(quotes, tags_filter)
save_to_json(filtered, tags_filter)

Problems:

• ❌ Pass tags_filter to every function

• ❌ No shared state

• ❌ Hard to track what data belongs together

• ❌ Difficult to extend

Today (Classes):

# Create instance with configuration
scraper = QuoteScraper(base_url=url, tags_filter=tags)

# Call methods - they share state via self
scraper.scrape()  # Uses self.base_url and self.tags_filter
scraper.save_to_json()  # Uses self.quotes

Benefits:

• ✅ Configuration stored once in self

• ✅ Shared state across methods

• ✅ Related data grouped together

• ✅ Easy to extend with new methods

Understanding the QuoteScraper Class

Class structure:

class QuoteScraper:
    def __init__(self, base_url, tags_filter):
        """Initialize the scraper with configuration"""
        self.base_url = base_url
        self.tags_filter = tags_filter
        self.quotes = []  # Store results here
    
    def fetch_page(self, url):
        """Fetch HTML from URL"""
        # Same logic as Day 1 function
        return html
    
    def parse_quotes(self, html):
        """Parse quotes from HTML"""
        # Same logic as Day 1 function
        return quotes
    
    def filter_by_tags(self, quotes):
        """Filter quotes by self.tags_filter"""
        # Uses self.tags_filter instead of parameter
        return filtered
    
    def scrape(self):
        """Main scraping method"""
        page = 1
        while True:
            url = f"{self.base_url}/page/{page}/"
            html = self.fetch_page(url)
            quotes = self.parse_quotes(html)
            filtered = self.filter_by_tags(quotes)
            self.quotes.extend(filtered)  # Store in self.quotes
            page += 1
    
    def save_to_json(self):
        """Save self.quotes to JSON"""
        # Uses self.quotes and self.tags_filter
        pass

Understanding self

What is self?

self refers to the instance of the class. It’s how methods access the instance’s data.

# Create an instance
scraper = QuoteScraper(
    base_url="http://quotes.toscrape.com",
    tags_filter=['life']
)

# When you call a method:
scraper.fetch_page(url)

# Python automatically passes the instance as 'self':
QuoteScraper.fetch_page(scraper, url)
#                       ^^^^^^
#                       This is 'self'!

Using self to share data:

class QuoteScraper:
    def __init__(self, tags_filter):
        self.tags_filter = tags_filter  # Store in instance
        self.quotes = []  # Shared across methods
    
    def scrape(self):
        # Access instance variables with self
        print(f"Filtering by: {self.tags_filter}")
        
        quotes = self.parse_quotes(html)
        filtered = self.filter_by_tags(quotes)
        
        # Store in instance variable
        self.quotes.extend(filtered)
    
    def filter_by_tags(self, quotes):
        # Use self.tags_filter instead of parameter!
        return [q for q in quotes if any(tag in self.tags_filter for tag in q['tags'])]
    
    def save_to_json(self):
        # Access self.quotes that scrape() filled
        data = {'quotes': self.quotes}
        # ...

Without self (doesn’t work):

class QuoteScraper:
    def __init__(self, tags_filter):
        tags_filter = tags_filter  # ❌ Local variable, lost after __init__
    
    def scrape(self):
        print(tags_filter)  # ❌ ERROR: tags_filter not defined!

Understanding Instance Variables

Instance variables = data that belongs to a specific instance.

Example:

# Create two different scrapers
scraper1 = QuoteScraper(tags_filter=['life'])
scraper2 = QuoteScraper(tags_filter=['humor'])

# Each has its own data!
print(scraper1.tags_filter)  # ['life']
print(scraper2.tags_filter)  # ['humor']

# Run both
scraper1.scrape()
scraper2.scrape()

# Each stores different quotes
print(len(scraper1.quotes))  # 20 life quotes
print(len(scraper2.quotes))  # 15 humor quotes

Common instance variables in our scraper:

def __init__(self, base_url, tags_filter):
    # Configuration (set once, used everywhere)
    self.base_url = base_url
    self.tags_filter = tags_filter
    
    # State (changes during execution)
    self.quotes = []  # Filled by scrape()
    self.current_page = 1  # Tracks pagination

Understanding Methods

Methods = functions that belong to a class.

Two types of methods in our scraper:

1. Public methods (meant to be called from outside):

class QuoteScraper:
    def scrape(self):
        """Main method - users call this"""
        # ...
    
    def save_to_json(self):
        """Save results - users call this"""
        # ...

2. Helper methods (used internally):

class QuoteScraper:
    def _fetch_page(self, url):
        """Internal helper - users don't call this directly"""
        # Underscore prefix = "private" by convention
        # ...
    
    def _parse_quotes(self, html):
        """Internal helper"""
        # ...

Calling methods:

# From outside the class
scraper = QuoteScraper(...)
scraper.scrape()  # Public method

# From inside the class (in another method)
class QuoteScraper:
    def scrape(self):
        html = self._fetch_page(url)  # Call helper method
        quotes = self._parse_quotes(html)  # Call another helper

Why Classes Are Better Here

Day 1 approach (functions):

# Problem: Pass everything everywhere
def main():
    tags = ['life', 'love']
    
    quotes = scrape_all_pages(BASE_URL, tags)
    filtered = filter_by_tags(quotes, tags)
    save_to_json(filtered, tags)
    
    # Want to scrape again with different tags?
    # Start over, pass everything again
    quotes2 = scrape_all_pages(BASE_URL, ['humor'])
    filtered2 = filter_by_tags(quotes2, ['humor'])
    save_to_json(filtered2, ['humor'])

Day 2 approach (classes):

# Solution: Create reusable objects
scraper1 = QuoteScraper(BASE_URL, ['life', 'love'])
scraper1.scrape()
scraper1.save_to_json()

scraper2 = QuoteScraper(BASE_URL, ['humor'])
scraper2.scrape()
scraper2.save_to_json()

# Easy to compare results
print(f"Life quotes: {len(scraper1.quotes)}")
print(f"Humor quotes: {len(scraper2.quotes)}")

Other benefits:

✅ Encapsulation - Related data and functions grouped together
✅ State management - self.quotes persists across method calls
✅ Reusability - Create multiple scraper instances
✅ Extensibility - Easy to add new methods tomorrow
✅ Clarity - Clear what data belongs to what

Coming Tomorrow

Tomorrow we’re adding inheritance! We’ll create a base Scraper class and inherit from it to create different scrapers (quotes, authors, tags). You’ll see how OOP makes it easy to reuse code across similar classes!

View Code Evolution

Compare today’s class-based solution with yesterday’s function-based version and see the differences in organization and structure.

Read more

This week, we learn Object-Oriented Programming (OOP) by building a web scraper that evolves from functions to classes to inheritance.

Why build this? Because OOP is how professional code is structured. You’ll see the same scraper written three ways — first with functions (today), then refactored to classes (Day 2), then enhanced with inheritance (Day 3). By the end, you’ll understand why classes matter!

What you’ll learn: This series teaches you function-based programming, class structures, object-oriented design, inheritance, code organization, and refactoring — essential skills for writing maintainable, professional Python code.

Why users love this: You’ll see the same project evolve from simple functions to elegant OOP. Perfect for understanding when and why to use classes instead of functions!

• Day 1: Quote Scraper with Functions (Today)

• Day 2: Refactoring to Classes

• Day 3: Adding Inheritance & Multiple Scrapers

View All Projects This Week

Today’s Project

We’re building a quote scraper that fetches quotes from quotes.toscrape.com, filters them by tag, and saves them to a JSON file. Today’s version uses pure functions — clean, simple, and procedural!

You’ll learn web scraping basics, HTML parsing, data filtering, and JSON storage!

Project Task

Create a quote scraper that:

• Scrapes quotes from quotes.toscrape.com

• Extracts quote text, author, and tags

• Filters quotes by specific tags (motivational, life, inspirational)

• Handles multiple pages of quotes

• Saves results to JSON file

• Clean console output showing progress

• Error handling for failed requests

• Uses only functions (no classes yet!)

This project gives you hands-on practice with web scraping, BeautifulSoup, requests library, data parsing, filtering, file I/O, and functional programming — all the foundations you need before learning OOP!

Expected Output

Running the scraper:

python solution.py

Console Output:

Running the program will print out the progress of the scraper as below:

Below that you will see the quotes scraped and printed out:

Generated JSON file: quotes_motivational_life_inspirational.json

In addition to printing out the scraped content, the program will also save the data in a JSON file:

Setup Instructions

Install Required Packages:

pip install requests beautifulsoup4

What each package does:

• requests - Makes HTTP requests to fetch web pages

• beautifulsoup4 - Parses HTML and extracts data

Run the scraper:

python solution.py

The scraper will:

1. Fetch quotes from quotes.toscrape.com

2. Filter by tags: motivational, life, inspirational

3. Save results to JSON file

4. Show progress in console

You can modify the tags in the script to scrape different quotes!

Understanding Web Scraping Basics

What is web scraping?

Web scraping is extracting data from websites by:

1. Sending HTTP request to get the HTML

2. Parsing the HTML to find specific elements

3. Extracting the data you need

4. Storing it in a structured format

The scraping workflow:

URL → HTTP Request → HTML Response → Parse HTML → Extract Data → Save to File

Example HTML structure from quotes.toscrape.com:

<div class="quote">
  <span class="text">"The world as we have created it..."</span>
  <small class="author">Albert Einstein</small>
  <div class="tags">
    <a class="tag">change</a>
    <a class="tag">inspirational</a>
    <a class="tag">life</a>
  </div>
</div>

How we extract it:

import requests
from bs4 import BeautifulSoup

# 1. Fetch the page
response = requests.get('http://quotes.toscrape.com/page/1/')
html = response.text

# 2. Parse HTML
soup = BeautifulSoup(html, 'html.parser')

# 3. Find all quote divs
quotes = soup.find_all('div', class_='quote')

# 4. Extract data from each quote
for quote in quotes:
    text = quote.find('span', class_='text').text
    author = quote.find('small', class_='author').text
    tags = [tag.text for tag in quote.find_all('a', class_='tag')]

Why quotes.toscrape.com?

This website is specifically designed for learning web scraping:

• ✅ Simple, clean HTML structure

• ✅ No anti-scraping measures

• ✅ Paginated data (multiple pages)

• ✅ Different data types (text, authors, tags)

• ✅ Legal and ethical to scrape

Understanding BeautifulSoup

BeautifulSoup is a Python library that makes HTML parsing easy.

Key methods we use:

from bs4 import BeautifulSoup

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

# Find first matching element
quote = soup.find('div', class_='quote')

# Find all matching elements
quotes = soup.find_all('div', class_='quote')

# Get text content
text = element.text

# Get attribute value
href = element.get('href')

CSS class selector:

# Find by class name
soup.find('div', class_='quote')

# Find by ID
soup.find('div', id='my-id')

# Find by tag name
soup.find('span')

Navigating the HTML tree:

# Find nested elements
quote = soup.find('div', class_='quote')
author = quote.find('small', class_='author')

# Find multiple nested elements
tags = quote.find_all('a', class_='tag')

Understanding Pagination

What is pagination?

Websites split data across multiple pages:

• Page 1: quotes.toscrape.com/page/1/

• Page 2: quotes.toscrape.com/page/2/

• Page 3: quotes.toscrape.com/page/3/

• ...

How we handle it:

page_num = 1
has_more_pages = True

while has_more_pages:
    url = f'http://quotes.toscrape.com/page/{page_num}/'
    response = requests.get(url)
    
    # Check if page exists
    if response.status_code == 404:
        has_more_pages = False
        break
    
    # Scrape this page
    quotes = scrape_page(url)
    
    # Move to next page
    page_num += 1

Detecting the last page:

We know we’re on the last page when:

• HTTP status code is 404 (page not found)

• Or there’s no “Next” button in the HTML

• Or we find 0 quotes on the page

Understanding Function-Based Design

Today’s architecture uses only functions:

# Each function does ONE thing

def fetch_page(url):
    """Fetch HTML from URL"""
    return html

def parse_quotes(html):
    """Extract quotes from HTML"""
    return quotes

def filter_by_tags(quotes, tags):
    """Filter quotes by tags"""
    return filtered_quotes

def save_to_json(quotes, filename):
    """Save quotes to JSON file"""
    # write to file

Why functions first?

✅ Simple to understand
✅ Easy to test each piece
✅ Clear data flow
✅ Good for small projects

Limitations we’ll see tomorrow:

❌ No shared state (passing data everywhere)
❌ Difficult to extend functionality
❌ Hard to manage related data
❌ No encapsulation

Tomorrow we’ll refactor to classes and see how OOP solves these problems!

Coming Tomorrow

Tomorrow we’re refactoring this exact code to use classes! You’ll see how the same scraper becomes cleaner, more organized, and easier to extend when we introduce OOP concepts like encapsulation and methods!

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