Imagine you build a small app with AI over a weekend. Signup works, login works, the core feature works. You are proud of it, and you should be. Now imagine a real stranger signs up on day one, forgets their password on day two, exactly the way real people do, and clicks “forgot password”.

Nothing happens. Not because you are a bad developer, but because the demo never needed that button to actually work, so neither you nor the AI ever built it.

That gap between “the demo works” and “a stranger can trust it” is the entire subject of this post.

The full list, category by category

I grouped everything into nine categories, roughly in the order we will build them over the coming weeks. This is the map; the visual has the details.

Authentication is usually the biggest gap, because a coding course happily stops at “login works”. Real authentication means a password reset flow, email verification, a Google or GitHub sign-in option because plenty of people refuse to make yet another password, passwords that are actually enforced as strong on your server and not just suggested by the frontend, a limit on how many times someone can guess a password per minute, and sessions that expire instead of lasting forever.

Email infrastructure is what makes half of the authentication category possible in the first place. Your own Gmail account was never built to send password resets to strangers at scale, and it will eventually get flagged. You need a real sending service, a template for each type of email, and a sending domain that is actually verified, or your emails quietly land in spam and you will not even know it is happening.

Database and data safety stops being optional the moment someone else’s data lives in your database. Automated backups, migrations tracked in version control instead of manual changes you might forget, and a database for development kept strictly separate from the one real users touch.

Secrets and configuration is one rule really: every key and password lives in an environment variable, never in your code, and your .env file is in .gitignore from the very first commit, not added after you almost leaked something.

Security basics covers HTTPS everywhere with no exceptions, validating anything a user types before it touches your database, deliberately configuring what is allowed to call your API instead of leaving it open to everyone, and not leaving known vulnerabilities sitting in your dependencies for a year.

Payments, if your app has any, means handling the boring but critical edge cases: a subscription renewal, a failed card, and the specific nightmare of a customer who paid successfully while your webhook silently failed to record it.

Ops and reliability is how you find out your app broke before an angry user tells you. Error monitoring, uptime monitoring, and logs you can actually read instead of print statements scattered across your codebase.

Legal and trust feels like paperwork until you notice that Stripe, Google sign-in, and most app stores simply will not approve you without a privacy policy and terms of service. Add cookie consent if you have visitors in the EU, and a support email that a real human reads.

Developer workflow closes the list: commits that make sense, no secrets ever committed to GitHub history, and a way to undo a deploy that breaks production, because eventually one will.

Why this list barely existed five years ago

Here is the part I find genuinely interesting. A few years ago, this list mattered less, because building the actual app already consumed most of your time and energy, and few solo learners even reached the point of having real users.

Now AI can build the core app in an afternoon, so this list has quietly become the majority of the real work. Writing the code was never the hard part for very long. Making it trustworthy always was, and it still is.

Where we go from here

Over the next weeks, we are going to build each of these, one at a time, starting where it hurts first: password resets, then email verification, Google sign-in, and onward through the list in order. Each post will be a complete, working piece you can drop straight into your own project.

For today, save the checklist image from this post. The next time you or an AI ship something that “works”, hold it up against these nine categories, and you will know exactly what is left before a stranger can actually use it.

If you learned something from this today, consider upgrading for the full experience: every weekly project with full source code, plus the complete archive. Since you read this far, I’d like to offer you 35% off the annual plan as a token of appreciation. Click below to get the discount:

Get 20% off: $99 → $79/year

Today we fix both, plus everything else that separates “a working script” from “a tool I use every day for two years.” Bookmarklet turns saving into a single click from any page in any browser. Full-text search (SQLite FTS5 with Porter stemming, so read matches reading) lets you find articles from months ago, with match highlights in the results. Tags organize your library. Dark mode for night reading. Keyboard shortcuts — j/k to move through the queue, Enter to open, a to archive, / to search — because every tool you use daily is 4x faster with keyboard shortcuts. Markdown export so your library is portable and future-proof, either one article at a time or the whole thing as a zip.

Everything from Day 1 keeps working. Same database file (~/.readlater/readlater.db), same extraction engine, same reader typography, same graceful failure. On first Day 2 run, the search index is built from any articles you already saved yesterday — no manual re-indexing.

Projects in this week’s series:

Day 1: Save, extract, and read articles from a local web UI

Yesterday, we built the working MVP — Flask server with a save form, trafilatura for content extraction, SQLite storage with normalized URLs (tracking params stripped so duplicates dedupe), a queue view, and a reader view with proper Georgia-serif typography. Graceful failure for JS-heavy sites and paywalls kept the tool usable even when extraction couldn’t work.

Day 2: Bookmarklet, search, tags, dark mode, keyboard shortcuts, export (Today)

Save any page with one click. Set up the bookmarklet on the Setup page — a draggable button that becomes a bookmark on your browser’s bookmarks bar.

Click that bookmark on any article and a small popup confirms the save and closes itself after a second, so your reading flow doesn’t get interrupted:

Find any article you’ve ever saved via the search box in the nav bar. Full-text search with Porter stemming and match highlighting — search for “ocean” and find articles about “oceans”.

The matched terms are highlighted in each result’s snippet so you can tell at a glance which article has what you’re looking for:

Tag articles from the reader view — type comma-separated tags into the input and hit Add. Small pills appear on queue cards showing an article’s tags. Click any tag pill to filter your queue to just articles with that tag. The Tags page shows all your tags with article counts:

Dark mode toggles from the moon icon in the nav bar and remembers your choice per browser via localStorage. The theme is set inline in the page <head> before any CSS renders, so there’s no flash of the wrong theme on page load — same technique GitHub, Twitter, and every well-built site uses.

Export any article or your whole library as clean Markdown. Individual articles get a Export .md button on the reader page. The whole library exports as a zip from the Setup page — perfect for importing into Obsidian, dumping into a git repo, or just having a plain-text backup that will still work in ten years.

View All Projects This Week

About the stack

Same as Day 1, plus one small addition. markdownify is a small library that converts HTML to clean Markdown. We use it to convert our stored content_html (the extracted article HTML from trafilatura) into the Markdown that goes into .md exports. Hand-writing HTML→MD conversion for all the edge cases (nested lists, blockquotes, code blocks, links inside paragraphs) is a rabbit hole; markdownify handles it in one function call.

Everything else — Flask, trafilatura, requests, sqlite3, Jinja2 — is unchanged from yesterday.

Setup Instructions

Add the new dependency:

pip install markdownify

Run:

python readlater_full.py                    # start the server on :8770
python readlater_full.py save <URL>         # save from the terminal
python readlater_full.py list               # print the queue
python readlater_full.py search <query>     # search from the terminal (new!)

Same ~/.readlater/readlater.db file as Day 1 — if you were using yesterday’s version, all your saved articles carry over. On first Day 2 run, the search index gets built from your existing articles automatically. Takes a few milliseconds even for thousands of articles.

First thing to do after starting the server: visit /setup and drag the bookmarklet to your browser’s bookmarks bar. That single action changes the tool from “occasionally used” to “used every day.”

Understanding the Bookmarklet

A bookmarklet is a bookmark whose URL is javascript:... instead of

http://...

. When you click it, the browser executes the JavaScript in the context of the current page instead of navigating. It’s one of the oldest and most under-appreciated web features — dead simple, works in every browser since IE 4, requires no extension install.

Our bookmarklet is generated by the /setup route, so it uses whatever port your server is running on:

@app.get("/setup")
def setup_page():
    server_url = request.url_root.rstrip("/")
    js = (
        "javascript:(function(){"
        f"window.open('{server_url}/save?close=1&url='"
        "+encodeURIComponent(location.href),"
        "'rl_save','width=380,height=240');"
        "})();"
    )
    return render_template_string(SETUP_HTML, bookmarklet_href=js, ...)

The JS is wrapped in an IIFE ((function(){...})()) so the bookmarklet’s variables don’t leak into the current page’s namespace. It calls window.open() with a small window size — the popup appears at ~380x240 pixels, big enough to show “Saved ✓” and the article title.

The close=1 query parameter is the important trick. Our /save handler treats it as “this was called by the bookmarklet — instead of the normal 302 redirect back to the queue, return a tiny self-closing popup HTML page”:

SAVED_POPUP_HTML = """<!DOCTYPE html>
<html>
<body>
  <div class="icon">📚 ✓</div>
  <h2>Saved.</h2>
  <div class="title">{{ title }}</div>
  <script>setTimeout(function() { window.close(); }, 1400);</script>
</body>
</html>
"""

@app.route("/save", methods=["GET", "POST"])
def save_url():
    close_after = request.args.get("close") == "1"
    # ... save the article ...
    if close_after:
        return render_template_string(SAVED_POPUP_HTML, ...)
    return redirect(...)

setTimeout gives the user 1.4 seconds to see confirmation, then window.close() closes the popup automatically. window.close() only works on windows opened by JavaScript, but that’s exactly our case — the bookmarklet opened this window via window.open(), so the browser lets it close itself.

One user-experience detail: the bookmarklet on the Setup page is deliberately un-clickable. Clicking a javascript: link in an <a> tag would run the code on the setup page itself (saving the setup page’s URL, which isn’t what you want). So we override the click:

<a class="bookmarklet-link" href="javascript:..."
   onclick="alert('Drag this button to your bookmarks bar - don\\'t click it here.'); return false;">

Clicking shows a helpful message. Dragging still works and gives you the bookmark. Standard pattern for bookmarklet install pages.

Understanding SQLite FTS5

SQLite ships with a full-text search extension called FTS5. It’s a virtual table type — you create it, insert rows into it, and query with special MATCH operators. Under the hood it maintains an inverted index (word → list of documents containing that word), same data structure Elasticsearch and Lucene use.

Setup is one CREATE statement:

CREATE VIRTUAL TABLE articles_fts USING fts5(
    title, byline, site_name, content_text,
    tokenize='porter unicode61 remove_diacritics 2'
);

The tokenizer options matter for real-world quality:

porter enables the Porter stemming algorithm — a set of rules for reducing English words to their root form. reading, reads, reader all stem to read. When you search for “read,” you find all of them. Without stemming, exact-match search fails constantly (”I searched for ‘reading’ but got zero hits — but I know I saved an article that said ‘reading’”).

unicode61 is the tokenizer that understands Unicode word boundaries. Without it, non-English text tokenizes wrong — “resumé” wouldn’t split correctly.

remove_diacritics 2 strips accents so “café” matches “cafe”. Critical for a personal tool where you might save articles in multiple languages.

Search queries use the MATCH operator:

conn.execute("""
    SELECT a.*,
           snippet(articles_fts, -1, '<mark>', '</mark>', '…', 20) AS matched_snippet
    FROM articles_fts
    JOIN articles a ON a.id = articles_fts.rowid
    WHERE articles_fts MATCH ?
    ORDER BY rank
    LIMIT 100
""", (fts_escape(query),))

Two SQL features doing real work here:

snippet(...) returns an excerpt from the matched text with the search terms wrapped in <mark> and </mark> tags. Column index -1 means “pick the best column automatically.” That’s what gives our results the highlighted “…async programming with Python’s asyncio library…” preview with the search terms highlighted. Same technique every serious search UI uses.

ORDER BY rank uses FTS5’s built-in BM25 ranking — matches with more occurrences of the search terms rank higher, matches in shorter documents rank higher, matches in the title rank higher than matches in the body. Better relevance than “most recent” ordering for open-ended search.

One footgun: user input can contain characters FTS5 treats as operators (AND, OR, NEAR, /, quotes, etc.). Feeding raw user input into MATCH risks syntax errors or unexpected behavior. Simple fix: quote each word individually so it’s treated as a literal term:

def _fts_escape(query):
    words = [w for w in re.split(r"\s+", query.strip()) if w]
    return " ".join('"' + w.replace('"', '""') + '"' for w in words)

That turns python/flask into "python/flask" — one literal term, no operators. Turns hello world into "hello" "world" — implicit AND across both terms. Simple, safe, works for any input.

Understanding Dark Mode Without the Flash

The classic dark-mode bug: user loads the page, sees a bright white flash for 100ms, THEN dark theme kicks in. Ugly, and gives away that dark mode is bolted on rather than built in.

The fix is: set the theme BEFORE any CSS renders. Which means a synchronous inline script at the very top of <head>, before the <style> tag:

<head>
  <script>
    (function() {
      var t = localStorage.getItem('rl-theme') || 'light';
      document.documentElement.setAttribute('data-theme', t);
    })();
  </script>
  <style>
    :root { --bg: #faf7f2; --text: #1a1a1a; ... }
    :root[data-theme="dark"] { --bg: #14181d; --text: #e6edf3; ... }
    body { background: var(--bg); color: var(--text); }
  </style>
</head>

The script runs synchronously (browsers block rendering on <script> tags without async or defer unless they’re modules). It reads the saved theme from localStorage, sets data-theme="dark" on the <html> element. Then the browser reads the CSS, sees the [data-theme="dark"] selector matches, applies the dark variables. Result: page renders dark immediately, no flash.

The CSS variables approach is what makes this clean. Instead of .dark-mode body { background: black; } in every place, we define variables once and reference them:

:root {
  --bg: #faf7f2;
  --text: #1a1a1a;
  --card: #ffffff;
  --muted: #6b6b6b;
  /* ... */
}
:root[data-theme="dark"] {
  --bg: #14181d;
  --text: #e6edf3;
  --card: #1c2128;
  --muted: #8b949e;
  /* ... */
}

Everything else in our CSS uses var(--bg), var(--text), etc. To add a new theme (sepia? high-contrast?), we’d just add another :root[data-theme="sepia"] block with different variable values. Zero changes to any other CSS.

The toggle button flips the attribute and saves the choice:

function toggleTheme() {
  var current = document.documentElement.getAttribute('data-theme');
  var next = current === 'dark' ? 'light' : 'dark';
  document.documentElement.setAttribute('data-theme', next);
  localStorage.setItem('rl-theme', next);
}

Total dark mode implementation: ~40 lines of CSS variables plus 20 lines of JS. Small effort, huge quality-of-experience improvement, especially for reading at night.

Understanding the Keyboard Shortcuts

Every tool you use daily is 4x faster with keyboard shortcuts. Gmail trained a whole generation of professionals to expect j/k for navigation, Enter to open, a for actions. Reddit and Twitter kept the muscle memory alive. Every keyboard-friendly interface uses the same vocabulary.

Our shortcuts are one document.addEventListener('keydown', ...):

document.addEventListener('keydown', function(e) {
  if (e.metaKey || e.ctrlKey || e.altKey) return;
  if (isEditable(e.target)) {
    if (e.key === 'Escape') e.target.blur();
    return;
  }

  if (e.key === '/') { e.preventDefault(); focusSearch(); return; }

  var cards = Array.from(document.querySelectorAll('.article-card'));
  if (cards.length) {
    var focusedIdx = cards.findIndex(c => c.classList.contains('kb-focus'));
    if (e.key === 'j' || e.key === 'ArrowDown') {
      focusedIdx = Math.min(focusedIdx + 1, cards.length - 1);
      setKbFocus(cards, focusedIdx);
    } else if (e.key === 'k' || e.key === 'ArrowUp') {
      focusedIdx = Math.max(focusedIdx - 1, 0);
      setKbFocus(cards, focusedIdx);
    } else if (e.key === 'Enter' && focusedIdx >= 0) {
      cards[focusedIdx].click();
    }
  }
});

Three details worth calling out:

Skip modifier keys. If user presses Cmd+K or Ctrl+J, that’s a browser shortcut — don’t hijack it. The first if (e.metaKey || ...) skips all combos with modifiers.

Skip inputs. If user is typing in the search box or a tag input, j/k/a should be regular typing, not shortcut activation. The isEditable check bails out early when the event target is an INPUT, TEXTAREA, or contenteditable element. The one exception: Escape inside an input blurs the input, so you can escape the search box back to keyboard-nav mode.

Use CSS class for focus state. We track the “focused” card via a kb-focus class rather than using the browser’s native :focus. Reason: browser focus behavior on scroll-into-view is buggy across browsers. Our own class + scrollIntoView({ block: 'nearest' }) gives predictable behavior.

The a shortcut on the reader page finds the archive form and submits it:

if (e.key === 'a') {
  var f = document.querySelector('form[data-shortcut-a]');
  if (f) f.submit();
}

And the archive form marks itself with data-shortcut-a:

<form method="post" action="/__u/dailypythonprojects.substack.com/article/1/archive" data-shortcut-a>
  <button type="submit" class="primary">Archive <kbd>a</kbd></button>
</form>

Nice separation — the JS doesn’t need to know URLs or article IDs. The form is the source of truth. Same pattern works if we add more shortcuts later.

Understanding Tags with Many-to-Many

Tags is the classic many-to-many database pattern. One article can have many tags. One tag can label many articles. So we need three tables:

CREATE TABLE tags (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL UNIQUE COLLATE NOCASE
);

CREATE TABLE article_tags (
    article_id INTEGER NOT NULL REFERENCES articles(id) ON DELETE CASCADE,
    tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
    PRIMARY KEY (article_id, tag_id)
);

The tags table stores tag definitions (name + id). The article_tags junction table has one row per article-to-tag link. Composite primary key (article_id, tag_id) means an article can’t be linked to the same tag twice — deduplication built into the schema.

COLLATE NOCASE on the tag name makes queries case-insensitive at the database level. So WHERE name = 'python' matches Python, PYTHON, and python, without us needing to do string comparisons in Python code. Same behavior as any modern web app’s tag input.

ON DELETE CASCADE on both foreign keys means: if we delete an article, the corresponding rows in article_tags are auto-deleted. Same for deleting a tag. Prevents orphaned rows without needing manual cleanup code.

Adding tags to an article is “get or create”:

def add_tags_to_article(article_id, raw):
    names = _parse_tag_input(raw)   # lowercase, split by comma, dedupe
    with db_connect() as conn:
        for name in names:
            conn.execute("INSERT OR IGNORE INTO tags (name) VALUES (?)", (name,))
            tag_row = conn.execute(
                "SELECT id FROM tags WHERE name = ? COLLATE NOCASE", (name,)
            ).fetchone()
            conn.execute(
                "INSERT OR IGNORE INTO article_tags (article_id, tag_id) "
                "VALUES (?, ?)", (article_id, tag_row["id"])
            )

INSERT OR IGNORE handles the “already exists” case silently — either the tag definition already exists, or the article-to-tag link already exists, and we just skip that step.

Removing a tag from an article optionally garbage-collects the tag definition too:

def remove_tag_from_article(article_id, tag_id):
    with db_connect() as conn:
        conn.execute(
            "DELETE FROM article_tags WHERE article_id = ? AND tag_id = ?",
            (article_id, tag_id),
        )
        conn.execute("""
            DELETE FROM tags WHERE id = ? AND NOT EXISTS (
                SELECT 1 FROM article_tags WHERE tag_id = ?
            )
        """, (tag_id, tag_id))

The second DELETE runs only if no other article has this tag — keeps the tags table from filling up with orphaned tag definitions from removed tags.

Understanding Markdown Export

The export feature is deceptively important. What it really means is: your library is not held hostage by this tool. You can export everything to plain text at any time and take it elsewhere — into Obsidian, into a git repo, into any note-taking app that reads Markdown, into another Read Later clone you build in five years.

Individual article export is a few lines:

def article_to_markdown(article):
    lines = [f"# {article['title'] or article['url']}", ""]
    meta = []
    if article['byline']: meta.append(f"**{article['byline']}**")
    if article['site_name']: meta.append(article['site_name'])
    if article['published_at']: meta.append(f"Published {article['published_at'][:10]}")
    if meta:
        lines.append(" · ".join(meta))
        lines.append("")
    lines.append(f"[Original]({article['url']})")
    lines.append("")
    lines.append("---")
    lines.append("")
    if article['content_html']:
        lines.append(html_to_md(article['content_html'], heading_style="ATX"))
    return "\n".join(lines) + "\n"

markdownify.markdownify() (imported as html_to_md) converts HTML to Markdown. It handles the annoying edge cases — nested lists, blockquotes with paragraphs inside, code blocks, links inside emphasis — that you’d otherwise have to write ~500 lines of regex to handle badly.

The whole-library zip export uses zipfile (stdlib) to stream a zip response:

def all_articles_zip():
    buf = io.BytesIO()
    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
        with db_connect() as conn:
            articles = conn.execute("SELECT * FROM articles ORDER BY saved_at DESC").fetchall()
        for a in articles:
            slug = _slugify(a["title"] or f"article-{a['id']}")
            filename = f"{a['id']:04d}-{slug}.md"
            zf.writestr(filename, article_to_markdown(a))
    return buf.getvalue()

io.BytesIO() is an in-memory file. We write the zip to it, then return the bytes as an HTTP response with Content-Type: application/zip and a Content-Disposition: attachment; filename="readlater-YYYY-MM-DD.zip" header. Browser triggers a download instead of trying to display the zip inline.

Filenames use NNNN-slug format (0042-why-python-is-slow.md) so they sort in save order in any file manager. Zero-padded IDs mean sorting stays correct even at 10,000+ articles.

Practical Use Cases

Bookmarklet becomes the entire save flow. Once installed, you never open the Read Later UI to save. You’re on Hacker News, see a good article, click your bookmarklet, popup confirms “Saved,” you’re back on Hacker News in under a second. That reduction in friction is what makes the tool actually get used daily.

Search becomes the entire retrieval flow. “I read something about SQLite triggers a few months ago” → hit /, type “sqlite trigger,” hit Enter, find it. The article you would otherwise have re-Googled to find is one keyboard shortcut away.

Tags for cross-cutting themes. Not for every article — that’s tedious. Just for the recurring themes worth clustering later. python, essays, career, startup-stories, long-reads — five tags cover most people’s actual usage. Click a tag pill to filter your queue.

Dark mode for reading in bed. The tool sitting on your laptop screen at 11pm is way easier on the eyes in dark mode. Once you toggle it once, it’s your default from then on because we save it to localStorage.

Export everything as backup. Once a month, hit /export.zip, save the file. If your laptop dies, your reading history isn’t gone — it’s in that zip, in plain text, forever.

Deploy on a home server for cross-device sync. Everything so far assumes local. But if you have a small always-on machine (Raspberry Pi, home NAS, VPS), run the server there instead of on your laptop. Configure the bookmarklet to point at that machine’s LAN address. Now the same queue is accessible from every device — laptop, phone, tablet, work computer. Same $5/month VPS could host this and Focus Timer from Week 32.

What’s Next

Thursday’s post is a standalone tutorial on a specific piece of infrastructure — free, all subscribers get it. Details Thursday morning.

Next week we pivot to something new — details on Tuesday.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

Read more

Mozilla is sunsetting Pocket. Instapaper feels frozen in 2013. Every “read it later” service in existence is one acquisition away from vanishing, taking your entire reading history with it. And the whole problem — save a URL, extract just the article, read it later — is genuinely 600 lines of Python you can write in a weekend and use forever.

This week we build it. Save any article’s URL, and the tool fetches the page, strips out the nav / ads / cookie banners / sidebars / “related articles” / newsletter popup / footer, and stores a clean reader-view copy in a SQLite database on your machine. Open the tool in your browser, see your queue, click one, read it in beautiful typography with none of the design that made you want to leave the original page. Archive when done. Weeks or months later, when you think “I read something about X” — it’s still there, still readable, even if the original page has died or gone behind a paywall.

Day 1 is the working MVP — save via web form or CLI, extract with trafilatura, store extracted content plus the raw HTML for future re-extraction, queue view, reader view, archive/delete actions, and graceful failure for the sites that resist extraction. Day 2 adds the bookmarklet for one-click saving from any page, full-text search across everything you’ve ever saved, tags, dark mode, keyboard shortcuts, and export to Markdown.

Projects in this week’s series:

Day 1: Save, extract, and read articles from a local web UI (Today)

You start the server with python readlater.py and it opens http://127.0.0.1:8770 in your browser. The queue page shows a URL input box at the top and your saved articles beneath. Paste any URL, click Save, and the tool fetches the page, extracts the article, and pushes it to the top of your queue with a title, byline, site name, reading time, and a short excerpt:

Click any article and you land on the reader view — clean serif typography, generous line-height, comfortable reading column, no distractions. The original site’s URL is one click away if you want it, but you probably don’t:

There you have a clean distraction-free view you can read and en joy.

Day 2: Bookmarklet, full-text search, tags, dark mode, and export

Save from ANY page in ANY browser with one click via a bookmarklet you drag to your browser bar — no more copy-paste-open-app-paste dance. Search across every article you’ve ever saved with SQLite FTS5, finding phrases from articles you saved months ago. Tag articles (”python”, “essays”, “long-reads”) for organization. Dark mode for night reading. Keyboard shortcuts (j/k to move through the queue, Enter to open, a to archive). Export any article or your whole archive to Markdown for keeping in your notes app or a git repo.

View All Projects This Week

About the stack

Flask for the web server — small, mature, single-user local tools don’t need async. Same choice as Week 32’s focus dashboard.

trafilatura for content extraction. Actively maintained (last update this year), specifically designed for extracting article content from arbitrary web pages, ships a well-tested extraction algorithm with metadata support out of the box. Gives you the article’s title, author, publication date, and site name for free — all in one call. It’s what many news aggregators and research tools use under the hood in 2026.

requests for HTTP. Battle-tested, still the gold standard for fetching a URL with sensible defaults.

sqlite3 (stdlib) for storage. One file on disk at ~/.readlater/readlater.db. Perfect for personal-scale — a few hundred saved articles is under 10 MB, a few thousand is under 100 MB.

Jinja2 for templates (bundled with Flask). Templates live inside our Python file as strings, loaded via DictLoader — same pattern we used in Weeks 28 and 32. One file, no separate templates/ folder.

Setup Instructions

Install three packages:

pip install flask trafilatura requests

Run:

python readlater.py                        # start the web server on :8770
python readlater.py save <URL>             # save from the terminal, no server needed
python readlater.py list                   # print the queue to the terminal

On first run, the tool creates ~/.readlater/ (a hidden folder in your home directory) with the SQLite database inside. This is where all your saved articles live. Back it up if you care about them, migrate it between machines to move your library.

No sudo required — this tool doesn’t touch anything system-level. Just saves stuff in your home directory and serves a web page on localhost.

Understanding Content Extraction

The hardest technical problem this project solves is: given a web page’s HTML, return just the article, without the surrounding junk.

The naive approach — “look for a <article> tag” — works maybe 30% of the time. Most pages don’t have semantic HTML. Some do, but the article is wrapped in twenty divs with class names like story-body-inner-wrapper-v3. Others have the article split across multiple divs with ads injected between paragraphs. Cookie consent modals, newsletter signup popups, “you might also like” carousels — the DOM is a battlefield.

The right approach is a statistical content extractor — an algorithm that scores every text-containing element in the page by likelihood-of-being-content vs likelihood-of-being-chrome, based on things like text density, link density, tag depth, and neighboring element scores. This is what trafilatura does, along with readability-lxml, newspaper3k, and the original Arc90 Readability algorithm that Firefox and Safari’s reader modes are based on.

The whole extraction step in our code is one function call:

extracted = trafilatura.extract(
    raw_html,
    output_format="json",
    with_metadata=True,
    include_comments=False,
    include_tables=True,
    include_images=False,
    favor_precision=True,
)

output_format="json" gives us title, author, publication date, site name, and cleaned text in one structured response. favor_precision=True biases toward “less content but cleaner” over “more content but might include some junk” — the right trade-off for a reader tool where readability trumps completeness.

Then we call trafilatura.extract a second time with output_format="html" to get the article as clean HTML with paragraph and heading structure preserved. That’s what the reader view renders. Text alone would be readable but less pretty — headings and blockquotes and lists all render better as HTML.

Understanding the Raw HTML Archive

Notice that we store both the extracted content AND the original raw HTML:

CREATE TABLE articles (
    ...
    content_html TEXT,     -- cleaned reader view
    content_text TEXT,     -- plain text for search
    raw_html TEXT,         -- the full original page bytes
    ...
)

Storing the raw HTML seems wasteful — the extracted content is what the user actually reads. Why keep 200 KB of DOM when 20 KB of article text would do?

Two reasons, both about future-proofing:

First, extraction algorithms improve. trafilatura in 2026 is way better than readability was in 2019. In 2030 there’ll be something better than both. If we only store the extracted version, we’re frozen at today’s algorithm quality forever. If we keep the raw HTML, we can re-extract with a better tool later. That’s the same reason photographers keep RAW files instead of just JPEGs — the source data is more valuable than any one processed version of it.

Second, the original page might die. Blogs shut down. Companies pivot and delete their content marketing. Paywalls appear in front of previously-free articles. Domains expire. When any of these happens, your extracted content still works — but you can’t verify it against the source, or notice you extracted a truncated version, without the raw HTML. Having the original bytes means your archive is truly permanent.

Storage cost is trivial. Even 5,000 saved articles at 200 KB each is 1 GB. That’s less than one HD movie.

Understanding URL Normalization

Same article, three different URLs:

https://blog.example.com/why-python?utm_source=twitter&utm_medium=social
https://blog.example.com/why-python?utm_source=newsletter&utm_campaign=weekly
https://blog.example.com/why-python#comments

All three point to the same content. If we treat them as different URLs and don’t dedupe, saving the article via Twitter, then via the newsletter link, then bookmarking it — three duplicate entries. That’s a silly failure mode. Real read-later tools normalize URLs before storing them.

Our normalize_url function strips ~25 common tracking parameters (all utm_* variants, fbclid, gclid, mc_cid, ref, and friends), lowercases the host, drops the fragment (#section — that’s client-side navigation, doesn’t identify content), and adds https:// if the scheme was missing:

TRACKING_PARAMS_TO_STRIP = {
    "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content",
    "fbclid", "gclid", "mc_cid", "mc_eid", "ref", "ref_src",
    # ...
}

def normalize_url(url):
    parsed = urlparse(url)
    kept = [(k, v) for k, v in parse_qsl(parsed.query)
            if k.lower() not in TRACKING_PARAMS_TO_STRIP]
    return urlunparse((
        parsed.scheme,
        parsed.netloc.lower(),
        parsed.path,
        parsed.params,
        urlencode(kept),
        "",              # drop fragment
    ))

Then the database has a UNIQUE constraint on url, so re-saving an already-saved article updates the existing row instead of creating a duplicate. And re-saving un-archives it, because saving an article you already read means you probably want it back in your queue for another look.

Understanding Graceful Extraction Failure

Some websites cannot be extracted. JavaScript-heavy sites (Twitter posts, most SaaS blogs with client-side rendering) return an empty HTML shell that fills in with JS after page load — trafilatura sees empty divs. Paywalled sites return a login page. Some sites detect our requests fetch as a bot and serve a captcha instead.

The wrong response to this is: refuse to save the URL. That would break the user’s mental model. They intended to save the article; the tool failing to extract shouldn’t discard their intent.

The right response is: save the URL anyway, mark it as extraction-failed, and show a helpful message in the reader view:

def save_url():
    extraction = fetch_and_extract(url)
    article_id, was_new = save_article(extraction)

    if extraction.extraction_succeeded:
        msg = "Saved."
    else:
        msg = ("Saved the link, but couldn't extract the article content. "
               "You can still click through to the original.")
    return redirect(url_for("queue", flash=msg))

In the queue, failed articles appear with italic muted titles and a small saved link only tag so users know they’ll be clicking through to the original site instead of a reader view. In the reader, they get a friendly panel explaining what happened and a prominent “open original” link.

This turns a hard failure into a soft one. The tool becomes a reliable bookmark holder even for content it can’t perfect. Users trust it more, and the failed cases teach us over time what sites need better extraction (Day 2 will add fallback extractors).

Understanding the Reader Typography

The whole point of a read-later tool is a better reading experience than the original page. That means the typography has to be genuinely nice, not just “an HTML page”:

.article-body {
  font-family: Georgia, "Times New Roman", serif;
  font-size: 1.15rem;
  line-height: 1.7;
  color: #262626;
}
.article-body p { margin: 0 0 1.1em; }
main.wrap { max-width: 780px; margin: 0 auto; }

A few decisions here are worth understanding:

Serif for the body. Georgia is the classic web-safe serif that renders well at any size. Serif fonts are traditionally considered easier to read for long passages of text, though the modern research is mixed. What matters more is that serif signals long-form reading — the same content in Arial feels like a blog post, in Georgia it feels like a book. That signal changes how you engage with it.

780px maximum content width. Line length matters enormously for reading comfort. Below 400px, your eyes have to jump back too often. Above 900px, you lose your place returning to the start of the next line. The sweet spot for readable prose is 50-75 characters per line, which at 18px font size is roughly 600-800px of column width. 780px is a comfortable middle.

1.7 line-height. Default browser line-height is around 1.2. That’s too tight for extended reading — the lines feel packed together. 1.7 gives the eye breathing room. Every good reader interface (Medium, Instapaper, Kindle) uses something between 1.5 and 1.8.

Off-white background (#faf7f2). Pure white can feel harsh in low light. A very slight warm off-white is easier on the eyes without being obviously “sepia mode” busy. Same logic as e-readers.

Sans-serif for UI, serif for content. The nav bar and buttons are -apple-system (Apple’s system font, which adapts to whatever the reader’s OS is). The article body is Georgia. That split makes the article visually distinct from the interface — you’re reading content, not clicking through an app.

These choices took ~50 lines of CSS total. Small effort, huge quality-of-experience win.

Practical Use Cases

Killing the “40 open tabs” problem. The main use case. See something interesting → save → close the tab → guilt evaporates. Come back to it in a quiet moment.

Reading during commutes without WiFi. Since everything is stored locally, articles read fine on a plane, in a subway, or anywhere with bad reception. As long as you saved them before losing signal.

Building a personal knowledge archive that survives platform deaths. Everything you save is yours forever, in a plain SQLite file you can back up, migrate, or export from. When (not if) some blog you love goes offline in 2028, you still have the articles you saved.

Sending yourself long-reads across devices. Save from your work laptop, read on your phone, archive from your tablet. The database is a single file — put it on Dropbox or Syncthing or a home NAS and every device sees the same queue.

Foundation for Day 2. Every function we built today gets reused tomorrow. fetch_and_extract gets a fallback chain for tough sites. save_article gains a tags table. list_articles grows a search parameter. humanize_time gets keyboard shortcut friends. The engine stays; the interface expands.

Coming Wednesday

Tomorrow we add the bookmarklet — one drag to your browser bar, then any page you’re on gets saved with one click. Full-text search across everything you’ve ever saved, powered by SQLite FTS5. Tags for organization. Dark mode for night reading. Keyboard shortcuts (j/k to navigate, Enter to open, a to archive, / to search). Export any article or your whole library to Markdown for keeping in your notes app or a git repo.

If you want the full tool, upgrade here before Wednesday.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

View Code Solution

Same blocking engine underneath. Exact same add_block_entries / remove_block_entries / flush_dns code we wrote yesterday, just wired into a Flask web UI with SQLite-backed stats. That’s the pedagogical arc of the week: write the engine on Day 1, wrap it in a product on Day 2. When your engine is a pure function that operates on a hosts file, you can wrap it in a CLI or a web app or a menu bar app or a Discord bot without changing the engine. The interface layer is the thing that changes; the engine stays the same.

Projects in this week’s series:

Day 1: CLI focus timer with real website blocking

Yesterday, we built a stdlib-only CLI that starts a focus session for N minutes, edits /etc/hosts (or the Windows equivalent) to make distracting sites unreachable via DNS, shows a live countdown in the terminal, and cleans everything up automatically — whether the timer completes normally, you Ctrl+C, or the process crashes. Zero external dependencies, three-layer cleanup safety net, marker-based hosts editing so we never touch anything else in the file.

Day 2: Web dashboard with presets, stats, streaks, and break enforcement (Today)

Run sudo python focus_dashboard.py and it starts a local server on http://127.0.0.1:8765 and auto-opens your browser. The dashboard shows named preset cards — Pomodoro (25 min), Deep work (90 min), Study (45 min), Quick focus (15 min). Click one and the session starts instantly, the block goes into effect, and the page swaps to a big centered countdown:

The countdown ticks smoothly in the browser without hammering the server — the JavaScript decrements locally every 200 ms and re-syncs with the server every 5 seconds. Below the timer, your daily stat cards show how much you’ve focused today, this week, your current streak, and your longest streak ever. Tab across to the Stats page for the deep view — a 30-day bar chart of daily focus minutes plus a table of your last 30 sessions with completion status:

Note: When a session completes, you don’t get to start another one immediately. The tool imposes a proportional break window — 20% of the session duration, clamped to 5-20 minutes — and refuses to start a new session until the break ends. That can be a good thing for users not to trick the program.

And the Presets page lets you edit the list — add “Writing sprint” (45 min with hackernews.com in the extras), “Morning deep work” (2 hours with LinkedIn added), whatever your workflows are. Stored as JSON at ~/.focustimer/presets.json so you can hand-edit them too.

View All Projects This Week

About the stack

Flask is the web framework — a change of pace after several weeks of FastAPI. Flask has been the classic “Python web app in one file” tool for over a decade. Its request/response model is synchronous and straightforward, which is exactly right for a single-user local tool where we don’t need async concurrency.

Jinja2 is the templating engine (bundled with Flask). We put templates inside our Python file as strings and load them via DictLoader — same pattern as the Notes app in Week 28. Full template inheritance, includes, filters, everything works.

sqlite3 is Python’s built-in database (stdlib since 2.5). No installation, no server, one file on disk at ~/.focustimer/focus.db. Perfect for personal-scale persistence.

threading runs the focus session in a background thread alongside the Flask request handlers. A threading.Lock protects the session state from concurrent read/write, and a threading.Event lets the main thread signal “stop early” to the session thread.

Chart.js from a CDN renders the 30-day bar chart. Battle-tested, works in every browser, one script tag.

Pico.css from a CDN styles the whole thing. Classless — write plain semantic HTML, get a professional look. Same choice we’ve made every week for a reason: it just works.

Setup Instructions

Install Flask (the only new dependency on top of Day 1):

pip install flask

Run:

sudo python focus_dashboard.py                # localhost:8765, auto-opens browser
sudo python focus_dashboard.py --port 8888    # custom port
sudo python focus_dashboard.py --no-browser   # don't auto-open
sudo python focus_dashboard.py --unblock      # emergency unblock, then exit

The recommended workflow is to leave one terminal tab running the server all day, and pin the dashboard tab in your browser. Ctrl+C in the terminal to shut down cleanly — the block is removed automatically if any session was active.

On first run, the tool creates ~/.focustimer/ (a hidden folder in your home directory) with two files inside: presets.json (editable) and focus.db (SQLite). Both survive across restarts, so your stats and custom presets persist.

Understanding the Reusable Engine Pattern

The single most important design decision this week: Day 2 doesn’t reinvent the blocking engine, it reuses it. Every function from Day 1 that does the actual work — add_block_entries, remove_block_entries, flush_dns, is_hosts_active, get_hosts_file, is_admin — appears again in Day 2, unchanged. Copy-paste from Day 1’s focus.py into Day 2’s focus_dashboard.py, no modifications required.

That copy-paste is intentional. Both files are self-contained — a subscriber can download either one and run it, without needing the other in the same folder. If you were writing this as a real project you’d factor the shared code into a focus_core.py module and import from it, but for teaching purposes the redundancy makes each day standalone.

The lesson underneath: when your engine is pure logic (takes inputs, mutates a file, returns nothing), it composes into any interface. CLI, web app, mobile app, cron job, all valid wrappers. The engine has no idea whether a human typed a command or clicked a button. That separation is what lets big software companies ship the same core to a web app and a mobile app and a desktop app.

Understanding the Threaded Session

The tricky part of Day 2 is: how do you run a long-running timer alongside a web server without either blocking the other?

The answer is threading. The Flask process runs the HTTP server on the main thread; when the user clicks “Start Pomodoro”, the request handler spawns a background thread that runs the countdown and does the eventual unblock:

class FocusSession:
    def start(self, preset):
        with self._lock:
            # ... update state to "active", record preset details ...
            self._stop_event.clear()

        # Do the actual blocking OUTSIDE the lock (DNS flush can be slow)
        add_block_entries(self.hosts_file, self.sites)
        flush_dns()

        self._thread = threading.Thread(target=self._run, daemon=True)
        self._thread.start()

    def _run(self):
        end_time = self.started_at + timedelta(seconds=self.duration_seconds)
        while datetime.now() < end_time:
            if self._stop_event.wait(0.5):     # returns True if event was set
                self._finish(completed=False)
                return
        self._finish(completed=True)

Two important patterns here:

threading.Event for cooperative interruption. The _stop_event.wait(0.5) sleeps for up to 500 ms but returns immediately if another thread calls set() on the event. So when the “Stop early” button posts to /session/stop, that request handler does self._stop_event.set(), and within 500 ms the session thread notices, breaks out of the loop, and unblocks. No busy-waiting, no polling, no killing threads (Python doesn’t actually let you kill a thread — cooperation via events is the right pattern).

daemon=True threads. A daemon thread doesn’t prevent the process from exiting. If the user Ctrl+Cs the server while a session is running, the daemon thread dies without cleanup. That’s OK because our atexit handler (registered separately) removes the hosts file entries before the process actually terminates. Same three-layer cleanup pattern as Day 1: explicit unblock in the finish method, atexit for normal exit, signal handlers for Ctrl+C.

Lock discipline. State mutations happen inside with self._lock:. External calls (adding block entries, DNS flush) happen outside the lock — they can take hundreds of milliseconds and holding the lock during them would freeze the API. The rule: only hold the lock for the duration of the state mutation itself, never during I/O.

Understanding the Live Countdown Without Server Hammering

The dashboard shows a smooth ticking countdown. The naive way to do this would be to poll /api/status every 200 ms — 300 requests per minute per open browser tab. Left open for 8 hours: 144,000 requests. That’s crazy for a local tool.

The correct pattern is client-side interpolation with periodic server sync:

let state = { state: 'active', remaining: 3547, lastSync: Date.now() };

function render() {
  const elapsed = (Date.now() - state.lastSync) / 1000;
  const remaining = Math.max(0, state.remaining - elapsed);
  activeTime.textContent = mmss(remaining);
}

async function sync() {
  const res = await fetch('/api/status');
  const data = await res.json();
  state = {
    state:     data.state,
    remaining: data.remaining_seconds || 0,
    lastSync:  Date.now(),
    // ...
  };
  render();
}

setInterval(render, 200);   // smooth local tick, no network
setInterval(sync,   5000);  // sync with server every 5 seconds

The render function reads state.remaining (last known value from server) and subtracts the local elapsed time since that value was received. So the countdown appears to tick every 200 ms even though the actual authoritative value is only refreshed every 5 seconds. Feels smooth to the user, gentle on the server — 12 requests per minute instead of 300.

The state-change reload trick handles transitions between active / break / idle — if the top-level state changes between syncs, we call window.location.reload() to pick up the freshly server-rendered dashboard with the correct view. Cheap and correct.

Understanding the Stats Database

The sessions table is stupidly simple:

CREATE TABLE sessions (
    id INTEGER PRIMARY KEY,
    preset_name TEXT,
    started_at TEXT,             -- ISO-8601 local time
    duration_seconds INTEGER,
    completed_seconds INTEGER,   -- actual focused time (< duration if stopped early)
    was_completed INTEGER
)

Every finished session (completed OR interrupted) gets one row. That’s it. Everything on the stats page is derived from this table via SQL:

def total_seconds_since(start_date):
    row = conn.execute("""
        SELECT COALESCE(SUM(completed_seconds), 0) AS total
        FROM sessions
        WHERE date(started_at) >= ?
    """, (start_date.isoformat(),)).fetchone()
    return int(row["total"])

date(started_at) is SQLite’s date function — extracts just the date portion of an ISO-8601 timestamp. So we can group sessions by day trivially. COALESCE(SUM(...), 0) returns 0 when there are no rows, avoiding a null response.

Streak calculation is the fun part. Walk backwards from today, day by day, counting how many consecutive days have at least one session:

session_days = {r["d"] for r in conn.execute(
    "SELECT DISTINCT date(started_at) AS d FROM sessions"
).fetchall()}

current_streak = 0
d = today
while d.isoformat() in session_days:
    current_streak += 1
    d -= timedelta(days=1)

The grace clause: if today has no session yet but yesterday does, the streak continues (haven’t broken it yet, still time to redeem the day). Same principle as Duolingo’s “streak freeze” — a small psychological accommodation that keeps people from despairing at 11pm.

Longest streak is a scan over all session days sorted ascending, tracking the longest consecutive run:

sorted_days = sorted(date.fromisoformat(d) for d in session_days)
run = 1
longest_streak = 1
for i in range(1, len(sorted_days)):
    if (sorted_days[i] - sorted_days[i - 1]).days == 1:
        run += 1
        longest_streak = max(longest_streak, run)
    else:
        run = 1

O(N) where N is the total number of days you’ve ever done a focus session. Fast even after years of use.

Understanding Break Enforcement

The whole point of a focus tool is not “maximize hours in front of screen with notifications off.” The point is sustainable deep work. Chaining focus sprints without breaks reliably leads to burnout — every productivity researcher will tell you the same thing. So Day 2 enforces breaks structurally:

def _compute_break_seconds(self, session_seconds):
    """20 percent of session, clamped to 5-20 minutes."""
    return int(min(20 * 60, max(5 * 60, session_seconds * 0.20)))

25-minute pomodoro → 5-minute break. 45-minute study session → 9-minute break. 90-minute deep work → 18-minute break. These proportions come from actual attention-restoration research (Kaplan’s ART) — longer focus needs proportionally longer rest.

When a session completes normally, the state transitions to "break" and break_until is set:

def _finish(self, completed):
    remove_block_entries(self.hosts_file)
    flush_dns()

    with self._lock:
        # ... record in stats DB ...
        if completed:
            break_secs = self._compute_break_seconds(self.duration_seconds)
            self.break_until = datetime.now() + timedelta(seconds=break_secs)
            self.state = "break"
        else:
            self.state = "idle"      # no break if you stopped early

Only completed sessions earn a break — if you stop early, you go straight back to idle. That subtle design choice prevents the exploit where you “start a session, immediately stop, then complain the break is stopping you from starting again.”

Attempts to start a new session while on break are rejected with a friendly countdown:

def start(self, preset):
    with self._lock:
        if self.state == "break":
            remaining = int((self.break_until - datetime.now()).total_seconds())
            if remaining > 0:
                m, s = divmod(remaining, 60)
                raise SessionError(
                    f"You're on a break for another {m}m {s:02d}s. "
                    "Rest, then start the next session."
                )

The SessionError bubbles up to the Flask handler, which redirects back to the dashboard with the message in a flash banner.

Understanding Local-Only Binding

The whole app binds to 127.0.0.1, not 0.0.0.0:

app.run(host="127.0.0.1", port=args.port,
        debug=False, threaded=True, use_reloader=False)

That single-word change from 0.0.0.0 to 127.0.0.1 means the server is only reachable from the same machine. Other devices on the LAN can’t see it. Your neighbor at the coffee shop can’t hit http://your-laptop.local:8765/session/stop to sabotage your focus. This is why we don’t need any auth — the OS-level network binding is the auth.

Contrast with LAN Share from Week 30, which bound to 0.0.0.0 precisely because we wanted other LAN devices to reach it, and therefore needed a PIN gate. Different tool, different security model, different binding.

threaded=True is essential because the background session thread needs to run alongside HTTP request handlers. use_reloader=False disables Flask’s dev-mode reloader, which would fork the process and destroy our in-memory session state.

Practical Use Cases

All-day pinned focus tab. Pin the dashboard tab in Chrome/Firefox/Safari. When you sit down to work, click a preset. Focus. Break. Click another. Repeat. Because it’s a browser tab, it’s always one keyboard shortcut away — no window management, no menu bar dance.

Weekly focus reports. The stats page shows exactly how many hours you focused this week. If you’re managing your own time as a freelancer, contractor, or founder, this is actually meaningful data — vastly more honest than “how did last week feel?”

Team focus challenges. Everyone in a small team runs the same tool, screenshots their weekly stats page every Friday. Not for judgment — for peer accountability. Turns out most people focus a lot less than they think they do, and seeing “9h focused this week” concretely changes behavior.

Kids doing homework blocks with visible progress. Parents can start a 45-minute Study session with expanded blocks (add Roblox, Discord, whatever the current addictions are). Kids see the countdown, know when it ends, get their brain break automatically enforced.

Baseline for a menu bar app. Everything we built today can be wrapped in a menu bar UI on macOS with rumps, a system tray app on Windows with pystray, or a GNOME extension on Linux. The engine and stats stay the same; the interface changes.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

Read more

This week we build a focus tool that removes the willpower part entirely. During a focus session, distracting sites don’t load. Not “muted”, not “hidden behind a nag screen” — the browser genuinely cannot reach them. Type reddit.com, get “This site can’t be reached.” Every time. For the duration you chose. When the timer ends, everything is unblocked automatically. If you Ctrl+C to give up, everything unblocks. If the script crashes, everything unblocks. The only way to keep sites blocked forever is to unplug your computer, which is another approach entirely.

Day 1 is the CLI tool — one Python file, zero external dependencies, works on macOS, Linux, and Windows. Day 2 wraps the same engine in a web dashboard with charts, streak tracking, per-site rules, and named presets (”deep-work”, “study”, “morning”). Both days build on the same core insight: you can edit your machine’s hosts file to make specific domains unreachable at the DNS level, and that’s the same technique advertisers, security researchers, and Pi-hole users have been using for years. We’re just wrapping it in a timer.

Projects in this week’s series:

Day 1: CLI focus timer with real website blocking (Today)

When you run the script with a number of minutes, it starts a live countdown right in your terminal. Big centered time, subtle context lines beneath, and behind the scenes your hosts file is now telling every DNS lookup for Reddit, Twitter, YouTube, TikTok, Facebook, Instagram, and Hacker News to go to 127.0.0.1. Where nothing is listening. So the browser gives up:

Try to open one of the blocked sites during the session and you get this — the browser genuinely cannot reach it, and no “unblock” button anywhere will change that until the timer ends:

The moment the timer hits zero — or you Ctrl+C early, or the script crashes, or your laptop shuts down and reboots — the block is removed automatically. Sites come back. No manual cleanup required.

Day 2: Web dashboard with charts, streaks, and named presets

The same blocking engine, wrapped in a web UI you can pin as a browser tab. Named presets (”deep-work 90 min”, “pomodoro 25/5”, “study 45 min”) save your favorite combos of duration + blocklist. Per-site rules let you allow LinkedIn during work hours but block it after 6pm, or unblock YouTube only for tutorials on a whitelist of channels. A dashboard on the front page shows your focus time today, this week, and this month, plus your longest streak of consecutive days with a focus session:

Users can set a focus session by clicking on of the items on the dashboard:

Break enforcement, too — after a completed focus session, the app enforces a mandatory break window where refocusing is disabled. Because the way you burn out isn’t by focusing too hard, it’s by never letting your brain rest between sprints.

View All Projects This Week

About the stack

Zero external dependencies. No pip install step. Just save the file and run it. That’s a deliberate design choice for system-level tools like this — every extra dependency is another thing that could break in six months when the maintainer decides to change an API, or when Python 3.15 ships and something isn’t ready. For a tool you want to still work in five years, stdlib-only is a real feature.

argparse parses the command-line arguments. Standard library, has been in Python since 3.2, will work forever. Handles --add, --list-sites, --unblock, and the positional minutes argument.

pathlib manages paths to the hosts file. Cross-platform out of the box — /etc/hosts on macOS and Linux, C:\Windows\System32\drivers\etc\hosts on Windows.

subprocess runs the DNS-cache flush commands (dscacheutil on macOS, resolvectl on Linux, ipconfig /flushdns on Windows). Same standard library, best-effort — if the flush command doesn’t exist, the block still works, just with a few seconds of stale cache before it kicks in.

signal and atexit are the cleanup safety net. Signal handles Ctrl+C and SIGTERM gracefully. Atexit runs on any process exit, including unhandled exceptions — so even if the script crashes with a bug, your hosts file gets cleaned up before Python shuts down. Data integrity is critical here: the failure mode of “sites stay blocked forever because we crashed” would be a genuinely bad bug.

ANSI escape codes for the terminal UI — colors, cursor positioning, in-place redraws. All modern terminals on macOS, Linux, and Windows Terminal support them natively. Old Windows CMD shows raw codes but the tool still functions.

Setup Instructions

No installation. Save the script as focus.py and run:

sudo python focus.py 25                      # 25-minute focus session
sudo python focus.py 90 --add twitch.tv      # add extra site to block
sudo python focus.py --unblock               # emergency unblock
python focus.py --list-sites                 # show default blocklist (no sudo)

On Windows, right-click your terminal (or PowerShell) and pick “Run as Administrator” instead of using sudo. Same script, same commands, just the elevation mechanism is different.

The reason for sudo: editing /etc/hosts requires root, and there’s no clean way around that. It’s the whole point — if any random program could edit your hosts file, malware would use it constantly. The permission gate is a security feature, not a bug.

Understanding the hosts File

This whole project rests on one piece of infrastructure everyone has and almost nobody thinks about — the hosts file.

Your operating system resolves domain names through a chain. When your browser wants reddit.com, the OS asks “who is reddit.com?” and the first place it checks is a plain text file. On macOS and Linux that file lives at /etc/hosts. On Windows it’s at C:\Windows\System32\drivers\etc\hosts. The file has been there since roughly forever — it predates DNS by about a decade.

The format is dead simple: one line per entry, IP address then hostname:

127.0.0.1 localhost
::1 localhost
127.0.0.1 reddit.com

The OS reads this file every time it needs to resolve a name, and if the name matches something in the file, it uses that IP and never asks a real DNS server. So 127.0.0.1 reddit.com means “when anything on this machine tries to reach reddit.com, send it to 127.0.0.1 instead.” 127.0.0.1 is your own machine, where nothing is listening for reddit’s traffic, so the browser gets connection refused and shows “This site can’t be reached.”

This isn’t a hack. It’s how the system is designed to work. Advertisers use hosts-file entries to block ad servers. Pi-hole uses network-level DNS blocking based on the same idea. Malware researchers block command-and-control servers this way. We’re just using it for focus.

The only catch: editing the hosts file requires root/admin privileges. That’s why the tool needs sudo. It’s not asking for those privileges to snoop on your system — it’s asking for the exact minimum permission needed to add a few lines to one specific file.

Understanding Marker-Based Edits

Never, ever, ever overwrite the whole hosts file. Your system has important entries in there — localhost, IPv6 mappings, entries added by Docker, VPN clients, corporate tools. Wiping them and rewriting from scratch would break things you didn’t know you had.

The right pattern is marker-based editing: wrap our block section in commented markers, and on removal only touch lines between those markers:

BEGIN_MARKER = "# BEGIN focustimer -- do not edit; managed by focus.py"
END_MARKER = "# END focustimer"

def add_block_entries(hosts_file, sites):
    remove_block_entries(hosts_file)   # idempotent: clear old block first
    existing = hosts_file.read_text() if hosts_file.exists() else ""
    if existing and not existing.endswith("\n"):
        existing += "\n"

    block = [BEGIN_MARKER]
    for site in sites:
        block.append(f"127.0.0.1 {site}")
    block.append(END_MARKER)
    block.append("")

    hosts_file.write_text(existing + "\n".join(block))

Removal is symmetric — walk the file line by line, and while we’re between our markers, drop those lines. Everything else stays exactly where it was:

def remove_block_entries(hosts_file):
    if not hosts_file.exists():
        return False
    content = hosts_file.read_text()
    if BEGIN_MARKER not in content:
        return False

    lines = content.splitlines(keepends=True)
    out_lines = []
    inside_block = False
    for line in lines:
        stripped = line.rstrip("\n\r")
        if stripped == BEGIN_MARKER:
            inside_block = True
            continue
        if stripped == END_MARKER:
            inside_block = False
            continue
        if not inside_block:
            out_lines.append(line)

    hosts_file.write_text("".join(out_lines).rstrip() + "\n")
    return True

Two properties this gives us for free: the function is idempotent (calling it twice is safe — the second call is a no-op), and it’s crash-tolerant (if a previous session died without cleanup, the next run’s add_block_entries sees the old markers, removes them, and writes fresh ones).

We tested this by writing a hosts file with several unrelated entries, running the full add/remove cycle, and confirming the file came back identical to how it started. Round-trip preserving.

Understanding Cleanup Safety

The single most important behavior of this tool is: at the end of every possible execution path, the hosts file must be clean.

If Ctrl+C is pressed, sites must unblock. If the process crashes with an unhandled exception, sites must unblock. If the timer completes normally, sites must unblock. There’s no acceptable outcome where the user’s hosts file gets left blocked forever because a script died mid-session.

The way we get all three is a two-layer defense — signal handlers plus atexit:

def cleanup():
    if remove_block_entries(hosts_file):
        flush_dns()

atexit.register(cleanup)

def _sig_handler(signum, frame):
    print(f"Session interrupted. All sites unblocked.")
    sys.exit(128 + signum)

signal.signal(signal.SIGINT, _sig_handler)
signal.signal(signal.SIGTERM, _sig_handler)

atexit.register runs the callback whenever the Python interpreter exits normally — including when an unhandled exception propagates out of main. So if we hit a bug during the countdown, the exception unwinds, Python starts shutting down, and atexit runs cleanup before actually terminating. Hosts file gets restored.

Signal handlers for SIGINT (Ctrl+C) and SIGTERM (the polite shutdown signal) convert the signal into a normal sys.exit. Because sys.exit triggers atexit, the cleanup runs.

The one case this doesn’t cover is SIGKILL (kill -9) or a power outage — no software can clean up when the OS kills you instantly. That’s what --unblock is for. If you find yourself unable to reach Reddit and don’t remember running a focus session, run sudo python focus.py --unblock and you’re back to normal.

Understanding DNS Cache Flushing

Editing the hosts file changes the source of truth immediately, but your OS may have cached the old resolution for a domain you’re blocking. Result: you edit the file, then your browser still loads Reddit for a few seconds via the cached DNS entry.

The fix is flushing the DNS cache after every hosts change:

def flush_dns():
    system = platform.system()
    try:
        if system == "Darwin":
            subprocess.run(["dscacheutil", "-flushcache"], check=False, capture_output=True)
            subprocess.run(["killall", "-HUP", "mDNSResponder"], check=False, capture_output=True)
        elif system == "Linux":
            r = subprocess.run(["resolvectl", "flush-caches"], check=False, capture_output=True)
            if r.returncode != 0:
                subprocess.run(["systemd-resolve", "--flush-caches"], check=False, capture_output=True)
        elif system == "Windows":
            subprocess.run(["ipconfig", "/flushdns"], check=False, capture_output=True, shell=True)
    except (FileNotFoundError, subprocess.TimeoutExpired):
        pass

Every platform has its own command. macOS needs two calls — one to flush the userspace cache and one to signal the mDNS resolver to reload. Linux switched from systemd-resolve to resolvectl a few years ago so we try both. Windows has had ipconfig /flushdns since Windows 2000 and it just works.

The capture_output=True and check=False mean the calls are best-effort — if the flush command isn’t available or fails, the block still works, just with a few seconds of stale cache before the browser catches up. The tool never crashes over a failed flush.

Note on browsers: Chrome specifically has its own DNS cache separate from the OS. If you find Reddit still loading after starting a session, open chrome://net-internals/#dns and click “Clear host cache”. Or just close and reopen the browser. Firefox and Safari respect the OS cache and don’t have this issue.

Understanding the Live Countdown

The countdown UI is pure ANSI escape codes — no rich, no blessed, no external terminal library:

class LiveDisplay:
    def __init__(self):
        self.prev_line_count = 0
        sys.stdout.write("\033[?25l")   # hide cursor
        sys.stdout.flush()

    def render(self, lines):
        if self.prev_line_count > 0:
            sys.stdout.write(f"\033[{self.prev_line_count}A")   # cursor up N
        for line in lines:
            sys.stdout.write("\033[K" + line + "\n")   # clear line, write, newline
        sys.stdout.flush()
        self.prev_line_count = len(lines)

Every call to render moves the cursor up by the height of the previous frame, then rewrites each line with a leading \033[K (clear-to-end-of-line). Result: smooth in-place redraw, no flicker, no scrollback pollution.

The countdown loop itself uses time.monotonic() — not time.time() — because monotonic time doesn’t jump if the system clock is adjusted mid-session (NTP sync, timezone change, whatever). Your 25-minute session lasts 25 minutes even if your laptop syncs its clock during it:

start = time.monotonic()
while True:
    elapsed = time.monotonic() - start
    remaining = duration_seconds - elapsed
    if remaining <= 0: break
    display.render(build_countdown_view(int(round(remaining)), ...))
    time.sleep(max(0.05, 1 - (time.monotonic() - start) % 1))

That last line is a subtle trick: instead of sleeping exactly 1 second per iteration (which would drift over long sessions because computation takes time), we sleep to the next whole-second boundary. Over an hour, drift stays under a second.

Practical Use Cases

Deep-work sprints for anyone who works from home. Two 90-minute sessions in the morning, protected from Reddit and Twitter, is a completely different day from six hours of shallow work with distractions. Especially for programmers, writers, students, anyone whose job requires sustained attention.

Kids doing homework without infinite YouTube tabs. Parents can start a 45-minute session with an expanded blocklist before homework time. When it ends, YouTube comes back. Beats standing over their shoulder.

Exam prep and studying. The Pomodoro technique combined with real enforcement. Most students who try Pomodoro give up in a week because “just 5 minutes of Reddit” turns into 40. Real blocking removes the option.

Recovering from a Twitter/TikTok habit. Not with a permanent block that feels punishing — with time-boxed sessions that build a habit of not checking. Twenty-five minutes six times a day teaches your brain “you can go 25 minutes without seeing what’s trending.”

Foundation for Day 2. Every function we built today — add_block_entries, remove_block_entries, flush_dns, the cleanup safety net — gets reused tomorrow. Day 2 is a web UI wrapping the same engine, with persistent stats and preset management. That’s the pedagogical arc of the week: minimal working thing today, complete production-quality tool tomorrow.

Coming Wednesday

Tomorrow we wrap this engine in a proper web dashboard — named session presets (”deep-work 90 min”, “pomodoro 25/5”, “study 45 min”), per-site rules with time-of-day windows, a stats page showing your focus time this week and your streak of consecutive days with sessions, and mandatory break enforcement so you don’t burn out chaining focus sprints.

If you want the full tool, upgrade here before Wednesday.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

View Code Solution

Picture this. You start a script that scrapes 900 pages. It is going to take an hour, so you close the laptop and go make coffee. When you come back, the script is gone. Not paused, not resumed. Gone, with maybe forty pages scraped instead of nine hundred.

What actually happens when you close the lid

Here is the part almost nobody explains. Your script has no idea what a laptop is. It does not know about lids, or WiFi, or coffee breaks. What it does understand is signals, small messages the operating system sends to processes. And when your terminal session ends, the OS sends every process under it a specific signal called SIGHUP, which literally stands for “hangup”, a name left over from the days terminals were connected by phone lines.

By default, a process that receives SIGHUP simply exits. So your script was not killed by your laptop. It was killed by a decades-old convention, faithfully followed by your operating system, because nobody told your script to ignore it.

The fix: tell it to ignore the signal

The simplest fix is a command called nohup, and the name tells you exactly what it does: no hangup.

nohup python3 script.py &

I actually ran this on a small test script that logs a line every couple of seconds. Here is the real terminal output:

Notice the process ID printed right after starting, 648 in this case. That number is how you would check on it or stop it later. And notice that even after the session ends, the log keeps growing, because the process ignored the signal that would normally have ended it. nohup also redirects anything your script would print into a file called nohup.out, so you do not lose your output either.

nohup does not stop your laptop from sleeping

Here is a question worth asking before you trust nohup completely: does it survive your laptop actually going to sleep, not just the terminal closing? The honest answer is no, and it is a different problem entirely.

Closing your terminal sends a signal, SIGHUP, which nohup tells your script to ignore. Sleep is not a signal at all. When your laptop sleeps, the whole operating system pauses, your script included, mid-instruction, exactly where it was. Nothing crashes. Time simply stops passing for your script until the laptop wakes up again, at which point it continues from that exact line as if no time had gone by.

That sounds harmless, and for a pure calculation it usually is. But most scripts worth leaving running involve a network connection, and that is where sleep quietly breaks things. Your WiFi disconnects during sleep, and when the laptop wakes, your script tries to keep talking to a connection that no longer exists. You will not see a dramatic crash. You will see it die on a random request twenty minutes after you opened the laptop again, and it will look like a completely unrelated bug.

So the honest rule is this: nohup protects you from closing the terminal, not from closing the laptop. If your script needs to survive actual sleep, either turn sleep off for that session, a checkbox in every operating system’s power settings, or accept that you are really back to the same answer as before: put the script on a server that never sleeps in the first place.

Two more tools worth knowing

nohup is the boring, always-available option, and I use it constantly for that exact reason. But there are two more tools worth having in your pocket, depending on the situation.

tmux creates a session you can detach from and reattach to later, from the same machine or a different one entirely. Instead of just letting a script survive in the background, you can walk away and come back to literally the same terminal, scrollback and all, as if you never left. It takes a bit longer to learn than nohup, but if you are the kind of person who likes checking on things, it is worth the twenty minutes.

And then there is the real answer for anything that truly needs to run forever: stop running it from your laptop at all. Deploy it to a server, a computer that stays on by design, and let a process manager restart it automatically if it ever crashes. Your laptop was never meant to be the thing holding your app up, and once you deploy, this entire problem disappears, because there is no lid to close.

A quick word on Mac, Linux, and Windows

Everything above assumes Mac or Linux, and the good news is that assumption barely matters, because both are built on Unix underneath. nohup, tmux, and SIGHUP itself behave identically on both. If you develop on a Mac, the exact commands in this post already work on your machine.

Windows is the exception, and it is a real one, not a small syntax difference. Windows does not use SIGHUP at all, closing a window sends a completely different kind of signal, and neither nohup nor tmux exist natively there. My honest advice, and what I use myself when I have to touch Windows, is to install WSL, the Windows Subsystem for Linux. It gives you a real Linux environment inside Windows, and once you are inside it, every command in this post works exactly as written. Trying to find native PowerShell equivalents for all of this is possible, but it is a rabbit hole not worth the time when WSL gets you the real thing in ten minutes.

Which one for you

If a script just needs to survive one afternoon while your terminal closes but the laptop stays awake, nohup is enough, and it costs you nothing to learn. If you find yourself wanting to check progress and jump back in, tmux earns its place, though it has the same blind spot as nohup the moment the laptop itself sleeps. And the moment something needs to run every single day, laptop open, asleep, or on the other side of the room, that is your sign it belongs on a server, not on your desk.

I used to just leave my laptop open and pray, for years, before I had a name for any of this. If that is you right now, you are in good company, and at least now you have three better options.

If you learned something from this today, consider upgrading for the full experience: every weekly project with full source code, plus the complete archive. Since you read this far, I’d like to offer you 35% off the annual plan as a token of appreciation. Click below to get the discount:

Get 20% off: $99 → $79/year

Yesterday, we built the smallest version of a real estate site that actually works: one owner, one password, one door. Anyone could browse, only the owner could publish.

Today, we open the doors. Any property owner can create an account and submit their own listings, complete with a photo. But nothing appears on the public site the moment it is submitted. It waits, quietly, until the site owner looks at it and decides.

View All Projects This Week

Why “anyone can submit” is a different problem entirely

Yesterday’s whole security model was one sentence: only the owner has the password. That sentence stops working the moment a second person needs to publish something, because now you need a way to let people in without handing them the keys to everything.

The answer is a queue. Anyone can submit a listing, but a submission is not the same thing as a published listing. It sits in between, in a state we call pending, until a human being with the authority to decide looks at it.

This pattern is everywhere once you notice it. Every app store review, every YouTube comment section with moderation, every marketplace where sellers list products, all of them run on the same idea: letting people contribute does not mean letting their contribution appear instantly.

Telling owners apart from everyone else

Yesterday there was one account. Today there is a table of accounts, and each one carries a single flag: is this person the site owner, or just one of the property owners? That one flag decides everything about what happens after someone submits a listing.

If the site owner submits a listing, it can go live immediately, because they already have full authority. If anyone else submits one, it lands in the pending pile instead, and stays invisible to regular visitors until it gets approved. The homepage itself never had to get more complicated to make this work. It simply only ever asks the database for listings marked approved, so a pending one is not hidden by some special rule, it just never matches the question being asked.

Seeing today’s feature actually work

I ran the whole flow for real before writing any of this: a property owner signs up, logs in, and submits a listing with a photo. It does not appear on the public homepage. The site owner logs in, sees it waiting in a pending list, and approves it. Only then does it appear.

So the flow is:

A property owner or agent can sign up for an account:

And they can add a listing:

The admin of the website can see the listings added by owners/agents and approve them:

Once the website admin approves, the listing shows on the website:

What this version can do that yesterday’s could not

Source Code and AI Prompt to create a similar professional real estate web app

The complete, working code for today’s exact version, all six files including the upload handling, is ready below.

Read more

That is what we are building this week. And the interesting part is not the website itself, it is the question sitting underneath it: who gets to add a listing, and how do you make sure it stays that way?

Projects in this week’s series

Today, we build the smallest version that actually works. There is exactly one person who can publish a listing: the site owner. Everyone else can look, nobody else can touch.

Tomorrow, paid subscribers get the “grown-up” version. Other property owners get their own accounts and can submit listings themselves, but nothing appears on the site until the owner reviews and approves it. We will also look at the specific ways this kind of feature quietly breaks when it is built carelessly, and what it takes to run it for real.

Tomorrow’s project is already posted. Get instant access by upgrading to a paid monthly or annual plan.

Unlock Day 2

With a paid plan you can:

• Read Day 2 right now instead of waiting until tomorrow

• Access to full code of Day 1 and Day 2 project

• Access to the full archive of 500+ projects

The shape of the problem

Every listing, once it exists, is really just a few facts: a title, a location, a price, and a description. Simple enough to hold in a single table. The harder question is not what a listing looks like, it is what stops a random visitor from adding fifty fake ones.

So today’s whole project comes down to one line of thinking: browsing is public, publishing is not.

Any visitor can open the site and see every property, no account needed. But the moment someone tries to add a new one, they hit a locked door, and only the owner has the key. For now, that key is a single password. It is not fancy, and it does not need to be, because there is only one person who should ever hold it.

Flask and SQLite, in plain terms

If every Python program you have written so far runs once, prints something, and stops, a website might feel like a different universe. It really is not one, and it is worth slowing down on this for a moment, because the rest of the post assumes it.

A website has to stay running and keep listening, so that the instant someone visits a page, something responds. Flask is a small Python library whose only job is exactly that. You write ordinary Python functions, and Flask makes sure the right one runs the moment someone opens a particular page in their browser. The homepage, the login page, the “add listing” form: each one is just a URL with a Python function waiting behind it.

That handles behavior, but behavior alone forgets everything the second the program restarts, and a listings site obviously cannot forget its listings between visits. That is what SQLite is for. It is a genuine database, yet it lives as a single file sitting right next to your code, nothing separate to install. Every listing gets written there, and it is still there tomorrow, next week, whenever the site starts back up again.

If you read the post on frontend versus backend a few weeks ago, here is where this project sits on that map: entirely on the backend side. There is no separate frontend framework here. Flask builds plain HTML pages and sends them straight to the browser, and for a site like this one, that is genuinely enough.

How the lock actually works

Here is the part worth understanding, even if you never open the code. When the owner visits the site and logs in, the server remembers them for as long as their browser stays open, using something called a session. From that point on, every request they make quietly carries proof that they are logged in.

Anyone else, someone who never logged in, gets redirected the instant they try to reach the “add listing” page. They never even see the form.

Notice something about that flow: the check happens before anything else runs. The server does not build the page and then decide whether to show it. It decides first, and only builds the page if the answer is yes. That order matters more than it looks, because it means there is no version of the page that briefly exists for someone who should not see it.

One more detail, small but worth knowing. The owner’s password is never stored as plain text anywhere, not even in the one-account version we are building today. It is stored as a hash, a kind of one-way scramble that can confirm a password is correct without ever revealing what it is. It is a habit worth having from the very first line of code, because it is exactly the same habit that will protect real users tomorrow.

Seeing it run

First install the needed Python libraries with:

pip install flask

Starting the site is one command, and a moment later it is live on your own machine.

Open it in a browser and you get a clean homepage listing whatever properties exist so far:

Try to sneak into the “add listing” page directly, without logging in, and the site quietly sends you to the login screen instead. Exactly as promised.

Log in as the owner, and a simple form appears.

Fill it in, publish, and the new property shows up on the homepage immediately, right at the top.

That is the whole loop. One person, one password, one door.

Coming tomorrow

Today’s version is genuinely enough if you are the only person who will ever list a property, which is true for plenty of small agencies and independent landlords. The moment a second person needs to publish their own listings, the whole shape of the problem changes, and that is exactly where tomorrow picks up.

Tomorrow we add the other half. If you want the full website, upgrade here and you can access both projects today.

Solution

The complete, working code for today’s version is ready for you below, all four files.

View and download app.py here:

app.py

Download the HTML files here and place them in a folder named templates directory and place the templates folder in the same directory with app.py:

HTML Files

Imagine you ask AI to build you a habit tracker. Cursor or Claude produces the whole app in a few minutes, and it works. However, somewhere in those generated files, the AI also made a quiet decision for you: where your data lives. Maybe it picked SQLite. Maybe it wired in Postgres. You nodded along, because the app runs. But that quiet decision determines how you will deploy the app, what happens when your laptop dies, and whether your data can follow you to your phone. The code was AI’s job. This decision was supposed to be yours.

So let’s give you the map. But first, answer this honestly:

If you picked “honestly, no idea”, you are in good company, and this post exists exactly for you. Keep your answer in mind, because by the end you will be able to check whether it was right.

The three realistic options

For a solo builder, there are really three options worth knowing, and they differ mainly in one thing: where the data physically sits.

SQLite is a complete database inside a single file. It comes with Python, so there is nothing to install, no server to run, and no password to configure. This is genuinely all it takes:

import sqlite3

con = sqlite3.connect("app.db")
con.execute("CREATE TABLE habits(name TEXT, done_on TEXT)")
con.execute("INSERT INTO habits VALUES ('stretch', '2026-08-10')")
con.commit()

After running this, there is a file called app.db in your folder, 8 KB in size, holding your data. People will tell you SQLite is a toy. It is not. It runs inside every phone and every browser you own, which makes it one of the most deployed pieces of software in history.

Local Postgres is a proper database server running as a separate program on your machine. It is the industry standard, and it is also installation, configuration, users, passwords, and a process that must always be running. It buys you complexity before it buys you anything else, so my honest advice for beginners is to skip it until a real need appears.

Supabase is Postgres again, but running on someone else’s computer, reachable from anywhere. Your data is no longer trapped on one machine: it survives your laptop dying, and ten users on ten devices can all reach it. In exchange, every query travels over the internet, your data lives elsewhere, and you are on a free tier with limits. Take those limits seriously. A few weeks ago, while building the file sharing tool for one of this publication’s projects, I had three free upload services fail under me in a single afternoon: one started returning JSON errors, its replacement turned out to be disabled for spam, and I finished the day on a third one. Free tiers are real infrastructure until the day they are not.

At this point you might be wondering about MySQL, because it appears in every tutorial from the last twenty years. MySQL is a server database like Postgres, and it still quietly runs a huge part of the internet, with WordPress alone keeping it very busy. However, among developers starting new projects today, Postgres has clearly won: it has more features, stricter and saner defaults, and it is what modern hosted services like Supabase are built on. So for your decision, MySQL and Postgres occupy the same slot on the map, and when you eventually reach for that slot, my advice is to pick Postgres.

One question decides it

When people ask me which one to pick, I ask back a single question: who needs to reach this data?

If the answer is “just this app, on my machine”, use SQLite and move on with your life. If the answer is “just this app, but deployed on a server”, SQLite still works: the file simply lives on the server next to your code. However, be careful here, because on many hosting platforms the disk gets wiped on every redeploy, and that trap deserves its own post soon. And if the answer is “many users or devices, from anywhere”, then the data needs its own home on the internet, and that is when hosted Postgres like Supabase earns its place.

Notice that local Postgres did not appear in any starting answer. That is not an accident.

Building with AI changes one thing

Here is the practical part. When you vibe-code an app, tell the AI which database to use, explicitly, in the first prompt. Something like: “Build me a habit tracker. Use SQLite, one file named app.db.” If you do not say it, the AI will pick for you, and you will inherit a decision you never made.

Then, after it builds the app, do one small thing: find the data file and open its folder. Knowing where your data physically is sounds trivial, yet it is the difference between people who recover from disasters and people who lose everything.

The good news is that switching databases later is cheaper than it has ever been, because AI can rewrite the code layer in minutes. Moving the data itself, however, is still your problem. So start simple, start with SQLite, and treat moving up as a milestone your app earned, not a mistake you made at the beginning.

Before you go, one small test of today’s map. Imagine you are building a recipe app, just for yourself, but you want to use it on both your phone and your laptop. Which database do you pick?

Think about the one question from the decision map before you answer.

If you learned something from this today, consider upgrading for the full experience: every weekly project with full source code, plus the complete archive. Since you read this far, I’d like to offer you 35% off the annual plan as a token of appreciation. Click below to get the discount:

Get 20% off: $99 → $79/year

Today we fix all of that. Downloads work now, so any device can pull files off your laptop, not just push files onto it. Drag-and-drop replaces the tap-to-pick UI — drop files anywhere on the browser window and they upload in the background. Real progress bars show you exactly how far along that 200 MB video is. And a 4-digit PIN gate protects the server from your coffee-shop neighbor.

The underlying philosophy: you don’t need to install an app or trust a cloud company just to move files between devices on the same physical WiFi network. A single Python file — 700 lines total, everything inline — replaces AirDrop, Snapdrop, LocalSend, WeTransfer, and all the “send a file to yourself” workflows people use every day. Once you’ve built one of these, you’ll never install a file-transfer app again.

Projects in this week’s series:

Day 1: Upload server with QR code

Yesterday, we built the upload half — a FastAPI server that binds to 0.0.0.0 on the LAN, prints a QR code in the terminal that any phone camera can scan, and accepts uploads from a mobile-first page with <input type="file" multiple>. Files stream to disk 1 MB at a time so a 4 GB video doesn’t blow up memory. Filename safety via Path.name blocks path traversal, and collisions auto-rename to foo (1).jpg. All in one Python file, ~300 lines, no accounts, no cloud.

👉 Day 2 (Today): Downloads, drag-and-drop, progress bars, and PIN protection

The main page now has two halves: a drop zone up top for uploads, and a gallery below showing every file already uploaded. Drag files from your desktop onto the browser window, or tap the drop zone on mobile to open your photo library — either way, each file gets its own live progress bar showing exactly how much has uploaded:

Once uploaded, files appear in the gallery with a thumbnail if it’s an image, or a document icon otherwise. Each card shows the filename, size, upload time (e.g., Aug 10, 15:00), and two buttons — Download and Delete. Tap Download and the file lands on your device. Tap Delete and it’s gone. This is what makes the tool actually two-way:

Before you see any of this, though, you have to enter the 4-digit PIN. You get the pin from the terminal when you run the .py script and you enter it in the app:

Every run, the server prints a fresh PIN in the terminal alongside the URL and QR code. Anyone opening the URL sees a PIN entry page first. After entering it correctly, a signed session cookie remembers them for the rest of the run.

Every file now is in both your devices.

That way if you fire this up on coffee-shop WiFi, random strangers on the network can’t find the server and dump files onto your laptop. Only the people you actually tell the PIN to get in.

View All Projects This Week

About the stack

Same base as yesterday — FastAPI, uvicorn, python-multipart, qrcode, rich. Two additions:

itsdangerous signs the session cookies that remember whether a browser has passed the PIN check. Same library we used in Week 28 for the Notes app. Signs data with a secret key, verifies it hasn’t been tampered with on the way back. If you know the key you can forge cookies; if you don’t, you can’t. The secret key gets regenerated on every server restart, which is what we want — sessions don’t need to survive across restarts.

Vanilla JavaScript, inline in the HTML template. About 80 lines. Handles drag-and-drop, XHR uploads, and progress bars. No React, no Vue, no build step, no node_modules. This is one of those cases where the amount of JS you need is small enough that reaching for a framework would slow things down, not speed them up.

Setup Instructions

Install the extra dependency on top of Day 1:

pip install itsdangerous

Everything else you already have from yesterday. Run:

python lanshare_full.py                       # save to ~/lanshare/
python lanshare_full.py ~/Downloads           # save to your Downloads folder
python lanshare_full.py ~/photos --port 9000  # custom folder and port

The startup banner is the same as Day 1 plus the PIN — you’ll see something like PIN: 4712 in yellow above the QR code. Read that number to whoever wants access. On subsequent runs the PIN changes because it’s regenerated on startup — that’s a feature, not a bug.

Understanding the PIN Gate

The whole “who is allowed in” system is three functions and a dependency:

signer = URLSafeSerializer(SECRET_KEY)

def make_session_cookie():
    return signer.dumps({"ok": True})

def is_authed(request):
    token = request.cookies.get(SESSION_COOKIE)
    if not token:
        return False
    try:
        return bool(signer.loads(token).get("ok"))
    except BadSignature:
        return False

def require_auth(request):
    if not is_authed(request):
        raise AuthRequired()

Login is POST /login with the PIN in a form field. If it matches, we set a cookie whose value is signer.dumps({"ok": True}) — a short signed string. Any subsequent request that includes this cookie passes the PIN check. If someone tries to fake the cookie by hand, signer.loads raises BadSignature and they get bounced back to /login.

The AuthRequired exception + @app.exception_handler pattern is what makes protection clean at the route level. Every protected route just adds one line:

@app.get("/")
async def home(_: None = Depends(require_auth)):
    ...

If the request is unauthed, require_auth raises AuthRequired, the exception handler catches it and returns a redirect to /login. The route body never runs. This is the exact same pattern from the Notes app in Week 28, extended here from “who are you” (username/password) down to “are you the person I told the PIN to” (single shared secret).

A note on brute force: 10,000 possible PINs might sound weak, but on a LAN with 5-10 devices, nobody is running a distributed brute-force attack. If you’re worried about a hostile actor on the same coffee-shop network trying 10,000 PINs, add a rate limiter — but for personal use it’s overkill.

Understanding Drag-and-Drop

The HTML5 drag-and-drop API is one of those things that sounds complicated but comes down to four event handlers:

const dropzone = document.getElementById('dropzone');

// Prevent the browser opening dropped files in a new tab (default behavior).
['dragenter', 'dragover', 'dragleave', 'drop'].forEach(ev => {
  document.body.addEventListener(ev, e => e.preventDefault());
});

dropzone.addEventListener('dragover', () => dropzone.classList.add('dragover'));
dropzone.addEventListener('dragleave', () => dropzone.classList.remove('dragover'));
dropzone.addEventListener('drop', e => {
  dropzone.classList.remove('dragover');
  if (e.dataTransfer && e.dataTransfer.files.length) {
    uploadFiles(e.dataTransfer.files);
  }
});

The dragover handler adds a CSS class that changes the border color and background — that’s the visual feedback showing the drop zone is active. The drop handler reads e.dataTransfer.files (a FileList object identical to what an <input type="file"> gives you), and passes them to the same upload function.

The one weird thing everyone hits the first time: you have to preventDefault on those four events on the whole body, otherwise dropping a file onto the page anywhere-not-the-dropzone causes the browser to navigate to that file. That’s why we attach preventDefault handlers to the body itself.

On mobile, drag-and-drop doesn’t exist as a gesture — you can’t drag files out of a file manager. So we also make the dropzone clickable, and clicking it opens the same hidden <input type="file" multiple>:

dropzone.addEventListener('click', e => {
  if (e.target.tagName !== 'INPUT') fileInput.click();
});

Same UI element, two interaction modes — drag-and-drop on desktop, tap-to-pick on mobile. One dropzone works on everything.

Understanding Live Progress Bars

Standard HTML form submission gives you no upload progress info at all. The browser posts the whole thing and shows you the response when it’s done. For a 200 MB video that could take a minute, the user sees nothing happening.

The fix is XMLHttpRequest, specifically its upload.progress event. Modern JavaScript prefers fetch(), but fetch() doesn’t expose upload progress at all — the spec still hasn’t shipped it. So for progress bars we have to reach for the older XHR API:

const xhr = new XMLHttpRequest();
const fd = new FormData();
fd.append('files', file, file.name);

xhr.upload.addEventListener('progress', e => {
  if (!e.lengthComputable) return;
  const pct = Math.round((e.loaded / e.total) * 100);
  bar.value = pct;
  pctText.textContent = pct + '%';
});

xhr.open('POST', '/upload');
xhr.send(fd);

The upload.progress event fires many times per second while the file is being sent. e.loaded is bytes uploaded so far, e.total is total bytes. Divide, round, done. The <progress> HTML element is a first-class native progress bar — no CSS gymnastics needed to make it look good.

Doing multiple files at once? Each file gets its own XHR, its own progress row in the DOM, its own progress event stream. Uploads run in parallel because the browser handles multiple simultaneous XHRs to the same origin. The main constraint is the browser’s per-origin request limit (usually 6), which is more than enough for a personal file-transfer tool.

Understanding the File Gallery

The gallery is server-rendered HTML, updated by reloading the page after uploads complete. Every request to / reads the current contents of the upload directory, sorts by modification time, and renders one card per file:

@app.get("/")
async def home(_: None = Depends(require_auth)):
    files = sorted(
        [p for p in upload_dir.iterdir()
         if p.is_file() and not p.name.startswith(".")],
        key=lambda p: p.stat().st_mtime,
        reverse=True,
    )
    return HTMLResponse(MAIN_PAGE.format(
        gallery_html=render_gallery(files),
        ...
    ))

iterdir() is pathlib‘s way of listing a directory. Filter out hidden files (.DS_Store, .thumbs), sort by st_mtime descending, done. Newest first is the right default because that’s what you just uploaded.

Each card decides whether to show a thumbnail image or a document icon based on the file extension:

IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".gif", ".webp", ".heic",
                    ".bmp", ".svg", ".avif"}

if is_image(f.name):
    thumb = f'<img src="/__u/dailypythonprojects.substack.com/files/%7Bname_escaped%7D" alt="" loading="lazy">'
else:
    thumb = '<span class="icon">&#128196;</span>'

For image thumbnails, we use the file itself as the <img src>. The browser downloads it, resizes it via object-fit: cover in CSS, and renders it. For a personal LAN tool with a few dozen files, this is fine. A production version would generate real thumbnails with Pillow, but that adds a dependency for very little UX gain at small scale.

The loading="lazy" attribute is important — it tells the browser to only load thumbnails as they scroll into view. Without it, opening a page with 100 images would trigger 100 simultaneous downloads.

Understanding Path Traversal on Downloads

Day 1 handled filename safety on uploads via Path(name).name. Day 2 adds two more attack surfaces: downloads (GET /files/{name}) and deletes (POST /files/{name}/delete). Both take a filename from the URL, and both could be tricked into escaping the upload directory if we weren’t careful.

We reuse the same safe_filename from Day 1, but also add a defense-in-depth check that resolves the final path to absolute form and confirms it’s still inside the upload directory:

def resolve_upload_path(upload_dir, name):
    candidate = (upload_dir / safe_filename(name)).resolve()
    upload_dir_r = upload_dir.resolve()
    try:
        candidate.relative_to(upload_dir_r)
    except ValueError:
        return None                    # escaped upload_dir - reject
    if not candidate.is_file():
        return None
    return candidate

safe_filename alone would probably be enough, but “probably enough” is not the right level of confidence for security-sensitive code.

The same helper protects the delete route. Without it, a malicious request would happily delete files outside the upload directory. With it, you get a 404 and nothing happens.

Understanding the JSON Upload Response

Day 1’s upload route returned a 303 redirect back to /?uploaded=N — the standard Post-Redirect-Get pattern for form submissions. That worked because Day 1 used a plain HTML form.

Day 2’s upload runs from JavaScript via XHR, so the response can be JSON instead:

python

return JSONResponse({"ok": True, "saved": saved})

The JavaScript doesn’t actually read the response body — it just checks xhr.status to know if the upload succeeded — but returning structured JSON is the right idiom for a JavaScript-driven endpoint, and gives us the option to expand the response later (thumbnails, previews, computed metadata) without breaking anything.

After all in-flight uploads finish, the JS reloads the page:

javascript

if (inFlight === 0) setTimeout(() => location.reload(), 600);

The 600ms delay lets the “Done” text on the progress rows stay visible for a moment before the page refreshes to show the new gallery. Small polish, feels much better than an instant snap.

Practical Use Cases

Family photo dump at Christmas.
Everyone at the family gathering AirDrops or Google-Drives their photos to one shared album, taking 45 minutes and losing quality. Alternative: someone starts LAN Share on their laptop, projects the QR code on the TV, everyone in the room scans it, uploads their photos in full quality in 30 seconds. Downloadable back to any device afterwards.

Workshop or conference submissions.
Running a two-hour Python workshop and want everyone to submit their solutions? Way faster than a shared Google Drive. Everyone’s on the venue WiFi, they scan the QR code, PIN is projected on your slide, files land in one folder on your laptop. No Google accounts needed.

Getting files off a phone with no cable.
Phone lost its cable, doesn’t have iCloud, or the photos are too big for email? Start the server, scan the QR, upload the 4 GB video, downloaded to your laptop in whatever time the WiFi takes. Faster than trying to work around whatever cloud service compresses your file.

Sharing a big file between two computers on the same network.
Two laptops on the same WiFi, want to move a 15 GB dataset between them? USB drives, cloud upload, Ethernet cables all take longer than starting LAN Share and dragging the file. LAN transfer runs at whatever your WiFi supports — often over 100 MB/s.

Deploy it to your own VPS with a domain and HTTPS.
Point it at a real domain with a Let’s Encrypt certificate and you have a private file-transfer service accessible from anywhere. Send the link + PIN to anyone. No SaaS, no monthly fee, no size limit, no expiring links, no ads. Total setup cost: $5/month VPS + one weekend of learning nginx and Certbot.

What’s Next

Thursday’s post is a standalone tutorial on a specific piece of infrastructure — free, all subscribers get it. Details Thursday morning.

Next week we shift into a different kind of build — details on Tuesday.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

Read more

This week we build the fix. Three hundred lines of Python that turns your laptop into an AirDrop-for-everyone server. Your phone, your friend’s Android, your kid’s iPad, a Windows machine, another laptop — anything with a browser on the same WiFi can send files to you. No accounts, no cloud, no apps to install anywhere except your laptop. You start the server, it prints a QR code, everyone scans it, everyone drops files, done.

Day 1 is the upload half — anyone on your WiFi can send files to your laptop. Day 2 adds the download half, drag-and-drop, PIN protection, and a file browser so it’s a two-way tool. Both days build on the same core insight: a laptop running a small web server on the LAN is a better peer-to-peer file transfer solution than anything in the app store, and modern Python makes it a weekend project.

Projects in this week’s series:

👉 Day 1 (Today): Upload server with QR code

When you run the script, the terminal prints a colored panel with the URL and a QR code your phone camera can scan directly. It also tells you exactly where uploaded files will land and starts logging every upload live:

Your phone opens the URL and sees a simple mobile-first upload page. Tap the file picker, choose photos from your library or take one with the camera, hit Upload, done. The page shows a green success banner after every upload:

I did use the actual app that I built to transfer the screenshot above to my computer and upload it in this post. Here is how my “lanshare” folder looks like in my computer after uploading some files from my phone:

Path traversal attacks are blocked, filename collisions auto-rename (photo.jpg becomes photo (1).jpg), and uploads stream to disk in chunks so a 4 GB video doesn’t blow up your laptop’s memory.

Day 2 (Tomorrow): Downloads, drag-and-drop, and PIN protection

Same server, but bidirectional and prettier. Drag files onto the browser window instead of using the picker. Real progress bars during upload so you know your video isn’t stuck. A file gallery on the page showing everything that’s been uploaded so far, with a Download button next to each — so your friend can grab files back off your laptop instead of only sending them:

Plus a 4-digit PIN shown in the terminal on startup that anyone visiting the page has to enter first. That way if your neighbor is on the same coffee shop WiFi, they can’t just find your server and upload themselves 200 GB of memes.

View All Projects This Week

About the stack

Four small packages and one CDN link, no JavaScript files, no accounts, no cloud.

FastAPI is the web framework, same one we used for the Notes app in Week 28. It handles multipart file uploads out of the box, streams big files through UploadFile.read(chunk_size), and gives us clean async routes.

uvicorn is the ASGI server that actually runs FastAPI. It binds to 0.0.0.0 so any device on the local network can reach it, and its default settings handle huge file uploads without any tuning.

python-multipart is a dependency FastAPI needs for parsing HTML form uploads. It’s the difference between “your server sees the multipart data” and “your server sees nothing.” Install it, then forget about it.

qrcode generates QR codes. Not a huge library, and importantly it can render straight to the terminal using Unicode half-block characters — a real, scannable QR code that fits in 33 characters of terminal width. No image file, no screen sharing, just Unicode in your terminal.

Rich styles the terminal output — the startup panel, the colored upload log. Not strictly necessary but the polish makes the tool feel like a real product rather than a script.

Pico.css from a CDN gives us a mobile-first, classless styling framework. We write plain semantic HTML like <form>, <input type="file">, <button>, and it looks like a real product on both desktop and mobile. Zero CSS files in our project.

Setup Instructions

Install dependencies:

pip install fastapi uvicorn python-multipart qrcode rich

Five packages. All small, all mature, none likely to break in the next five years.

Run it:

python lanshare.py                       # save uploads to ~/lanshare/
python lanshare.py ~/Downloads           # save to your Downloads folder
python lanshare.py ~/photos --port 9000  # custom folder and port

The default target folder is ~/lanshare/, auto-created on first run. The default port is 8000. Once running, the terminal prints the URL to open on any device on the same WiFi and a QR code you can scan directly.

Firewall note: on macOS, the first time you run this you’ll get a popup asking whether to allow incoming connections. Click Allow. On Windows, Windows Defender Firewall will ask the same thing. On Linux you’re on your own.

Understanding LAN IP Discovery

The single most useful trick in this entire project is finding your own LAN IP so you can print it. Sounds easy — you have an IP, right? — but it’s actually one of the classic gotchas of network programming.

The obvious way, socket.gethostbyname(socket.gethostname()), doesn’t work reliably. On many machines it returns 127.0.0.1 (localhost), which is useless for LAN sharing. On some machines it returns an IP from a virtual network interface (Docker, VMware, VirtualBox) that no other real device can reach. On multi-homed machines with multiple network interfaces, it might return the wrong one entirely.

The elegant trick that actually works is this:

def get_lan_ip():
    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    try:
        s.connect(("8.8.8.8", 80))
        return s.getsockname()[0]
    finally:
        s.close()

We open a UDP socket and “connect” it to Google’s public DNS server (8.8.8.8). But UDP is connectionless — no actual network traffic happens here. What happens is the operating system’s kernel picks the network interface that would be used if we were to send a packet to 8.8.8.8, and the socket now has that interface’s IP bound to it. We read that back with getsockname(), close the socket, and we’re done.

This works because the kernel’s routing table is the ground truth for “what IP would other devices see if I sent them a packet.” Whether you’re on WiFi, Ethernet, or a hotspot from your phone, the kernel knows which interface has internet access and returns its IP. It works on macOS, Linux, and Windows without changes. And crucially, it ignores virtual network adapters like Docker’s docker0 which would otherwise confuse things.

The 8.8.8.8 address is arbitrary — any routable public IP works. We use Google’s DNS because it’s globally famous and unlikely to disappear, but 1.1.1.1 or literally any public IP would work equally well.

Understanding FastAPI File Uploads

FastAPI handles file uploads through the UploadFile type, which is a Starlette wrapper around a SpooledTemporaryFile. The magic is that FastAPI never loads the whole file into memory unless you make it. You get to control the streaming yourself:

from fastapi import FastAPI, File, UploadFile
from typing import List

@app.post("/upload")
async def upload(files: List[UploadFile] = File(...)):
    for f in files:
        size = 0
        with open(target_path, "wb") as out:
            while True:
                chunk = await f.read(1024 * 1024)   # 1 MB at a time
                if not chunk:
                    break
                out.write(chunk)
                size += len(chunk)

The critical part is that await f.read(1024 * 1024) reads at most 1 MB of the upload at a time. We write it to disk immediately, then loop back for the next chunk. Total memory used: about 1 MB per file being uploaded, no matter how big the file is. A 4 GB video and a 4 KB text file both use the same amount of RAM.

Contrast this with the naive contents = await f.read() which reads the entire file into a single bytes object. Send a 4 GB video that way and your server tries to allocate 4 GB of RAM. Bad.

The List[UploadFile] type combined with <input type="file" multiple> in the HTML lets users pick multiple files at once and we handle them all in a single request. Each file goes through the same streaming loop.

Understanding Collision Handling

If two people upload files called photo.jpg, only one of them can win — unless we auto-rename on collision. The pattern that every operating system’s file manager uses is foo.jpg, foo (1).jpg, foo (2).jpg, and so on:

def unique_path(folder, name):
    p = folder / name
    if not p.exists():
        return p
    stem, suffix = p.stem, p.suffix
    for i in range(1, 10_000):
        candidate = folder / f"{stem} ({i}){suffix}"
        if not candidate.exists():
            return candidate
    # Fallback if someone somehow has 10k files with the same name
    return folder / f"{stem}-{datetime.now():%Y%m%d-%H%M%S}{suffix}"

pathlib gives us stem (filename without extension) and suffix (extension including the dot) for free. Loop up to some large number, and if we somehow hit 10,000 files with the same base name, fall back to appending a timestamp. That fallback will basically never trigger in practice but it keeps the function total — always returns a valid path.

There’s a subtle race condition here: between checking not candidate.exists() and actually opening the file for writing, another concurrent request could theoretically create that filename first. For a LAN tool with a handful of concurrent uploaders it’s not a real problem, but a truly bulletproof version would use os.open with O_EXCL flag to atomically create-if-not-exists. Overkill for our use case.

Understanding QR Codes in the Terminal

The QR code lives in the terminal, not in a browser or an image file. The qrcode library can do this directly:

qr = qrcode.QRCode(border=1)
qr.add_data(url)
qr.make(fit=True)
qr.print_ascii(invert=True)

print_ascii(invert=True) renders the QR using Unicode half-block characters (▀, ▄, █) which pack two “pixels” of QR data into every character cell. That’s why the whole QR fits in 33 columns instead of 66. invert=True means “light QR on dark background” which reads correctly in modern dark terminals like iTerm, Terminator, or Windows Terminal.

Any modern phone camera app opens QR codes automatically. iPhone Camera, Android Camera, most third-party barcode scanners — they all see the QR, recognize the URL, and offer to open it in the browser with a single tap. The whole “print QR in terminal, phone scans it, browser opens” flow takes about three seconds.

Understanding the Mobile-First HTML

The upload page is one Jinja-free HTML string, styled entirely by Pico.css from a CDN. The whole payload is 1.5 KB and renders identically on desktop browsers and mobile ones:

<form method="post" action="/__u/dailypythonprojects.substack.com/upload" enctype="multipart/form-data">
  <div class="upload-box">
    <input type="file" name="files" multiple required>
  </div>
  <button type="submit">Upload</button>
</form>

Three tricks worth pointing out:

enctype="multipart/form-data" is required for file uploads. Without it, the browser sends just the filename as a text field and your file goes nowhere. Miss this one attribute and you spend an hour debugging.

multiple on the file input lets users pick multiple files at once. On iPhone, this makes the photo picker allow multi-select. On Android, same thing. On desktop, Cmd/Ctrl-click in the file picker works. One attribute, huge UX win.

No accept attribute means the picker accepts any file type. On iPhone this shows a menu with “Photo Library”, “Take Photo or Video”, and “Choose Files”. On Android, “Camera”, “Files”, and “Photos”. On desktop, the normal file picker. The whole platform-specific file selection UI comes free with <input type="file">.

Practical Use Cases

Airdropping to Windows or Android friends. This solves the “I have an iPhone but my friend/partner/kid has an Android” problem forever. Start the server, share the QR code (screenshot it, or just show them your terminal), and both devices can send files to your laptop.

Getting photos off a phone at a party or event. Instead of everyone AirDropping photos to one person and then that person figuring out how to share them, everyone uploads to one laptop over the venue WiFi. All photos land in a shared folder in real time. Then you sync them to a shared album later.

Team file drops during a workshop or meeting. Running a workshop and want everyone to submit their exercise files? Way faster than a shared Google Drive folder and doesn’t require anyone to have a Google account. Start the server, project the QR code, everyone submits.

Foundation for Day 2. Every function we built today gets reused tomorrow. safe_filename and unique_path become the basis for a file gallery view. The Rich terminal logging pattern gets extended with download events. The Pico.css upload page evolves into a drag-and-drop UI. That’s the pedagogical arc of the week: minimal working thing today, complete production-quality tool tomorrow.

Coming Wednesday

Tomorrow we add the other half — downloads, so your friend can pull files off your laptop instead of only sending them. Drag-and-drop upload with real progress bars during transfer. A file gallery on the page showing everything that’s been uploaded, with a Download button next to each file. And a 4-digit PIN protection layer so your neighbor at the coffee shop can’t upload themselves onto your laptop.

If you want the full tool, upgrade here before Wednesday.

Solution

Below you will find the downloadable solution.py file containing the correct solution.

Get the code here:

View Code Solution

Last week you learned how to turn a function into an API, and when you opened it in the browser, you got something like {"password": "NlDRymnljPanqFp2"}. Perhaps a part of you was slightly disappointed by that. Real websites do not look like raw JSON. They have buttons, colors, input fields, animations. So where does all of that come from, and why did your Python produce none of it?

The answer is that every web application is actually two programs, running on two different computers.

The two halves

One program runs in the browser, on the visitor’s machine. It is written in HTML, CSS, and JavaScript, and its job is everything you can see and touch. This half is called the frontend.

The other program runs on a server, which as we have said before is simply a computer that stays on. Its job is the data and the logic. This half is called the backend, and this is where your Python lives.

Here is the part that surprises most beginners: Python never runs inside the browser. Browsers only run one programming language, and that language is JavaScript. So when you wonder why your Python script cannot change a button color on a page, the answer is that your Python is not there. It is on the other side of the border, on the server, and the only thing that crosses that border is HTTP requests going one way and data coming back the other way.

What actually happens when you click a button

Let’s make this concrete with a scenario. Imagine a weather website. You type “Lagos” into a search box and click Search. Here is the full trip:

JavaScript in your browser notices the click and sends a request, something like GET /weather?city=Lagos. If that shape looks familiar, it should, because it is exactly how you called your own password API last week. The request travels to the server, where the Python backend runs: it might check a database, or call an external weather service using an API key. Then it sends back JSON, something like {"temp": 24, "sky": "clear"}. Finally, JavaScript receives that JSON and turns it into pixels: a big 24°C and a sun icon.

So the ugly JSON you saw last week was not a limitation. It is the handshake between the two halves. Backends speak data, and frontends turn data into things you can look at.

Who does what, and why it matters

The division of labor is fairly clean. The browser handles everything that needs to feel instant: layouts, hover effects, reacting while you type. The server handles everything that involves data and trust: the real logic, the database, and the secrets.

That word “trust” deserves a moment. Everything in frontend code is visible to every visitor. Anyone can right-click your page, choose View Source, and read all of it. So if you place an API key in JavaScript, you have published it to the internet. This is one of the most common beginner mistakes out there, and it is why secrets always stay on the backend, where visitors cannot see them.

Do you need to learn frontend now?

My answer is no, and the reason is different than it would have been three years ago. Today you can let AI write your frontend. Describe the page you want, and tools like Claude or Cursor will produce the HTML, CSS, and JavaScript for you in a minute. Frontend is also where AI shines the most, because you can immediately judge the result with your own eyes: the button is either blue or it is not.

The backend is a different story. AI can write that code too, and I encourage you to let it. However, the backend is where the logic of your app lives: what gets saved, who is allowed to do what, what happens when a payment fails. Those are decisions, not code, and AI cannot make them for you. If you do not understand your backend, you do not understand your app. That is why you are learning Python, and not CSS.

This is also why I believe there has never been a better time to learn Python. The frontend used to be a wall: you either learned a second craft or hired a frontend developer. Now AI fills that gap for free, and one person with Python and a clear picture of the logic can ship a complete app alone. The map from this post is what lets you direct the AI, because you know which half a feature belongs to, and which half a bug lives in.

One more thing: this map is not just for websites. Every app on your phone works the same way. The app itself is a frontend, and somewhere a server is running someone’s backend code. Two programs, one handshake. You now have the whole picture.

If you learned something from this today, consider upgrading for the full experience: every weekly project with full source code, plus the complete archive. Since you read this far, I’d like to offer you 35% off the annual plan as a token of appreciation. Click below to get the discount:

Get 20% off: $99 → $79/year

Yesterday you built the astronomy engine — a Python script that takes a location and returns the precise eclipse timing for that spot, computed from the same JPL ephemerides NASA uses. Impressive as a CLI, but a terminal report isn’t something you share with friends, students, or your family WhatsApp group.

Today we take the same engine and wrap it in a live, interactive world map. Full eclipse path drawn as a bold red line across the North Atlantic. Cities in the path pre-marked as green dots, cities near it as orange or blue depending on coverage. Click anywhere on Earth and the sidebar populates with what you’ll see from that exact point — start time, maximum, end time in local timezone, coverage percentage, whether you’re in the path of totality. Search box for city lookup, live countdown to the moment of greatest eclipse. All in one Python file, wrapping yesterday’s script.

The lesson underneath: your astronomy engine should be reusable. Written well, compute_eclipse(lat, lon) is a pure function that doesn’t care whether it’s being called from a terminal script or a web app. Day 1’s file becomes an importable module for Day 2, and Day 2 is short because the hard work is already done. That separation between engine and interface is one of the most important design habits a working Python developer can build.

Projects in this week’s series:

Day 1: Command-line eclipse info tool (Yesterday)

Yesterday, we built a Python CLI script that computes precise eclipse timing for any location on Earth — start, maximum, and end times in local timezone, coverage percentage, whether you're inside the path of totality, and if so how long totality lasts. The astronomy runs off Skyfield with JPL DE421 ephemerides, accurate to within seconds of NASA's published numbers.

👉 Day 2: Interactive Streamlit web map (Today)

The same astronomy engine, wrapped in Streamlit + Folium. The full eclipse path is drawn as a bold red line arcing from Siberia across the North Pole, down through Iceland, across the Atlantic, into northern Spain, exiting over the Balearic Sea. Featured cities appear as colored dots: green for cities inside the path of totality, orange for cities with over 90% coverage, blue for moderate partials:

Click anywhere on the map — Boston, Almada, Tokyo, wherever — and the left sidebar populates with the local eclipse info for that exact point, complete with local time conversion. There’s a search box that geocodes any city name in the world, a live countdown to the eclipse, and popups on every featured city. All computed live from the same compute_eclipse() function we built yesterday.

Here the map shows that Boston will have a 16.01% partial eclipse:

Zero JavaScript files. Zero HTML files. Zero CSS files. About 420 lines of Python that read like a normal script.

View All Projects This Week

About the stack

Three new packages, each doing one clean thing on top of Day 1’s foundation.

Streamlit is Python’s most popular framework for turning scripts into web apps. Its whole philosophy is “write a normal Python script; get a web app for free.” No routes, no HTML templates, no request handlers. Every widget (button, text input, map) is a Python function call. st.title("Hello") puts a title on the page. st.button("Click me") adds a button and returns True when clicked. Then the whole script re-runs and your logic reacts.

Streamlit’s re-run model is the one thing that surprises people. Every widget interaction — every click, every keystroke, every zoom on the map — re-runs your entire script from top to bottom. That sounds inefficient, but combined with @st.cache_data for expensive computations and st.session_state for persisting values across re-runs, it’s actually a delightful mental model: no callbacks, no event handlers, just linear code that runs whenever anything changes.

Folium is a Python wrapper around Leaflet.js — the same JavaScript library that powers OpenStreetMap, Airbnb, and most of the interactive maps you’ve ever used online. Folium lets you build a map object in pure Python (folium.Map(), folium.PolyLine(), folium.CircleMarker()) and renders it as an HTML/JS widget. Nice API, zero JS to write.

streamlit-folium is the bridge. Folium alone gives you a beautiful map but it’s one-way — you can display it but users can’t send anything back to Python. streamlit-folium adds st_folium(), a component that renders a Folium map and returns click coordinates, current center, zoom level, and marker interactions as a Python dict. That’s what makes the map bidirectional — clicks flow back to your script, which reruns with the new click, which populates the sidebar. Without this component, our whole “click anywhere to see local eclipse info” flow wouldn’t work.

Understanding the Reusable Engine Pattern

Day 1’s eclipse.py was written as a script — it has a main() function, CLI parsing, colored terminal output. But look at the actual astronomy: compute_eclipse(lat, lon) takes two floats and returns a dict. Pure function. No CLI dependencies, no printing, no side effects other than reading the ephemeris (which is loaded once at module level).

That’s what makes Day 2 short. The first non-import line of eclipse_map.py is:

from eclipse import CITIES, compute_eclipse, format_duration

Everything else — Streamlit widgets, Folium map construction, click handling — is UI code around that pure function. If tomorrow we wanted a REST API version, we’d write a FastAPI file that imports the same three names. If we wanted a Discord bot, same thing. The engine doesn’t care about the interface.

This split — pure engine, thin interface — is one of the most valuable habits a Python developer can build. Every time you catch yourself hardcoding print() calls or hardcoding CLI arguments deep inside computational code, you’re gluing the engine and the interface together, and future-you (or future-teammate) will pay for it.

Understanding Streamlit’s Re-run Model

The Streamlit mental model is genuinely different from anything else in web development, and getting it wrong is the fastest way to end up with a broken app. Here’s the rule: every widget interaction re-runs the entire script from top to bottom.

Type a character in the search box? Whole script reruns. Click a button? Whole script reruns. Pan the map by one pixel? Whole script reruns. Nothing survives between runs by default.

This sounds catastrophic — surely computing the eclipse for 12 cities on every keystroke would be unbearably slow? — but Streamlit gives you two tools that make it work.

@st.cache_data memoizes expensive functions by their arguments. Wrap compute_eclipse in a cached version and it runs once per unique lat/lon:

@st.cache_data(show_spinner=False)
def cached_eclipse(lat: float, lon: float) -> dict:
    return compute_eclipse(round(lat, 3), round(lon, 3))

The round(..., 3) trick is worth calling out. Rounding to 3 decimal places means about 100 meters of precision — way finer than eclipse timing needs — but crucially it makes the cache key stable across nearby clicks. Click one pixel apart on the map, the cache still hits. Without the round, every micro-click would be a cache miss.

st.session_state is a dict-like object that persists across reruns for the current user’s session. Store anything you need to remember:

st.session_state.setdefault("selected", None)
st.session_state.setdefault("map_center", [55.0, -10.0])
st.session_state.setdefault("map_zoom", 3)

Now st.session_state.selected survives across every rerun. When the user clicks the map, we update it; when the script reruns, we read it and populate the sidebar accordingly.

Understanding the Bidirectional Map

The whole app hinges on st_folium() returning click data back to Python. Look at how it’s called:

map_state = st_folium(
    fmap,
    height=600,
    returned_objects=["last_clicked", "last_object_clicked", "center", "zoom"],
    key="eclipse-map",
)

returned_objects is the key argument. It tells the component: “here are the things I care about; give them to me on every rerun.” Then map_state is a Python dict with keys like:

{
    "last_clicked": {"lat": 43.263, "lng": -2.935},   # or None
    "last_object_clicked": None,                       # or {"lat", "lng"} of clicked marker
    "center": {"lat": 55.0, "lng": -10.0},
    "zoom": 3,
    ...
}

We use these three pieces:

# Preserve pan/zoom so it doesn't reset every rerun
if map_state.get("center"):
    st.session_state.map_center = [map_state["center"]["lat"], 
                                    map_state["center"]["lng"]]
if map_state.get("zoom") is not None:
    st.session_state.map_zoom = map_state["zoom"]

# React to new clicks
click = map_state.get("last_clicked") or map_state.get("last_object_clicked")
if click is not None:
    new_selected = (click["lat"], click["lng"],
                    f"({click['lat']:.3f}, {click['lng']:.3f})")
    if new_selected != st.session_state.selected:
        st.session_state.selected = new_selected
        st.rerun()

The st.rerun() at the bottom forces a fresh script run — needed because we changed session state after the map rendered. That fresh run picks up the new selected lat/lon and rebuilds the sidebar with the new eclipse info.

Understanding Folium PolyLines and Markers

Drawing the eclipse path is one line:

folium.PolyLine(
    locations=CENTERLINE,   # list of (lat, lon) tuples
    color="#dc2626",        # bold red
    weight=4,
    opacity=0.85,
    tooltip="Eclipse centerline",
).add_to(fmap)

The CENTERLINE list is 21 precomputed (lat, lon) points along the umbra’s track. I computed them once by finding, at each 5-minute step, the (lat, lon) on Earth’s surface where the Sun and Moon appear at exactly zero angular separation. That’s the definition of the shadow’s center. The optimization runs in scipy.optimize.minimize, takes about a second per point, and the output is baked into eclipse_map.py as a Python list — no runtime cost, works offline.

The featured cities are CircleMarker objects colored by coverage:

folium.CircleMarker(
    location=[lat, lon],
    radius=7,
    color=color,
    weight=2,
    fill=True,
    fillOpacity=0.75,
    popup=folium.Popup(popup_html, max_width=220),
    tooltip=name,
).add_to(fmap)

Popups are HTML strings — Folium accepts any HTML you throw at them. For each city, we compute its eclipse info once (cached forever), and stuff the coverage percentage and totality duration straight into the popup body.

Understanding the Sidebar Rendering

Streamlit has a built-in sidebar accessible via st.sidebar. Everything you’d normally do with st.something(...) you can do with st.sidebar.something(...):

def render_sidebar(lat, lon, label):
    st.sidebar.markdown(f"### 📍 {label}")
    st.sidebar.caption(f"{lat:.3f}, {lon:.3f}")

    res = cached_eclipse(lat, lon)

    if not res["visible"]:
        st.sidebar.error("No eclipse visible — Sun below horizon here.")
        return

    pct = res["max_obscuration"] * 100
    if res["in_totality"]:
        st.sidebar.success(
            f"### 🌑 **TOTAL ECLIPSE**\n"
            f"**{format_duration(res['totality_seconds'])}** of totality"
        )
    elif pct >= 90:
        st.sidebar.warning(f"### 🌗 **{pct:.2f}%** partial eclipse")
    else:
        st.sidebar.info(f"### 🌘 **{pct:.2f}%** partial eclipse")
    ...

st.success, st.warning, st.info, st.error are colored callout boxes — perfect for status messages. Green for totality, yellow for deep partials, blue for moderate, red for “not visible.” Zero CSS written.

Understanding the Live Countdown

The countdown line updates every time Streamlit re-runs (which is often, given re-runs happen on every widget interaction). No JavaScript setInterval, no WebSocket — just a normal Python function reading datetime.now():

GREATEST_ECLIPSE_UTC = datetime(2026, 8, 12, 17, 46, tzinfo=timezone.utc)

def countdown_line():
    delta = GREATEST_ECLIPSE_UTC - datetime.now(timezone.utc)
    if delta.total_seconds() <= 0:
        return "🌒 The 2026 eclipse has already happened."
    days = delta.days
    hours, rem = divmod(delta.seconds, 3600)
    minutes, _ = divmod(rem, 60)
    return f"⏱ **{days}d {hours}h {minutes}m** until greatest eclipse"

Between reruns the countdown stays frozen, but the moment anyone interacts with anything — even hovering a marker triggers a re-run — the countdown ticks. Good enough for a friendly display; if you needed literal per-second precision you’d use a small JS component, but that’s out of scope.

Understanding Layout and Ordering

Streamlit renders in the order you call widgets. That’s why we call render_sidebar() before st_folium() — even though visually the sidebar is on the left and the map is on the right, we want the sidebar to reflect the current st.session_state.selected, and the map click handling that might change selected happens after. So the flow is:

1. Read st.session_state.selected

2. Render sidebar based on it (frozen for this rerun)

3. Render the map

4. Handle map clicks — if there’s a new one, update session state and st.rerun()

5. Next rerun starts at step 1 with the new selection

If we rendered the sidebar after the map, the sidebar would always be showing the previous click, one step behind. Small ordering thing, big UX difference.

Setup Instructions

Install dependencies:

pip install streamlit folium streamlit-folium

Three new packages on top of Day 1’s stack. If you skipped Day 1, also install:

pip install skyfield skyfield-data rich geopy timezonefinder numpy

Run it:

streamlit run eclipse_map.py

Streamlit opens the app in your browser automatically at

http://localhost:8501

. First load takes about 6 seconds — most of that is loading the JPL ephemeris and computing eclipse info for the 12 featured cities (all cached after that, so subsequent interactions are instant). Any changes to eclipse_map.py while the server runs get detected and Streamlit prompts you to reload.

Important: both files must be in the same folder. eclipse_map.py imports from eclipse.py. Put them together, cd into that folder, then run.

Practical Use Cases

Ship it publicly for eclipse day. Streamlit Community Cloud hosts Streamlit apps for free directly from a public GitHub repo. Push these two files plus a requirements.txt, connect the repo, and you have a live URL you can share on social media, WhatsApp, or a personal newsletter. Total setup: about ten minutes. Free tier is more than enough for a novelty app that gets shared for a week.

Template for any point-on-map computation. Any problem shaped like “user picks a location on Earth → I compute something for that location” fits this exact pattern: weather forecasts, elevation lookups, travel-time calculations, real estate comparisons, air-quality checks. Swap compute_eclipse for compute_weather and you have a weather app.

Real portfolio project. Two files, ~830 lines total, real astronomy, real interactive UI, deployable in ten minutes. Put it on your CV under Projects with a link to the live version — dramatically stronger than “made a chatbot with the OpenAI API” like every other candidate.

What’s Next

Thursday’s post is a standalone deep-dive on a specific piece of infrastructure. Coming this week: why your app should never talk to your database on port 5432, and the three-line change that makes it 10x faster. Free post, all subscribers get it.

Next week we shift gears again — details on Tuesday.

Solution

Click below to find the complete source code that produces the interactive map with the eclipse path and other data:

Read more

This week we build a real astronomy tool. Day 1 is a Python CLI script that answers “what will I see from my location?” for any place on Earth — eclipse start, maximum, end, percentage of Sun covered, whether you’re in the path of totality. Day 2 wraps the astronomy in an interactive Streamlit web map: click anywhere on the world, get instant local eclipse timing. The astronomy is the hard part, and we do it once — Day 2 imports the same functions we build today.

Projects in this week’s series:

👉 Day 1: Command-line eclipse info tool (Today)

When the user runs the script with no arguments, it prints a colored summary table of all the major cities in the eclipse path — Reykjavik, Bilbao, Burgos, Zaragoza, Palma, plus nearby cities like Barcelona, Madrid, and Lisbon that get deep partials:

When they run it with a city name, for example:

python eclipse.py Madrid

or coordinates:

python eclipse.py "43.26, -2.94" 

they get a detailed report — start/max/end times in local timezone plus UTC, coverage percentage, magnitude, and totality duration if applicable:

Everything is computed live from JPL ephemerides. Accurate to within seconds of NASA’s published numbers.

Day 2 (Tomorrow): Interactive Streamlit web map of the eclipse

Tomorrow we will use the astronomy engine, but wrapped in Streamlit + Folium. Full eclipse path drawn on an interactive world map — centerline and totality band. Click anywhere on Earth and the sidebar populates with local eclipse info computed live for that exact point. City search box (type “Rome” or “Boston” instead of clicking). Real-time countdown to the eclipse. Major cities pre-marked with popups:

The map is the payoff of the week — turning terminal output into something you can share with your family, your students, or a WhatsApp group.

View All Projects This Week

About the stack

Today’s script uses five packages, each doing one specific thing:

Skyfield is Python’s modern astronomy library. It reads JPL planetary ephemeris files — the same tables NASA uses to navigate spacecraft — and gives you sub-second-accurate positions of the Sun, Moon, planets, and satellites from any point on Earth at any time. This is real, professional-grade astronomy code. When you run it and get an eclipse timing, that timing is correct to within a second or two.

skyfield-data is a companion package that bundles the DE421 ephemeris file (about 17 MB of JPL data covering 1900–2050) as a Python package. Normally Skyfield downloads the file from JPL on first run; using skyfield-data means it just works offline, no download step, no waiting.

Rich is the library for beautiful terminal output in Python. Colored text, formatted tables, spinners, progress bars — one import and your CLI script suddenly looks professional instead of like a homework submission. The tables it produces are Unicode box-drawing characters that render perfectly in any modern terminal.

geopy does geocoding — city name to lat/lon. It’s a thin wrapper around Nominatim (OpenStreetMap’s free geocoder), so geopy.geocode("Bilbao") returns (43.263, -2.935) and works for any place OpenStreetMap knows about.

timezonefinder does the opposite of geocoding for time — given a lat/lon, it tells you the timezone. Purely offline, backed by polygon data for every timezone on Earth. We use this to convert Skyfield’s UTC timestamps into local time at the user’s chosen location, so “eclipse maximum at 18:27:20 UT” becomes “20:27:20 CEST” for a Spanish city and “17:48:00 GMT” for Reykjavik automatically.

The single-file philosophy stays

Everything — imports, constants, city list, astronomy math, geometry, formatting, CLI parsing — lives in one eclipse.py file. Around 400 lines total, organized in clearly-labeled sections. No config file, no separate modules, no folder hopping.

Setup Instructions

Install dependencies:

pip install skyfield skyfield-data rich geopy timezonefinder numpy

Six packages. The one to know about is skyfield-data — without it, Skyfield will download the JPL ephemeris file on first run (~17 MB, one-time). With it, the file lives inside the pip package and everything works offline.

Run it in one of the following ways:

python eclipse.py                       # summary table for cities in the path
python eclipse.py Bilbao                # detailed report for one city
python eclipse.py "Palma de Mallorca"   # quote names with spaces
python eclipse.py "43.26, -2.94"        # or pass raw coordinates

First run takes a couple of seconds to load the ephemeris and Rich; subsequent runs are near-instant.

Understanding the Astronomy

The whole eclipse question — from your specific location on Earth — reduces to one geometric question repeated over time: how much do the Sun’s and Moon’s apparent disks overlap as seen from your standing point?

Each disk has an angular size in the sky. The Sun’s angular radius from Earth is about 15.8 arcminutes (roughly a quarter of a degree). The Moon’s is almost identical — around 15.5 to 16.7 arcminutes depending on where the Moon is in its elliptical orbit. That near-perfect size match is why total solar eclipses exist at all: if the Moon were noticeably smaller in the sky, we’d only ever get annular eclipses; if noticeably larger, no “diamond ring” moment. It’s a coincidence of two body sizes and orbital distances that will end in about 600 million years as the Moon slowly drifts away.

For an eclipse from your location, the question is what fraction of the Sun’s disk area is covered by the Moon’s disk at each moment. When that fraction is 0, no eclipse. When it’s 1 and the disks are perfectly overlapping, totality. Everything between is a partial. Simple in principle. In practice, we need to know the exact angular positions of Sun and Moon as seen from your specific lat/lon at every moment during the event.

That’s what Skyfield gives us.

Understanding Skyfield

Skyfield is the professional-grade astronomy library for Python. Under the hood, it reads JPL DE421 — a giant table of planetary positions computed by NASA’s Jet Propulsion Laboratory for the years 1900 to 2050, accurate to sub-arcsecond. Every time we ask “where is the Moon right now?”, Skyfield interpolates through this table.

Three fundamental objects:

from skyfield.api import load, load_file, wgs84
from skyfield_data import get_skyfield_data_path
import os

# The ephemeris (planetary positions table).
bsp = os.path.join(get_skyfield_data_path(), 'de421.bsp')
ts = load.timescale()          # for building Time objects
eph = load_file(bsp)           # the JPL ephemeris

sun = eph['sun']
moon = eph['moon']
earth = eph['earth']

Then we build an observer — a point on Earth’s surface with a lat/lon:

observer = earth + wgs84.latlon(43.263, -2.935)   # Bilbao

Now we can ask “what does the observer see?” at any time:

t = ts.utc(2026, 8, 12, 18, 27)              # Aug 12, 2026, 18:27 UT
sun_app = observer.at(t).observe(sun).apparent()
moon_app = observer.at(t).observe(moon).apparent()

The .apparent() at the end applies all the corrections that make astronomy hard: light-travel time (the Sun’s photons left it 8 minutes ago, the Moon’s about 1.3 seconds ago), aberration of light due to Earth’s motion, and the deflection of light passing near the Sun. Real, textbook astronomy.

From these, we can extract everything we need:

separation = sun_app.separation_from(moon_app)       # angular gap
sun_dist_km = sun_app.distance().km                  # for angular radius
sun_alt_deg = sun_app.altaz()[0].degrees             # is Sun above horizon?

Understanding Angular Radii

Physical radii are known constants — the Sun is about 695,700 km in radius, the Moon 1,737.4 km. Angular radius depends on how far away the object is at that moment. The formula:

sun_rad = np.arcsin(R_SUN_KM / sun_dist_km)     # radians
moon_rad = np.arcsin(R_MOON_KM / moon_dist_km)  # radians

Simple trigonometry. The Sun’s distance varies by about 3% over the year (Earth’s slightly elliptical orbit). The Moon’s distance varies by about 12% each month (much more elliptical orbit). These small variations are exactly what determines whether a given eclipse is total or annular — and what fraction of the Sun’s disk gets covered at maximum in a given place.

Understanding Vectorized Time

Naive approach: loop through 5040 times (7 hours × 720 samples/hour at 5s resolution), computing Sun and Moon positions at each. That’s slow.

Better approach: pass all 5040 times to Skyfield at once, as a numpy array:

minutes = np.arange(0, 7*60, 5/60)   # every 5 seconds for 7 hours
times = ts.utc(2026, 8, 12, 14, minutes)   # ONE Time object containing 5040 timestamps

sun_app = observer.at(times).observe(sun).apparent()      # 5040-point result
moon_app = observer.at(times).observe(moon).apparent()    # 5040-point result

seps = sun_app.separation_from(moon_app).radians          # numpy array
sun_dist_km = sun_app.distance().km                       # numpy array

Skyfield handles vectorized time natively — internally, everything is numpy arrays. Total runtime for computing the eclipse at one city: about 0.4 seconds. For all 12 cities in the table: about 5 seconds. Fast enough that you can compute it live in a web app (which is what we’ll do on Day 2).

Understanding Circle-Circle Intersection

Once we have angular separation d and angular radii R and r, we need the intersection area of two circles. This is a classic geometry problem with a well-known closed-form solution:

def circle_intersection_area(d, R, r):
    """Works elementwise on numpy arrays. Three cases:"""

    # Case 1: no overlap
    if d >= R + r: return 0

    # Case 2: one disk fully contains the other
    if d <= abs(R - r): return np.pi * min(R, r)**2

    # Case 3: partial overlap - standard formula
    part1 = r**2 * np.arccos((d**2 + r**2 - R**2) / (2*d*r))
    part2 = R**2 * np.arccos((d**2 + R**2 - r**2) / (2*d*R))
    part3 = 0.5 * np.sqrt((-d+r+R) * (d+r-R) * (d-r+R) * (d+r+R))
    return part1 + part2 - part3

The math looks intimidating but the shape is intuitive. part1 is the area of the moon’s disk chord cut by the sun’s disk. part2 is the same for the sun cut by the moon. part3 corrects for the overlap of those two chords (which would otherwise be double-counted). The intersection area is part1 + part2 - part3. It’s the same formula every graphics engine uses for lens-flare rendering and collision detection.

Divide the intersection area by the sun’s area, and you have obscuration — the fraction of the Sun’s disk covered by the Moon at any given moment. Multiply by 100, you have the percentage.

Understanding the Horizon Check

Geometry can happily tell you the Sun and Moon are perfectly aligned at 3 AM local time — but no eclipse is visible then because the Sun is on the other side of the Earth. Every eclipse calculation has to check whether the Sun is actually above the horizon:

sun_alt_deg = sun_app.altaz()[0].degrees   # array of altitudes
above_horizon = sun_alt_deg > 0
obscuration = np.where(above_horizon, obscuration, 0.0)

altaz() returns (altitude, azimuth, distance) — altitude is how high above the horizon, azimuth is compass direction. Above 0 means visible, below 0 means the Sun has set (or hasn’t risen yet). Any moment when the Sun is below the horizon has effective obscuration of zero — the eclipse might be “happening” geometrically, but it’s happening on the far side of the world.

This is exactly why the eclipse table shows different results for Sydney (Sun already set, no eclipse visible) versus NYC (Sun at 62° altitude, small partial eclipse visible) versus Bilbao (Sun at 8° altitude — near sunset but still up, gets full totality).

Understanding Timezone Conversion

Skyfield returns everything in UTC. But nobody thinks in UTC. When we report to the user, we want their local time. Two libraries:

timezonefinder takes a lat/lon and returns a timezone name:

from timezonefinder import TimezoneFinder
tf = TimezoneFinder()
tf.timezone_at(lat=43.263, lng=-2.935)   # 'Europe/Madrid'
tf.timezone_at(lat=64.147, lng=-21.940)  # 'Atlantic/Reykjavik'

It works entirely offline using polygon data of every timezone on Earth. Fast and reliable.

zoneinfo (Python stdlib since 3.9) converts UTC datetimes into that timezone:

from zoneinfo import ZoneInfo
local = utc_dt.astimezone(ZoneInfo('Europe/Madrid'))

Together, they let us take any (lat, lon, utc_datetime) triple and produce a properly-localized display like 20:27:20 CEST. Handles daylight saving automatically because that’s built into the timezone data.

Understanding Path of Totality

The path of totality is where the Moon’s disk completely covers the Sun’s disk. Geometrically: separation + sun_radius <= moon_radius. That is, even at the farthest edge of the Sun from the Moon’s center, the Sun’s edge is still inside the Moon’s disk.

total_mask = (seps + sun_rad <= moon_rad) & above_horizon
in_totality = bool(total_mask.any())

if in_totality:
    first_total = np.argmax(total_mask)
    last_total = len(total_mask) - 1 - np.argmax(total_mask[::-1])
    totality_seconds = (last_total - first_total) * SAMPLE_STEP_SECONDS

For Burgos, our tool reports 1m 45s of totality. NASA’s official prediction is 1m 42s. That 3-second discrepancy is our sampling resolution (5 seconds), not an astronomy error — the underlying JPL data is accurate to milliseconds. If you needed sub-second precision, you’d interpolate between grid points; for a human-readable report, 3 seconds is fine.

Practical Use Cases

Trip planning right now. If you’re anywhere in Europe on August 12 and want to know exactly what you’ll see from your Airbnb, run this script with your coordinates. Get the exact times, plan your dinner around them.

Teaching astronomy. This is one of the most compact “real astronomy” projects you can build in Python. Under 400 lines and it produces genuinely correct results. Assignable to students at any level: middle-schoolers can play with cities, undergrads can dig into the geometry, grad students can extend it to future eclipses (there’s a total in North America in August 2044).

Foundation for Day 2. Every function we built today gets reused tomorrow in the web map. compute_eclipse(lat, lon) becomes the callback when someone clicks the map. That’s the pedagogical arc of the week: build the engine on Day 1, wrap it in something beautiful on Day 2.

Coming Wednesday

Tomorrow we take today’s astronomy engine and wrap it in an interactive Streamlit web app with a Folium/Leaflet map. Full eclipse path drawn as centerline and totality band. Click anywhere on the world and the sidebar populates with local eclipse info computed live. City search box, countdown timer, popups on major cities. The full “wow” of the week.

If you want the map, upgrade here before Wednesday.

Solution

Below you will find the source code of this project which will produce the same output as shown in the screenshots in this post.

Get the source code here:

View Code Solution

You have probably written a function you are a bit proud of. Perhaps it generates strong passwords, or cleans up messy text, or calculates something useful for you. It works fine on your laptop. However, there is a limitation you might not have thought about: the only way to use that function is to open your laptop, activate the environment, and run the script yourself. Your friend cannot use it. Your phone cannot use it. Even another one of your own scripts, running on a different machine, cannot use it.

The fix for that is called an API. You have probably used APIs before, at least as the caller/client: you send a request to a URL and you get data back instead of a web page. So today we do the other side. We take your function and give it a URL.

Five lines around your function

For this we will use FastAPI. Install it together with uvicorn, the program that will run your API:

pip install fastapi uvicorn

Now say this is your function, saved in a file called main.py:

import secrets
import string

def generate_password(length):
    chars = string.ascii_letters + string.digits
    return "".join(secrets.choice(chars) for _ in range(length))

To turn it into an API, you add this around it:

from fastapi import FastAPI

app = FastAPI()

@app.get("/password")
def password(length: int = 16):
    return {"password": generate_password(length)}

The line that does the magic is the decorator. @app.get("/password") tells FastAPI: when someone visits /password, run this function and send back whatever it returns.

Starting the server

Now run it from the terminal:

uvicorn main:app

Your function is now listening at http://127.0.0.1:8000.

Open http://127.0.0.1:8000/password in your browser and you will see something like {"password":"NlDRymnljPanqFp2"}. Refresh, and you get a new one. Then try adding ?length=24 to the end of the URL, and you will get a longer password back.

Notice what happened there. You typed ?length=24 in a browser, and FastAPI passed that value to your function as the length argument. The URL became a function call.

That mapping is the entire idea of an API, and it is worth staring at for a minute. The path picks the function, the query string fills its arguments, and the return value travels back as JSON.

Two things you got for free

There are two more things FastAPI did without asking you.

First, open http://127.0.0.1:8000/docs in your browser. You will find a documentation page for your API, generated from your function’s signature. It lists your endpoint, its parameters, and even has a button to try it out. You wrote no documentation, yet your API has some.

Second, try calling your API with ?length=abc. Instead of crashing, it responds with a clear message saying that length should be a valid integer. FastAPI read the length: int hint in your function and built the validation for you. When I first saw this, I had written type checks by hand for years, so this felt slightly unfair.

Before you send the URL to a friend

One warning, and if you read last week’s post about webhooks you already know what is coming. If you send http://127.0.0.1:8000/password to a friend, it will not work. That address means “this machine”, so your API is real but only reachable from your own computer. To let the world call it, you deploy it to a server, which is a computer with a public address that stays on. That trip from laptop to server is a topic we keep circling back to in this publication, because it is the trip that matters most.

The bigger picture

Here is the way I want you to think about all this. Every API you have ever used, whether it was a weather API, a payment API, or an AI API, is exactly what you built today: someone’s function, wrapped with a decorator, running on a computer that stays on. There is no magic in between.

And it also means any useful function you have ever written is about five lines away from becoming a service.

If you learned something from this today, consider upgrading for the full experience: every weekly project with full source code, plus the complete archive. Since you read this far, I’d like to offer you 35% off the annual plan as a token of appreciation. Click below to get the discount:

Get 20% off: $99 → $79/year

Projects in this week’s series:

Day 1 (Yesterday): Sign up, log in, and take notes

When the user visits the site, they see a clean signup / login page. After creating an account, they land in their notes dashboard, with a form to add notes and a list of all their existing ones:

Each note has a delete button that removes it instantly, without a full page reload. Logging out clears the session, and trying to visit /notes while logged out bounces you back to the login page. Every user only sees their own notes — I can’t peek at yours, you can’t peek at mine.

👉 Day 2 (Today): Wiki-links between notes + full-text search

Type [[computer tricks]] in one note:

And “computer tricks” automatically becomes a separate note and a clickable hyperlink in the first note:

Click it, and you’re on the “computer tricks” note where you can enter more details about that new note:

The app also shows a backlinks section at the bottom listing every other note that mentions this one. Same pattern as Notion, Obsidian, and Roam Research.

Plus a search bar on the notes list that finds any word across all your notes as you type — powered by SQLite’s built-in FTS5 full-text search extension, no external dependencies. Type a word, wait 250ms, and the notes grid updates in place with matching notes:

View All Projects This Week

Setup Instructions

Same dependencies as yesterday, no new packages:

pip install fastapi uvicorn jinja2 sqlalchemy bcrypt itsdangerous python-multipart

Everything today uses stuff that’s already installed: re for parsing, sqlalchemy.text for the raw SQL that creates the FTS5 virtual table, markupsafe.Markup to tell Jinja “I’ve already escaped this HTML, don’t double-escape it.”

Run it:

uvicorn notes_app_wiki:app --reload

Same as yesterday. The notes.db file from Day 1 works — the new tables (wiki_links and notes_fts) get created on startup if they don’t exist. Your existing notes stay, but they won’t be indexed for search or wiki-links until you edit-save them once (because indexing happens on write, not on read).

Understanding Wiki-Links as a Graph

A note is not just text — it’s a node in a graph. Every [[link]] inside a note’s content is a directed edge to another note. Once you have edges, you get all the things graphs give you: neighborhoods, paths, backlinks, connected components.

The technical decision that unlocks this: store the link target as a string, not as a foreign key.

class WikiLink(Base):
    __tablename__ = "wiki_links"
    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False, index=True)
    source_note_id = Column(Integer, ForeignKey("notes.id"), nullable=False, index=True)
    target_title = Column(String, nullable=False, index=True)

Note that target_title is a plain string, not a ForeignKey(notes.id). This is deliberate. If it were a foreign key, you couldn’t create the link before the target note existed — which would ruin the Obsidian pattern of writing [[future recipe]] first and creating the actual note later. Storing the title as text lets you write “forward references” that resolve automatically when the target gets created.

The trade-off: renaming a note breaks all links pointing to its old name. Same as Obsidian. Most systems handle this by finding-and-updating all wiki-links on rename; we skip that for now.

Understanding the Wiki-Link Parser

Two functions do the work: extract_wiki_links (for indexing) and render_wiki_links (for display):

import re

WIKI_LINK_RE = re.compile(r"\[\[([^\[\]]+)\]\]")

def extract_wiki_links(content: str) -> list[str]:
    """Return lowercased target titles from all [[links]] in text."""
    return [m.group(1).strip().lower()
            for m in WIKI_LINK_RE.finditer(content)]

The regex is intentionally simple: two brackets, one or more characters that aren’t brackets, two brackets. No nesting, no multi-line links. Fewer edge cases, fewer surprises.

We lowercase the target title on the way out because wiki-link lookups should be case-insensitive — [[Groceries]] and [[groceries]] should point to the same note. Store lowercase, query lowercase, display whatever the user typed.

Understanding Safe HTML Rendering

This part is subtle. When we render a note’s content, we’re generating HTML from user input, which is where XSS vulnerabilities usually live. The naive “just escape everything at the end” doesn’t work — we’re intentionally producing HTML for the wiki-links, and Jinja’s autoescape would treat our generated <a> tags as text.

The right approach is to tokenize the content into pieces and escape each piece separately as we go:

from html import escape as html_escape
from urllib.parse import quote
from markupsafe import Markup

def render_wiki_links(text, notes_by_title):
    parts = []
    last_end = 0

    for match in WIKI_LINK_RE.finditer(text):
        # Regular text before this link - escape it as HTML
        parts.append(html_escape(text[last_end:match.start()]))

        raw_title = match.group(1).strip()
        safe_display = html_escape(raw_title)     # for display in the link
        target = notes_by_title.get(raw_title.lower())

        if target is not None:
            parts.append(
                f'<a href="/__u/dailypythonprojects.substack.com/notes/%7Btarget.id%7D" class="wiki-link">'
                f'{safe_display}</a>'
            )
        else:
            safe_url = quote(raw_title, safe="")   # for the URL
            parts.append(
                f'<a href="/__u/dailypythonprojects.substack.com/notes/new?title={safe_url}" '
                f'class="wiki-link broken">{safe_display}</a>'
            )
        last_end = match.end()

    parts.append(html_escape(text[last_end:]))
    return Markup("".join(parts))

Two things happen safely:

1. Every piece of user content — the text between links, and the link titles themselves — goes through html_escape before being placed in the HTML. A note that contains <script> gets rendered as literal <script>.

2. We return Markup(...) at the end, which tells Jinja “trust this string, don’t escape it again.” Otherwise Jinja’s autoescape would turn our <a> tags into <a> and destroy the links.

The URL title gets quote() instead of html_escape because it’s going into a URL, not into HTML. quote() handles URL-encoding (spaces → %20, special chars percent-encoded). Same principle: escape for the context you’re inserting into.

Understanding the Sync Pattern

The wiki-links table doesn’t magically populate itself — you have to keep it in sync with the notes table by hand. Every time a note is created, edited, or deleted, the wiki-links index has to be updated:

def sync_wiki_links(db: Session, note: Note) -> None:
    """Rebuild the wiki_links rows for one note. Call after create or edit."""
    db.query(WikiLink).filter(WikiLink.source_note_id == note.id).delete()
    for target_title in extract_wiki_links(note.content):
        db.add(WikiLink(
            user_id=note.user_id,
            source_note_id=note.id,
            target_title=target_title,
        ))

Simple pattern: delete all wiki-links FROM this note, re-parse the content, insert the new set. No fancy diff-and-update logic. For hundreds of links per note it might matter, but for typical note content it’s fine.

Then the create/edit routes call this after saving the note:

@app.post("/notes")
async def create_note(title, content, user, db):
    note = Note(user_id=user.id, title=title.strip(), content=content)
    db.add(note)
    db.flush()                    # need note.id for the derived indices
    sync_wiki_links(db, note)     # update the wiki-links table
    fts_insert(db, note)          # update the FTS5 index
    db.commit()
    return RedirectResponse(f"/notes/{note.id}", status_code=303)

Note db.flush() — this sends the INSERT to SQLite so note.id gets populated, but doesn’t commit yet. We need the ID to link the derived tables. Then everything commits together as one atomic transaction.

This is the pattern for every derived index in every real app. Materialized views, cache layers, search indexes, activity feeds — they all follow this shape. Source of truth (your notes) gets a write, then N derived indexes get updated in the same transaction. If any step fails, everything rolls back and stays consistent.

Understanding Backlinks

Once wiki-links are indexed, backlinks are trivial — just query the same table in the other direction:

def get_backlinks(db: Session, note: Note) -> list[Note]:
    """Notes (of the same user) that link TO this note via [[title]]."""
    rows = (db.query(WikiLink.source_note_id)
              .filter(WikiLink.user_id == note.user_id,
                      WikiLink.target_title == note.title.lower(),
                      WikiLink.source_note_id != note.id)
              .distinct()
              .all())
    ids = [row[0] for row in rows]
    if not ids:
        return []
    return (db.query(Note)
              .filter(Note.id.in_(ids))
              .order_by(Note.updated_at.desc())
              .all())

Two queries, two SQL round-trips: find the note IDs, then hydrate them. Indexed on both user_id and target_title, so this stays fast even with thousands of notes.

The source_note_id != note.id filter avoids showing a note as its own backlink if it happens to contain [[itself]]. Small polish; you’d hit this bug in production without it.

Understanding SQLite FTS5

Here’s a fact that surprises most people: SQLite has a built-in full-text search engine. It’s called FTS5, it’s compiled into virtually every SQLite install since 2015, and it’s genuinely production-grade. Big tech uses it internally for shipping products. You don’t need Elasticsearch, Meilisearch, Algolia, or even PostgreSQL’s tsvector — just a CREATE VIRTUAL TABLE statement:

def init_fts(engine):
    with engine.connect() as conn:
        conn.execute(text("""
            CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(
                note_id UNINDEXED,
                user_id UNINDEXED,
                title,
                content,
                tokenize = 'porter unicode61'
            )
        """))
        conn.commit()

A few important pieces:

• USING fts5(...) — this is a virtual table. It doesn’t work like a normal table; it’s backed by an inverted index. You still INSERT, UPDATE, DELETE into it, but the storage under the hood is optimized for fast text search.

• UNINDEXED — these columns are stored in the FTS5 table but not searchable. note_id and user_id are just tags we use to filter results and link back to the notes table. Marking them UNINDEXED skips building an index for them and saves disk space.

• title and content — these are the searchable columns. FTS5 tokenizes them and builds an inverted index.

• tokenize = 'porter unicode61' — this stacks two tokenizers. unicode61 handles Unicode text properly (Chinese, Arabic, accented Latin, emoji). porter applies English stemming — so running matches run, flies matches fly. If you’re not making an English notes app, drop porter.

The FTS5 virtual table lives entirely inside your existing notes.db SQLite file. No new database process, no new port, no new dependency. That’s a real production-grade full-text search engine embedded in a single file.

Understanding HTMX Search-as-You-Type

The search input on the notes list has four HTMX attributes:

<input type="search"
       name="q"
       placeholder="Search your notes..."
       hx-get="/notes/search"
       hx-trigger="input changed delay:250ms, search"
       hx-target="#notes-grid"
       hx-swap="innerHTML">

• hx-get="/notes/search" — send a GET request to this URL

• hx-trigger="input changed delay:250ms, search" — fire on input changes with a 250ms debounce, and also on the browser’s native “search” event (fired when the user clears the input via the × button on the search input)

• hx-target="#notes-grid" — put the response into the element with this ID

• hx-swap="innerHTML" — replace the target’s inner HTML with the response

The 250ms debounce is critical. Without it, every keystroke fires a request — a user typing “groceries” would fire 9 requests. With the debounce, HTMX waits until the user has been idle for 250ms before firing one request. Instant-feeling for humans, gentle on the server.

What’s Next

Thursday’s post is a standalone deep-dive on a specific piece of infrastructure. Coming this week: why your app should never talk to your database on port 5432, and the three-line change that makes it 10x faster. Free post, all subscribers get it.

Next week I’m switching gears into a different kind of build — details on Tuesday.

Solution

Below you will find the source code of this project which will produce the same output as shown in the screenshots in this post.

Get the source code here:

Read more

Two days, one file, zero JavaScript. You’ll build a working note-taking web app with real authentication — sign up, log in, protected pages, sessions, password hashing. Wednesday adds the innovative feature that makes it feel like Notion or Obsidian instead of a class project.

Projects in this week’s series:

👉 Day 1 (Today): Sign up, log in, and take notes

When the user visits the site, they see a clean signup / login page:

After creating an account, they land in their notes dashboard, with a form to add a note:

Once the user has some notes added they will see a list of all their existing ones:

Each note has a delete button that removes it instantly, without a full page reload. Logging out clears the session, and trying to visit /notes while logged out bounces you back to the login page. Every user only sees their own notes — I can’t peek at yours, you can’t peek at mine.

Day 2 (Tomorrow): Wiki-links between notes + full-text search

Type [[groceries]] in one note and it becomes a live hyperlink.

Click it, and you’re on the “groceries” note — with a backlinks section at the bottom showing every other note that mentions this one. Same pattern as Notion, Obsidian, and Roam Research:

Plus a search bar in the nav that finds any word across all your notes as you type — powered by SQLite’s FTS5 full-text search extension, no external dependencies. Two novel features that turn a plain notes list into a real personal wiki.

View All Projects This Week

Today’s Project

A working multi-user notes app with real authentication.

Users can sign up with a username and password. They can log in and log out. The password is stored hashed — even you as the app owner can’t read it. When they’re logged in, they see their own notes. When they’re not, they get bounced to the login page. And user A can never, ever see user B’s notes, no matter what URLs they try to hack.

Everything lives in one Python file. Routes, database models, HTML templates, security helpers — all in notes_app.py. Templates are strings inside the Python file, loaded through Jinja2’s DictLoader. CSS and interactivity come from CDN links — Pico.css handles styling, HTMX handles the delete-without-reload button. No .html files, no .css files, no .js files.

This is deliberate. Real web apps eventually get split into folders and modules, but that split hides the shape of the whole system from students learning it for the first time. Seeing every route, every model, every template in one file is worth more than “good practice” for now.

About the stack

We’re using a modern, deliberately-chosen stack. Not the biggest one, not the trendiest one — the one that gets us to a working web app fastest while teaching real concepts.

FastAPI is Python’s most popular modern web framework. Async by default, tiny footprint, gets out of your way. It surpassed Flask in weekly downloads in early 2024 and hasn’t looked back.

Jinja2 is the templating engine — it’s what Flask uses too. Templates look like HTML with {{ variables }} and {% if conditions %}. We put them inside our Python file as strings using Jinja2’s DictLoader, so the whole app is one file.

SQLAlchemy is Python’s most-used database toolkit. We use its ORM (Object-Relational Mapper) so we can write Python classes that map to database tables. Backend is SQLite — one file, no separate database server.

bcrypt hashes passwords. This is the standard for password storage — slow by design so brute-force attacks are impractical, and includes a random salt so identical passwords hash to different values.

itsdangerous signs session cookies. When a user logs in, we put their user ID in a cookie signed with a secret key. If anyone tampers with the cookie, the signature won’t verify and we reject it.

Pico.css is a classless CSS framework. That means you don’t have to write class="btn btn-primary" — you just write a plain <button> and it looks professional automatically. One CDN link in the HTML <head> and everything looks like a real product.

HTMX is the “modern web app without JavaScript” library. It adds attributes to HTML (hx-post="/notes/1/delete") that fetch responses and swap them into the page — like React, but written as HTML attributes. Zero JavaScript files in our project.

Project Task

Build a single-file FastAPI app that:

• Has a signup page — validates the username (3-30 chars, not already taken) and password (min 6 chars)

• Has a login page — verifies credentials against the hashed password

• Sets a signed session cookie on successful signup/login

• Has a /logout route that clears the session cookie

• Bounces logged-out users away from protected pages

• Shows the logged-in user’s notes (only theirs — never anyone else’s)

• Lets users create a new note (title + content)

• Lets users view a single note

• Lets users delete a note without a page reload, using HTMX

• Stores everything in a local SQLite database via SQLAlchemy

• Puts all HTML templates inside the Python file (Jinja2 DictLoader)

• Loads CSS and JavaScript from CDN — no local static files

Setup Instructions

Install dependencies:

pip install fastapi uvicorn jinja2 sqlalchemy bcrypt itsdangerous python-multipart

Seven packages. uvicorn is the web server that runs our FastAPI app. python-multipart is required by FastAPI to parse HTML form submissions (signup, login, new note). The rest we’ve discussed.

Run it:

uvicorn notes_app:app --reload

The --reload flag restarts the server automatically whenever you save the file. Open http://127.0.0.1:8000 in your browser. You’ll see the login page. Click “Sign up”, create an account, and you’re in.

A note about the database: the first time you run the app, it creates a file called notes.db in the current directory. That’s your SQLite database — every user, every note lives inside it. Delete the file to start fresh; back it up if you don’t want to lose your notes.

Understanding Password Hashing

The single most important idea in this project.

Never store passwords in plain text. Even if you promise yourself the database is safe, you’re one leaked backup, one misconfigured cloud bucket, one disgruntled employee away from disaster. Every major breach in the news is either “they stored plain-text passwords” or “they stored badly hashed passwords.”

The right approach: store a cryptographic hash of the password. A hash is a one-way function — you can compute it from the password, but you cannot recover the password from it. When a user logs in, you hash whatever they typed and compare it to the stored hash. Match = correct. No match = wrong.

But not just any hash. Fast hashes like SHA-256 are the wrong choice for passwords — an attacker who steals your database can compute billions of hashes per second and brute-force weak passwords in minutes. You need a slow hash, deliberately designed to be expensive to compute.

bcrypt is that hash. It’s slow by design — takes ~100ms per hash, which is invisible to a legitimate user but makes brute-forcing impractical. It also includes a random salt per password, so even two users with the same password get different hashes.

Our code:

import bcrypt

def hash_password(password: str) -> str:
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()

def verify_password(password: str, hashed: str) -> bool:
    return bcrypt.checkpw(password.encode(), hashed.encode())

Three details worth noting:

• bcrypt.gensalt() generates a random salt every call. That’s why two identical passwords produce different hashes. Never reuse a salt.

• .encode() on input, .decode() on output — bcrypt works in bytes, we work in strings.

• bcrypt.checkpw is constant-time. It compares in a way that doesn’t leak how much of the hash matched — otherwise an attacker could time your responses and gradually learn parts of the hash.

There’s one bcrypt quirk worth knowing: it silently ignores anything past the first 72 bytes. So bcrypt.hashpw("A" * 100) and bcrypt.hashpw("A" * 72) produce the same hash. Newer versions of the bcrypt library raise an error instead of silently truncating — we defensively truncate to 72 bytes ourselves:

BCRYPT_MAX_BYTES = 72

def _prepare_password(password: str) -> bytes:
    """Encode as UTF-8 and truncate to bcrypt's 72-byte limit safely."""
    encoded = password.encode("utf-8")
    return encoded[:BCRYPT_MAX_BYTES]

Truncating on the byte boundary (not the character boundary) handles emoji and non-Latin scripts safely — a multi-byte character never gets split in the middle.

Understanding Session Cookies

Once a user logs in, how do we remember them for the next request? HTTP is stateless — every request is independent, the server has no memory of who’s who. We need to give the browser something to send with every subsequent request.

The universal answer: cookies. When the user logs in, we set a cookie in their browser. Every future request from that browser includes the cookie, and we use it to identify the user.

But cookies live in the browser, which means anyone — including malicious extensions, XSS attacks, or the user themselves — can read and modify them. We can’t just put user_id=1 in a cookie and trust it. Anyone could edit that to user_id=2 and impersonate any user.

The fix is signing. We store the user ID in the cookie, but we sign it with a secret key that only the server knows. When the cookie comes back, we verify the signature. If it’s been tampered with, the signature won’t match and we reject it.

itsdangerous is the standard Python library for this. Two functions:

from itsdangerous import URLSafeSerializer, BadSignature

signer = URLSafeSerializer(SECRET_KEY)

def create_session_token(user_id: int) -> str:
    return signer.dumps({"user_id": user_id})

def read_session_token(token: str) -> Optional[int]:
    try:
        return signer.loads(token)["user_id"]
    except (BadSignature, KeyError, TypeError):
        return None

signer.dumps(data) returns a signed string — the data is not encrypted, just signed. Anyone can read what’s in it, but nobody can change it without knowing the secret key.

signer.loads(token) verifies the signature and returns the data if valid. If someone tampered with the cookie, it raises BadSignature and we return None — the user is treated as not logged in.

The security of the whole app depends on SECRET_KEY staying secret. Anyone who knows it can forge cookies for any user. In production, load it from an environment variable and never commit it to git.

Understanding Protected Routes

Some routes should only work if the user is logged in — /notes, /notes/new, etc. FastAPI’s dependency injection makes this clean:

def get_current_user(
    request: Request,
    db: Session = Depends(get_db),
) -> Optional[User]:
    token = request.cookies.get(SESSION_COOKIE)
    if not token:
        return None
    user_id = read_session_token(token)
    if not user_id:
        return None
    return db.query(User).filter(User.id == user_id).first()


class AuthRequired(Exception):
    pass


def require_user(user: Optional[User] = Depends(get_current_user)) -> User:
    if not user:
        raise AuthRequired()
    return user


@app.exception_handler(AuthRequired)
async def auth_required_handler(request: Request, exc: AuthRequired):
    return RedirectResponse("/login", status_code=302)

Then any route that requires login just adds user: User = Depends(require_user) to its signature:

@app.get("/notes")
async def notes_list(user: User = Depends(require_user), ...):
    # If we got here, user is guaranteed to be logged in.
    ...

The pattern: require_user runs before the route body. If there’s no session, it raises AuthRequired. The exception handler catches it and redirects to /login. Neat separation of concerns — the routes never have to check if user is None.

Understanding HTMX for the Delete Button

The delete button on the notes list uses HTMX to remove the note without reloading the whole page. In the template:

<button
  hx-post="/notes/{{ note.id }}/delete"
  hx-target="#note-{{ note.id }}"
  hx-swap="outerHTML swap:0.2s"
  hx-confirm="Delete this note? This cannot be undone.">
  Delete
</button>

Four attributes:

• hx-post — send a POST request to this URL when clicked

• hx-target — find this element on the page (the note’s article tag)

• hx-swap — replace the target with the server’s response (with a 0.2s fade)

• hx-confirm — show a browser confirmation dialog first

Server side, we detect HTMX requests by checking a header they include:

@app.post("/notes/{note_id}/delete")
async def delete_note(request: Request, note_id: int, ...):
    # ... delete the note ...

    if request.headers.get("HX-Request") == "true":
        # HTMX call: return empty HTML - it replaces the note card with nothing.
        return HTMLResponse("")
    else:
        # Regular form submit (from the detail page): redirect back to the list.
        return RedirectResponse("/notes", status_code=303)

Same route, two behaviors, cleanly separated. This “progressive enhancement” pattern is HTMX’s superpower — the app works fine without JavaScript, and gets nicer with it.

Understanding the Post-Redirect-Get Pattern

Notice we return status_code=303 after form submissions. This is a hard-won piece of web app wisdom called PRG (Post-Redirect-Get):

• User submits a POST form (signup, create note, login, delete)

• Server processes it, then redirects to a GET route

• Browser shows the GET page

If we returned HTML directly from the POST route, and the user hit refresh, the browser would ask “Resubmit form?” and re-run the POST. Duplicate signups, duplicate notes, duplicate everything. PRG makes refresh safe — the browser only ever refreshes the GET.

Use 303 See Other specifically for POST → GET redirects. It’s the HTTP status code designed for exactly this pattern. 302 Found also works but has slightly different semantics for some HTTP clients.

Coming Wednesday

Type [[groceries]] in a note, and it magically becomes a hyperlink to your “groceries” note. Click through — and at the bottom of that note, a Backlinks section shows every other note that references it. Same pattern as Notion, Obsidian, and Roam Research. It’s what turns a pile of notes into a personal knowledge base.

Plus a search bar in the nav that finds any word across all your notes as you type, using SQLite’s built-in FTS5 full-text search extension (yes, SQLite has one — most people don’t know).

Wednesday’s the paid post — upgrade here if you’re not already a subscriber.

Solution

Below you will find the source code of this project which will produce the same output as shown in the screenshots in this post.

Get the source code here:

View Code Solution

In this post, you will learn what webhooks are and how to use one to send notifications from your scripts straight to your phone. Webhooks are one of the most common building blocks in software development, and once you understand them, a big part of modern automation stops being mysterious.

You have probably created an automation with Python before. Perhaps a script that sends an email, or something that scrapes data from a weather website. Now imagine the script crashed for some reason. You would not know immediately. You might come back days later and see that no data has been scraped for a week.

So what most people do is add a loop somewhere that keeps checking:

import time

while True:
    if check_if_done():
        break
    time.sleep(10)

This approach is called polling. Your script keeps asking “is it done yet?” over and over. It works, but think about what is actually happening here: your script sends thousands of requests a day just to hear “no” almost every time. It is like calling the pizza place every two minutes to ask if your order is ready. They will not enjoy that, and neither will the server you are polling.

The pizza place solves this differently, of course. You give them your number, and they call you when the order is ready. In software, that pattern is called a webhook.

A webhook is not a technology

So what is a webhook exactly? It is an HTTP request that someone else’s computer sends to a URL of your choice when an event happens. That is really the whole definition. It is not a library you install or a protocol you have to study. It is just an agreement between two computers: when X happens, send a POST request to this address.

Until now, you have always been the caller. Every requests.get() you have written is your script phoning a server. A webhook is the same thing in the opposite direction: the server phones you.

The script that texts you

Let me show you the fastest way to experience this. We will make a script send a notification to your phone.

The tool we will use is ntfy.sh. There is no signup, no API key, and no credit card involved. I have seen enough free services die under my projects to be careful with recommendations, but ntfy has been reliable for me.

First, install the ntfy app on your phone (free on iOS and Android) and subscribe to a topic. A topic is just a name you invent. Keep in mind that anyone who knows the name can send messages to it, so pick something hard to guess, like da-topic-4821, not test.

Then run this script:

import requests

requests.post(
    "https://ntfy.sh/da-topic-4821",
    data="Scraper finished. 340 rows."
)

About one second later, your phone buzzes.

That is four lines of Python, and your script can now reach you anywhere.

What actually traveled over the wire

Let’s look at what your script actually sent to ntfy’s server.

It is a verb (POST), an address, a couple of headers, and a body with the message. Every webhook in the world has this same shape. When Stripe informs an online shop that a payment succeeded, it sends this exact structure, just with a bigger JSON body. When GitHub tells a build server that someone pushed code, same thing.

The other side of the phone call

So far you have been the sender. Receiving a webhook is the reverse: you have a URL, and other computers send POST requests to it when something happens.

You might think you need Flask or FastAPI for this, but you don’t. Python comes with everything built in:

from http.server import HTTPServer, BaseHTTPRequestHandler

class Hook(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers["Content-Length"])
        body = self.rfile.read(length).decode()
        print("Webhook received:", body)
        self.send_response(200)
        self.end_headers()

HTTPServer(("", 8000), Hook).serve_forever()

Run this and you have a webhook receiver at http://localhost:8000. If you send it a POST request from a second terminal (reuse the four-line script from above and just change the URL), you will see the message printed. You just ran both sides of a webhook on one machine, with the standard library only.

By the way, if you want to watch a real webhook arrive before writing any code, open webhook.site in your browser. It gives you a temporary URL and shows every request that hits it, live. Five minutes there and webhooks will never feel mysterious again.

The catch: localhost is a private address

There is one thing that catches almost everyone at this point. Your receiver works when you send to it. However, if you paste http://localhost:8000 into Stripe’s webhook settings, nothing will ever arrive.

That is because localhost means “this machine”. It is a name only your own computer can hear. Your laptop has no public address on the internet. It sits behind your router, and the router has no idea it should forward anything to you.

There are two solutions. For testing, you can use a tunnel like ngrok, which gives you a temporary public URL that forwards to your laptop. For real applications, you deploy the receiver to a server, which is simply a computer with a public address that stays on. That trip from laptop to server is a topic we will keep coming back to in this publication.

The pattern to steal today

Here is what I recommend you do with all this. Wrap the sender in a small function and keep it in every project:

import requests

def notify(message):
    requests.post("https://ntfy.sh/da-topic-4821", data=message)

notify("Backup complete: 2.3 GB")
notify(f"Script crashed: {error}")
notify("Price dropped below 40 EUR")

My personal rule is that any script running longer than a coffee gets a notify() call at the end and one in the error handler. It changes how you work, because your scripts stop being things you watch and start being things that report to you.

And once you know the shape, you will notice webhooks everywhere: GitHub triggering tests, Stripe unlocking accounts, Telegram bots replying to messages.

In a future post, we will take the next step: giving your own function a public URL, so that anything on the internet can call your code.

-Ardit

Today we build that.

Projects in this week’s series:

Day 1 (Yesterday): CLI recorder + local Whisper transcription

When the user runs the Day 1 script, they get prompted to press Enter, speak, and press Enter again. The transcript appears in the terminal and the audio + text are saved to ~/VoiceNotes/:

Everything runs locally — the transcript appears within a second or two of hitting Enter to stop. It works, but you have to be in the terminal.

👉 Day 2 (Today): “Whisper Flow” mode — press Right Option anywhere, dictate anything

When the user presses and holds Right Option (or Right Alt on Windows) inside any app on their computer, the voice notes daemon starts recording. On release, the transcript is typed directly into whichever app has focus. Here’s it landing in a Slack message input:

No window. No terminal to switch to. Just dictate, release, done. Same experience as the commercial dictation apps, running fully offline on your own hardware.

View All Projects This Week

Today’s Project

The Day 1 script had two things wrong for real daily use:

1. You had to be in the terminal. No app you actually use fires up in the terminal — email, Slack, docs, code editors all live in their own windows.

2. The transcript went to a file. You still had to open that file, copy the text, tab back to your target app, paste. More clicks than just typing.

The fix is a background daemon that listens for a global hotkey. When you press it, the app records — no matter which window you’re in. When you release, the app transcribes and types the text into whichever window has keyboard focus. Nothing visible, no context switching, no copy-paste.

The daemon reuses Day 1’s record_until_stopped() and transcribe() functions unchanged. What changes is the trigger (a hotkey instead of ENTER) and the destination (a keystroke stream instead of a file). Same underlying pipeline; radically different UX.

Project Task

Build a background daemon that:

• Loads a faster-whisper model on startup and prints a “ready” banner

• Uses pynput to listen for a global hotkey (default: Right Option / Right Alt)

• On key press: starts recording from the microphone in a background thread

• On key release: stops recording, transcribes, and types the result into whichever window has focus

• Runs forever until Ctrl+C

• Filters out accidental quick taps (recordings under 0.3s)

• Archives each note to ~/VoiceNotes/ for later reference

This project teaches you pynput (global hotkeys + typing), how threading events coordinate press-and-release-driven state, and — critically — the macOS Accessibility permission dance that trips up everyone the first time.

Setup Instructions

This one’s more involved than Day 1 because we’re doing operating-system-level things — listening to keyboard events across all apps, injecting keystrokes into whichever app has focus. macOS in particular has security requirements that need explicit setup. Read this section carefully. Half the errors you’ll hit are permissions, not code.

Python dependencies (all platforms):

pip install sounddevice soundfile numpy faster-whisper pynput

If Day 1 already installed the first four, only pynput is new.

macOS setup — the Accessibility permission

You need to grant Accessibility permission to whichever app runs the script. This is macOS’s security model for anything that observes or injects keyboard events — Python needs it, Chrome needs it, Zoom needs it. Without it, pynput still runs, but macOS feeds it garbage events. The daemon will appear to record and stop on its own, in an infinite loop, without you touching anything. If that happens to you, permission is the problem, not the code.

The app that needs permission is the one running python — usually Terminal, iTerm2, Warp, or your IDE. Not Python itself.

To grant it:

1. Open System Settings → Privacy & Security → Accessibility

2. Click the + button

3. Add Terminal (path: /System/Applications/Utilities/Terminal.app), or whichever terminal you actually use

4. Toggle the switch next to it on

5. Fully quit Terminal with Cmd+Q (not just close the window) and reopen it

That last step is non-negotiable. macOS only checks the permission list at process startup. A running Terminal keeps behaving as unpermitted even after you flip the toggle, until you fully quit and relaunch.

macOS setup — the SSL cert gotcha

If you get an SSL certificate error the first time faster-whisper tries to download the model — something like FileNotFoundError: [Errno 2] No such file or directory deep in the traceback, pointing at a .pem file — you’ve been bitten by a stale SSL_CERT_FILE environment variable. Fix it with:

unset SSL_CERT_FILE
python3 voice_notes_daemon.py

If that works, find where the variable is being set and remove it permanently:

grep -H SSL_CERT_FILE ~/.zshrc ~/.zprofile ~/.bash_profile 2>/dev/null

Delete the offending line from whichever file grep finds it in. This isn’t a problem with your code or with faster-whisper — it’s a common misconfiguration on Macs that had older Python setups or Anaconda installed at some point.

Windows setup

pynput works out of the box on Windows. No permissions, no config. Just install and run.

One note: some antivirus software flags apps that install global keyboard hooks, which is what pynput does under the hood. This is a legitimate flag in general — apps that watch keystrokes globally could be keyloggers — but our code only reads press/release events for the hotkey and never captures other keys’ values. Whitelist the script or the Python interpreter if your antivirus balks.

Linux setup

pynput needs an X server. If you’re on desktop Linux, you already have one. Wayland users get “failed to acquire X connection” errors — either switch to an X11 session or install xwayland. pynput‘s Wayland support is limited as of writing.

Choosing your hotkey

The default hotkey is Right Option on Mac, called Right Alt on Windows keyboards. In pynput it’s keyboard.Key.alt_r — one code, both platforms.

Why not CAPS LOCK, which is what commercial apps seem to use?

Because CAPS LOCK on macOS is a broken abstraction for userspace keyboard libraries. Unlike every other key, CAPS LOCK doesn’t send normal press-and-release events at the OS level — it’s a hardware toggle, and macOS emits weird 0-millisecond press-plus-release event pairs that pynput can’t reliably interpret. You end up with the daemon firing “recording started / recording stopped” on its own, in a loop, without touching the keyboard. I spent longer than I’d like to admit figuring this out.

Commercial dictation apps that use CAPS LOCK reach for lower-level APIs than Python has access to from userspace. The nearest equivalent you can build in plain Python is Right Option, which sits on the same row as CAPS LOCK, is rarely used for anything else, and behaves like a normal key.

If you really want CAPS LOCK on Mac: install Karabiner Elements — free, well-maintained, the standard tool for Mac keyboard remapping — and remap Caps Lock → F13. Then set the daemon’s hotkey to keyboard.Key.f13. Karabiner handles the CAPS LOCK weirdness at the hardware event level, and pynput never sees anything unusual. But honestly? Right Option works great and requires zero extra software. Don’t add complexity for a wart.

Windows users don’t have a “Right Option” key — the same physical key is labeled “Right Alt” or “AltGr” on international keyboards. Same pynput code (Key.alt_r), different physical label. No remapping needed.

Running it

python voice_notes_daemon.py

You should see this in the terminal:

🎙️  Voice Notes daemon
    Model: base (int8)
    Hotkey: Key.alt_r
    Archive: /Users/you/VoiceNotes

Loading Whisper model...
✓ Model ready.

🟢 Ready. Hold Key.alt_r anywhere on your system to dictate.

Then the daemon goes quiet. Silence is correct. If “Recording...” messages appear immediately without you pressing anything, that means macOS Accessibility permission isn’t granted, or the terminal wasn’t fully quit after granting it. Go back to the Accessibility section above.

Once it’s idle at the “🟢 Ready” line: open any other app, put your cursor in a text field, hold Right Option, speak a sentence, release. The daemon prints a transcription line, and the text appears in the app you had focused.

Understanding Global Hotkeys with pynput

Yesterday’s script used input() — a built-in that reads from stdin. It only fires when the terminal window has focus. That’s the opposite of what we want.

We want to listen for key presses anywhere on the system, regardless of which app has focus. That’s called a global hotkey, and it requires operating-system-level integration:

• On macOS: the Quartz event system

• On Windows: the SetWindowsHookEx API

• On Linux: the X server or evdev

pynput wraps all three behind one Python API. You never touch the platform-specific code:

from pynput import keyboard

def on_press(key):
    print(f"pressed: {key}")

def on_release(key):
    print(f"released: {key}")

with keyboard.Listener(on_press=on_press, on_release=on_release) as listener:
    listener.join()

The Listener runs in its own thread, calling your callbacks whenever a key event happens anywhere on the system. listener.join() blocks the main thread until the listener stops.

This is the entire core of what commercial dictation apps do. Everything else is polish.

Understanding the Press-Release State Machine

Our daemon has three states:

• Idle — no key held, no recording

• Recording — hotkey pressed, audio flowing

• Transcribing — hotkey released, waiting for Whisper

The state transitions are triggered by press/release events, not by ENTER. Two subtleties:

The listener callback thread must not block. If we started the actual recording synchronously in on_press, the listener would freeze — meaning it would miss the release event. Instead, we hand recording off to a new thread and use a threading.Event from Day 1 to signal stop:

recording = False
stop_event = threading.Event()

def on_press(key):
    global recording
    if key == HOTKEY and not recording:
        recording = True
        stop_event.clear()
        threading.Thread(target=record_and_transcribe, daemon=True).start()

def on_release(key):
    global recording
    if key == HOTKEY and recording:
        stop_event.set()
        recording = False

The recording flag prevents double-starts when a key auto-repeats. On some keyboards, holding a key down makes the OS fire “press” events repeatedly. Without the flag, each auto-repeat would spawn a fresh recording thread — chaos. The flag ensures one press = one recording session, no matter how many repeat events arrive during the hold.

Three threads coordinating: the main thread runs the listener, the listener thread calls our callbacks, and each recording session spawns a worker thread. Sounds like a lot, but it maps cleanly: one thread per concern, no thread ever blocking another.

Understanding Typing Into the Focused Window

Once we have transcribed text, we inject it into whichever app has keyboard focus. pynput handles this with a Controller:

from pynput.keyboard import Controller

kb = Controller()
kb.type("hello world")

That’s it. type() iterates through each character and synthesizes press+release events for it. From the OS’s perspective, it’s indistinguishable from a human typing very fast. The text lands in whichever field currently has focus — which is exactly what we want, because the user’s cursor was there before they held the hotkey.

There’s one gotcha worth flagging: type() can be slow for long text because it’s really simulating individual keystrokes. For a 200-word paragraph you might see a subtle typing animation. That’s authentic UX (matches what commercial apps do) and rarely a problem, but if you want instant paste-style insertion, put the text on the clipboard with pyperclip and simulate Cmd+V / Ctrl+V instead. Left as an exercise.

Understanding the Accessibility Permission Under the Hood

macOS-specific, but worth explaining what’s actually going on because the failure mode is confusing.

macOS enforces TCC (Transparency, Consent, and Control) — a database of which apps can do which sensitive things. Reading global keyboard events is one of the sensitive things. Every app that wants to observe keyboard events across other apps must be individually approved in System Settings → Accessibility.

The reason pynput doesn’t just crash without permission is that macOS deliberately lets the process create the event listener — it just feeds it garbage. This is a security design: apps that don’t have permission are silently sandboxed from the real event stream, so a malicious keylogger can’t tell whether the user knows about it. From the app’s point of view, everything looks fine; it’s just receiving fake events.

The practical implication for us: when the terminal doesn’t have Accessibility permission, pynput sees phantom events — 0ms-duration press-plus-release pairs, ghost keystrokes — that trigger the daemon’s callbacks. That’s why the symptom of missing permission is “recording started / recording stopped fires by itself” instead of a clean error message. It’s not the code being buggy. It’s macOS feeding fake data as a security measure.

After granting permission and fully quitting the terminal, the event stream becomes real. Press a key, pynput sees a real press. Release, it sees a real release. Silence when idle.

Understanding Why This Composes with Any App

The reason the daemon works in Slack, VS Code, Google Docs, terminal, email, and every other app is that we’re not integrating with any of them. We’re operating at the OS level, one layer below the applications. macOS, Windows, and Linux each own their own keyboard focus model. Whichever app currently has focus receives the keystrokes we generate — the app has no idea whether they came from a human, a Bluetooth keyboard, or a Python daemon.

This is the architectural insight behind commercial dictation apps. They don’t have Slack integrations. They don’t have VS Code integrations. They just type into the OS’s keystroke stream, and every app that receives keystrokes normally receives their keystrokes too. Universal by construction.

The trade-off: we can’t do app-specific behavior. We can’t detect that we’re in Slack and format the text as a reply-to-thread. We can’t notice we’re in VS Code and put the text in a comment vs. code. But 95% of the daily value is just “make the text appear where my cursor is” — and that’s what we do, in every app, forever, with no integrations to maintain.

Practical Use Cases

Meeting notes on the fly: Cursor in your notes app, dictate a bullet, release. Cursor in your Slack channel, dictate a message, release. No app switching, no re-focusing.

Writing code comments: Cursor in a code file. Hold, describe what the function does, release. The comment types itself. This is how you get comments on functions you’d normally skip because typing them is friction.

Dictating emails: The hardest part of email is starting. Voice makes the first draft trivial. Cursor in Gmail’s compose box, hold hotkey, ramble, release, edit. Ships faster.

Language learning: Whisper is multilingual. Dictate in Spanish, get Spanish text. Dictate in French, get French text. Detects the language automatically per recording.

Accessibility: For anyone whose typing is limited by RSI, tremor, or vision. Fully offline means no cloud dependency, no privacy trade-off, works on airplanes.

What You’ve Accomplished This Week

Two days ago, you had no dictation tool. Now you have one that’s competitive with $12/month commercial apps, running fully on your machine, forever.

You’ve learned:

• Real-time audio recording with sounddevice and thread-safe queues

• Local AI transcription with faster-whisper — no API keys, no data leaves your machine

• Global keyboard event capture with pynput

• Programmatic keystroke injection into the OS event stream

• How macOS Accessibility permission actually works under the hood

• Why CAPS LOCK is a landmine on Mac for userspace apps, and how to route around it

The tool is useful daily, and you own every line of the code. Modify the hotkey. Add auto-save to a specific folder per app. Trigger different behavior when you double-tap the hotkey. Change the model size for accuracy vs. speed. This isn’t a toy tutorial — it’s a real personal productivity tool that will still work five years from now, because it depends on nothing except your local machine.

Next steps you might explore:

• Add sound feedback (a subtle beep on recording start/stop) using simpleaudio or playsound

• Add a menu bar icon (macOS) or system tray icon (Windows) using rumps or pystray so you can see the daemon status at a glance

• Swap type() for clipboard-paste (pyperclip + Cmd+V) for instant insertion instead of simulated typing

• Add language selection — press the hotkey once for English, twice quickly for Spanish, etc.

• Swap the base model for small or medium if you want more accuracy and can spare the extra CPU

That’s the finish line for this week. See you next Tuesday.

Solution

The complete daemon code — hotkey listener, threading choreography, and the type-into-focused-window integration — is below. Save it as voice_notes_daemon.py, install the dependencies, grant Accessibility permission (macOS), and run.

Read more

This week we build it in Python. Running fully on your machine. No cloud. No API keys. No subscription — ever.

Projects in this week’s series:

👉 Day 1 (Today): CLI recorder + local Whisper transcription

When the user runs the program, they get asked to press Enter to record their voice:

After pressing Enter again, the program will transcribe their voice, print out the transcribed text in the terminal and also indicate where the saved audio and transcribed file were saved.

Day 2 (Tomorrow): “Whisper Flow” mode — press Right Option anywhere, dictate anything

When the user presses and holds the Right Option / Right Alt key on their keyboard inside any app on their computer, the voice notes daemon starts recording on the background. On release of the button, the transcript is typed directly into whichever app has focus — here shown landing in a Slack message input as an example:

No terminal to switch to. No copy-paste. The exact same experience as Whisper Flow and Superwhisper, running fully offline on the user’s machine.

View All Projects This Week

By Wednesday, you’ll have this:

You’re in Slack. Cursor in the message box. Press Right Key/ Right Option. Say “hey team, running 5 minutes late for standup.” Release. The words appear in the message box, typed by the app. No browser tab open, no cloud upload, no monthly fee.

Same in VS Code — you’re writing a code comment. Right Key / Right Option, dictate, release. Text lands in the file. Same in Google Docs, Notes, terminal, email — anywhere your cursor is. Nothing on your screen changes except the words appearing.

That’s Wednesday. Today we build the foundation that makes it possible: recording and transcribing audio locally, without touching the cloud.

Today’s Project

The CLI voice recorder.

Run the script. Press ENTER. Speak. Press ENTER again. Watch the transcript appear. The audio and text are auto-saved to ~/VoiceNotes/ for later reference.

Simple, useful, works entirely offline after the first run. And it teaches the full pipeline that Wednesday’s magic depends on:

1. Stream audio from the microphone into a numpy array

2. Save the array as a WAV file

3. Feed it to Whisper for transcription

4. Print + save the result

Wednesday just changes how those steps are triggered — from an ENTER prompt to a system-wide hotkey — and where the transcript goes: not to a file, but typed directly into whichever app has focus.

About Whisper (and Why “Faster”)

Whisper is an open-source speech recognition model from OpenAI, released in 2022. Trained on 680,000 hours of multilingual audio, it’s genuinely excellent — accurate, robust to accents, handles background noise, and works in 99 languages.

The original whisper library from OpenAI uses PyTorch and is somewhat slow on CPU. faster-whisper is a re-implementation using CTranslate2 — the same model, but 4x faster on CPU and using less memory. Same accuracy, better performance. It’s what nearly every real-world Whisper app uses today.

Model sizes:

• tiny — 75 MB, fastest, less accurate

• base — 150 MB, great balance for voice notes ← our default

• small — 500 MB, more accurate

• medium — 1.5 GB, close to human parity

• large-v3 — 3 GB, state of the art

For personal voice notes on a laptop, base is the sweet spot — fast enough to transcribe a 30-second note in ~1 second on a modern CPU, accurate enough for casual dictation.

Project Task

Build a CLI script that:

• Loads a faster-whisper model on startup

• Loops: prompts the user, records audio, transcribes, saves, repeats

• Uses sounddevice to stream from the microphone into a numpy array

• Streams audio through a thread-safe queue so recording keeps working while the main thread waits for input

• Uses a threading.Event to signal “stop recording” from the main thread

• Saves each note as a timestamped pair of .wav + .txt files in ~/VoiceNotes/

• Handles Ctrl+C cleanly

• Filters out accidental too-short recordings (under 0.3s)

This project gives you hands-on practice with sounddevice, thread-safe programming, threading.Event, queue.Queue, faster-whisper, and soundfile.

Setup Instructions

System dependencies (macOS + Linux):

macOS:

brew install portaudio

Linux:

sudo apt install portaudio19-dev

Windows: no system dependencies needed — sounddevice bundles PortAudio.

Python dependencies:

pip install sounddevice soundfile numpy faster-whisper

Run it:

python voice_notes.py

First run takes ~30 seconds to download the Whisper model. After that, model load is 2-3 seconds and everything works offline. You’ll see a startup banner, then a “Press ENTER to start recording” prompt. Speak, press ENTER again, and the transcript appears in the terminal — matching the screenshot at the top of this post.

A note on microphone permissions: on macOS, the first time you run this, macOS will pop up a dialog asking to grant microphone permission to whichever terminal you’re using. Grant it, then restart the script. This is a one-time setup.

Understanding sounddevice and Streaming Audio

Recording audio in real time is fundamentally different from reading a file. A file has a fixed size; a live audio stream has no end until you tell it to stop. So instead of “read all the audio,” we say “start a stream, and call this function every time a chunk of audio is available.”

sounddevice gives us exactly that — the InputStream with a callback:

import sounddevice as sd

def my_callback(indata, frames_count, time_info, status):
    # Called every ~10ms with a fresh chunk of audio.
    # indata is a numpy array of shape (frames, channels)
    print(f"Got {frames_count} frames")

with sd.InputStream(samplerate=16000, channels=1,
                    dtype="float32", callback=my_callback):
    time.sleep(3.0)  # let it run for 3 seconds

Three things worth internalizing:

• The callback runs on a separate thread, managed by PortAudio internally. It fires at whatever rate the audio hardware ticks (usually every 10-30ms).

• indata is a view into a stream-owned buffer that will be overwritten as soon as the callback returns. If you want to keep the data, you MUST .copy() it. Failing to do this is the #1 rookie sounddevice bug.

• The with block is what starts and stops the stream. As soon as you enter it, audio starts flowing; as soon as you exit, it stops. Clean lifetime management.

Understanding queue.Queue for Cross-Thread Data

Now we have a problem: the audio callback is running on the audio thread. We want to process the audio on the main thread. How do we get data safely from one thread to the other?

queue.Queue is the answer. It’s a thread-safe FIFO buffer. One thread puts items in, another thread takes them out. All the locking is handled internally.

import queue

audio_queue = queue.Queue()

def audio_callback(indata, frames_count, time_info, status):
    audio_queue.put(indata.copy())    # audio thread: producer

# Main thread: consumer
while not stop_event.is_set():
    try:
        block = audio_queue.get(timeout=0.1)
        frames.append(block)
    except queue.Empty:
        continue

Two habits worth forming:

• .copy() before putting into the queue. Otherwise the audio thread will overwrite what you queued.

• .get(timeout=0.1) instead of .get() — the timeout lets the main thread wake up periodically and check stop_event, instead of blocking forever on an empty queue. 100ms is a good compromise between responsiveness and CPU wake-ups.

The producer-consumer pattern with a queue is foundational for any streaming-data work. Once you’ve done it with audio, you know how to do it with sensor data, live network feeds, real-time file monitoring, and everything in between.

Understanding threading.Event for Stop Signals

We need a clean way for the main thread to tell the recording thread “stop now, wrap it up.” A boolean flag would work but has subtle threading issues. threading.Event is the idiomatic answer:

import threading

stop_event = threading.Event()   # starts unset

# In recording thread:
while not stop_event.is_set():
    # ... record ...

# In main thread:
stop_event.set()                 # signal stop
recording_thread.join()          # wait for it to actually stop

An Event is essentially a thread-safe boolean with three operations:

• .set() — turn it on

• .is_set() — check its state

• .wait(timeout) — block until it turns on

This is the pattern for graceful shutdown in any threaded Python program: web servers, background workers, real-time processors. Learn it once, use it forever.

Understanding the Main Loop Choreography

Now let’s zoom out and see how ENTER, the event, and the thread all coordinate:

while True:
    input("Press ENTER to start recording...")   # blocks main thread

    stop_event = threading.Event()               # fresh event per note
    result = {}                                  # place for thread's output

    def worker():
        result["audio"] = record_until_stopped(stop_event)

    recording_thread = threading.Thread(target=worker, daemon=True)
    recording_thread.start()                     # off it goes

    print("Recording... Press ENTER to stop.")
    input()                                       # blocks main thread again
    stop_event.set()                              # signal the worker
    recording_thread.join()                       # wait for actual shutdown

    audio = result["audio"]                       # retrieve results
    # ... transcribe, save, loop ...

Key ideas:

• The result = {} dict pattern — since Python functions can’t easily return values from a threading.Thread(target=...), we use a dict as a shared “result box.” The thread writes into it; the main thread reads after .join().

• daemon=True — daemon threads die automatically when the main program exits. If the user hits Ctrl+C during recording, the recording thread won’t linger.

• The two input() calls block the main thread — but only the main thread. The recording thread keeps happily filling the queue during both waits. This is why threading is essential here: without it, ENTER would never work while recording was happening.

Read this section twice if it’s new. Understanding this dance is the difference between “I can use threading” and “I can design threaded programs.”

Understanding faster-whisper

faster-whisper is dead simple to use:

from faster_whisper import WhisperModel

# Load once. This takes 2-3 seconds and downloads the model on first run.
model = WhisperModel("base", device="cpu", compute_type="int8")

# Transcribe. audio is a 1-D float32 numpy array at 16 kHz.
segments, info = model.transcribe(audio, beam_size=5, vad_filter=True)

# segments is a generator. Consume it to get the text.
text = " ".join(seg.text.strip() for seg in segments)

Three parameters worth knowing:

• compute_type="int8" — the fastest CPU inference mode. Slight accuracy loss vs. float32, but ~4x faster and half the RAM. Perfect for laptops.

• beam_size=5 — how many candidate sequences the model considers. Bigger = more accurate, slower. 5 is a great default; you can drop to 1 for speed or bump to 10 for the last few percent of accuracy.

• vad_filter=True — Voice Activity Detection. Whisper’s biggest annoyance is that it “hallucinates” transcriptions in silent audio (”thank you for watching” is a common one, from YouTube training data). VAD drops silent segments before transcription, dramatically reducing this problem.

The info object tells you what language Whisper detected and how confident it was — a handy little UX detail.

Understanding Saving with soundfile

soundfile is our WAV writer. One function does everything:

import soundfile as sf

sf.write(wav_path, audio, SAMPLE_RATE, subtype="PCM_16")

• subtype="PCM_16" — 16-bit signed integer WAV format. Widely compatible, ~half the size of float32 WAV. soundfile handles the float→int conversion automatically.

• The path can be a string or pathlib.Path — both work.

If you ever need to read an audio file, it’s the mirror:

audio, sample_rate = sf.read(wav_path)

Both soundfile and sounddevice use numpy arrays as their common language — no format juggling, no encoding conversions.

Understanding the Auto-Save Pattern

We save every note automatically with a timestamped filename:

from datetime import datetime

stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
wav_path = NOTES_DIR / f"note_{stamp}.wav"
txt_path = NOTES_DIR / f"note_{stamp}.txt"

Two design choices worth explaining:

• Timestamp format YYYYMMDD_HHMMSS — sorts lexically the same as chronologically. note_20260721_143000.wav sorts before note_20260721_143500.wav. Both ls and file explorers show them in order automatically.

• Paired WAV + TXT with the same stem — makes it trivial to find “the audio for this transcript” or “the transcript for this audio.”

Never save with just datetime.now().isoformat() — that produces strings like 2026-07-21T14:30:00.123456+00:00, which contain colons and special characters that break on Windows filenames. strftime with only safe characters is the right call.

Practical Use Cases

Personal dictation: Record thoughts on a walk, transcribe them later, paste into your journal.

Meeting notes: Record short “action item” reminders after a call. The transcripts feed right into your task list.

Language learning: Whisper is multilingual — record yourself speaking Spanish, get back the transcript to verify pronunciation.

Accessibility: Transcription for anyone who prefers speaking over typing. Fully local means it works on airplanes.

Foundation for Wednesday: The record + transcribe + save pipeline stays. Wednesday just changes what triggers it (a system-wide hotkey) and where the transcript goes (into whatever app you’re using).

Coming Wednesday

Wednesday: no ENTER prompt. No terminal you have to switch to. No copy-paste.

The app runs invisibly in the background. You press Right Key / Right Option anywhere on your system — inside Slack, inside VS Code, inside a Google Doc, inside your email. You speak. You release Right Key / Right Option. The transcription lands directly in whichever app you’re focused on, character by character, like you typed it yourself.

It’s the same experience as Whisper Flow and Superwhisper. It costs nothing. It runs on your laptop offline. And you’ll own every line of the code.

Wednesday’s the paid post — upgrade here if you’re not already a subscriber.

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