Profile First: A 10x Faster Django Test Suite

2026-06-20T00:00:00+00:00

The Rust Platform Django test suite took 30 seconds to run. I had a hunch it was database-related. Of course I was wrong. I profiled it with cProfile and cut it from 30 to 3 seconds.

Stop guessing, run the profiler</h2>
The instinct on a slow test suite is to start making assumptions: too many fixtures, the database is slow, I should parallelize, it's the GIL. Every one of those is a real fix for some issues. The problem is you don't know until you measure.
From High Performance Python</a>:

Sometimes it’s good to be lazy. By profiling first, you can quickly identify the bottlenecks that need to be solved, and then you can solve just enough of these to achieve the performance you need. If you avoid profiling and jump to optimization, you’ll quite likely do more work in the long run. Always be driven by the results of profiling. </blockquote>
`cProfile</code> ships with Python. In this case I pointed it at my test suite:`
`uv run python -m cProfile -o tests.pstats -m pytest -k unit</code></pre> That gives you a pstats</code> file. You can read it from the command line, but it's not intuitive:`
`uv run python -c "import pstats; pstats.Stats('tests.pstats').sort_stats('tottime').print_stats(10)"</code></pre>`
Adam Johnson recently released profiling-explorer</a>, a browser viewer over the same data. You can invoke it like this:
uvx profiling-explorer tests.pstats</code></pre> It opens on http://127.0.0.1:8099</code>. I sorted by internal time and the bottleneck was obvious: Reading the numbers without fooling yourself</h2> Two columns matter: tottime (the viewer calls it "internal ms"): time spent inside a function, excluding what it called. This is where the CPU actually went.</li> cumtime ("cumulative ms"): the function plus everything beneath it. Useful for finding the expensive subtree, useless for finding the hot leaf.</li> </ul> Sort by tottime to find what to fix: Frame</th> Calls</th> tottime</th> Share</th></tr></thead> _hashlib.pbkdf2_hmac</code></td> 177</td> 26,470 ms</td> 82.8%</td></tr> psycopg2 cursor.execute</code></td> 4,682</td> 1,522 ms</td> 4.8%</td></tr> </tbody></table> pbkdf2_hmac</code> is Django's default password hasher. It's meant to be slow, because it resists brute-forcing real passwords. But it fires on every test that creates a user: fixtures, create_user</code>, client.login</code>. In production it runs once per login. In a test suite it runs hundreds of times for no security benefit at all. One more thing the table teaches you: on a high-call-count frame, the call count is the signal, not the time. cursor.execute</code> at 4,682 calls is mostly real database wait, and the count is high because every test sets up its own data: inserts, auth lookups, session reads, across 355 tests. A high count is worth a second look (it can hide an N+1), but you have to confirm that before believing it. (cProfile adds a fixed cost per call too, but at a few thousand calls that overhead is marginal; it only distorts the picture when a frame fires millions of times.) PBKDF2 only ran 177 times, so its time really was concentrated there, and it was the real culprit. The five-line fix</h2> Swap the hasher to fast MD5 in tests only. An autouse</code> fixture in conftest.py</code> (default "function" scope does it for every test): import pytest @pytest.fixture(autouse=True) def fast_password_hashing(settings): settings.PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]</code></pre> Hash strength is irrelevant under test, so there's no loss of coverage. Test suite speed went from ~30s to ~3s. It turns out this is also a documented Django trick</a>, which is the point: the profiler led me to a known fix I didn't know I needed, instead of me making assumptions. The new top frame is cursor.execute</code> at ~4.7k calls, which smelled like an N+1. So I measured that too: I wrapped the suite to capture every query and grouped them by shape. No N+1. The list views already batch their lookups into one query, and the high count was just 355 tests each doing honest setup. The only real waste was a save()</code> path firing redundant COUNT</code> queries, cheap, but easy to halve. Which is the whole point: I guessed N+1 and was wrong again. The profiler keeps you honest. What's the slowest thing you run every day that you've never actually measured? Let me know on LinkedIn</a> or X/Twitter</a>. End-to-End Testing Every Rust Exercise with Playwright 2026-06-19T00:00:00+00:00 The Rust platform</a> has 71 exercises and counting (I just added a new track of Unix exercises</a>). They all share the same interface: load an editor, type code, validate it against a Rust backend. When I make any changes to the platform, how do I confirm nothing breaks? Enter end-to-end testing with Playwright. The Problem</h2> Manual testing doesn't scale. Every time I add an exercise, tweak the editor, or update the validation flow, I need confidence that all exercises still work. Not just that the page loads, but the full loop: login, navigate, type code, submit, see results. Unit tests cover the Django app, and the Rust validator has its own test suite. But neither exercises the full path a student takes: loading an exercise and getting a real pass or fail back. One Test Function, 71 Test Cases</h2> Playwright with pytest covers this in under 50 lines. Here's the core test file: import psycopg2 import pytest from decouple import config from .constants import DOMAIN exercises = [] with psycopg2.connect(dsn=config("DATABASE_URL")) as conn: with conn.cursor() as cursor: cursor.execute( "SELECT slug, solution FROM bites_exercise WHERE public = true" ) exercises = cursor.fetchall() @pytest.mark.parametrize("exercise", exercises, ids=[ex[0] for ex in exercises]) def test_exercise(logged_in_page, exercise): slug, solution = exercise page = logged_in_page exercise_url = f"{DOMAIN}/{slug}" page.goto(exercise_url) page.wait_for_url(exercise_url) page.wait_for_selector(".CodeMirror", state="visible") page.wait_for_function( "document.querySelector('.CodeMirror')?.CodeMirror !== undefined" ) page.evaluate( f"""document.querySelector('.CodeMirror').CodeMirror.setValue({repr(solution)})""" ) page.click("#validate-button") page.wait_for_function( "document.querySelector('#feedback').innerText.includes('Congrats') || " "document.querySelector('#feedback').innerText.includes('Oops')", timeout=30000, ) validate_result = page.text_content("#feedback") assert "Congrats, you passed this exercise" in validate_result</code></pre> The database query at module load fetches every public exercise with its solution. @pytest.mark.parametrize</code> turns that into 71 test cases. Each test navigates, injects the solution, validates, and asserts success. Here is Playwright running the tests locally against the real Rust validator, one exercise after another: Your browser does not support embedded video. </video> Patterns That Made It Work</h2> Session-scoped fixtures for speed</h3> Launching a browser is expensive. Logging in is expensive. Do it once: @pytest.fixture(scope="session") def browser(e2e_user): with sync_playwright() as p: with p.chromium.launch(headless=HEADLESS) as browser: yield browser @pytest.fixture(scope="session") def logged_in_page(browser): page = browser.new_page() page.set_default_timeout(30_000) page.goto(f"{DOMAIN}/pbadmin/") page.fill('input[name="username"]', LOGIN) page.fill('input[name="password"]', PASSWORD) page.click('input[type="submit"]') yield page</code></pre> All 71 exercises run against the same authenticated browser session, so the login cost is paid once. Waiting for CodeMirror</h3> One tricky thing with Playwright is timing. Sometimes elements are not yet ready when you hit the page. In this case you have to wait for the CodeMirror editor to be fully initialized before injecting code: page.wait_for_selector(".CodeMirror", state="visible") page.wait_for_function( "document.querySelector('.CodeMirror')?.CodeMirror !== undefined" ) page.evaluate( f"""document.querySelector('.CodeMirror').CodeMirror.setValue({repr(solution)})""" )</code></pre> First we wait for the selector to be visible, then we wait for the JavaScript instance to be ready. Avoiding Django's async context trap</h3> Another issue I faced was creating a Django user inside a Playwright fixture triggered: SynchronousOnlyOperation: You cannot call this from an async context</code></pre> I worked around it by creating the test user in a separate fixture that runs before Playwright starts: @pytest.fixture(scope="session") def e2e_user(django_db_blocker): with django_db_blocker.unblock(): return ensure_e2e_user() @pytest.fixture(scope="session") def browser(e2e_user): # e2e_user runs first with sync_playwright() as p: ...</code></pre> The django_db_blocker.unblock()</code> context manager allows database access in session-scoped fixtures. Order matters: the user must exist before the browser fixture runs. Running Locally vs CI</h2> The E2E suite runs against a live database with the Rust validator running. That's deliberate: for this layer I want real integration, not mocked responses. (The mocked cases have their own home, more on that below.) # Run all 71 exercises uv run pytest tests/test_e2e.py -v # Debug a specific exercise HEADLESS=False uv run pytest tests/test_e2e.py -v -k "exercise-slug"</code></pre> By default, the tests run headless, which means no browser window opens. This is faster and works well in CI. If you want to see what Playwright is doing, set HEADLESS=False</code> to open a visible browser window. This is essential for debugging why a particular exercise fails. Use the -k</code> option to filter for a specific exercise by slug. And you can use --pdb</code> to leave the browser window open when a test fails, so you can inspect the state. For CI, I run unit tests only. E2E tests require the Rust backend and take longer. I run them locally before pushing major changes. This is a good example of separating unit and integration tests. What about the unhappy paths?</h2> A reader pointed out that these E2E tests only cover the happy path: type the correct solution, see "Congrats". Fair observation. What happens when a student submits wrong code, or the validator itself blows up? Those cases live in the unit tests, where I mock out the validator API call: Scenario</th> Test</th> Asserted message</th></tr></thead> Wrong code (tests fail)</td> test_validate_failure</code></td> mock returns success: False</code> → b"Oops, try again"</code></td></tr> Correct code</td> test_validate_success</code></td> success: True</code> → b"Congrats"</code></td></tr> Runner/API throws</td> test_validate_api_error</code></td> mock_post.side_effect = Exception</code> → b"Error while executing code"</code></td></tr> Exercise doesn't exist</td> test_validate_exercise_not_found</code></td> b"Exercise not found"</code></td></tr> Tests deleted/altered</td> test_validate_missing_tests</code></td> b"tests are missing"</code></td></tr> Prohibited code (std::fs</code>, unsafe</code>, include!</code>, std::io</code>...)</td> test_validate_prohibited_pattern_</code></td> b"prohibited pattern"</code> (parametrized over 6 snippets)</td></tr> </tbody></table> This is the split that makes the whole thing manageable. The E2E suite proves the full loop works end to end against the real validator. The unit tests, with the validator mocked, assert the exact message a student sees in each error case. Mocking is the natural home for these: some failure modes, like the runner throwing an exception, are hard to trigger on demand against a live backend, and even the ones you could reproduce in a browser are faster and clearer to pin down with a mock. See How to Tell if Your Python Mock Is Actually Working</a> for the gotchas there. What this buys me</h2> Add an exercise, it's tested automatically, no new test code. That's the whole point of parameterizing over the database instead of hand-writing cases. Every frontend change now runs through a regression suite before it reaches users. I find Playwright more modern and ergonomic than Selenium; the one rough edge is element timing, which the wait_for_function</code> calls above handle. If you're testing anything with dynamic content, parameterizing over your real data beats writing one test per case. When to use classmethod, staticmethod, or instance method in Python 2026-06-18T00:00:00+00:00 In a coaching call this week we discussed a create</code> classmethod, and someone asked the obvious question: why is that here? It just forwarded its arguments to init</code>. We ended up discussing the difference between instance methods, classmethods, and staticmethods, and how to tell which is which. Here's a simple decision rule. The decision rule</h2> Look at what the method actually touches: Needs the instance (self</code>) → instance method</li> Needs the class (cls</code>) but not a specific instance → @classmethod</code></li> Needs neither → @staticmethod</code></li> </ol> Nice, but what are some actual use cases? Let's look at the create</code> method that prompted the question. The create</code> method from the call fails the rule above. It took the same arguments as init</code> and passed them straight through. It still adds a nice interface (Class.create(...)</code>), but it doesn't do any work that the constructor doesn't already do: # shortened for clarity @classmethod def create(cls, amount: Decimal, currency: Currency = Currency.EUR) -> "Expense": return cls(amount=amount, currency=currency)</code></pre>When a classmethod earns its place</h2> A classmethod pulls its weight when it does work the constructor shouldn't, or builds the object from a different starting point. Add a normalization step and the same method suddenly has a job: @classmethod def create(cls, amount: Decimal, currency: Currency = Currency.EUR) -> "Expense": return cls(amount=amount.quantize(Decimal("0.01")), currency=currency)</code></pre> The canonical use of a @classmethod</code> is the alternative constructor. Python won't let you overload init</code>, so when you want to build an object several ways, each way becomes a classmethod. The standard library has rich examples, for example take a look at datetime.date</code>: date.today() # from the system clock date.fromtimestamp(1718539200) # from a POSIX timestamp date.fromisoformat("2026-06-16") # from an ISO 8601 string date.fromordinal(739418) # from a proleptic Gregorian ordinal date.fromisocalendar(2026, 25, 1) # from ISO year/week/day</code></pre> Source: # Additional constructors @classmethod def fromtimestamp(cls, t): "Construct a date from a POSIX timestamp (like time.time())." if t is None: raise TypeError("'NoneType' object cannot be interpreted as an integer") y, m, d, hh, mm, ss, weekday, jday, dst = _time.localtime(t) return cls(y, m, d) @classmethod def today(cls): "Construct a date from time.time()." t = _time.time() return cls.fromtimestamp(t) ... ...</code></pre> Every one of those returns a date</code>, but starts from different raw material. They have to be classmethods because they need cls</code> to construct the instance, and they return cls(...)</code> which makes it also work with subclasses. For instance, if MyDate</code> subclasses date</code>, then MyDate.today()</code> will return a MyDate</code> instance, not a date</code>. Bonus: I was annoyed that my pysource</code> package</a> didn't work, so I've since patched it, and now you can get to this source code easily with: uvx --from pybites-pysource pysource -m datetime.date</code></pre> (I tend to pip this into Vim with | vi -</code> to read the source code in a scratch buffer.) You'll see the same pattern across the ecosystem: dict.fromkeys(...)</code>, int.from_bytes(...)</code>, and in Pydantic Model.model_validate(...)</code></a> / model_validate_json(...)</code> are all classmethods that build an instance from different raw material. Another classmethod use case is class-level state: registries, caches, counters. A plugin registry is the clean example, because the method reads and mutates state that belongs to the class, not to any instance: class Handler: _registry: dict[str, type["Handler"]] = {} @classmethod def register(cls, name: str, handler: type["Handler"]) -> None: cls._registry[name] = handler @classmethod def get(cls, name: str) -> type["Handler"]: return cls._registry[name] # called on the class, no instance needed; it mutates state that lives on the class Handler.register("json", JSONHandler)</code></pre>When it's really a staticmethod</h2> If the method touches neither self</code> nor cls</code>, it's a staticmethod, which is a plain function that happens to live inside the class for namespacing. That's a legitimate choice when the helper is tightly bound to the class and you want Expense.normalize(...)</code> to read well. It's now part of the class API (it shows up in dir(Expense)</code>) and can be called without an instance. Genuine staticmethods are rarer than the other two, which itself tells you something. A clean example is a Color</code> class with conversion helpers (from a Pybites exercise): class Color: def init(self, name: str): self.name = name self.rgb = COLOR_NAMES.get(name.upper()) @staticmethod def hex2rgb(hex_value: str) -> tuple[int, int, int]: return tuple(int(hex_value[i:i + 2], 16) for i in (1, 3, 5)) @staticmethod def rgb2hex(rgb: tuple[int, int, int]) -> str: return f"#{rgb[0]:02x}{rgb[1]:02x}{rgb[2]:02x}"</code></pre> hex2rgb</code> and rgb2hex</code> touch neither the instance nor the class. They're pure conversions that live on Color</code> so Color.hex2rgb("#ff0000")</code> reads well next to the rest of the API. But that's exactly the signal worth noticing: a staticmethod might be just a function in disguise, and sometimes the honest move is to pull it out to a module-level function where it's easier to test and use on its own. Summary</h2> Method type</th> First argument</th> Access to</th> Common use case</th></tr></thead> Instance method</td> self</code></td> Instance & class state</td> Modifying object state</td></tr> Class method (@classmethod</code>)</td> cls</code></td> Class state only</td> Alternative constructors, registries</td></tr> Static method (@staticmethod</code>)</td> none</td> Neither</td> Isolated utility/helper functions</td></tr> </tbody></table> Why this matters more now</h2> When you write the code yourself, you rarely add a method without a reason. When an agent writes it, you get plausible-looking structure that nobody chose. A create</code> classmethod that does nothing, a staticmethod that should be a free function, a helper hanging off the wrong class. That's your judgment call: is this method doing work that belongs to the class, or is it just a pattern the agent learned from other code? It pays to slow down and look critically at any code and ask those questions. With AI producing more code faster, it's easy to assume that if it looks like Python, it's good Python. But the agent has no taste, and it will happily produce code that is technically correct but structurally wrong. This is also why I keep writing articles like this one: to give you a simple decision rule you can run in your head during review. It reminds me of Rust, which makes data flow explicit right in the signature with self</code>, &self</code>, and &mut self</code>. The signature tells you what the method touches, same idea as the rule here. (That data-and-behavior split is the whole theme of Why Rust does not need OOP</a>.) So use AI, but keep developing your knowledge and taste. The more you know, the better you judge the code that comes your way, whether a human or an agent wrote it. Building an AI Agent in 6 Weeks (and Finally Understanding How They Work) 2026-06-17T00:00:00+00:00 Jeff Haemer has written software since he was teaching it at the University of Colorado in the early 1980s. But he felt he needed to brush up his Python, and above all get a grounding in AI. In his words AI was "a big undifferentiated cloud of things I didn't know." Time to change that. Six weeks into our Python Agentic AI</a> cohort, he ended up with an agentic application</a> with a few thousand lines of code, almost 250 unit tests, 100% coverage, and three working interfaces: a web UI, a command line, and a Telegram bot that talks to his phone. He even went as far as running mutation testing. More than that, through the program he developed a mental model of how agents actually work under the covers. The gap</h2> Jeff came in with a long career behind him and a clear-eyed view of what he was missing: "It's a giant world and changing every day, and I didn't even know in many ways where to start. When you told me you were thinking about doing an AI cohort, I said, please do that and sign me up, and I will happily jump in feet first." </blockquote> He set expectations low on purpose. "I expected myself to crash and burn because I have a very spotty background." He'd taught plenty of courses; he knew how the first run of anything goes. He signed on as the cohort's beta tester and decided to stay enthusiastic through whatever broke. Watch the full interview with Jeff: Watch on YouTube</a> Core logic first, interfaces on top</h2> An agent is a program that takes a request, reasons about it with an AI model, and acts. The cohort builds the reasoning core first, then wraps interfaces around it. That structure got tested the hard way in the Telegram week, when connecting the agent to a chat app hit a wall. "I got to the end of that week and I wasn't even close, and I said, okay, I failed you. And you said, go on to the next week, because we designed the software so those units are independent of one another. We'll rewrite it." </blockquote> He moved on. The Telegram unit was independent, so an unfinished interface didn't block the rest of the build. We later rebuilt that week's material from almost 100 pages down to 41, starting from a simpler working version. When Jeff came back to it, it worked. "It was beautiful. When we hit a speed bump, that worked. It proved itself." </blockquote> There's a meta lesson here, and a reminder of what well-designed software looks like: build the thing that does the work first, keep the edges replaceable. This saved the beta cohort from going under. Mocking, the thing he kept putting off</h2> The concept that gave Jeff the most trouble was mocking, the practice of replacing a real outside service (an API, a database) with a stand-in so a test can run fast and offline. "The biggest pain for me was finally understanding what mocking involves. I even asked a friend of mine, a test automation Python guy, and he said, I never really understood that either." </blockquote> He avoided it until week four or five, when Juanjo made it non-negotiable: "You got me to the point where I could actually separate my unit tests, which were independent of outside services, from my integration tests. I learned stuff about pytest, I learned stuff about mocking, and I learned stuff about my own code. I just ended up thinking about things in a different way." </blockquote> Jeff's rigor with the test suite paid dividends. By the end they were catching real issues, including a function that slipped coverage when he deployed to a Debian box, which he set out to track down on his own. AI as teaching assistant, not autopilot</h2> Jeff wrote the code by hand. He used AI deliberately, as a tutor for the spots where his Python ran out, not as a generator to fill the file for him. "I understand conceptually what to do here, but I don't know enough Python to struggle through the docs and work through all the bugs in that short amount of time. So, show me how to do this. AI turns into a great teaching assistant." </blockquote> Unit tests gave each week a definition of done. The result is an artifact he can reason about, not a diff he has to trust on faith. Understanding by building</h2> The win Jeff cared about most wasn't the repo. It was the mental model: "It's different having done it than even reading about it. If somebody had written an explanation, a week later I'd have a vague idea, a month later I'd say I read an article about it but don't remember anything, and two months later I'd say I've never heard of that. This, I think I understand." </blockquote> He tested it against a toy agent he found in the wild, a hallucinating Wikipedia clone, and could trace exactly what it did: validate the input, structure it, hand it to the model, get structured output back, cache it in a database. From "big undifferentiated cloud of things I didn't know" to a firm grounding in how AI agents work. Jeff ended up with a great artifact on GitHub, but the real win has been this deeper understanding that he will take to his next AI project. We're excited to see what Jeff will build next with this new skill set. Why Rust does not need OOP 2026-06-14T00:00:00+00:00 When I heard structs replace classes in Rust, I was a bit surprised. I thought, how can you do without classes? But as I started to learn Rust, I realized that structs, traits, ownership and composition help resist the temptation of OOP. In fact, Rust's approach to programming is more focused on data and behavior rather than objects. Let's look at 5 reasons why Rust does not need OOP. 1. Composition</h2> One major drawback of OOP is deep inheritance trees. In classic OOP you would define class A, then class B inherits from A, then class C inherits from B, and so on. This can lead to a complex and fragile codebase where changes in one class can affect many others. class Animal {} class Dog extends Animal {} class ServiceDog extends Dog {}</code></pre> In What Rust Structs Taught Me About State Ownership</a> I showed this example: struct Tokenizer { chars: Vec<char>, position: usize, } impl Tokenizer { fn advance(&mut self) -> Option<char> { let ch = self.chars.get(self.position).copied(); self.position += 1; ch } fn peek(&self) -> Option<char> { self.chars.get(self.position).copied() // char is Copy, returns a value not a reference } }</code></pre> We see a clear separation of data (the fields) and behavior (the methods). The Tokenizer struct holds the state, while the methods define how to interact with that state. This is a more flexible and modular approach than OOP's class-based design. Rust also uses composition instead of inheritance. You can create complex types by combining simpler ones without the need for a class hierarchy. struct Animal {} struct Dog { animal: Animal, } struct ServiceDog { dog: Dog, }</code></pre> A great resource on this principle is Composition Over Inheritance</a>, part of Brandon Rhodes' Python Patterns Guide. For an example where I think OOP & inheritance went off the rails is Django's class-based views. The inheritance tree of those views is too deep making it an unpleasant API to work with, and the code so much harder to reason about. A better way is the more functional approach, see Luke Plant's Django Views — The Right Way</a>. 2. Traits</h2> In Python, think Protocols. In Java, think interfaces. In Rust, traits are a powerful way to define shared behavior without the need for a class hierarchy; polymorphism without inheritance. Classic OOP: Animal a = new Dog(); a.speak();</code></pre> In Rust, you can achieve similar behavior using traits: trait Speak { fn speak(&self); } fn make_noise(x: &impl Speak) { x.speak(); }</code></pre> The advantage here is that you can implement the Speak</code> trait for any type, and you don't need to have a common base class. This allows for more flexibility and code reuse. Python has something similar with Protocols, which are part of the typing</code> module. They allow you to define a set of methods that a class must implement, without requiring inheritance. from typing import Protocol class Speak(Protocol): def speak(self) -> None: ... def make_noise(x: Speak) -> None: x.speak()</code></pre> This is a more flexible alternative to ABCs (Abstract Base Classes) and allows for duck typing while still providing type safety. I wrote an article about this on Pybites</a>. Where OOP couples data and behavior, Rust's traits allow you to define behavior separately from data. This promotes code reuse and flexibility without the need for a rigid class structure. Rust encourages: struct User {} trait Serialize {} trait Validate {} trait Persist {}</code></pre> This is closer to the Single Responsibility Principle, the Unix philosophy of "do one thing and do it well", functional programming of data-oriented design with pure functions that operate on data, and composition over inheritance. Hence Rust allows you to mix and match traits to create complex behavior without the need for a class hierarchy. 3. Ownership and borrowing</h2> Many OOP patterns exist to control mutation and provide proper encapsulation. In Rust, ownership and borrowing rules ensure that data is accessed safely and efficiently. fn process(data: Data) // takes ownership (moved in) fn process(data: &Data) // borrows, read-only fn process(data: &mut Data) // borrows, can mutate</code></pre> Just by looking at the function signature in Rust, you can understand how data is being used and modified: who owns it, who mutates it, and when it goes out of scope. It eliminates the need for patterns like getters/setters, which are often used in OOP to control access to data. And these rules are enforced at compile time, not runtime. 4. Modularity</h2> I came to the conclusion some time ago that Python's module scope is a great feature. It allows you to organize code in a way that is more flexible than OOP's class-based organization. In Rust, modules and crates provide a way to organize code without the need for classes. Classic OOP: public class Counter { private int value; public void increment() { value += 1; } }</code></pre> In Rust, you can use module-level functions and structs to achieve the same result: mod internal { pub struct Counter { value: i32, } impl Counter { pub fn increment(&mut self) { self.value += 1; } } }</code></pre> Outside: counter.value // inaccessible counter.increment() // ok</code></pre> Yes, increment</code> is a mutating method, the same as a setter. The win isn't avoiding methods, it's two things. First, the privacy boundary is the module, not the object: value</code> is hidden from the whole module, and you can hide free functions and structs too, not just wrap fields in a class. Second, you only write the method when you need to guard an invariant. If a field is just plain data, mark it pub</code> and read it directly, no getter ceremony. Java's idiom nudges you to wrap every field in get</code>/set</code> whether it needs it or not. So encapsulation lives at the module level, not the class level. It also leans toward a more functional style where pure functions operate on data without mutable state. In Python you can also hide functions and variables at the module level: def _private_function(): pass</code></pre> But this does not prevent somebody importing it so you need fencing mechanisms like all</code> to control what gets imported. Python's _private</code> is a suggestion, Rust's module privacy is enforced by the compiler. 5. Enums and pattern matching</h2> In OOP, you often use class hierarchies to represent different types of objects. In Rust, you can use enums and pattern matching to achieve similar results without the need for a class hierarchy. Classic OOP: abstract class Shape {} class Circle extends Shape {} class Square extends Shape {}</code></pre> In Rust, you can use enums to represent different shapes: enum Shape { Circle(f64), Square(f64), } fn area(shape: Shape) -> f64 { match shape { Shape::Circle(r) => 3.14 r r, Shape::Square(s) => s s, } }</code></pre> Not only is an enum more lightweight than a class hierarchy, it also pairs up really well with pattern matching handling different cases in a concise and (!) exhaustive manner. The compiler will not let you forget a case. Conclusion</h2> In short, OOP bundles data and behavior together which made a lot of sense to me for a long time. Learning Rust though, I am seeing new paradigms how the language designers have decoupled the two. With Rust you get the good parts of OOP: encapsulation, abstraction and polymorphism, while dropping the less maintainable parts: inheritance trees, mutable state and coupling. So to wrap up, here is a comparison of classic OOP -> Python -> Rust: Concern</th> Traditional OOP</th> Python</th> Rust</th></tr></thead> Encapsulation</td> Classes with private/public members</td> Modules + _private</code> convention</td> mod</code> + pub</code> visibility</td></tr> Polymorphism</td> Inheritance + virtual methods</td> Duck typing / Protocols</td> Traits</td></tr> Reuse</td> Inheritance</td> Composition</td> Composition</td></tr> State modeling</td> Class hierarchies</td> dict</code>, dataclass</code>, classes</td> struct</code> + enum</code></td></tr> Object lifecycle</td> GC / constructors</td> GC</td> Ownership + borrowing</td></tr> Error handling</td> Exceptions</td> Exceptions</td> Result<T, E></code> + exhaustive matching</td></tr> </tbody></table> Typical style evolution</h3> Old-school OOP: Object → Class → Inheritance → Framework</code></pre> Modern Python: Data → Functions → Composition → Protocols</code></pre> Rust: Data → Ownership → Traits → Composition</code></pre> As you see Python gets you far and is versatile, but Rust's ownership and traits give you an even more reliable and maintainable way to structure your code without the need for OOP. Different philosophy</h3> I am not picking on Java or OOP, I've been a fan for a long time. Studying philosophy (e.g. Plato) gives you a deeper appreciation for this way of thinking</a>. But it can also lead to overcomplication and unnecessary coupling. It's good to learn the different paradigms and understand their strengths and weaknesses. In summary: Traditional OOP: "Model the world as interacting objects." </blockquote> Python: "We trust developers." </blockquote> Which is awesome, but not without risk. It allows for great flexibility and rapid development, but it can also lead to bugs and maintenance issues if not used carefully. Rust: "Prove correctness to the compiler." </blockquote> A newer paradigm for me, but the way Rust decouples data and behavior, enforces ownership and borrowing rules, and promotes composition over inheritance, all sit well with me. Those things do lead to more reliable and maintainable code. It encourages you to think about your code in a way that is more focused on data and behavior rather than objects. How to Update Multiple Page Elements from One htmx Request 2026-06-05T00:00:00+00:00 A button submits code, tests run, feedback appears. Standard htmx. But the submissions dropdown stays stale; the new submission is in the database, just not in the dropdown. One request, two elements to update. The problem: one request, two things to update</h2> On our Rust platform</a>, each exercise page has a "Run Tests" button. It posts the editor code to a Django view, which compiles and runs the tests, then swaps a pass/fail panel into a #feedback</code> div. Next to the editor there is a dropdown of your past submissions. Run the tests, and a new submission gets saved server-side. But the dropdown stayed stale until you reloaded the page. The new submission was there in the database, just not in the <select></code>. So now I have one request that needs to update two unrelated parts of the page: the feedback panel (the htmx target) and the submissions dropdown (somewhere else entirely in the DOM). First instinct: write JavaScript to read the response, build a new <option></code>, prepend it to the select. That works until you remember the dropdown also enforces a max number of submissions, drops duplicates, and orders newest-first. Replicate that logic in the browser and you now have two sources of truth that drift apart the first time you change the server rule. Htmx out-of-band swaps</h2> htmx has a feature for exactly this: out-of-band swaps</a>. The hx-swap-oob attribute allows you to specify that some content in a response should be swapped into the DOM somewhere other than the target, that is "Out of Band". This allows you to piggyback updates to other element updates on a response. </blockquote> htmx swaps any element carrying hx-swap-oob</code> into its matching target on the page, separately from the main swap. One response, many updates. First I pulled the submissions dropdown options into a partial so the page and the view render them identically:  <option disabled selected>Submissions / Reset</option> {% for submission in submissions %} <option value="{{ submission.unique_hash }}">{{ submission.created_at|date:"Y-m-d H:i" }} {% if submission.ok %}(OK){% else %}(Failed){% endif %}</option> {% endfor %} <option value="reset">Reset</option></code></pre> The page includes it inside the <select id="submissions"></code>. The view renders the same partial and tags it for an out-of-band swap: from django.template.loader import render_to_string from django.utils.html import escape def validate(request): # ... run the tests, save the submission ... submissions = Submission.objects.filter( exercise=exercise, user=user ).order_by("-created_at") options = render_to_string( "_submission_options.html", {"submissions": submissions} ) return HttpResponse( f""" <div class="...">{message}</div> <pre>{escape(output)}</pre> <div hx-swap-oob="innerHTML:#submissions">{options}</div> """ )</code></pre> The first part of the response swaps into #feedback</code> as usual. htmx spots the hx-swap-oob</code> element, pulls it out, and applies it to #submissions</code> instead. The button HTML only knows about #feedback</code>. The view decides what else to update. Whoever owns the data controls how it renders. A second example: progress bars that update themselves</h2> On the Python platform the same trick drives the learning-path progress widget. Passing an exercise recomputes your progress along every path it belongs to and swaps the bars into a sidebar, from the same request that renders the pass/fail panel: if ok: paths_html = "" for path in bite.bite_paths.prefetch_related("bites"): # ... compute completed / total / pct for this path ... paths_html += render_progress_bar(path, completed, total, pct) extra_html += ( f'<div id="learning-paths-progress" hx-swap-oob="innerHTML">{paths_html}</div>' )</code></pre> The two examples aim at their targets differently. The progress widget uses a bare hx-swap-oob="innerHTML"</code>: htmx swaps the fragment into whatever element already shares its id</code>. The dropdown uses the selector form, hx-swap-oob="innerHTML:#submissions"</code>, so the carrier <div></code> can target the <select id="submissions"></code> without needing to share its id. Use innerHTML</code> instead of the default hx-swap-oob="true"</code>. true</code> replaces the whole element (its outerHTML</code>), which for the <select></code> throws away the htmx listener attached to it. innerHTML</code> keeps the element and swaps only its children, so the listener survives and the options refresh underneath it. Here's the progress bars before and after passing an exercise. The bars update via out-of-band swap from the same response that renders the pass/fail feedback: You might spot the submissions dropdown in these shots and wonder why it is not OOB-swapped here too, like on the Rust platform above. It is the boundary of the technique: OOB swap is solid when you replace an element's whole inner content (innerHTML:#submissions</code>), but inserting a single new <option></code> means wrapping it in a <template></code> so the browser does not strip it, and htmx 2.x handled that case unreliably. So here the one-option insert runs through a small htmx:afterSwap</code> listener instead. The view writes the new submission into a hidden div, and the listener reads it and prepends the <option></code>: document.addEventListener("htmx:afterSwap", () => { const newSub = document.getElementById("new-submission"); if (!newSub) return; const select = document.getElementById("submissions"); const opt = document.createElement("option"); opt.value = newSub.dataset.hash; opt.textContent = newSub.dataset.label; select.insertBefore(opt, select.children[1]); // after the placeholder select.value = opt.value; });</code></pre> One honest cost: this adds a query. After saving, the view re-fetches the submissions to render the partial. The alternative is re-implementing state changes in pure JavaScript, creating behavior in two places. With out-of-band swaps you drive the logic from the view, all in one place. One more query, but less code and a more maintainable solution. Whoever fetches the data should render it. Keep the query and the template together. For more on hypermedia-driven applications, see this great book: Hypermedia Systems</a>. "Rust Is for People Who Want to Be Punished." Now Jochen Trusts It More Than Python. 2026-06-04T00:00:00+00:00 Jochen Deister is a lawyer who codes for fun. He has years of Python behind him and no intention of ever being hired to program. Three months ago, Rust was just a name to him, the language for "the big shots" with a notoriously steep learning curve. Then he built a JSON parser from scratch in Rust, and it ran faster than the equivalent in Python on every dataset he tested, up to 3.5x faster on some. "Holy F" he reacted when he saw the results. Six weeks of work produced: A from-scratch JSON parser</a>, no parsing libraries</li> Benchmarks beating Python's standard json</code> module (C-accelerated in CPython), up to 3.5x faster</li> Close to 30 commits in the final week alone, each one a single performance step</li> A deliberate 78-error refactor, with the compiler as the guide to a faster implementation</li> A new default language: Rust is now the one he reaches for first</li> </ul> Here's how it happened. The gap</h2> Jochen learned to code on a Commodore VIC-20 with six kilobytes of RAM, then a C64, then a stint in assembly and Turbo Pascal when the bottleneck moved from memory to speed. Then life took him into law and academia, and he forgot all of it until he picked Python back up years ago. Python suited him, but it hid the machine. "Python abstracts a lot of these concepts away" he said. "It hides the mechanics". He'd heard Rust had a notoriously steep learning curve, and he was doing this for fun. "Rust is for people who want to be punished in their life" he figured, and left it there. The trigger that changed it was small: the last Pybites podcast episode</a>, a $49 lifetime offer on our Rust practice platform</a>, and a remote cabin on the Danish coast where his only job was to keep his kids fed during exam season. He finished all 61 platform exercises, third on the leaderboard, then shortly after signed up for the cohort for a deeper challenge. The platform taught him the vocabulary. What it couldn't give him was a real project with a coach reading his code in detail. That's what our cohort is about: six weeks building a JSON parser, one PR review a week with Jim Hodapp</a>, expert Rust coach. The constraints stopped feeling like constraints</h2> Most people describe their first weeks of Rust as a fight with the borrow checker; the compiler rule that tracks who owns each value and won't let two parts of your code modify the same data at once. Jochen didn't feel it this way at all. "I never had the feeling that I was fighting the borrow checker. The error messages were my friends right out of the gate. They had a good explanation of the error, but also a hint about what you could do differently." </blockquote> What hooked him was aesthetics. Run the formatter on a chain of iterator steps and each transformation lands on its own line, readable top to bottom. "Rust is a beautiful language. It's an aesthetic language. It looks good, and working toward more beautiful code was really something I liked." </blockquote> That pulled him toward idiomatic Rust on its own. He stopped wanting code that merely worked, the bar he'd accepted in Python, and started wanting code that was safe, performant and idiomatic. He broke his own code on purpose</h2> Week five, PyO3, was the real step up. PyO3</a> is the bridge that lets you call a Rust module straight from Python, the same layer Pydantic and Polars are built on. It was the first concept the practice platform hadn't prepared him for, so he leaned on the implementation steps and went slowly. The clearest sign of how his thinking changed came in the final week. Three of his four benchmark datasets were already beating Python; one wasn't. He suspected the parser was copying the entire input onto the heap instead of borrowing it. So he changed the entry point to take a borrowed string with an explicit lifetime (a lifetime is Rust's way of letting you reference data without copying it, while proving the reference can't outlive the data) and ran cargo check</code>. It reported 78 errors. "Those 78 errors were my path of what I needed to fix to get to the results. You change something up the chain and 78 reduces to 50, and so on down the line. It is your implementation guide." </blockquote> He'd deliberately broken the code, then followed the compiler error by error back to a working, faster version. It's like having a 200% test suite for free; you feel confident making changes. The rewrite turned a parser that collected every token into a list up front into one that reads tokens on demand in a single pass. Jim's note on the PR: "This is such a clean functional style API for your tokenizer, it's evolved and matured nicely". The profiler told him where he was wrong</h2> Speed in Rust isn't automatic, and Jochen learned that the hard way. He'd swapped a list for a double-ended queue, proud of it. "Two days later, when I looked at the profiler, that very line that I was so proud of was now by far the biggest offender." </blockquote> A profiler measures where a program actually spends its time, so you optimize the real bottleneck instead of a guessed one. His showed the standard-library hash map dominating. He read the docs, realized that map carries protection against denial-of-service attacks he'd never need in a local command-line tool, and replaced it with a stripped-down one. Data-driven, one commit at a time, until the last dataset crossed the line. Through all of it he kept AI out of the code on purpose. He used it to make himself learn faster, NotebookLM turning Rust docs into podcasts and flashcards, never to write a solution. "Only I write the code" is the rule he gives his AI mentor. What changed</h2> Ask him how confident he feels starting a new Rust project and he says a 3 out of 10, and means it as a compliment to the language. "I'm not a total noob anymore. I have a rough understanding of the key concepts, but I also know there's a heck of a lot to learn." </blockquote> The transfer is in the habits. Rust is now his default for new projects, he caught himself skipping the Python newsletters to read about Rust instead, and the deliberate, idiomatic thinking followed him back into his Python. After years in the Python community, his loyalty quietly shifted: "I've always liked Python. But it's changed in a way that I think I like Rust more, because of its honesty and because it forces you to think stricter." </blockquote> His favorite piece of the language is pattern matching, the construct that lets you branch on the shape of a value and pull data out of it in one move. He went deep enough that he used a binding trick his coach hadn't seen before, matching and naming a value in the same arm. Jim's reply on the PR: "You taught me something I didn't realize Rust has. It's a nice match-and-bind pattern that saves boilerplate code." </blockquote> The reason he loves it is the same one running through everything he said: "Computer languages need to be beautiful." </blockquote> Next up for Jochen: porting a coding agent from Python to Rust, and a privacy tool that strips personal data out of text before it reaches an LLM. For someone who started three months ago thinking Rust was punishment, that's a real shift. (For more on how Rust rewires the way you write Python, see Learning Rust Made Me a Better Python Developer</a>.) Here is our full conversation with Jochen about his cohort experience, the parser he built, and the performance work he did: Watch on YouTube</a> If you're a Python developer wanting to reach a new level in your career, Rust is a strong contender. Book me in for a call</a> and we'll discuss this further. How to Tell if Your Python Mock Is Actually Working 2026-06-03T00:00:00+00:00 A test can pass for the wrong reason. When you're mocking a third-party API call, the test might look green because the real API happened to return an error, not because your mock did anything at all. This came up in a recent session in our agentic AI cohort</a> where we were looking at a test to verify that converting to an invalid currency raised an exception. The test passed. But something felt off. The test that passed for the wrong reason</h2> The code under test calls the ExchangeRate API and raises CurrencyConversionError</code> when the response signals failure: def convert_currency(amount: Decimal, from_currency: str, to_currency: str) -> Decimal: if from_currency == to_currency: return amount response = requests.get( f"https://v6.exchangerate-api.com/v6/{EXCHANGE_RATE_API_KEY}/pair/{from_currency}/{to_currency}" ) data = response.json() if data["result"] != "success": raise CurrencyConversionError(f"{data['error-type']}") return Decimal(data["conversion_rate"]) amount</code></pre> The test set up a mock_response</code>, patched requests.get</code> to return it (mock_get.return_value = mock_response</code>), but configured it as a successful response: mock_response.json.return_value = { "result": "success", # <-- this will never raise CurrencyConversionError "conversion_rate": 1.5, }</code></pre> If the mock was intercepting, the function would return normally and pytest.raises</code> would fail. But the test was passing. That meant the mock wasn't intercepting at all: the real API was being hit, and it was returning an error for the bogus "CTM" code. Proving the mock actually intercepted</h2> My instinct was to add print("calling external api")</code> before requests.get</code>. That proves the code reached that line. It does not prove whether the mock intercepted the call or the real network was hit. At this point you can put a breakpoint()</code> in the actual requests.get</code> code in your venv, but there is a better way: mock_get.assert_called_once()</code>: with pytest.raises(CurrencyConversionError): convert_currency( amount=Decimal("1.00"), from_currency="CAD", to_currency="CTM", # Canadian Tire Money, not a real currency ) mock_get.assert_called_once()</code></pre> If the mock was never called, this assertion fails and tells you directly: your patch didn't intercept the request. If the mock was called, the assertion passes and you know for sure that the test is relying on the mock, not the real API. Running the test with this assertion in place settled it. Once the patch targeted the right name (the fix in the next section), the mock intercepted the call and pytest.raises</code> failed with DID NOT RAISE</code>. That flip is the proof: a real call for "CTM" would have raised, so a non-raising run means the mock was in control. The earlier green had been the real API answering, never the mock. With the success response still in place, nothing raised. Fixing the response to signal an error made the test pass for the right reason, and assert_called_once()</code> then confirmed the call went through the mock and not the network: mock_get.return_value.json.return_value = { "result": "error", "error-type": "unknown-code", }</code></pre>Patch where the name is used, not where it's defined</h2> The currency module does import requests</code> then calls requests.get(...)</code>, so patching expenses_ai_agent.utils.currency.requests.get</code> targets the call site. With this import requests</code> style, patching requests.get</code> happens to work too, since both names point at the same module object. The rule bites when a module does from requests import get</code>: now get</code> is a local name in the currency module, and you must patch expenses_ai_agent.utils.currency.get</code>, not requests.get</code>. Patching the wrong location is a common mistake that leads to the mock not intercepting and the real API being called. The cleaned-up test with pytest-mock</h2> Once the mock response was correct and interception was verified, the test got two more improvements. First, the intermediate mock_response</code> variable is unnecessary: chain directly off mock_get.return_value</code>, as in the snippet above. Second, pytest-mock</code> (added with uv add --dev pytest-mock</code>) replaces the nested with patch(...)</code> context managers with a mocker</code> fixture. The result is flatter and easier to scan. Annotated: def test_bad_currency_conversion_raises(self, mocker): """Converting to a non-existing currency should raise an exception.""" # Patch requests.get as imported inside the currency module* so no # real HTTP call is made; patch target must match where the name is used mock_get = mocker.patch("expenses_ai_agent.utils.currency.requests.get") # Simulate the API response for an unrecognised currency code mock_get.return_value.json.return_value = { "result": "error", "error-type": "unknown-code", } with pytest.raises(CurrencyConversionError): convert_currency( amount=Decimal("1.00"), from_currency="CAD", to_currency="CTM", ) # Confirm the mock intercepted the call; if this fails, the real API was hit mock_get.assert_called_once()</code></pre> mocker</code> also handles teardown automatically via the fixture lifecycle, so you don't need with</code> to ensure cleanup. Another reason to mock: forcing a collision</h2> So far the mock has stood in for a network call. That's not the only reason to reach for one. Here's a test from my simple CRM</a> that stores contacts as files on disk: def create_contact( name: str, email: str = "", company: str = "", product: str = "" ) -> str: contacts_dir().mkdir(parents=True, exist_ok=True) code = next_code(name) path = contact_path(code) if path.exists(): raise FileExistsError(f"Contact {code} already exists") path.write_text(...) return code</code></pre> next_code</code> generates a unique code from the name. To test that creating two contacts with the same code raises FileExistsError</code>, you need both calls to produce the same code. That's nondeterministic by design, so you patch next_code</code> to pin it: @patch("crm.data.next_code") def test_cannot_create_contact_with_same_code(mock_next_code): mock_next_code.return_value = "jd1" data.create_contact("Jane Doe") with pytest.raises(FileExistsError): data.create_contact("Jane Doe")</code></pre> Note the patch target again: crm.data.next_code</code>, where the function is used. Same rule as before. And note that's the only mock here. Isolation matters as much as the mock, but it doesn't belong in this test. An autouse fixture already points the data dir at a fresh tmp_path</code>: @pytest.fixture(autouse=True) def crm_data(tmp_path, monkeypatch): monkeypatch.setenv("CRM_DATA", str(tmp_path)) (tmp_path / "contacts").mkdir() return tmp_path</code></pre> create_contact</code> calls path.write_text(...)</code>, so the first call writes a real jd1</code> file. Because every test runs against a fresh tmp_path</code>, that file lives only for the test: the collision can only come from the second call, nothing leaks between runs, and the test fails solely when the duplicate guard fires. Without that isolation, a leftover jd1</code> from a previous run makes the first call raise, pytest.raises</code> still passes, and you've tested nothing. Update: I later dropped this mock for an explicit override parameter. Instead of patching next_code</code>, I gave create_contact</code> an optional code</code> parameter (keyword-only, so it can't be passed by accident): def create_contact(name: str, , email: str = "", company: str = "", product: str = "", code: str | None = None) -> str: ... code = code if code is not None else next_code(name)</code></pre> The test pins the code through the public surface, no patching: def test_cannot_create_contact_with_same_code(): data.create_contact("Jane Doe") with pytest.raises(FileExistsError): data.create_contact("Jane Doe", code="jd1")</code></pre> One naming caveat, since this post points to Harry Percival's "Stop Using Mocks" below: this isn't dependency injection, tempting as it is to call it that. DI would pass next_code</code> itself in and let the test swap a fake. Here I pass the value the dependency would have produced, so it's really an explicit override parameter, the simpler tool. Real DI, with an injected collaborator, comes up at the end of this post. The trade-off is worth being honest about: I added a production parameter partly to make the test simpler. That's the "test-induced design damage" critics of mocking warn about: a seam that exists only to serve tests. I think it's justified here because code</code> doubles as a real feature: an explicit-code escape hatch for imports or restoring from backup. The test just happens to use it. If the parameter was only added for the test, I'd consider leaving the mock. Unit vs integration: where does this test belong?</h2> All this then led to a related question: How should you organize tests that hit real external services? </blockquote> The convention that holds up in practice: tests/ ├── unit/ # fast, fully mocked, no network, no secrets └── integration/ # slower, hits real DB / LLM / API endpoints</code></pre> The currency test above belongs in unit/</code>: it mocks requests.get</code> and never touches the network. A test that actually calls the ExchangeRate API to verify end-to-end behavior belongs in integration/</code>. A @pytest.mark.integration</code> marker is a lighter-weight way to get the same split without moving files. Register it in pyproject.toml</code>, then skip those tests in CI with pytest -m 'not integration'</code>. Both work, but the directory structure makes the distinction obvious at a glance. Explicit is better than implicit. The practical rule: if your test needs an environment variable or some external service to do its real work, it's an integration test. Mock that dependency out and it becomes a unit test. Or put it at the boundary</a> so you can inject a fake in unit tests and the real thing in integration tests (if still needed). For a practical example of test organization, see this video: Python Unit vs. Functional Testing: Understanding the Difference + Practical Example</a>. When mocks are the wrong tool</h2> There's a broader point underneath all this. Every time you patch requests.get</code> you're writing a test that's tightly coupled to one import path. Change import requests</code> to from requests import get</code> and every patch breaks. The tests test implementation, not behavior. I highly recommend watching Harry Percival's PyCon talk "Stop Using Mocks"</a>. He makes the case for alternatives: build an adapter class that owns the external call, write a fake in-memory implementation of it, and use dependency injection to pass it in. The repository pattern</a> is the same idea: your test passes in a fake, your production code passes in the real thing, and neither needs patching. Mocks are still the right choice here: we want to test one small unit whose only external dependency is well contained. AI Human-in-the-loop: News Digest Triage Telegram Bot 2026-06-01T00:00:00+00:00 In my trend digest article</a> I shared a quick tool to keep on top of tech trends, but it's a one-way street: the model gives information, but I still have to decide what to do with it. Let's build the second half: a Telegram bot that shows me each story, guesses a tag, and lets me confirm or overrule it with one tap. Human-in-the-loop (HITL): the model proposes, you decide</h2> AI makes suggestions but it can hallucinate, so it's important to have a human in the loop to catch mistakes. The model does the work of categorizing, the human makes the final decision. This is a good example of the control layer above the model</a> and it's where you can make AI more reliable. This is what we teach in week 4 of our Agentic AI cohort</a> where things come together: expense parsing, AI category suggestion, and the human in the loop to confirm it. This requires the bot to keep state, route responses, and a way to be wrong gracefully. Below is a smaller version so you can get a taste for how this works. We'll build it in seven steps. Clone the repo</a> to follow along step by step. Step 1: create the bot and get a token</h2> Telegram bots are created by another bot. Open Telegram and search for @BotFather (it has a blue checkmark): Send /newbot</code>.</li> Give it a display name (anything).</li> Give it a username ending in bot</code> that is globally unique, e.g. alice_trend_bot</code>.</li> </ol> BotFather replies with a token like 123456789:ABCdef...</code>. Treat it like a password. Put it in a .env</code> file next to your script (or export</code> in your shell), together with your OpenAI key: TELEGRAM_BOT_TOKEN=123456789:ABCdef... OPENAI_API_KEY=sk-...</code></pre> If the token ever leaks, send /revoke</code> to BotFather for a fresh one. Step 2: the dependencies</h2> The whole thing is one file. I use a PEP 723 header</a> so uv run</code> resolves everything into its own environment, no virtualenv to manage. Put this at the top of trend_triage_bot.py</code>: # /// script # requires-python = ">=3.12" # dependencies = [ # "python-telegram-bot>=21", # "openai>=1.40", # "httpx", # "python-decouple", # "pydantic", # ] # ///</code></pre> If you would rather build this inside an existing project, the equivalent is: uv init && uv add python-telegram-bot openai httpx python-decouple pydantic</code></pre> Then the imports and a few constants: import json import logging from pathlib import Path from typing import Literal, Protocol import httpx from decouple import config from openai import AsyncOpenAI from pydantic import BaseModel from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Message, Update from telegram.ext import ( Application, CallbackQueryHandler, CommandHandler, ContextTypes, ) logger = logging.getLogger(name) TAGS = ["read", "lib", "tool", "skip"] DEFAULT_TOPIC = "rust" READING_LIST = Path("reading_list.jsonl") LOBSTERS_FEED = "https://lobste.rs/t/{tag}.json"</code></pre>Step 3: fetch the stories</h2> Lobsters</a> has a per-tag JSON feed, no auth required: https://lobste.rs/t/rust.json</code> returns the latest Rust-tagged stories, .../t/python.json</code> the Python ones, and so on. It's a tighter, more engineering-focused signal than a broad keyword search, and parameterizing the tag is what lets /digest rust</code> and /digest python</code> hit the same code. A Story</code> is just a title and a URL. Let's set up the model and fetch the latest five stories for a given tag: from pydantic import BaseModel, HttpUrl class Story(BaseModel): title: str url: HttpUrl async def fetch_stories(tag: str, , limit: int = 5) -> list[Story]: async with httpx.AsyncClient( timeout=10, headers={"User-Agent": "trend-triage-bot"} ) as http: response = await http.get(LOBSTERS_FEED.format(tag=tag)) response.raise_for_status() return [ Story.model_validate( { "title": story["title"], "url": story["url"] or f"https://lobste.rs/s/{story['short_id']}", } ) for story in response.json()[:limit] if story.get("title") ]</code></pre> Two small details: Lobsters expects a User-Agent</code> header, and a text/discussion post has an empty url</code>, so we fall back to its comments page (/s/{short_id}</code>), the same pattern you'd use for an HN self-post. The </code> in the function signature makes the limit</code> keyword-only, so you have to call fetch_stories("rust", limit=10)</code>, which is a nice safeguard against accidentally changing the default. Step 4: let the LLM propose a tag</h2> The model picks one of TAGS</code>. As the digest topic is variable (/digest rust</code>, /digest python</code>), the tags have to be topic-agnostic, so they describe what a story is (read</code> / lib</code> / tool</code>), not anything Rust- or Python-specific. Content-type beats intent here: "is this a tool or a library" is answerable from a headline, whereas "will I read this or build with it" depends on me, not the title. And a tag the model can't infer is a tag you end up correcting every time. And using structured outputs</a> I get typed values back, not strings I have to parse and second-guess; consistent data types are the foundation of reliable AI. SYSTEM = ( "Tag this software/tech headline with one of: " "read (an article, post, or tutorial), " "lib (a library, framework, or package you import), " "tool (a CLI, app, or utility you run). " "Use 'skip' only if it is off-topic or clickbait." ) class TagChoice(BaseModel): tag: Literal["read", "lib", "tool", "skip"] class Classifier(Protocol): async def tag(self, story: Story) -> str: ... class OpenAIClassifier: def init(self, api_key: str, model: str = "gpt-4o-mini") -> None: self._client = AsyncOpenAI(api_key=api_key) self._model = model async def tag(self, story: Story) -> str: completion = await self._client.beta.chat.completions.parse( model=self._model, messages=[ {"role": "system", "content": SYSTEM}, {"role": "user", "content": story.title}, ], response_format=TagChoice, ) choice = completion.choices[0].message.parsed return choice.tag if choice else "skip" def _build_classifier() -> Classifier: return OpenAIClassifier(config("OPENAI_API_KEY"))</code></pre> _build_classifier()</code> constructs the client at runtime, not at import; we call it once in main()</code> and stash the result (more on that in step 7). This decoupling allows a test to inject a fake tagger without touching OpenAI. It's the same lazy-wiring trick I used demonstrating the repository pattern</a>. The Protocol</code> means any class with an async tag()</code> method drops in. Protocols are more flexible here, because they don't require inheritance like ABCs do, so the test double doesn't have to know about the real classifier at all. Filing a tagged story is a one-liner to a JSONL file. JSONL (or JSON Lines) is a way to store structured data; each line contains a single, valid JSON object. def save_to_reading_list(story: Story, tag: str) -> None: with READING_LIST.open("a") as f: f.write(json.dumps({"tag": tag, story.model_dump(mode="json")}) + "\n")</code></pre> Note that model_dump()</code> hands back a pydantic Url</code> object (HttpUrl</code>) that json.dumps</code> can't serialize; mode="json"</code> coerces it to a string first. Step 5: the keyboard that highlights the guess</h2> The AI's pick is prefixed with >></code>, but every other tag is one tap away. The callback_data</code> stays plain (tag:read</code>) so the handler never has to strip the decoration: def triage_keyboard(suggested: str) -> InlineKeyboardMarkup: buttons = [ InlineKeyboardButton( f">> {tag}" if tag == suggested else tag, callback_data=f"tag:{tag}", ) for tag in TAGS ] rows = [buttons[i : i + 3] for i in range(0, len(buttons), 3)] return InlineKeyboardMarkup(rows)</code></pre> The marker goes in front, and that detail matters: Telegram clips long button labels from the end, so my first attempt, wrapping the tag in >> tool <<</code>, showed up as >> tool…</code> with the closing marker eaten. The kind of bug you only catch by testing it on a real phone. Step 6: two steps, one stashed queue</h2> A simple bot is stateless: message in, reply out. This one is not. Step one (the /digest</code> command) fetches and shows the first story; step two fires later, when I tap a button, and needs the queue from step one. context.user_data</code> is a per-user dict the library keeps between handler calls, so I park the queue there: async def start_digest(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: if update.message is None or context.user_data is None: return topic = context.args[0].lower() if context.args else DEFAULT_TOPIC await update.message.reply_text(f"Fetching today's {topic} stories...") try: context.user_data["queue"] = await fetch_stories(topic) except httpx.HTTPStatusError: await update.message.reply_text( f"No feed for '{topic}'. Try a Lobsters tag like rust, python, or go." ) return except httpx.RequestError: await update.message.reply_text( "Couldn't reach Lobsters right now — try again in a bit." ) return await show_next(update.message, context) async def show_next(message: Message, context: ContextTypes.DEFAULT_TYPE) -> None: queue: list[Story] = (context.user_data or {}).get("queue", []) if not queue: await message.reply_text("Inbox zero. That's all the trends today.") return story = queue[0] suggested = await context.bot_data["classifier"].tag(story) await message.reply_text( f"{story.title}\n{story.url}", reply_markup=triage_keyboard(suggested), )</code></pre> context.args</code> is whatever followed the command: /digest python</code> gives ["python"]</code>, a bare /digest</code> gives []</code> and falls back to DEFAULT_TOPIC</code>. A typo'd topic is a 404 from Lobsters, so I catch HTTPStatusError</code> and reply with a helpful message, otherwise the user would just stare at a digest that never arrives. Validate at the boundary where untrusted input enters. The second except</code> covers the other failure mode: the request never gets an HTTP response at all. HTTPStatusError</code> only fires once Lobsters answers with a 4xx/5xx. A connect timeout, read timeout, or DNS failure is an httpx.RequestError</code>, which is a sibling of HTTPStatusError</code>, not a subclass. Miss it and a flaky network crashes the handler with a traceback instead of a friendly reply. Catching RequestError</code> covers every transport-level failure (ConnectTimeout</code>, ReadTimeout</code>, ConnectError</code>) in one branch. Read user_data</code> with .get(...)</code>, never [...]</code>. It lives in memory, so if the bot restarts mid-flow the dict is empty and you want a graceful reply, not a KeyError</code>. context.bot_data</code> is its per-bot sibling: one dict shared across all users. That makes it the right home for the classifier, which holds no per-user state. We build it once in step 7 and read it back here, so every story reuses the same OpenAI client instead of constructing a fresh one each time. Step 7: the callback, then wire it up</h2> When I tap a button Telegram sends a callback query, not a message. Three rules keep it sane, numbered in the code: async def on_tag(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None: query = update.callback_query if query is None or query.data is None: return await query.answer() # 1. stop the spinner, first thing _, tag = query.data.split(":", 1) # 2. "tag:read" -> "read" queue = (context.user_data or {}).get("queue", []) if not queue: # stale button after a restart await query.edit_message_text("Session expired, send /digest again.") return story = queue.pop(0) if tag != "skip": save_to_reading_list(story, tag) # the human's final say await query.edit_message_text( # 3. edit, don't reply f"Filed under {tag}: {story.title}" if tag != "skip" else f"Skipped: {story.title}" ) if isinstance(query.message, Message): await show_next(query.message, context)</code></pre> Call await query.answer()</code> first or the loading spinner on the button never stops, even when everything else works. Edit the original message instead of replying, or the dead keyboard sits there inviting a second tap on a story you already filed. The same .get(...)</code>-not-[...]</code> rule applies here: an old keyboard from before a restart can still send a tap, and you want a "send /digest again" nudge, not a KeyError</code>. Routing is by prefix. The pattern="^tag:"</code> is why a future second keyboard (say setcurrency:EUR</code>) would not trip this handler: async def on_error(update: object, context: ContextTypes.DEFAULT_TYPE) -> None: logger.exception("Handler failed", exc_info=context.error) def main() -> None: logging.basicConfig( format="%(asctime)s %(name)s %(levelname)s %(message)s", level=logging.INFO, ) logger.info("Starting trend triage bot, polling for updates") app = Application.builder().token(config("TELEGRAM_BOT_TOKEN")).build() app.bot_data["classifier"] = _build_classifier() app.add_handler(CommandHandler("digest", start_digest)) app.add_handler(CallbackQueryHandler(on_tag, pattern="^tag:")) app.add_error_handler(on_error) app.run_polling() if name == "main": main()</code></pre> Three things to notice here in main()</code>: logging.basicConfig(...)</code> turns on output: run_polling()</code> blocks silently otherwise, so without it a freshly started bot looks dead in the terminal even though it's happily polling. </li> app.bot_data["classifier"]</code> builds the OpenAI client once instead of per story. </li> add_error_handler</code> means a network blip or a rate limit gets logged through on_error</code> rather than vanishing into the framework. </li> </ul> Run it</h2> $ export OPENAI_API_KEY=sk-proj-... $ export TELEGRAM_BOT_TOKEN=... $ uv run trend_triage_bot.py 2026-06-01 13:19:42,866 main INFO Starting trend triage bot, polling for updates 2026-06-01 13:19:43,190 httpx INFO HTTP Request: POST https://api.telegram.org/bot.../getMe "HTTP/1.1 200 OK" 2026-06-01 13:19:43,242 httpx INFO HTTP Request: POST https://api.telegram.org/bot.../deleteWebhook "HTTP/1.1 200 OK" 2026-06-01 13:19:43,244 telegram.ext.Application INFO Application started</code></pre> Open your bot in Telegram and send /digest</code> for the default topic, or use a tag like /digest python</code>, /digest rust</code> or any Lobsters tag</a>. The bot walks you through today's stories one at a time. Tap the highlighted tag to accept the model's guess, or any other tag to overrule it, until you hit inbox zero: Same bot, any topic: finish the Rust queue, then /digest python</code> and triage that, no code change: Filed stories land in reading_list.jsonl</code>: {"tag": "read", "title": "One year of Roto, the compiled scripting language for Rust", "url": "https://blog.nlnetlabs.nl/one-year-of-roto-the-compiled-scripting-language-for-rust/"} {"tag": "lib", "title": "Announcing Rust 1.96.0", "url": "https://blog.rust-lang.org/2026/05/28/Rust-1.96.0/"} {"tag": "read", "title": "What kache actually caches", "url": "https://kunobi.ninja/blog/what-kache-actually-caches"} {"tag": "read", "title": "Creusot helps you prove your Rust code is correct", "url": "https://github.com/creusot-rs/creusot/tree/master"} {"tag": "tool", "title": "uv must be installed to build a standalone Python distribution", "url": "https://github.com/astral-sh/python-build-standalone/commit/c9c40c56eb53136587f0a32382cad9e5cd8d184a"} {"tag": "tool", "title": "SPy: an interpreter and a compiler for a statically typed variant of Python", "url": "https://github.com/spylang/spy"} {"tag": "read", "title": "Opaque Types in Python", "url": "https://blog.glyph.im/2026/05/opaque-types-in-python.html"} {"tag": "read", "title": "uv is fantastic, but its package management UX is a mess", "url": "https://www.loopwerk.io/articles/2026/uv-ux-mess/"}</code></pre> That file is the actual output; one JSON object per line, ready to feed into whatever reads it next. You can find the repo here</a>. The interesting question is not whether the model can tag a headline. It's pretty accurate, but it can get it wrong, and that's where you want to have a human in the loop. This has been a simple example to show the flow, but real workflows might involve more interesting things like approving trades, triaging support tickets, or moderating content. The model can do the heavy lifting of making a guess, but the human gets the final say, and that's where the value is. The control layer is the product, not the model 2026-05-30T00:00:00+00:00 Gary Bernhardt posted something this week that names a phenomenon we're teaching in our agentic AI cohort: Everyone seems fixated on the models, but I think there's so much low-hanging fruit in the control layer above the model. "Agent" and "harness" sell that layer short. There's so much more that we can do beyond "read input, send to model, run commands it returns." </blockquote> He's right. The model is a brain in a jar. Useful, fast, occasionally wrong, stateless. Everything that turns it into a product lives in the code that wraps it: the routing, the validation, the state, the audit trail. Gary calls that the control layer. I'm stealing the term. One of the replies under the tweet</a> nailed the design goal in a single question: do you actually know what the agent is going to do? That's what a control layer buys you. Not magic, not autonomy, predictability. A workflow where, by the time the model is called, the next move is already constrained to something safe. Why "agent" and "harness" sell it short</h2> When a developer says "I'm building an agent", they usually mean a while True</code> loop that pings an LLM, parses a tool call, runs it, feeds the result back, and repeats. That pattern works for demos. It rarely survives contact with a real workflow. The word "harness" makes the wrapping code sound passive, a strap that holds the model in place. It's actually the control layer where the engineering happens. The model is a function call inside it. Once you flip that mental model, you stop asking "which LLM should I use" and start asking "what guarantees does my control layer make?" and "how can I make the inherently unpredictable model fit into a predictable workflow?" These are the questions production teams have to answer. Pattern 1: deterministic state machines, not unconstrained agents</h2> An agent without constraints decides what to do next from inside the model. A state machine</a> decides outside the model and gives the model one bounded job at each step. The pipeline runs categorize → validate → confirm → persist</code>, and the LLM only ever gets called inside one of those buckets. This shifts control flow back to your code, where you can test it, log it, and reason about it. The expense agent we build in our cohort, which I broke down in How an AI expense agent is actually structured</a>, follows exactly this pattern: Protocol-defined LLM boundary, Pydantic-validated outputs, service layer holds the state, human-in-the-loop (HITL) confirms before anything writes. Four layers, no free-roaming agent, constraints at every step. Pattern 2: the model behind a typed boundary</h2> The model should be one swappable function call inside your control layer, not a dependency threaded through every layer. In our cohort the LLM lives behind a Python Protocol: a small interface the service layer depends on, so nothing downstream knows or cares whether the call goes to OpenAI or Anthropic. Once the boundary is a Protocol, the decisions people reach for "routing" to solve become wiring instead of rewrites. Picking a cheap fast model for a 12-way classification and saving the expensive one for hard reasoning is a one-line change. Falling back to a second provider when the first is rate-limited is a small factory, not a refactor. Swapping OpenAI for Anthropic, two SDKs that disagree on almost every detail, touches one file because the boundary absorbs the difference. And it makes the whole pipeline testable. Tests pass a mock that satisfies the Protocol, so you exercise every path without an API call incurring latency or cost. Pattern 3: evaluators and guardrails</h2> The model's output is not the user's output. Between the two sits validation: schema checks, business rules, PII filters, sometimes a second model grading the first one's work. This is the generator-evaluator split and it's an important pattern (apart from HITL) I've found for AI code that has to be right. The generator proposes. The evaluator approves or rejects. When the evaluator rejects, control loops back with feedback, not a stack trace. It's also the layer that catches the worst failure mode of multi-step agents. What production AI agents actually require</a> goes deeper on the four questions the control layer answers before any action runs: state, idempotency, audit, rollback. Pattern 4: structured generation</h2> A raw string from the model is the start of your problems. You can't store it, validate it, or test it well. The fix is to constrain output at the boundary: the model is allowed to speak, but only in shapes your code understands. Where the typed boundary in Pattern 2 decides where the model sits in your code, structured generation decides what shape it's allowed to emit. Pydantic plus your model's structured outputs gives you typed data instead of strings, which means the next layer of your control flow becomes ordinary Python. I covered this in Build the data layer before you touch the LLM</a>, explaining why we teach developers to build the schema before they make a single API call. The frontier models make the headlines. The control layer ships the product. Gary's tweet names a gap that has been there the whole time, between the people optimizing benchmarks and the people building products. The control layer is the product, not the model. If you want to build AI products, that's where you need to spend your time. If you want a working walkthrough of the patterns above, the 10 small agentic AI exercises</a> Juanjo</a> and I shipped, run in the browser and cover the arc from a 3-line model call to a complete loop with HITL. They're the conceptual map. The cohort</a> is the same map, end to end. Six weeks, no frameworks, the control layer built explicitly, with code review at every step. By the end you can answer that one question: you know what your agent is going to do. Two Python Scoping Bugs: A Lesson in Object Lifetimes 2026-05-28T00:00:00+00:00 Your app works fine with one user. You open a second browser tab and the data is wrong. Your tests pass individually but fail when run together. The culprit: a global object created at module scope. How it starts</h2> I see this a lot in Python web projects: # database.py from sqlmodel import create_engine, Session engine = create_engine("sqlite:///database.db") def get_session(): with Session(engine) as session: yield session</code></pre> This 'innocent' engine</code> is created the moment database.py</code> is first imported. Every module that imports from database</code> shares the same engine, the same connection pool, the same database file. For a simple script, this is fine. For a multi-module app, it creates hidden coupling and shared state. The test isolation problem</h2> I hit this recently in a FastAPI app: # test_app.py from myapp.database import engine, create_db_and_tables, clear_db_and_tables @pytest.fixture(autouse=True) def setup_database(): clear_db_and_tables() create_db_and_tables() def test_create_race(race_events): championship = create_races(2026, race_events) assert championship.id == 1 # Passes alone, fails in suite</code></pre> That assert championship.id == 1</code> works when the test runs first. Run it after another test that inserts data, and the auto-increment ID comes back as 2. The fixture does its job, but state still leaks between tests in subtle ways: connection pool state, cached metadata, and SQLite's own bookkeeping on the shared file can carry over even with drop/recreate cycles. The root cause is upstream: every test reaches for the same module-level engine pointed at the same on-disk database. If you want true isolation, the engine itself has to be per-test, not the cleanup ritual around it. The fix is creating an engine per test session: @pytest.fixture def engine(): engine = create_engine("sqlite://", echo=False) SQLModel.metadata.create_all(engine) yield engine engine.dispose() @pytest.fixture def session(engine): with Session(engine) as session: yield session</code></pre> Now each test gets a fresh database (no scope defined on the fixture decorator means function scope = per test). No cleanup needed. No shared state. Alternatively, keep the module-level engine and wrap each test in a transaction you roll back at teardown (sqlmodel's Session</code> supports this). If you omit engine.dispose()</code> in the code above, you may see a ResourceWarning: unclosed database</code>, but only when running pytest --cov</code>. Coverage's sys.settrace()</code> hook keeps frame locals alive longer, delaying GC of the engine. The shared simulator problem</h2> The database engine bug is about too much sharing. Here is the inverse: not enough sharing, which breaks in a different way. Consider a race simulation dashboard. FakeDataSource</code> wraps a RaceSimulator</code> that holds the full mutable race state, driver positions, lap counter, cumulative changes, and advances it on each call: class FakeDataSource(RaceDataSource): def init(self, data_file: Path, delay_ms: int = 100): drivers = self._load_drivers(data_file) self.simulator = RaceSimulator(drivers=drivers) # mutable state lives here async def get_positions(self, fixture_id: str) -> list[Position]: self.simulator.tick() # randomly swaps adjacent positions, advances lap return self.simulator.get_current_positions()</code></pre> The FastAPI dependency looks like this: def get_data_source() -> RaceDataSource: source_type = config("DATA_SOURCE", default="fake") if source_type == "fake": return FakeDataSource(data_file=..., delay_ms=...) # new instance every call ... def get_race_data_source() -> RaceDataSource: return get_data_source()</code></pre> FastAPI calls get_race_data_source()</code> once per request. Each browser tab that opens the SSE stream gets a brand new FakeDataSource</code> with a brand new RaceSimulator</code> starting at lap 1 with drivers in their initial order. The random swaps then diverge independently: Tab A shows Verstappen in P1 at lap 12, Tab B shows Hamilton in P1 at lap 3. Neither reflects a shared reality, because there is no shared state at all. Two fixes, from quick to idiomatic</h2> 1. cache</code>: one line, works immediately from functools import lru_cache @lru_cache(maxsize=1) def get_data_source() -> RaceDataSource: source_type = config("DATA_SOURCE", default="fake") if source_type == "fake": return FakeDataSource(...) return SportmonksDataSource()</code></pre> One instance for the lifetime of the process. Simple, but hard to override in tests. 2. FastAPI app.state</code>: idiomatic and testable @asynccontextmanager async def lifespan(app: FastAPI): app.state.data_source = get_data_source() yield app = FastAPI(lifespan=lifespan) def get_race_data_source(request: Request) -> RaceDataSource: return request.app.state.data_source</code></pre> The data source is created once at startup, shared across all requests, and easy to replace in tests via app.dependency_overrides[get_race_data_source] = lambda: test_source</code>. Key takeaways</h2> Module-level objects are created at import time and shared everywhere: global mutable state, and a common source of subtle bugs.</li> Tests that share a database engine aren't isolated, even with setup/teardown fixtures.</li> Web apps that create per-request instances lose shared state; apps that share module-level instances lose testability.</li> Use app.state</code> or cache</code> for shared runtime state; override the FastAPI dependency in tests for isolation.</li> </ul> The rule of thumb: if an object holds mutable state, pick its scope deliberately. Too broad (module scope) and tests leak into each other. Too narrow (per-request) and there's no shared reality. Match the scope to the object's intended lifetime. Or put more sharply: any module-level object that holds mutable state or owns a resource (DB engines, HTTP clients, caches, queues, connection pools) should be encapsulated. Move it into a fixture, a Depends()</code>, or app.state</code>. Constants and pure values at module scope are fine; resources are not. The cost of "just import it" is paid later, in test isolation, debugging, and concurrency. Under real concurrency the GIL hides this class of bug until it doesn't, see a race condition Rust wouldn't have let me write</a>, where the same module-global pattern leaked one user's data into another user's response. From Python Script to Production: A Django Coaching Case Study 2026-05-26T00:00:00+00:00 Six weeks of 1:1 coaching. The output: a Django app in production on Fly.io, covering movies, anime, and manga, with user accounts, a save library, Docker, and CI/CD on every push. Daniele started with Python skills and a project idea. Here's what the work actually looked like. The starting point</h2> The idea was a platform to discover and track movies, anime, and manga. He had enough Python to start, already building a CLI tool with a swappable data layer</a> in our first app together. What he didn't have was experience building a web app: the real mechanics of Django, how the pieces connect, what "ready to ship" means in practice. Self-study can get you to a prototype. It won't tell you when code that works is teaching you the wrong habits. That's what weekly PR reviews are for. Starting with discipline, not speed</h2> The first PR was a Python script. It called the TMDB API, parsed the results, and displayed them. Functional and already a place to build habits. For example: the type hint on _fetch_tmdb_data</code> said -> dict</code>, but the function could return None</code>. Fix the type hint. The constants TMDB_URL</code> and headers weren't uppercased consistently. Follow PEP8 conventions. The API key loaded from an .env</code> file, but there was no .env-template</code> telling other developers which variables to set. Add the template. None of these changes affect whether the script runs. All of them affect whether another developer, or Daniele himself in six months, can reason about it. That's where professional developer habits form. Django's machinery is yours to understand</h2> Moving from a script to Django means the framework does a lot for you. The risk is accepting what it does for you without understanding its deeper workings. In week 2, Daniele ran uv run ty check .</code> and got two errors: Class 'Movie' has no attribute 'objects'</code>. Django adds the objects</code> manager dynamically at runtime; ty</code> is a static type checker and can't see it. He asked the right question: "So this was because of ty/type checker flagging an error? If we have a way to instrument ty globally to recognize Django's dynamic managers, that would be better. Do we need to pull in 'django-stubs' or a similar configuration?" </blockquote> The answer was: Django's dynamic ORM creates real friction with static type checkers. The pragmatic fix was to explicitly declare objects: models.Manager</code> on the model, making the implicit explicit for both the type checker and any developer reading the code. The question itself was the point. Understanding why the error existed led to a better solution. We also made a note to compare with other type checkers like pyrefly</code> (v1.0 just came out) or mypy</code> and see if they have better Django support. The same week, the movie detail page returned 404s even though data existed. The cause: movie_list</code> fetched from the API but didn't persist to the database. movie_detail</code> queried the database. Nothing matched. Daniele fixed the sync logic and wrote: "I ran across a problem earlier that was caused by not having the DB in sync. So lesson learned and now I try not to forget to run it." </blockquote> Running makemigrations</code> after every model change now became a habit. Refactoring is how architecture emerges</h2> By week 6, the codebase had grown. Two API functions, get_movie_list_from_api</code> and get_services_list_from_api</code>, had identical try/except blocks. The only difference was the endpoint and the default return value. Extracting a private _get_from_api(endpoint, default)</code> helper isn't a trick. It's a principle: if two pieces of code do the same thing, one is a future bug waiting to diverge. The refactor also cleaned up the return types from list[Movie] | None</code> to list[Movie]</code>, replacing a None</code> sentinel with a proper empty list default. Each review surfaced one decision that sharpened his model of how good code behaves. Week 6: Docker, CI/CD, and a live URL</h2> Week 6 was Docker and Fly.io. The app that ran locally needed to run in the cloud: no SQLite disappearing on container restart (or moving to Postgres), environment variables properly set, static files served correctly, no secrets hardcoded anywhere, GitHub Actions deploying on every push to main (with passing tests). Daniele learned a lot here and shipped his app</a>: When Daniele shared the deploy win in my coaching Slack, he put into words something that sits at the center of anybody wanting to improve their coding/developer skills now: "Addressing quality and best practices and security and maintainability in your code does not pair well with velocity, especially when you're learning. So I preferred to improve my code quality and to become better at it by learning properly, postponing some feature release for later. In the process I learned Django and its main mechanics, Docker and deployment in the cloud." </blockquote> The velocity-vs-quality tradeoff he named isn't unique to learning Django. It's the choice every developer makes every week. My coaching gave him the framework, the discipline and persistence were his. What production AI agents actually require 2026-05-22T00:00:00+00:00 Most "AI agents" shipping right now are demos wearing production paint. They answer questions fluently and break the moment they touch a workflow with money, state, or consequences. The agent illusion</h2> Multi-agent frameworks benchmark beautifully. Five specialist LLMs cooperate, the demo plays cleanly, the README has a diagram with arrows. Then someone wires the thing to a real billing system and it issues three refunds for the same chargeback because a tool call retried on a flaky network. That gap is the actual job most agent tutorials skip. When I review AI code, the same pattern keeps appearing. The LLM call is fine. The agent loop is fine. What is missing is the layer underneath: state, idempotency, audit, and a tool surface the agent cannot use to hurt you. The unsexy layer</h2> Systems answer four questions before the agent does anything: What did the agent already do? Persisted state, not "look at the conversation history."</li> What happens if this action runs twice? Idempotency keys on every external effect.</li> Who approved this? An audit log a human can read during a postmortem.</li> Can I roll this back? A clear inverse for every irreversible operation, or a freeze before execution.</li> </ol> None of this is glamorous. It is also what separates a system that is a toy demo from one that can run mostly unsupervised in production. The shape of that contract in code: class ExpenseAction(BaseModel): idempotency_key: str requested_by: str requested_at: datetime approval_required: bool = True dry_run: bool = True payload: ExpensePayload def submit(action: ExpenseAction, repo: ExpenseRepo) -> Result: if repo.find_by_key(action.idempotency_key): return Result.duplicate() if action.dry_run: return Result.preview(action.plan()) if action.approval_required and not action.is_approved(): return Result.pending_approval() repo.persist(action) return Result.ok(action.execute())</code></pre> The agent does not call the side effect. It builds a typed plan. A function decides whether to run it. State that survives retries</h2> Agents need state management that works across restarts and network failures. The Telegram expense bot we build in our Agentic AI cohort program, uses context.user_data</code> to track multi-step flows: async def handle_expense_text(self, update, context): text = update.message.text result = self._preprocessor.preprocess(text) if not result.is_valid: await update.message.reply_text(f"Invalid: {result.error}") return ConversationHandler.END response = self._build_service().classify(result.text).response # Store state for the callback handler context.user_data["expense_description"] = result.text context.user_data["classification_response"] = response keyboard = build_category_confirmation_keyboard( suggested_category=response.category, all_categories=[c.value for c in ExpenseCategory], ) await update.message.reply_text( f"I categorized this as {response.category} ({response.total_amount} {response.currency}). Confirm or pick another category:", reply_markup=keyboard, ) return ConversationState.WAITING_FOR_CATEGORY async def handle_category_selection(self, update, context): query = update.callback_query await query.answer() # Retrieve state from previous handler description = context.user_data.get("expense_description") response = context.user_data.get("classification_response") if description is None or response is None: await query.edit_message_text("Session expired. Send expense again.") return ConversationHandler.END _, category = query.data.split(":", 1) self._build_service().persist_with_category( expense_description=description, category_name=category, response=response, telegram_user_id=update.effective_user.id, ) await query.edit_message_text(f"Saved as {category}!") return ConversationHandler.END</code></pre> The .get()</code> with defensive error handling is what saves you when the bot restarts mid-conversation. No silent corruption, no half-written database rows. The user just has to resend their expense description and pick the category again. This is the work of production agents. Tools the agent cannot trust</h2> LLMs are undeterministic and hallucinate. Design your tool surface for mistrust: Narrow scopes. read_expense</code> and flag_expense</code> are two tools, not one tool with a mode flag the LLM can flip.</li> Dry-run by default. Every write tool returns a plan first. The agent opts in to execute. You get human-in-the-loop (HITL) for free.</li> Schema-validated inputs. Pydantic at the tool boundary</a> so a malformed argument cannot reach your database.</li> Explicit confirmation for anything destructive. The agent proposes, a human taps approve.</li> </ul> The agent is not the brain of your application. It is a planner that we acknowledge is fallible. The real logic lives in the tools, and the agent's job is to call them with valid inputs and ask for help when it is unsure. Input validation before the LLM sees anything</h2> Validate at system boundaries before user input reaches your tools. This prevents XSS, length attacks, and malformed data from consuming tokens: from dataclasses import dataclass, field import re XSS_PATTERNS = ("<script", "javascript:", "onerror=", "onload=") CURRENCY_SYMBOLS = {"$": "USD", "€": "EUR", "£": "GBP", "¥": "JPY"} AMOUNT_PATTERN = re.compile(r"\d+([.,]\d+)?") @dataclass class PreprocessingResult: text: str is_valid: bool warnings: list[str] = field(default_factory=list) error: str | None = None class InputPreprocessor: def preprocess(self, text: str) -> PreprocessingResult: text = text.strip() if len(text) < 3: return PreprocessingResult(text, False, error="Input too short") if len(text) > 500: return PreprocessingResult(text, False, error="Input too long") if any(pattern in text.lower() for pattern in XSS_PATTERNS): return PreprocessingResult(text, False, error="Invalid characters") for symbol, code in CURRENCY_SYMBOLS.items(): text = text.replace(symbol, code) warnings = [] if not AMOUNT_PATTERN.search(text): warnings.append("No amount detected") return PreprocessingResult(text, True, warnings)</code></pre> This runs before the LLM call, returning error messages without burning tokens or risking injection. Human-in-the-loop as a design pattern</h2> Production agents are not fully autonomous. They classify, extract, or suggest, then wait for a human to confirm. Confidence scores guide when to ask: from dataclasses import dataclass @dataclass(frozen=True) class ClassificationResult: response: ExpenseCategorizationResponse persisted: bool def process_with_hitl(result: ClassificationResult, threshold: float = 0.8) -> str: if result.response.confidence >= threshold: return result.response.category print( f"Low confidence ({result.response.confidence:.0%}): '{result.response.category}' — {result.response.reason}" ) user_input = input( f"Accept '{result.response.category}'? (Enter to confirm, or type a category): " ).strip() if not user_input: return result.response.category return user_input</code></pre> In the Telegram bot, this becomes an inline keyboard. The bot states its category guess and asks the human to confirm or pick a different one, with the AI suggestion highlighted. The pattern: AI proposes, human disposes. This surfaces in the service layer we built in prior weeks: @dataclass class ClassificationService: assistant: Assistant expense_repo: ExpenseRepository def classify(self, description: str) -> ClassificationResult: messages = self._build_messages(description) response = self.assistant.completion(messages) return ClassificationResult(response=response, persisted=False) def persist_with_category( self, expense_description: str, category_name: str, response: ExpenseCategorizationResponse, telegram_user_id: int | None = None, ) -> None: """Store the user's chosen category, not the AI guess.""" expense = Expense( amount=response.total_amount, currency=response.currency, category=ExpenseCategory(category_name), description=expense_description, telegram_user_id=telegram_user_id, ) self.expense_repo.add(expense)</code></pre> The persist_with_category</code> method accepts the human's decision. The database stores what the user confirmed, not what the model guessed. As the ExpenseCategorizationResponse</code> captures the AI's original category and confidence, we can analyze overrides later to identify model weaknesses. Dependency injection for testable agents</h2> The service layer pattern separates business logic from LLM provider details. Inject dependencies rather than hardcoding them: from unittest.mock import create_autospec from decimal import Decimal def test_classify_calls_assistant(): # No real OpenAI call, no .env file, no network mock_assistant = create_autospec(Assistant) mock_assistant.completion.return_value = ExpenseCategorizationResponse( category="Food", total_amount=Decimal("5.50"), currency=Currency.USD, confidence=0.95, cost=Decimal("0.001"), ) mock_repo = create_autospec(ExpenseRepository) service = ClassificationService(assistant=mock_assistant, expense_repo=mock_repo) result = service.classify("Coffee at Starbucks $5.50") mock_assistant.completion.assert_called_once() assert result.response.category == "Food" assert result.persisted is False</code></pre> Because the service receives its dependencies rather than creating them, you can test classification logic without burning API credits or waiting on network calls. This is a key strategy to test the interface at the service layer, not the LLM provider. The same service powers the CLI, Telegram bot, and REST API. Change providers (OpenAI to Anthropic) or add caching by swapping the Assistant</code> implementation. Business logic stays untouched. Speed vs safety</h2> The tradeoff is iteration speed vs execution safety. Put the LLM behind a typed service boundary</a> and you can swap models without touching business logic. Store actions as events instead of overwriting state, and your audit log writes itself. I wrote about why event sourcing pays off</a>. Agentic loops with typed tool results</h2> The tool-use loop needs to handle partial results, retries, and tool failures. Here is the pattern from the warm up exercises you can do on our Agentic Cohort page</a>: from typing import cast import anthropic from anthropic.types import ( MessageParam, TextBlock, ToolUseBlock, ToolResultBlockParam, ) # TOOLS defined with JSON schema for get_exchange_rate(from_currency, to_currency) def answer_with_tools(question: str, client: anthropic.Anthropic) -> str: messages: list[MessageParam] = [{"role": "user", "content": question}] while True: response = client.messages.create( model="claude-sonnet-4-6", max_tokens=512, tools=TOOLS, messages=messages, ) if response.stop_reason == "end_turn": return cast(TextBlock, response.content[0]).text if response.stop_reason != "tool_use": # anything other than tool_use here means no tool calls to process — looping would spin forever raise RuntimeError(f"Unexpected stop reason: {response.stop_reason}") tool_uses = [ cast(ToolUseBlock, b) for b in response.content if b.type == "tool_use" ] tool_results: list[ToolResultBlockParam] = [ { "type": "tool_result", "tool_use_id": b.id, "content": str(get_exchange_rate(cast(dict[str, str], b.input))), } for b in tool_uses ] messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results})</code></pre> The loop continues until stop_reason == "end_turn"</code>. Tool results are typed, preventing schema drift between the tool definition and implementation. In production, wrap get_exchange_rate()</code> in a try/except and return error results to the LLM when tools fail. The agent can retry, pick a different tool, or surface the error to the user. The fix is separation of concerns, typed interfaces, and a well-defined contract between the agent and its tools. Learn agentic AI in Python with 10 small exercises 2026-05-14T00:00:00+00:00 Most "build an AI agent" tutorials hand you a framework and skip the part where you actually understand what it's doing under the hood. When the abstraction breaks, you can't debug it because you never built the layer underneath. Juanjo</a> and I think that gap is worth closing. Yesterday we shipped 10 small browser-based exercises</a> that walk through that layer one pattern at a time (more on how we run them in the browser with Pyodide here</a>). This article is the conceptual journey behind them: how you get from "I can call Claude" to a complete agent loop with a testable architecture and a human-in-the-loop workflow. Each stage builds on the previous one. Stage 1: make a model reply (exercise 1)</h2> Every agent app starts with the same 3-line skeleton. Build a client, call messages.create</code>, read content[0].text</code>. The shape doesn't change much. Only what wraps around it does. import anthropic client = anthropic.Anthropic() msg = client.messages.create( model="claude-sonnet-4-6", max_tokens=256, messages=[{"role": "user", "content": "Say hi"}], ) print(msg.content[0].text)</code></pre> Why content[0].text</code> and not .text</code>? Because content</code> is a list of blocks (text, tool_use, and others). That list is how tool use plugs in later without breaking the response shape. Get this mental model before anything else. Stage 2: make the reply machine-readable (exercises 2, 3)</h2> Raw LLM strings are unreliable. The fix is two paired habits: a specific system prompt that locks the output shape, and a Pydantic model that validates it on the way back in. from pydantic import BaseModel class ExpenseResult(BaseModel): category: str confidence: float result = ExpenseResult.model_validate_json(msg.content[0].text)</code></pre> Treat the system prompt like an API contract. Say "JSON only", show the literal shape, forbid improvisation ("no punctuation, no explanation, nothing else"). The phrase "nothing else" is doing real work; without it, models love to append a friendly sentence that breaks your parser. Stage 3: make it remember (exercise 4)</h2> LLMs don't remember anything. They have no state, no memory, no context beyond the current call. The "conversation" is a fiction we create by sending the whole message history every time. To get a continuous conversation, you keep the list of {"role": ..., "content": ...}</code> dicts and send the whole thing every turn. Append the user message before the call, the assistant reply after. Roles must alternate. history = [] def ask(user_msg): history.append({"role": "user", "content": user_msg}) reply = client.messages.create( model="claude-sonnet-4-6", max_tokens=512, messages=history, ).content[0].text history.append({"role": "assistant", "content": reply}) return reply</code></pre> State lives in your code, not the model. That single realization clears up most of the confusion developers have about context windows and "memory." Stage 4: give the model hands (exercise 5)</h2> Tool use turns a chatbot into something that can act. The loop is dumber than people think: while True: response = client.messages.create(..., tools=TOOLS, messages=messages) if response.stop_reason == "end_turn": return response.content[0].text # else: run the tool the model asked for, append the result, loop again</code></pre> Two gotchas: append the full response.content</code> as the assistant turn (it contains the tool_use</code> blocks the model needs to see), and tool results come back wrapped in a user</code> message, not assistant. Stage 5: make it swappable and testable (exercises 6, 7, 8)</h2> By exercise 6 the chatbot works, but it's also often a highly coupled mess importing external dependencies like anthropic</code> and sqlite3</code> into the business logic. Time for three common patterns, applied to LLM apps: A Protocol</code> for the LLM provider, so tests can pass a MockProvider</code> with a .calls</code> list instead of an API key.</li> A Repository pattern</a> for the persistence layer, so an in-memory dict satisfies the same interface as a database backend.</li> A service layer that accepts both via init</code> and orchestrates: call provider, parse, save, return.</li> </ul> That's the four-layer agent architecture</a>, built piece by piece instead of dumped on you all at once. Stage 6: keep a human in the loop (exercise 9)</h2> When the model returns a confidence score, use it. Above the threshold: auto-accept. Below: show the suggestion and let the user confirm or override. def process(result, threshold=0.8): if result.confidence >= threshold: return result.category answer = input(f"Accept '{result.category}'? (Enter to confirm): ").strip() return answer or result.category</code></pre> Make the accept path the cheapest action (empty input or y</code>). Users pay the manual handling cost only when overriding. This is what separates a trusted assistant from one that quietly mislabels things, and it's the gap between "AI demo" and production-ready workflow</a>. Stage 7: generalize the loop (exercise 10)</h2> The agent is exercise 5 with one change: replace the hardcoded function call with a TOOL_FUNCTIONS[name]</code> lookup. TOOL_FUNCTIONS = { "add": lambda a, b: a + b, "multiply": lambda a, b: a b, } # inside the loop: content = str(TOOL_FUNCTIONS[block.name](**block.input))</code></pre> Now adding a tool is one schema entry plus one dict entry. Swap add</code>/multiply</code> for search_web</code>, query_db</code>, send_email</code> and the loop is identical. Look at agent frameworks under the hood (LangChain, OpenAI Assistants) and you'll see this same pattern. What the journey teaches</h2> Frameworks make sense once you can write the layer underneath. Skip that, and you are stuck the first time the abstraction leaks. After coaching many developers through this, the dividing line is clear: have they ever written the loop themselves? The 10 exercises are deliberately small. The arc matters more than any single one. Once you've done them, "agentic AI" stops being "magic" and starts being a loop, schema, and some patterns you might already know. Try them out: In the browser: pythonagenticai.com/exercises</a>. No install, no API key, no dependencies. Loads fast.</li> Locally: clone the repo</a> and work through them in your IDE.</li> </ol> Coding exercises that run in the browser with Pyodide 2026-05-13T00:00:00+00:00 I've built coding-exercise platforms before (Python</a>, Rust</a>). AWS API Gateway + Lambda, Docker, etc. It works great, but that's a lot of infrastructure to teach someone a four-line function. For our new Agentic AI cohort</a> I wanted a free warm-up: ten short Python exercises that introduce the AI vendor SDK patterns (in this case Anthropic). The hard constraint was that visitors should be able to click "Run" without signing up, without bringing an API key, and without complex third party infrastructure. As this site is built on Cloudflare Pages, that meant an in-browser Python runtime. Enter Pyodide ... Unlike toy Python interpreters, Pyodide</a> runs real CPython compiled to WebAssembly (listen to my interview Elmer Bulthuis</a> why Wasm is cool), which enables broad compatibility with the Python ecosystem, including native extension packages. Getting it working was easy with some Claude Code prototyping; the interesting part was the last 20%. Some of the challenges I faced and how I worked around them. Mocked tests + a stubbed SDK</h2> Every exercise has a solution.py</code> and a test_exercise.py</code>. The tests look like this: from unittest.mock import MagicMock, patch from solution import get_completion def test_returns_text(): mock_client = MagicMock() mock_client.messages.create.return_value.content = [MagicMock(text="Hello, Pythonista!")] with patch("solution.anthropic.Anthropic", return_value=mock_client): assert get_completion("Say hello") == "Hello, Pythonista!"</code></pre> patch("solution.anthropic.Anthropic")</code> replaces the class with a mock for the duration of the with</code> block. The original Anthropic</code> class is never instantiated. Which means the only thing the real SDK contributes is the name anthropic.Anthropic</code> existing somewhere on the Python path. So I don't install it. I write a tiny stub package straight to Pyodide's in-browser filesystem: const ANTHROPIC_INIT = ` class Anthropic: def init(self, *args, **kwargs): pass `; const ANTHROPIC_TYPES = ` class TextBlock: ... class MessageParam: ... class ToolParam: ... class ToolUseBlock: ... `; await pyodide.loadPackage(["pytest", "pydantic"]); pyodide.FS.mkdirTree("/home/pyodide/anthropic"); pyodide.FS.writeFile("/home/pyodide/anthropic/init.py", ANTHROPIC_INIT); pyodide.FS.writeFile("/home/pyodide/anthropic/types.py", ANTHROPIC_TYPES);</code></pre> It's a package, not a single file, because some exercises also do from anthropic.types import TextBlock</code>, which I needed to fix ty</code> type errors. Both modules exist only so the imports resolve. The bodies never execute under test thanks to the mocking. # Inside Pyodide, before running pytest: sys.path.insert(0, "/home/pyodide") # `import anthropic` finds the stub. `patch` replaces it. Tests run.</code></pre> That one decision cuts ~3 seconds and several megabytes off the boot. The real anthropic</code> package pulls in pydantic-core</code>, httpx</code>, httpcore</code>, anyio</code>, sniffio</code>, idna</code>, distro</code>, certifi</code>, typing-extensions</code>. Every byte irrelevant to learning the pattern, because the test never lets the SDK run anyway. If you've read build the data layer before you touch the LLM</a>, this is the same strategy: cut the AI piece down to its smallest shape so the rest of the engineering is more flexible. Lazy-loading the runtime</h2> Pyodide is 5MB+ over the network. I don't want this to load on the homepage, not even on the exercise index page. Even on an exercise page, visitors might skim and leave. So the pyodide.js</code> script tag isn't in the HTML. The page ships a ~250-line runner.js</code> and that script injects Pyodide on demand: // Module-level constants, defined once at the top of runner.js: const PYODIDE_VERSION = "0.27.7"; const PYODIDE_URL = `https://cdn.jsdelivr.net/pyodide/v${PYODIDE_VERSION}/full/`; const PYODIDE_JS_SRI = "sha384-90so5tCKvl0xs9agU29IMKlAVzhfzFX7QO//YxQkRhJG58bBZrFN+2ZTRB026X5X"; async function ensurePyodide() { if (pyodide) return pyodide; if (bootPromise) return bootPromise; bootPromise = (async () => { if (typeof loadPyodide !== "function") { await new Promise((resolve, reject) => { const s = document.createElement("script"); s.src = PYODIDE_URL + "pyodide.js"; s.integrity = PYODIDE_JS_SRI; s.crossOrigin = "anonymous"; s.onload = resolve; s.onerror = () => reject(new Error("Failed to load pyodide.js")); document.head.appendChild(s); }); } pyodide = await loadPyodide({ indexURL: PYODIDE_URL }); await pyodide.loadPackage(["pytest", "pydantic"]); // write the anthropic stub here… return pyodide; })(); return bootPromise; }</code></pre> Two triggers prewarm the runtime before the user clicks Run: cm.on("focus", prewarm); runBtn.addEventListener("mouseenter", prewarm, { once: true });</code></pre> The moment they tab into the editor or hover the button, the 3-second cold start starts ticking. By the time they're done typing, the runtime is usually ready. The cached bootPromise</code> deduplicates: focus and hover both await the same in-flight promise, never two parallel boots. Tracking progress without a backend</h2> No users, no database, no sessions, but I still want: ✓ badges on completed exercises in the list view</li> A progress bar across all ten</li> Draft code that survives a tab close</li> A next step that only appears once all ten are green</li> </ul> One localStorage</code> key holds the whole state: const STORAGE_KEY = "pyai_progress_v1"; // { "first-api-call": { passed: true, code: "...", lastRun: 1736... } }</code></pre> Three operations carry the state: saveCode(slug, code)</code> runs on every CodeMirror change, markPassed(slug)</code> runs when pytest returns 0, and get(slug)</code> reads on page load to restore drafts and badges. In a similar vein, the Solution tab stays locked until the tests pass. The point of an exercise is the struggle, not the answer. Once markPassed(slug)</code> writes to localStorage, it also fires a pyai:passed</code> event, and a separate tabs.js</code> listener flips the solution from <div data-solution-locked></code> to <div data-solution-revealed></code> and lazy-fetches solution.py</code> for a side-by-side compare. No reload. One key, three consumers (runner, list page, solution tab). And the key is versioned: pyai_progress_v1</code>. The day I want to change the shape, I can bump it to _v2</code> and old state cleanly stops loading. No migration code, no schema check. The list page reads the same store on render and walks the DOM: document.querySelectorAll(".exercises-list-item").forEach((item) => { const slug = item.dataset.exerciseSlug; const { passed } = window.PyAIProgress.get(slug); if (passed) item.classList.add("is-passed"); });</code></pre> When passedCount() >= total</code>, a hidden next-step block flips visible. That's the whole mechanism: ten green checks reveal one element, all computed in the browser from that one localStorage</code> key. All static, all local</h2> The whole thing is a static site. Cloudflare serves the HTML, JS, and the synced exercise files. The browser does the rest. Zero extra cost. It scales for free because the load is on the client, not a server. For development, uv runs the end-to-end check</a> with a single command: uv run scripts/e2e_test.py</code></pre> It walks every exercise in headless Chromium, pastes the reference solution, clicks Run, asserts the test suite passes. Ten exercises in ~22 seconds. Anytime the upstream content changes I know in under half a minute whether all ten warm-ups still pass end-to-end. I will save the details of this Playwright end-to-end testing for another article. Starter code</h2> The site this runs on is standalone so I put together a single-file Pyodide starter gist</a> of a mini coding platform experience: code in the browser, click "Run tests", pytest runs against your code, all in the browser. Lazy boot and the Solution/Tests tabs are wired up. The SDK stub and localStorage progress I left out for simplicity, but the core Pyodide integration is there. You can download and build on it if you want to try your hand at a browser-based Python coding experience. Try it out</h2> Back to the 10 exercises, you can try them out here</a>. They cover the basics that show up in the typical production Agentic AI app: a first API call, structured outputs with Pydantic, system prompts, multi-turn state, tool use, then the architectural patterns (Protocol, Repository, Service layer, HITL, the agent loop). One bigger lesson I'm taking away from this: every time I've built a thing server-side over the years, I was usually paying a complexity tax for flexibility I didn't need. Sometimes the right architecture is to push the work to the client, especially where modern browsers and Wasm can handle this performantly and securely. A Race Condition Rust Wouldn't Have Let Me Write 2026-05-12T00:00:00+00:00 A two-agent Python service ran fine in tests. Two concurrent users hit it and one user's search results showed up in the other user's response. The pattern looked safe. The Rust port doesn't compile. The pattern that looked fine</h2> A former student walked me through this one. It's another case of module-level globals biting in concurrent code. The agent in this service had a tool-call budget per query. Five tool calls, then stop. The implementation was the kind of thing I see in a lot of Python codebases: _call_count = 0 _sources: list[str] = [] _lock = threading.Lock() def reset() -> None: global _call_count, _sources with _lock: _call_count = 0 _sources = [] def _check_and_increment() -> int: global _call_count with _lock: if _call_count >= MAX_CALLS: raise ToolCallLimitExceeded() _call_count += 1 return _call_count def _add_source(source: str) -> None: with _lock: _sources.append(source)</code></pre> Every operation locks. Looks safe. Locally it is. The orchestrator runs the Cypher and Mongo agents in parallel via asyncio.gather</code>. A single user's request is fine because the two agents touch different modules. Streamlit puts each session on its own thread, so when two users query at the same time, both threads share the same _call_count</code>, _sources</code>, and _lock</code>. Because Python modules are cached in sys.modules</code>, _call_count</code> isn't just a variable; it's a piece of memory shared by every thread in that process. The race</h2> Two users, each plans four tool calls (within their own five-call budget). Output from the repro: [userA] DONE: made=2 expected=4 | sources: 2 own + 2 foreign [userA] LEAKED foreign sources: ['userB:q0', 'userB:q1'] [userB] DONE: made=3 expected=4 | sources: 3 own + 2 foreign [userB] LEAKED foreign sources: ['userA:q0', 'userA:q1']</code></pre> Two failures at once. The shared counter hits 5 before either user finishes, so each one gets their budget eaten. And get_sources()</code> returns whatever happens to be in the shared list, mixed across users. A timeline makes the leak obvious: T+0 userA: lock, count 0->1, unlock # userA's call 1 of 4 T+1 userB: lock, count 1->2, unlock # userB's call 1 of 4 T+2 userA: lock, count 2->3, unlock # userA's call 2 of 4 T+3 userB: lock, count 3->4, unlock # userB's call 2 of 4 T+4 userA: lock, count 4->5, unlock # userA's call 3 of 4 T+5 userB: lock, sees 5 >= MAX, raises # userB barely started, budget gone</code></pre> userA looks at the counter after two of its own increments and sees 4. "Wait, why is my count already 4?" Because userB has been incrementing the same number. The locks were doing their job. Each individual op is atomic. They don't give per-request isolation, because there is no per-request anything. The data is one global. The fix: contextvars</h2> contextvars.ContextVar</code> was built for this. Each thread, and each asyncio Task, gets its own copy. Default values give every fresh context a clean slate. This matters more in asyncio than in threads. threading.local</code> would catch the threaded case, but every asyncio task runs on the same thread. They all share one threading.local</code>. Picture two tasks on one event loop: task A sets foo = 2</code>, hits await</code>, the loop runs task B, B reads foo</code> and sees 2</code>. There's no isolation, because there's no separate thread to key off. ContextVar</code> keys on context instead, and asyncio.Task</code> copies the context when it's created, so each Task gets its own slot. A's set()</code> is invisible to B even though they're on the same thread. import contextvars _call_count: contextvars.ContextVar[int] = contextvars.ContextVar( "call_count", default=0 ) _sources: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar( "sources", default=() ) def reset() -> None: _call_count.set(0) _sources.set(()) def _check_and_increment() -> int: n = _call_count.get() if n >= MAX_CALLS: raise ToolCallLimitExceeded() _call_count.set(n + 1) return n + 1 def _add_source(source: str) -> None: _sources.set(_sources.get() + (source,))</code></pre> Same demo, fixed: [userA] DONE: made=4 expected=4 | sources: 4 own + 0 foreign [userB] DONE: made=4 expected=4 | sources: 4 own + 0 foreign</code></pre> One subtle point: _sources</code> is a tuple, not a list. With ContextVar(default=[])</code>, every context that hasn't called set()</code> shares the same default list object. A stray cv.get().append(x)</code> would silently leak across contexts, mutating the default that every other context still points at. Tuples make that mistake non-expressible, which is close to Rust where immutable data is the default and mutable state has to be explicitly marked (mut</code>). What would Rust make of this?</h2> If you mostly write Python, the gist of Rust's model is: by default everything is immutable, and the type system tracks who is allowed to read or write each piece of memory. That tracking is what blocks the bug shape from existing. Porting the Python pattern naively, the compiler refuses it four different ways. 1. Module globals can't just exist. The Python _call_count = 0</code> at module scope has no clean Rust equivalent. The closest thing is static mut CALL_COUNT: u32 = 0</code> (static</code> is the Rust word for a true module-level value, mut</code> opts into mutability), and every read or write of it requires an unsafe { ... }</code> block. The compiler is flagging the same risk we hit in Python (module-level mutable state is shared by every thread), but it forces you to acknowledge it in the syntax. You cannot accidentally write the buggy pattern. 2. Two threads cannot share a &mut</code> reference. In Python you pass an object reference into a thread and trust that locks will sort it out at runtime. Rust tracks references at compile time. The rule is aliasing XOR mutability: a value is either readable by many or writable by one, never both at once. &mut T</code> is the "writable by one" case. While it exists, no other reference of any kind is allowed. That single rule is what blocks the Python bug; two threads writing the same counter is exactly the case it forbids. Moving the same Tracker</code> into two thread::spawn</code> closures doesn't compile: error[E0382]: use of moved value</code></pre> The exact aliasing the Python bug relied on, two threads writing to one shared counter, is not a thing the type system will let you express. 3. Shared global state must be wrapped in a lock. Try a global without a lock and the compiler refuses with a different error: error: `Tracker` cannot be shared between threads safely</code></pre> Rust calls this the Sync</code> trait, "safe to access from multiple threads at once". Tracker</code> doesn't qualify because mutating its fields would race. To opt in, you wrap it: Mutex<Tracker></code>, similar to a threading.Lock</code> in Python but with a critical difference. The lock wraps the data, not the operations. In our Python version we had a _lock</code> and three free functions that called it; nothing prevented a fourth function from forgetting. In Rust, the only way to read the counter is to call .lock()</code> on the mutex first, because the counter lives inside it. The bug class of "I forgot to take the lock here" is structurally absent. 4. The idiomatic version doesn't share state at all. The cleanest Rust port doesn't go anywhere near a global. Each thread owns its own Tracker</code> on its own stack: fn run_agent(user_id: String) { let mut tracker = Tracker::new(); for i in 0..CALLS_PER_USER { call_tool(&mut tracker, &user_id, &format!("q{i}")); } }</code></pre> There is no global to reset. The Python reset()</code> race, where userA's reset zeroes userB's mid-flight counter, has no syntax in this design. This is the kind of explicitness that I described in what Rust structs taught me about state ownership</a>: the compiler refuses to let you store state in places it shouldn't live. What Rust doesn't save you from</h2> Worth pinning down two terms that get conflated: Bug class</th> What it is</th> Does Rust prevent it?</th></tr></thead> Data race</td> Two threads touching the same memory without synchronization</td> Yes, won't compile</td></tr> Race condition</td> Logic that breaks because operations interleave in an unexpected order</td> No, even with Arc<Mutex<T>></code></td></tr> </tbody></table> Wrap the tracker in Arc<Mutex<Tracker>></code> and share it across users, and the compiler is satisfied. Two pieces of jargon there, but they map directly onto Python ideas: Arc<T></code> is Python's reference counting, made explicit. When you write data = []</code> in Python and pass it to two threads, both hold the same list. CPython tracks how many references exist and frees it when the count hits zero. That bookkeeping is automatic and invisible. Rust doesn't do it for you by default. When you genuinely want "many owners, last one out cleans up" across threads, you opt in with Arc</code> (Atomic Reference Count). Same model as Python; you just ask for it by name. Mutex<T></code> is threading.Lock</code>, except the lock owns the data. In Python you write: lock = threading.Lock() data = [] # somewhere else, hopefully: with lock: data.append(x)</code></pre> Two separate objects, held together by convention. Nothing stops a caller from touching data</code> without the with</code>. In Rust the data lives inside the mutex: let mutex = Mutex::new(Vec::new()); let mut guard = mutex.lock().unwrap(); guard.push(x);</code></pre> The only way to reach the vec is to call .lock()</code>, which hands back a guard that auto-releases when it goes out of scope. "I forgot the with lock:</code>" doesn't compile. Arc<Mutex<T>></code> is the two combined. Think of it as the Python idiom (threading.Lock(), shared_data)</code> welded into one type, with the compiler enforcing that you never use the data without the lock. No data race. But you have reintroduced the Python bug at a higher level, because userA's reset()</code> still clobbers userB's counter under that same lock. Rust rules out memory unsafety. Per-request isolation is still your design decision. The fix is the same in both languages: one tracker per request. Rust rules out the data-corruption variant at compile time. "Shared mutable state is the root of all evil in concurrent systems." — Edward Kmett </blockquote> The bug here is hard to see in tests. It needs concurrent traffic to fire, and that's the painful kind. Lesson: in Python you can guard against it, but it takes knowledge and discipline. In Rust, the compiler does more of the work: it makes illegal states unrepresentable. The more bugs you can design out of the syntax, the fewer you debug at runtime. Build a daily AI digest in 200 lines of Python (no framework) 2026-05-08T00:00:00+00:00 One command and get the AI stories worth reading today, ranked by an LLM loaded from config. Two hundred lines of Python, no framework, no venv juggling thanks to PEP 723 (inline script metadata). Below are four patterns I explored. We need curation</h2> It's hard to keep up with AI: a lot is happening fast, and most of it is noise. I wanted a script that fans out to my sources concurrently, dedupes, and asks a model to surface what's worth my limited time. Plenty of tools do this already, but it was a good excuse to play with asyncio and Protocols, keeping the LLM provider swappable. Pattern 1: fan out with asyncio.gather, fail soft</h2> IO-bound work is where asyncio</code> works well. Here I parallelize the data gathering work with asyncio.gather</code>. But a single raised exception would cancel the whole batch. That's why I ended up wrapping each coroutine in a try/except that prints the error and returns an empty list: async def safe_fetch(coro: Awaitable[list[Post]], label: str) -> list[Post]: try: return await coro except Exception as e: print(f"# fetch failed ({label}): {e}") return [] async def main() -> None: async with httpx.AsyncClient() as http: tasks = [safe_fetch(fetch_hn(http, q), f"hn:{q}") for q in HN_QUERIES] tasks += [safe_fetch(fetch_reddit(http, s), f"r/{s}") for s in SUBREDDITS] results = await asyncio.gather(tasks)</code></pre> The batch survives a single failure, and the error stays close to its source. If you are on Python 3.11+ and want stricter structured concurrency, asyncio.TaskGroup</code> is the modern default. Here I stuck with gather</code> because the safe_fetch</code> wrapper makes the fail-soft behavior explicit at the call site. A small dedupe_and_filter</code> step (sort by points, drop seen URLs) runs after gather</code> returns. Standard Python, no library needed, but it stops the LLM from scoring the same HN-vs-Reddit story twice. Pattern 2: swap the LLM with a Protocol</h2> I initially hardcoded the AI vendor, but it's nicer to have people use their vendor of choice. Using a Protocol</code> is a nice way to define an interface without needing full inheritance. Both AnthropicRanker</code> and OpenAIRanker</code> have the same shape, so they both satisfy the Ranker</code> contract without needing to inherit from it: class Ranker(Protocol): model: str async def rank(self, digest: str, system: str) -> str: ... class AnthropicRanker: def init(self, api_key: str, model: str) -> None: self.client = AsyncAnthropic(api_key=api_key) self.model = model async def rank(self, digest: str, system: str) -> str: msg = await self.client.messages.create( model=self.model, max_tokens=2048, system=system, messages=[{"role": "user", "content": digest}], ) block = msg.content[0] if not isinstance(block, TextBlock): raise RuntimeError(f"expected text block, got {block.type}") return block.text</code></pre> OpenAIRanker</code> has the same shape but has a different rank implementation. Neither inherits from Ranker</code>. Structural typing means the type checker confirms the contract without inheritance ceremony. I covered the broader pattern in How an AI expense agent is actually structured</a>, where the same idea drives a four-layer architecture (used in our Agentic AI cohort</a>) that keeps the core logic of the agent separate from the LLM provider and the data source. Pattern 3: dispatch with StrEnum + match + assert_never</code></h2> The provider comes from an environment variable. A plain string would let typos through to runtime. StrEnum</code> makes it a typed value, and match</code> with assert_never</code> makes adding a third provider a type error until I handle it: class Provider(StrEnum): ANTHROPIC = "anthropic" OPENAI = "openai" def make_ranker(provider: Provider) -> Ranker: match provider: case Provider.ANTHROPIC: return AnthropicRanker( config("ANTHROPIC_API_KEY"), config("CLAUDE_MODEL", default=DEFAULT_ANTHROPIC_MODEL), ) case Provider.OPENAI: return OpenAIRanker( config("OPENAI_API_KEY"), config("OPENAI_MODEL", default=DEFAULT_OPENAI_MODEL), ) case _: assert_never(provider)</code></pre> Add Provider.GROQ = "groq"</code> tomorrow and ty</code></a> flags it before the script runs: error[type-assertion-failure]: Argument does not have asserted type `Never` --> trend_digest.py:NN:13 | NN | assert_never(provider) | ^^^^^^^^^^^^^--------^ | | | Inferred type of argument is `Literal[Provider.GROQ]` | info: `Never` and `Literal[Provider.GROQ]` are not equivalent types</code></pre> The checker is saying: I thought this case was unreachable (Never</code>), but I found a way to reach it when provider</code> is Provider.GROQ</code>. The closest thing Python has to Rust's exhaustive match</code>, which is what I really like about Rust</a>. Two layers of safety in one line: assert_never</code></a> gives a static error at check time, and at runtime it raises AssertionError</code> if anything ever bypasses the enum. Pattern 4: a new way to share scripts: PEP 723 inline script metadata</h2> The whole script (gist here</a>) ships with a PEP 723 inline script header</a>, and the rank prompt lives as a string constant in the same file. So uv run trend_digest.py</code> resolves dependencies in its own environment, and I can keep the whole thing in one file. I can even run the gist URL directly: $ uv run https://gist.github.com/bbelderbos/af7097f98d5d0e4baee003367b472b56</code></pre> However now I get decouple.UndefinedValueError: REDDIT_USER_AGENT not found</code>, because the script does require some environment variables to be set. The config(...)</code> calls come from python-decouple</a>. It reads environment variables and falls back to a .env</code> file (searched upward from the script's directory), raising UndefinedValueError</code> for anything missing without a default=</code>. There is a small catch when running the gist URL directly: uv</code> downloads the script to a temp location, so a .env</code> in your current directory is not picked up. Two ways around it: # Option A: export them in your shell first export ANTHROPIC_API_KEY=sk-ant-... export REDDIT_USER_AGENT="trend-digest/1.0 by yourname" export PROVIDER=anthropic uv run https://gist.github.com/bbelderbos/af7097f98d5d0e4baee003367b472b56 # Option B: let uv load the file into the subprocess env uv run --env-file .env https://gist.github.com/bbelderbos/af7097f98d5d0e4baee003367b472b56</code></pre> The rank prompt is a string constant at the top of the file (not an external file, to keep it all in one script), so tweak it to your taste: bias toward certain topics, change the output format, or ask for a one-line "why this matters" per story. Set those, and one command from anywhere fetches and ranks today's AI news. Four patterns, one file, no framework. Event Sourcing in Python: Get More Insights Into Your Data 2026-05-05T00:00:00+00:00 Chris May knew about event sourcing for over a decade before he used it for real. Once he tried it in production, he was sold. After hearing him describe the pattern</a>, I can see why, so in this article I'll walk you through what event sourcing is and why it changes what questions your data can answer. Watch on YouTube</a> The Problem: CRUD loses data</h2> To make this tangible imagine two users completing an exercise on the Rust platform</a>. With a CRUD (Create, Read, Update, Delete) approach, you would have a table that records the final state of each user's progress: User starts → submits once → passes. However, this only records the end state. What actually happens in the exercise lifecycle for a user is much richer: User starts → submits (fails) → submits (fails) → submits (fails) → requests hint → submits (passes). In a CRUD app, both rows look identical: user</th> exercise</th> completed</th> score</th></tr></thead> user-a</td> ownership</td> true</td> 10</td></tr> user-b</td> ownership</td> true</td> 10</td></tr> </tbody></table> What you lost: How many attempts did each user need?</li> Which exercises cause the most failures?</li> Do users who request hints complete faster or slower?</li> What is the conversion path from free to paying?</li> </ul> There might even be questions you do not know you have yet. With just CRUD you overwrite data, which you need to make up for with ETL pipelines, bolted on analytics, and guesswork. With event sourcing, you have all the data you need to answer these questions immediately. It just requires a bit more planning upfront, designing the right events and commands. # What CRUD sees: identical end states state_a.total_score == state_b.total_score == 10 # True, indistinguishable # What event sourcing sees: state_a.attempts["ownership"] == 1 # sailed through state_b.attempts["ownership"] == 4 # struggled state_b.hints_used["ownership"] == 1 # needed help</code></pre> (This is from the test suite of a demo app we'll look at later; the full comparison test is test_crud_loses_data_event_sourcing_keeps_it</code>.) What Event Sourcing Actually Is</h2> Essentially with event sourcing you have two types of tables: the event table and the projection tables. The event table is your source of truth: an append-only log of everything that has happened. The projection tables are optimized read models, built by listeners that fire when events arrive. Appends are cheap (like Python list.append</code>), while updates and deletes are not; shifting to append-only means you pay less and keep more. You derive the current state by replaying the events. This also takes advantage of storage being much cheaper than compute. I also like the immutability aspect: events are facts, not mutable state, similar to having to explicitly say mut</code> for mutable variables in Rust. There are no updates and no deletes. A "delete" is just an event: ExerciseCancelled, CartClosed. State is derived by replaying events, never stored directly. This has its origins in DDD (Domain-Driven Design); Greg Young coined the term "event sourcing", though the concept is much older: accounting ledgers, shipping logs, double-entry bookkeeping. Software just needed a name for it. Chris described it well in our conversation: You just keep writing events to a table. The complexity shifts from mutations to queries, which is a better problem to have. </blockquote> Here is what the events look like in our demo app, a coding platform where users complete exercises. Each event captures a specific action that happened, along with relevant data and a timestamp. @dataclass(frozen=True) class ExerciseStarted: stream_id: str exercise: str timestamp: datetime = field(default_factory=_now) @dataclass(frozen=True) class TestsFailed: stream_id: str exercise: str output: str # the exact compiler error: preserved forever timestamp: datetime = field(default_factory=_now)</code></pre> frozen</code> means immutable; once created, you cannot change the event. Rebuilding state from events</h2> As mentioned, state is not stored, it's computed by replaying the event stream. This is a fundamental shift from CRUD, where you store the current state directly. You get an audit trail for free and can replay to any point in time, powerful for debugging and for questions you haven't thought to ask yet. Here is rebuild_state</code>, which takes the event stream and returns the current state: def rebuild_state(events: list[Event]) -> ExerciseState: state = ExerciseState() for event in events: match event: case ExerciseStarted(exercise=ex): state.exercises_in_progress.add(ex) case CodeSubmitted(exercise=ex): state.attempts[ex] = state.attempts.get(ex, 0) + 1 case HintRequested(exercise=ex): state.hints_used[ex] = state.hints_used.get(ex, 0) + 1 case ExerciseCompleted(exercise=ex, points=pts): state.exercises_in_progress.discard(ex) state.exercises_completed[ex] = pts state.total_score += pts return state</code></pre> And here we see another paradigm I really like: functional programming. The rebuild_state</code> function is a pure function; same input, same output, no side effects. This makes it easy to test and debug. Replay the same events, get the same state every time. Commands: validate before you produce events</h2> Events are one half. Commands are the other: requests to change state, validated against the current state before producing events. This is where your business rules live, similar to how I covered FSM transition validation</a>. Chris's example: "no more than one item added per minute"; with event sourcing, you load the stream, check the timestamps, and reject or accept based on that history. With CRUD, you would need a separate audit table. When your boss asks for 30-day performance metrics, the structured history is already there for AI tools to query. Here is how execute_command</code> validates a start request: def execute_command(store: EventStore, , stream_id: str, command: str, **kwargs): events = store.load_stream(stream_id) state = rebuild_state(events) # current reality match command: case "start_exercise": exercise = kwargs["exercise"] if exercise in state.exercises_in_progress: raise CommandError(f"{exercise} already in progress") if exercise in state.exercises_completed: raise CommandError(f"{exercise} already completed") event = ExerciseStarted(stream_id=stream_id, exercise=exercise) ... store.append(event) return event</code></pre> Business rule enforcement is just: load stream → rebuild state → check conditions → append or reject. CQRS: Separating Reads from Writes</h2> Next up is CQRS, which stands for Command Query Responsibility Segregation, a different pattern from event sourcing, but they pair naturally. Chris told a story that made this click for me: "Every now and then we would have to create a report for important people in the organization. Whenever they clicked the button — 'okay, I want the report now' — it would take so many resources to build that report in memory that it slowed down the rest of the application. Users could tell when they did it because all of a sudden the application just slowed down. We didn't use event sourcing at the time, but what we figured out we could do is just update the report on the server in place. And so when the executive said 'okay, I want that report,' it was now a static file download instead of building the whole thing up." </blockquote> That is the projection pattern in a nutshell: the expensive work happens on write, so the read is instant. In our coding platform example we can build two projections from the same event stream: a leaderboard that shows the top scores, and a progress view that shows which exercises a user has completed and which are in progress. Both projections listen to the same events, but they build different read models optimized for their specific queries. def build_leaderboard(store: EventStore) -> list[tuple[str, int]]: scores = Counter() for event in store.all_events(): if isinstance(event, ExerciseCompleted): scores[event.stream_id] += event.points return scores.most_common() def build_progress(store: EventStore, stream_id: str) -> UserProgress: events = store.load_stream(stream_id) state = rebuild_state(events) return UserProgress( completed=set(state.exercises_completed), in_progress=state.exercises_in_progress, )</code></pre> Vertical slice architecture pairs naturally with event sourcing. Every bit of code related to one feature lives in one folder. Independent. No cross-cutting dependencies, no "which file handles this again?" Chris had a dashboard showing 200 items. A user asked for filtering: query by this, sort by that. His first instinct: "This is really going to complicate the code." Then he realized he could just create a new slice. Duplicate the folder, add the filtering logic, run it alongside the original. Iterate with the user until it was right, then swap it in. The old version kept running the whole time. Rust's strong safety guarantees come to mind here. With Rust, you have to be explicit about mutability and ownership. This forces you to think about data flow and side effects in a way that is similar to event sourcing. You are always aware of when you are changing state and when you are not. (Rust has that effect on how you think about code.</a>) There is an AI angle here too. When Chris asks Claude Code to change something in the event sourced code, it reads one folder and produces good results. When it touches the CRUD code, it has to scan the whole codebase to figure out what is involved. This is slower, more token greedy, and more error prone. The vertical slice architecture with event sourcing is much more AI-friendly because it has clear boundaries and less coupling. Gradual adoption works the same way. You do not convert your whole app. Pick one component, define events for it, start a new append table alongside your existing CRUD tables, and try it there. Chris was hesitant for a long time, partly because he could not see how event sourcing could coexist with regular CRUD code. Now he has seen that the two different approaches can actually co-exist. A practical demo</h2> "The only way to learn a new programming language is by writing programs in it" (Dennis Ritchie). Same goes for understanding a new design pattern. The demo below walks you through building an event sourcing system from scratch, test by test, using the coding platform domain example from this article. You will start with a blank slate and end up with a fully functional event sourcing implementation, complete with commands, projections, and a comparison to CRUD. The demo has six levels, each unlocked by making a group of tests pass: Level</th> What you build</th></tr></thead> 1. Events</td> Frozen dataclasses (immutable facts)</td></tr> 2. Event Store</td> Append-only, load by stream</td></tr> 3. State Reconstruction</td> Replay events → current state</td></tr> 4. Commands</td> Validate business rules before appending</td></tr> 5. Projections (CQRS)</td> Leaderboard, progress views</td></tr> 6. Integration</td> Full journey + the CRUD comparison</td></tr> </tbody></table> git clone git@github.com:bbelderbos/event_sourcing_demo.git cd event_sourcing_demo uv sync cp event_sourcing_template.py event_sourcing.py uv run pytest test_event_sourcing.py -v # work through the levels, making the tests pass</code></pre> Work through event_sourcing_template.py</code> top to bottom. Each step has a hint. The tests tell you exactly when you are done. Where to go from here</h2> Start with my conversation with Chris that inspired this article: Chris May on Event Sourcing, Simpler Frontends & AI Workflows</a>. Two more resources Chris recommends: Package: eventsourcing</code></a> by John Bywater: over a decade of active maintenance. Uses base classes and decorators to hide the ceremony. The Event sourcing in 15 minutes</a> video in the docs, starts from scratch with TDD, installing the package, etc.; very approachable. Book: Understanding Event Sourcing</a> by Martin Dilger. Written in Java but with minimal code, easy to follow, but profound. Some patterns are old and do not expire. They just wait for new use cases. I hope you find a use case for this pattern soon, and that Chris and I have helped you get started. Actually, as I was publishing this article, Chris pushed up the first version of his intro event sourcing ebook, check it out here</a>, as well as his latest Talk Python interview</a>. Build the data layer before you touch the LLM 2026-04-29T00:00:00+00:00 Every AI tutorial I've seen opens the same way: client.chat.completions.create(...)</code>. Within ten lines you have a response. Within twenty you feel like you're building something. What you're actually building is a demo. The instinct to reach for the LLM first</h2> It makes sense. The LLM is the interesting part. You want to see it work. So you call the API, print the result, and layer on functionality from there. The problem surfaces when you try to do something real with that result, for example save it to a database, validate it against business rules, test it without paying per call. You have a string from an API and no structure underneath it. In the first week of our Agentic AI cohort</a>, participants don't touch the LLM at all. Instead, they build the data layer: models, enums, repositories, and 29 tests that all pass before a single API call is made. This article shows why that order matters. StrEnum for currencies: compile-time safety over runtime surprises</h2> The app tracks expenses. Expenses have currencies. The obvious approach is a string field. The problem with strings is that "USD"</code>, "usd"</code>, "Us Dollars"</code>, and a typo like "USd"</code> are all valid Python; and all wrong in different ways. StrEnum</code> fixes this: from enum import UNIQUE, StrEnum, verify @verify(UNIQUE) class Currency(StrEnum): USD = "USD" EUR = "EUR" GBP = "GBP" JPY = "JPY" # ... 6 more</code></pre> The @verify(UNIQUE)</code></a> decorator raises at class definition time if any two members share a value. For currency codes that's not a real risk, but it documents intent: these values should be distinct. The decorator turns a convention into a constraint. Because StrEnum</code> members are also strings, they work everywhere strings work (database columns, JSON serialization, comparisons) without any conversion step. SQLModel: one class, two roles</h2> SQLAlchemy handles persistence. Pydantic handles validation. Traditionally you write two separate classes and keep them in sync. SQLModel</code> collapses them into one: from decimal import Decimal from datetime import datetime, timezone from sqlmodel import Field, SQLModel class Expense(SQLModel, table=True): id: int | None = Field(default=None, primary_key=True) amount: Decimal currency: Currency = Field(default=Currency.EUR) description: str | None = None date: datetime = Field(default=datetime.now(timezone.utc)) category_id: int | None = Field(default=None, foreign_key="expensecategory.id") category: ExpenseCategory | None = Relationship(back_populates="expenses")</code></pre> table=True</code> tells SQLModel to also create a database table from this class. The type annotations become both Pydantic validators and SQLAlchemy column definitions. Add an expense with wrong types and Pydantic raises before the database ever sees it. The Decimal</code> type for amount</code> matters too. Floating point arithmetic is not appropriate for money. Decimal("10.50") + Decimal("0.10")</code> gives Decimal("10.60")</code>. 10.50 + 0.10</code> gives 10.600000000000001</code>. The repository pattern: swap implementations without changing the app</h2> The real payoff of a proper data layer is the repository pattern</a>. from abc import ABC, abstractmethod from typing import Sequence class ExpenseRepository(ABC): @abstractmethod def add(self, expense: Expense) -> None: ... @abstractmethod def get(self, expense_id: int) -> Expense | None: ... @abstractmethod def list(self) -> Sequence[Expense]: ... @abstractmethod def delete(self, expense_id: int) -> None: ... # ... more methods</code></pre> The abstract base class defines what a repository can do. Concrete implementations decide how. The app gets two: InMemoryExpenseRepository</code> (a dict) and DBExpenseRepo</code> (SQLite via SQLModel). Tests use the in-memory version: fast, no I/O, no cleanup. The production app uses the database version. The classification service, the CLI, the Telegram bot, they all accept an ExpenseRepository</code> and don't care which one they get. When you add a new interface (an API endpoint, a dashboard), you wire it to the same repository interface you already have. No duplication. No hidden coupling. The abstract class also enforces completeness: class IncompleteRepo(ExpenseRepository): def add(self, expense: Expense) -> None: pass # forgot the other methods repo = IncompleteRepo() # TypeError: Can't instantiate abstract class IncompleteRepo # without an implementation for abstract methods 'delete', 'get', 'list', ...</code></pre> You find out at instantiation, not at runtime when a user tries to list their expenses. Aggregator patterns exist for combining multiple data sources behind a single repository interface. But rolling your own is the point here: once you understand the pattern, the library that wraps it stops being magic. TDD: write the test first</h2> The discipline that makes all of this work is test-driven development. Not "write tests after." Write the test, watch it fail, then write the code that makes it pass. A simple model test: def test_create_expense(db_session): category = ExpenseCategory(name="Transportation") expense = Expense( amount=Decimal(100), currency=Currency.USD, description="Train tickets", date=datetime(2025, 8, 31, 20, 0, 0), category=category, ) db_session.add(category) db_session.add(expense) db_session.commit() assert expense.id is not None assert expense.category == category assert expense.currency == Currency.USD</code></pre> The db_session</code> fixture creates a fresh in-memory SQLite database for each test and tears it down after. Tests are isolated and fast; the full model + repository suite runs in under a second. In practice, the first friction is tooling, not the pattern: one developer ran into the src-layout gotcha directly: pythonpath = ["src"]</code> in pyproject.toml before pytest can even find your code. Pre-commit hooks need wiring, and six dev tools have to coexist before you submit your first PR. Another common discovery is conftest.py</code>: that fixtures can be centralized rather than redefined per test class. One developer skipped it entirely (no shared fixtures, each test class self-contained) and still hit 97% coverage. The discipline of testing at every step, for teaching and code quality both, is non-negotiable. What this foundation buys you</h2> When the LLM returns a classification next week, there's a typed ExpenseCategory</code> to validate it against, a Decimal</code> field to store the amount, and a repository to persist the result. The LLM output is just one more input to a data layer that already knows how to handle it. Without the foundation, you're forever parsing strings from the API and hoping they match whatever your database expects. With it, the LLM integration is a small piece of a well-typed pipeline. That's the switch in mindset this series is built on: the LLM is one component, not the app. The app is the data model, the service layer, the interfaces. Build those first. See how the full agent is structured once the data layer is in place.</a> Vibe Coding is Easy, Owning the Architecture Isn't 2026-04-28T00:00:00+00:00 These days you can prompt Claude to generate a working feature in twenty minutes. File uploads, database queries, API calls; the code appears, it runs, it looks right. But if you've never owned a mature architecture, AI-generated code becomes a liability you don't know how to manage. You don't know how the pieces fit together, what breaks first under load, or how to go from works locally to deployed securely and ready to scale. A developer recently put it well: "I barely write code from scratch anymore. AI can handle a big part of that, incredibly fast. But interestingly, the job hasn’t become easier." </blockquote> A few years ago the trap was tutorial paralysis. With LLMs, it just looks different: the code runs, but you didn't decide how it's structured. The tools have changed, but the problem remains: when we hand over decision-making, whether to tutorials or to LLMs, we keep getting stuck. Before: tutorial hell</h2> Tutorials are good at one thing: showing you that code works. They walk you through syntax in a logical order and give you working code to follow. Automate the Boring Stuff, CS50, a Udemy course, all solid resources. They do what they promise, but it's often biased towards the happy path. What they don't teach: How to break an app idea into features small enough to actually build.</li> Which feature to build first and why.</li> How to structure a project so it doesn't collapse past a thousand lines.</li> How to use Git and GitHub to save your work and work effectively with other developers.</li> </ul> These aren't advanced topics per se. In practice though, they have so much more nuance and ambiguity. The result: someone finishes a Django tutorial, sits down to build something real, and spends two hours stuck on a decision the tutorial never prepared them for. As Mike Tyson once said: "Everybody has a plan until they get punched in the face." </blockquote> That's the blank page syndrome. Every decision has already been made for you in a tutorial. When you open your own project, you feel lost. Now: vibe coding hell</h2> LLMs have made this more pronounced. You can prompt your way to working code faster. But to go from prototype to something real and high quality, people still hit a wall, just differently. Instead of "I cannot replicate the syntax after consuming tutorials," now it is: "I can vibe code but I've never owned an architecture end to end; if it breaks in production, I'm guessing"</li> "I know there are couplings between parts of my system but I don't fully understand the infrastructure beneath them"</li> "I've set up logs, tests, and audits, but I don't feel confident interpreting what they're telling me"</li> "I can't keep one part of the system consistent when another part changes"</li> "Deploying my app to the cloud is still a black box to me, even with AI"</li> </ul> The code runs. But you didn't decide how it's structured, and you can't foresee what breaks when it grows. You're executing without deeper understanding. The gap is the same</h2> Both traps share one root cause: someone else made the decisions. Tutorials gave you syntax and a happy path to follow. Vibe coding with AI gives you code and a design to accept. Neither forced you to decide what to build first, how the data should flow, or what your architecture will cost you in six months. Being deliberate is hard. AI is designed to feel fast, intuitive, and effortless. That pull is System 1 thinking by design. But real architectural ownership requires System 2 thinking: the slow, deliberate, and often frustrating "productive struggle" of weighing trade-offs. When the AI removes that struggle, the knowledge doesn't stick. I see this all the time in coaching: "The hands-on approach made all the difference. Building something real made Rust click in a way that tutorials never could — and honestly, it's made me a better Python developer too." - Vikas Z </blockquote> It's the decision-making muscle we need to keep training to really own the code we write. To better understand System 1 vs 2 thinking, read Thinking Fast and Slow</a>. The solution isn't more prompts</h2> More prompts will make you better at prompting. If the goal is to own what you build, that's not the skill you need. You need to learn how to make decisions about your project, how to structure it, and how to maintain it. Working on your real project with someone who's done it before gives you that. Not abstract lessons, but your actual code, your actual decisions. Feedback on why something will break, how to structure it better, or what to build first and why. Vibe coding is fast at output. But it can't tell you which problem to solve first, why your architecture will hurt in six months, or that you're modeling the whole thing wrong. It also can't ask you why you made that decision</a>, and that question is often where the real learning happens. Vibe coding doesn't have to be a trap; it can be a power tool. But that only happens when you use the AI to augment your decisions rather than replace them. A power user prompts for a feature, but then pauses to ask: 'Why did you choose this pattern?' or 'How does this change our database load?' They use the generation speed to test architectural hypotheses and apply critical thinking. From prompts to software architecture</h2> Start with a problem worth solving. I usually scratch my own itch or look at what people are complaining about in forums. If the problem belongs to someone else and it's real enough, they might pay for it. Don't get bogged down in documentation or jump straight into prompts. Start with the design: How does data flow? What are the main features? Plan before you prompt. If you need help, reach out to me. In one or two sessions you stop prompting and start thinking in architecture, and how to own your project end to end. I give you deep feedback on your code and design, not lessons in the abstract. You learn to make those decisions yourself, and feel confident in them, instead of relying on the model to tell you what to do next. That's 1:1 coaching. Here's what it did for Ryan</a>: "My Python coaching, however, gave me the ability to 'see under the hood.' Because I understand the core principles of Python and Django, I can effectively direct the AI. Without coaching, you're just a passenger; with it, you're the navigator who actually understands the map." </blockquote> Ryan went from building alone to directing AI agents with confidence for a business that now supports his life in the Bahamas. If you're ready to stop being a passenger in your own codebase and start navigating with a map you actually understand, let's talk. From Hobby Code to SaaS to Orchestrating AI Agents 2026-04-20T00:00:00+00:00 Ryan Austin runs a payroll SaaS solution</a> in the Bahamas. He uses AI agents for customer support triage, feature scaffolding, and automated issue resolution. He has even implemented a rating system for issues, allowing agents to autonomously tackle specific tasks based on my available token budget. Four years ago, none of this would have been possible. The gap</h2> In 2021, Ryan had a real business idea and enough Python to be dangerous. He was building alone, with no one to tell him whether his architecture was sound or whether he was creating a hobby project or something that could actually run a business. He didn't know what he didn't know. We did 1:1 coaching together. He shipped his first SaaS MVP. And the foundation he built then is paying off now in ways neither of us anticipated. The foundation</h2> When I asked Ryan what coaching gave him that made the payroll app possible, he was direct: "Delivering this product would have been impossible without that coaching. It provided the necessary space to brainstorm and, more importantly, provided validation from someone who had shipped products at a high level. Coaching didn't just help me execute a plan; it gave me the confidence that my architecture was sound and that the product met a professional standard rather than just being a 'hobby project.'" </blockquote> Later it all started to click: "There were several moments where I initially followed certain patterns simply because I was told they were 'best practices.' The click happened when I stopped just following instructions and began to understand the why behind the architecture. I realized that with a solid structural foundation, the complexity of a system like payroll wasn't an obstacle, but a series of solvable logic problems." </blockquote> Understanding why patterns exist is what makes them useful. Without that, you're following rules you can't adapt when circumstances change. The iOS test</h2> Here's what Ryan told me when I asked about the link between coaching and AI effectiveness: "I've never had coaching for iOS development, and despite having AI tools, I don't feel comfortable building a native app because I lack the fundamental mental model of the folder structures and utilities. My Python coaching, however, gave me the ability to 'see under the hood.' Because I understand the core principles of Python and Django, I can effectively direct the AI. Without coaching, you're just a passenger; with it, you're the navigator who actually understands the map." </blockquote> AI tools take the path of least resistance. Ryan knows his app must stay Content Security Policy compliant because of his previous security audits. He constantly has to remind the AI to avoid inline scripts or styles. If you don't know what good software looks like (e.g. security, modularity, compliance), you'll get something that works today but breaks tomorrow. How Ryan uses AI tools today</h2> His workflows: Customer support: "Payroll is complex, and our support tickets often involve nuanced inquiries about tax calculations or labor law compliance. I use agents to ingest these emails and run tests against the live logic to see if a bug exists or if the system performed as intended. This results in faster, more accurate data-driven responses without breaking my deep-work flow." Feature scaffolding: "I find that structural planning is 80% of the work; the agents handle that heavy lifting, allowing me to drive the 'last mile.' I always stay hands-on for the final implementation because I need to intimately understand how the features I support actually function." Issue triage: He's automated the low-hanging fruit by having agents review GitHub issues, test if bugs still exist, and propose fixes. As said, he rates issues so agents can tackle tasks autonomously based on his available token budget. Ryan can now build onboarding and integration tools that were stuck in the backlog. The TDD inversion</h2> One habit from coaching stuck harder than any other: "In the early days of AI, the models weren't quite reliable enough to write production code, but they were decent at code review. Today, the roles have flipped: I'm writing and reading less 'raw' code, but I am reading tests more than ever. You always emphasized that code will eventually break and bugs are inevitable. Consequently, the tests have become my 'source of truth.' By focusing on the test suite, I can verify the AI's output without getting bogged down in every line of implementation." </blockquote> Nearly all his prompts now begin with "Using a TDD approach..." and end with a request to review the tests before any code is written. He calls it a "short-circuit manager's review", ensuring the logic is sound before committing to the build. But there's a catch: "I recently experienced a session where an agent modified some essential tax calculations. Because the agent was also responsible for the tests, it updated the test suite to match its own logical error, creating a 'self-validating' mistake. The tests passed, but the math was wrong. I only caught the error during a manual walkthrough because I am intimately familiar with the expected Bahamian tax outputs." </blockquote> If you let AI write the logic and the proof of that logic simultaneously, you risk a closed loop of misinformation. You must remain the ultimate authority on expected outcomes. Practical guardrails</h2> Aggressive prompt editing: "If an agent veers off course, I don't keep chatting; I stop and edit the initial prompt immediately. It's a massive time and token saver." </li> Variable reasoning: Toggle reasoning levels based on stakes. High-stakes payroll logic gets maximum reasoning; UI tweaks get minimal settings. </li> Decision fatigue is real: "Using agents is cognitively taxing. It reminds me of the 'innovation tokens' concept: we only have so much mental bandwidth per day. Agentic workflows require dozens of high-level decisions every hour. I've found that 'resting' the context, and myself, results in much better output." </li> The trap of easy: "The friction of development has decreased so significantly that it's tempting to over-engineer or add 'nice-to-have' features simply because they are now easy to implement. However, every line of code, even AI-generated code, is a future liability. Just because it's easier to build doesn't mean it belongs in your product. Maintaining a lean, intentional roadmap is harder when the 'cost' of building feels like it has dropped to zero." </li> Context files: Ryan maintains an agents.md file that defines his system's context and standards, allowing new agents to get to work instantly without a long onboarding chat. </li> </ul> The compounding</h2> Ryan's point generalizes: our tolerance for "good enough" is vanishing. Because agents make refactoring and profiling so much faster, we no longer have an excuse for slow queries or poor performance. We can tackle those painful refactors in a fraction of the time. But the developers who benefit most are the ones who know what good looks like before the agent starts writing. The foundational skills compound. Ryan went from building alone with no validation to directing AI agents with confidence. The coaching didn't teach him AI tools, they didn't even exist yet. It taught him the fundamentals that make any tool useful. He went from passenger to a navigator who actually understands the map. How an AI expense agent is actually structured 2026-04-15T00:00:00+00:00 Most AI agent tutorials show you the LLM call. They skip the part where you have to do something useful with the response. An LLM call is just a function call that returns structured data. Once you see it that way, the rest of the architecture follows using patterns you already know. This is the architecture we use for the expense AI agent program. Four layers, all standard Python. Layer 1: Abstract the provider with a Protocol</h2> The first decision is how to talk to the LLM. You could hardcode openai.chat.completions.create(...)</code> everywhere, but then you are coupled to one vendor. Swap to Groq, Anthropic, or a local model later, you have to update it in many places. Instead, define a Protocol</code> that describes what any LLM provider must do: from decimal import Decimal from typing import Protocol, Sequence class Assistant(Protocol): def completion(self, messages: list[dict[str, str]]) -> ExpenseCategorizationResponse: ... def calculate_cost(self, prompt_tokens: int, completion_tokens: int) -> Decimal: ... def get_available_models(self) -> Sequence[str]: ...</code></pre> Now OpenAIAssistant</code> and GroqAssistant</code> satisfy this protocol without inheriting from it. Your service layer accepts Assistant</code>, the concrete provider is injected at startup. Swap it in tests without touching anything else. This is called structural typing and the type checker enforces the contract for you; duck typing with safety. Layer 2: Return a Pydantic model, not a string</h2> The LLM returns text. You want typed data. Pydantic bridges this gap. OpenAI's structured outputs API accepts a Pydantic model directly and returns an instance of it: from decimal import Decimal from pydantic import BaseModel, Field class ExpenseCategorizationResponse(BaseModel): category: str total_amount: Decimal currency: Currency confidence: float cost: Decimal comments: str | None = None</code></pre>response = client.beta.chat.completions.parse( model="gpt-4o-mini", messages=messages, response_format=ExpenseCategorizationResponse, ) result: ExpenseCategorizationResponse = response.choices[0].message.parsed # result.total_amount is Decimal("5.50"), not a string # result.currency is Currency.USD, not "USD"</code></pre> No regex. No JSON parsing. No float(response.split("$")[1])</code> hacks. Pydantic validates types on the way in, coerces where it can, and raises a clear error when the model returns something unexpected. If you've worked with FastAPI, you've already seen what Pydantic does for request/response models. The same applies here. The LLM also returns a confidence</code> score for each classification. You'll use it in layer 4. Layer 3: The service layer coordinates everything</h2> Without a service layer, classification logic ends up copy-pasted into the CLI, the Telegram bot, and the REST API. The service layer centralizes it: from dataclasses import dataclass @dataclass class ClassificationService: assistant: Assistant expense_repo: ExpenseRepository | None = None def classify( self, expense_description: str, persist: bool = False, ) -> ClassificationResult: messages = self._build_messages(expense_description) response = self.assistant.completion(messages) if persist and self.expense_repo: self._persist_expense(expense_description, response) return ClassificationResult(response=response, persisted=persist)</code></pre> The assistant</code> is injected, not created inside. The expense_repo</code> is optional so you can classify without writing to storage (useful for preview UI, dry runs, and testing). Testing this service is straightforward: pass in a mock Assistant</code> that returns a known ExpenseCategorizationResponse</code>. No real API call. No .env</code> file. from unittest.mock import create_autospec def test_classify_calls_assistant(): mock_assistant = create_autospec(Assistant) mock_assistant.completion.return_value = ExpenseCategorizationResponse( category="Food", total_amount=Decimal("5.50"), currency=Currency.USD, confidence=0.95, cost=Decimal("0.001"), ) service = ClassificationService(assistant=mock_assistant) result = service.classify("Coffee at Starbucks $5.50") assert result.response.category == "Food" assert result.persisted is False</code></pre> Note that, using create_autospec</code> instead of MagicMock</code> directly, means the test will fail if you refactor the Assistant</code> protocol but forget to update the mock. See Jan Giacomelli's tip here</a>. Layer 4: Human-in-the-loop catches what the model gets wrong</h2> "Uber to airport" → Transport. Correct. "Uber Eats dinner" → Transport (85% confidence). Wrong. The LLM is often right. Not always. Human-in-the-loop (HITL) is how you catch what the model gets wrong. It proposes, you decide. When confidence drops below a threshold, the Telegram bot presents an inline keyboard with the AI's suggestion highlighted: def build_category_confirmation_keyboard( suggested_category: str, all_categories: list[str], ) -> InlineKeyboardMarkup: buttons = [] for category in all_categories: text = f">> {category} <<" if category == suggested_category else category buttons.append(InlineKeyboardButton(text=text, callback_data=f"cat:{category}")) ...</code></pre> The user sees [>> Transport <<] [Food] [Shopping]</code>. One tap to confirm or correct. When they select, the service persists with confidence=1.0</code>: def persist_with_category(self, expense_description: str, category_name: str, response: ExpenseCategorizationResponse) -> Expense: expense = Expense( amount=response.total_amount, currency=response.currency, description=expense_description, category=ExpenseCategory(category_name), confidence=Decimal("1.0"), # human confirmed ) self._expense_repo.add(expense) return expense</code></pre> A human-confirmed label is by definition correct. The stored confidence should reflect that. Python AI agent architecture: four layers</h2> The four layers map to Python patterns you already know: Layer</th> Pattern</th> What it gives you</th></tr></thead> Provider</td> Protocol</code></td> Swap LLM backends without touching business logic</td></tr> Response</td> Pydantic BaseModel</code></td> Typed, validated data from unstructured text</td></tr> Coordinator</td> Service + dependency injection</td> Testable logic, reused across CLI/bot/API</td></tr> Verification</td> HITL</td> Human oversight where model confidence is low</td></tr> </tbody></table> None of this is new. Service layers and dependency injection are standard patterns</a>. Protocols give you duck typing with type safety: structural contracts that don't require inheritance. Pydantic is the de facto standard for structured data in modern Python APIs. And HITL is a form flow where AI proposes and humans confirm. Simple in concept, but the feedback loop is what makes it powerful. What makes it feel like "AI development" is that the LLM sits in the middle. The code around it is just Python. The patterns are the same; the capabilities are new. This is the project structure from our Expense AI Agent cohort</a> that Juan José Expósito</a> and I are running. Build Your First MCP Server: Code Tips in Claude and Slack 2026-04-13T00:00:00+00:00 MCP (Model Context Protocol</a>) is the standard connector between AI clients and external tools. I built a server from scratch in 78 lines. Result: my coding tips repo, searchable inside Claude Code and a Slack slash command, using the same server. Before MCP, connecting an AI assistant to your own data meant one-off integrations (a custom plugin, a pasted prompt). MCP defines a shared protocol, so you write the server once and any compliant client can use it. A server exposes three kinds of things: Tools: functions Claude can call (search, get a specific tip, list categories)</li> Resources: data Claude can browse (a full index of all tips)</li> Prompts: suggested workflows (pre-written instructions for common tasks)</li> </ul> You don't need all three. For a tips collection, tools are enough. Here's how Claude Code connects to an MCP server: ┌─────────────────────────────────────────────────────┐ │ Claude Code │ │ You type: "search my tips for generators" │ └──────────────────────┬──────────────────────────────┘ │ MCP protocol (JSON-RPC / stdio) ▼ ┌─────────────────────────────────────────────────────┐ │ MCP Server (server.py) │ │ │ │ Tools: search_tips(query) │ │ get_tip(tip_id) │ │ Resource: tips://all │ │ │ │ Data: ~/code/bobcodesit/notes/.md (240 files) │ └─────────────────────────────────────────────────────┘</code></pre> Claude Code launches the server as a subprocess and communicates over stdin/stdout. Claude discovers your tools at startup and calls them whenever the conversation warrants it. The data: my Python tip collection</h2> My bobcodesit</code> repo</a> is a good candidate. It holds 240 markdown files in the notes/</code> subfolder. Each one looks like this: # divmod built-in Ever needed both integer division and remainder? Use Python's `divmod()` built-in — it returns both in one go. ```python >>> minutes, seconds = divmod(133, 60) >>> minutes, seconds (2, 13) ``` #built-ins</code></pre> The structure is consistent: title on line one, body in the middle, one or more #hashtags</code> at the end. That predictability makes parsing trivial. Building the MCP server</h2> First, clone the tips repo so the notes are on your machine: # assuming a code directory in your home folder cd ~/code git clone git@github.com:bbelderbos/bobcodesit.git</code></pre> Then set up the MCP server project: mkdir tips-mcp && cd tips-mcp uv init uv add mcp</code></pre> Create server.py</code>: import json import random import re from functools import cache from pathlib import Path from mcp.server.fastmcp import FastMCP NOTES_DIR = Path.home() / "code/bobcodesit/notes" mcp = FastMCP("code-tips") @cache def load_notes() -> list[dict]: notes = [] for path in sorted(NOTES_DIR.glob(".md")): lines = path.read_text().strip().splitlines() title = lines[0].lstrip("# ").strip() tag_line = lines[-1] if lines[-1].startswith("#") else "" tags = [t.lstrip("#") for t in tag_line.split() if t.startswith("#")] content_lines = lines[1:-1] if tag_line else lines[1:] body = "\n".join(content_lines).strip() notes.append({"id": path.stem, "title": title, "tags": tags, "body": body}) return notes @mcp.tool() def search_tips(query: str, limit: int = 10) -> list[dict]: """Search code tips by keyword. Pass a single short keyword (e.g. 'generator', 'decorator', 'contextmanager'), not a full sentence. Returns up to `limit` matching tips with id, title, and tags. Use get_tip to fetch the full body of a specific tip.""" pattern = re.compile(rf"\b{re.escape(query.lower())}\b") results = [ {"id": n["id"], "title": n["title"], "tags": n["tags"]} for n in load_notes() if pattern.search(n["title"].lower()) or pattern.search(n["body"].lower()) or any(pattern.search(t) for t in n["tags"]) ] return results[:limit] @mcp.tool() def random_tip(tag: str = "") -> dict: """Return a random tip, optionally filtered by tag (e.g. 'built-ins', 'generators', 'decorators').""" notes = load_notes() if tag: t = tag.lower().lstrip("#") notes = [n for n in notes if any(t in note_tag for note_tag in n["tags"])] if not notes: return {"error": f"No tips found for tag: {tag}"} return random.choice(notes) @mcp.tool() def get_tip(tip_id: str) -> dict: """Get the full content of a single tip by its filename (without .md).""" path = NOTES_DIR / f"{tip_id}.md" if not path.exists(): return {"error": f"Tip not found: {tip_id}"} lines = path.read_text().strip().splitlines() return { "id": tip_id, "title": lines[0].lstrip("# ").strip(), "body": "\n".join(lines[1:]).strip(), } @mcp.resource("tips://all") def all_tips() -> str: """Browse all tips: IDs, titles, and tags.""" return json.dumps( [{"id": n["id"], "title": n["title"], "tags": n["tags"]} for n in load_notes()], indent=2, ) if name == "main": mcp.run()</code></pre> @cache</code> from functools</code> memoises the result of the first call and returns it on every subsequent call, no global variable needed. The notes are only read from disk once per server lifetime. A few design decisions worth explaining: search_tips</code> returns only id</code>, title</code>, and tags</code>, no body. Claude uses this summary list to decide which tip is most relevant, then calls get_tip</code> to fetch the full content. Returning bodies for all matches at once can easily overflow the context window (a broad query like "ast" matches dozens of tips that all contain the substring). The two-phase pattern (search for summaries, then fetch the one you need) keeps responses small and Claude's reasoning sharp. </li> random_tip</code> accepts an optional tag filter, so "give me a random built-in tip" becomes a direct call to random_tip(tag="built-ins")</code> rather than a broad search. Word-boundary matching in search_tips</code> (using re.compile(r"\bquery\b")</code>) prevents false positives where short queries match as substrings inside unrelated words. </li> Tool results go to Claude, not directly to the user. Claude reads the structured dicts and decides how to present them. That's why the tools return raw data rather than formatted strings. Claude handles the formatting for the conversation context. </li> </ul> Test it standalone before wiring it up: uv run python server.py</code></pre> No output is good. This means the server is waiting for a client to connect over stdio. Register with Claude Code</h2> You can add the MCP server with: claude mcp add --scope user code-tips -- uv --project /path/to/tips-mcp run python /path/to/tips-mcp/server.py</code></pre> --scope user</code> registers it in ~/.claude.json</code> so it's available across all your projects. For a per-project setup instead, add a .mcp.json</code> file in the project root: { "mcpServers": { "code-tips": { "type": "stdio", "command": "uv", "args": ["--project", "/path/to/tips-mcp", "run", "python", "/path/to/tips-mcp/server.py"] } } }</code></pre> Restart Claude Code. You'll now see the server listed: ❯ /mcp ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Manage MCP servers 4 servers User MCPs (/Users/pybob/.claude.json) ❯ code-tips · ✔ connected claude.ai ... ...</code></pre> Let's search for a tip: ❯ Search my tips for anything about generators ⏺ code-tips - search_tips (MCP)(query: "generator") ⎿ { "result": [ { … +63 lines (ctrl+o to expand) ⏺ Found 5 tips directly tagged #generators: 1. pathlib list files in directory — using yield from with .glob() 2. itertools.count — infinite iterator with optional step 3. split a sequence into pairs — generator function + itertools.batched() (3.12+) 4. slicing generators — can't subscript a generator; use itertools.islice() 5. Logging memory usage — shows list vs generator memory difference with psutil Plus a couple of tangential mentions (classes tip mentions generators as an alternative; sets tip uses a generator expression with set.intersection). ❯ all_tips ⏺ readMcpResource(Read resource "tips://all" from server "code-tips") ⎿ { "contents": [ { … +321 lines (ctrl+o to expand) ⏺ You have 218 tips in total. Here's a breakdown by tag frequency from what's there: Most common topics: - zen — 15+ tips - built-ins — 15+ tips - strings — 12+ tips - collections — 8 tips - itertools — 7 tips - dataclasses — 6 tips - django — 6 tips - pytest — 5 tips - generators — 5 tips - sets, regex, pathlib, exceptions, oop, datetime — 4–5 each - debugging, packaging, typehints, functools, classes, dicts, decorators — 3–4 each Newest tips (2026): - Sending email with Resend SDK - StrEnum and auto() - Rust ? operator - Context manager for transaction rollback - Dataclass config flags - Binary search with bisect - Mermaid Diagrams in GitHub READMEs - Reliable CI Benchmarks with pytest-codspeed ❯ get_tip ⏺ Which tip would you like to retrieve? Give me the title or ID (e.g. 20240711112100 for "slicing generators"). ❯ StrEnum and auto() ⏺ code-tips - get_tip (MCP)(tip_id: "20260410104036") ⏺ StrEnum and auto() (Python 3.11+) If you're still using standard Enum for states, categories, or API keys, you're missing out. Wins: - Direct comparison: a StrEnum member is a string — no more if status.value == "active": - Auto-naming: auto() assigns the lowercase variable name as the value automatically - Serialization: works with json.dumps() without custom encoders # Old way — forced to use .value from enum import Enum class Status(Enum): PENDING = "pending" if Status.PENDING == "pending": # False! pass print(Status.PENDING.value) # "pending" # Modern way from enum import StrEnum, auto class Status(StrEnum): PENDING = auto() # "pending" ACTIVE = auto() # "active" if Status.PENDING == "pending": # True! print("It's a match!") print(f"Current status: {Status.ACTIVE}") # "active" — no .value needed Useful for state machines, API clients, and configs. #enums</code></pre> Let's try one more: ❯ search for zen of python tips ⏺ code-tips - search_tips (MCP)(query: "zen") ⎿ {"result":[{"id":"20220904170128","title":"Regex replacements and counting","tags":["regex"],"body":"Here is ho w to replace all vowels from a text while keeping a count of the number of replacements made:\n\n```\n>>> impor t re\n>>> vowels = 'aeiou'\n>>> text = \"\"\"\n... The Zen of Python, by Tim Peters\n...\n... Beautiful is bett … +179 lines (ctrl+o to expand) ⏺ You have quite a few Zen of Python tips. Here's a summary: --- Directly tagged #zen: 1. zip() strict keyword arg — zip(..., strict=True) surfaces mismatched-length bugs. "Errors should never pass silently." 2. How to capture the Zen of Python — Uses contextlib.redirect_stdout + codecs to grab import this output silently. 3. Sparse is better than dense — Code formatting with whitespace for readability. 4. Beautiful is better than ugly — Idiomatic sum(data.values()) vs verbose loops. 5. Readability counts — Meaningful variable names. 6. Special cases aren't special enough — Consistent interfaces via capitalize(), len(), iteration protocols. 7. Although practicality beats purity — When except Exception or *args/**kwargs is justified. 8. Errors should never pass silently — Proper exception handling with logging + typed return float | None. 9. Unless explicitly silenced — contextlib.suppress for intentional error suppression. 10. In the face of ambiguity, refuse the temptation to guess — Python's explicit type errors vs JS coercion. 11. There should be one obvious way — enumerate, f-strings, Counter, dict.get, etc. 12. Now is better than never — Ship early, drop perfectionism. --- That's a solid series — looks like you worked through the Zen aphorisms one by one. Want to do anything with these?</code></pre>Integrate with Slack</h2> I want to create a Slack slash command that searches my tips. When I type /tip generators</code>, the bot calls search_tips("generator")</code> on the MCP server, gets the results, and responds with a summary of the most relevant tips. Because we're not using Claude Code here, we interface through the API directly. The MCP server is still in the middle of the reasoning loop though: Slack slack_bot.py server.py (tools) │ │ │ │ "/tip generators" │ │ │──────────────────────→│ │ │ │ Claude API call │ │ │ (tools: search_tips, │ │ │ get_tip) │ │ │──────────────────────→ │ │ │ search_tips("generator") │ │←───────────────────────│ │ │ [5 matching tips] │ │ │ │ │ "Here are 5 tips..." │ │ │←──────────────────────│ │</code></pre> Claude receives your Slack message, decides which tools to call, gets the results, and writes the response. Same reasoning engine, different interface. Configure the Slack App</h3> Create the App: Go to api.slack.com/apps</a> and create an app "From Scratch". Call it "Code Tips Bot" and select a workspace.</li> Enable Socket Mode: In the left sidebar, click Socket Mode and toggle it on. You'll be prompted to generate an App-Level Token (starts with xapp-</code>). This opens an outbound WebSocket to Slack, no public URL or ngrok needed.</li> Add Permissions: Under OAuth & Permissions → Scopes, add the commands</code> bot scope. No chat:write</code> needed; responses use the response_url</code> from the slash command payload.</li> Create the Slash Command: Go to Slash Commands and create /tip</code>. Socket Mode means no Request URL is needed.</li> Install & Connect: Click Install App to generate your Bot User OAuth Token (starts with xoxb-</code>).</li> </ul> Slack bot code</h3> First add the dependencies: uv add slack-bolt python-decouple anthropic</code></pre> You'll also need Claude API credits. Add a payment method at console.anthropic.com</a> and grab an API key. A few dollars is enough to get started. The bot uses the mcp</code> package (already installed) as a client to connect to your running MCP server over stdio, the same protocol Claude Code uses. All the connection state (the event loop, the session, the tool list) lives in an MCPClient</code> class that starts the server once at bot startup and keeps it alive. Add slack_bot.py</code>: import asyncio import json import threading from pathlib import Path from anthropic import AsyncAnthropic from anthropic.types import MessageParam, TextBlock, ToolParam, ToolResultBlockParam, ToolUseBlock from decouple import config from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client from mcp.types import TextContent from slack_bolt import App from slack_bolt.adapter.socket_mode import SocketModeHandler SERVER_PATH = Path(file).parent / "server.py" anthropic = AsyncAnthropic(api_key=config("ANTHROPIC_API_KEY")) app = App(token=config("SLACK_BOT_TOKEN")) SYSTEM_PROMPT = ( "Format all responses for Slack mrkdwn: " "use bold not bold, _italic_ (underscores) for italics, " "`code` for inline code, no ## headers, no markdown tables, " "use bullet points instead." ) class MCPClient: def init(self) -> None: self.loop = asyncio.new_event_loop() self.session: ClientSession | None = None self.tools: list[ToolParam] = [] self._ready = threading.Event() self._lock = asyncio.Lock() threading.Thread(target=lambda: self.loop.run_until_complete(self._start()), daemon=True).start() self._ready.wait() async def _start(self) -> None: server_params = StdioServerParameters( command="uv", args=["--project", str(SERVER_PATH.parent), "run", "python", str(SERVER_PATH)], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools_result = await session.list_tools() self.tools = [ ToolParam( name=t.name, description=t.description or "", input_schema=t.inputSchema, ) for t in tools_result.tools ] self.session = session self._ready.set() await asyncio.Event().wait() # keep server alive for the bot's lifetime async def ask(self, query: str) -> str: async with self._lock: return await self._ask(query) async def _ask(self, query: str) -> str: messages: list[MessageParam] = [{"role": "user", "content": query}] for _ in range(10): response = await anthropic.messages.create( model="claude-haiku-4-5-20251001", max_tokens=1024, tools=self.tools, messages=messages, system=SYSTEM_PROMPT, ) if response.stop_reason == "end_turn": return next( (block.text for block in response.content if isinstance(block, TextBlock)), "No response.", ) assert self.session is not None tool_results: list[ToolResultBlockParam] = [] for block in response.content: if isinstance(block, ToolUseBlock): result = await self.session.call_tool(block.name, block.input) tool_results.append(ToolResultBlockParam( type="tool_result", tool_use_id=block.id, content=json.dumps([c.text for c in result.content if isinstance(c, TextContent)]), )) if not tool_results: break messages.append(MessageParam(role="assistant", content=response.content)) messages.append(MessageParam(role="user", content=tool_results)) return "No response after maximum tool-use iterations." mcp = MCPClient() @app.command("/tip") def handle_tip(ack, command, respond): ack() query = command["text"].strip() if not query: respond("Usage: `/tip <question>` e.g. `/tip how do generators work?`") return respond(f"> `/tip {query}`\n\n_Searching bobcodesit tips..._") def process(): try: future = asyncio.run_coroutine_threadsafe(mcp.ask(query), mcp.loop) respond(future.result(timeout=60)) except Exception as e: respond(f"Error: {e}") threading.Thread(target=process).start() if name == "main": SocketModeHandler(app, config("SLACK_APP_TOKEN")).start()</code></pre> MCPClient.init</code> spins up a dedicated background thread running a private event loop, calls _start</code> on it, then blocks on _ready</code> until the server is initialised. From that point the stdio_client</code> and ClientSession</code> context managers stay open. The server process and its in-memory note cache persist for the bot's lifetime. Each /tip</code> command submits mcp.ask</code> to that loop with run_coroutine_threadsafe</code> and waits for the result. A few beginner traps I fell into: Use Haiku, not Opus, for tool-use loops. Opus is powerful but expensive and slow. For a search task over local notes, Haiku is more than capable and roughly 20× cheaper. Each /tip</code> invocation makes multiple API calls (one per tool-use round), so model choice compounds quickly. </li> Guard against empty tool results. If Claude finishes a round without calling any tools but also doesn't return stop_reason: "end_turn"</code>, appending an empty content</code> list to the messages causes a 400 Bad Request: user messages must have non-empty content</code>. The if not tool_results: break</code> guard handles this. </li> Cache your data loading. The naive version of load_notes()</code> reads all 240 files from disk on every tool call. Since the MCP server process stays alive for the duration of a session, decorating load_notes</code> with @cache</code> means the files are only read once, making subsequent calls much faster. </li> Spawning a new server per request defeats the cache. The first version called stdio_client</code> inside ask_claude</code>, spawning a fresh process on every /tip</code> command, so the _cache</code> in server.py</code> never warmed up. Claude Code keeps the server alive across your whole session; the bot has to do that explicitly. MCPClient</code> is the fix. Beyond the cache: each uv run python server.py</code> launch costs ~1-2 seconds of subprocess startup before any actual work happens. The persistent MCPClient</code> eliminates that overhead on every request, even for a single user. </li> Protect the session from concurrent commands. The MCP session over stdio is a single pipe. If two /tip</code> commands arrive at the same time, both try to read and write on it simultaneously and the responses get scrambled. An asyncio.Lock</code> in MCPClient</code> serialises calls so only one runs at a time. Unlikely in a private bot, but the right default. </li> Keep tool responses small. The first version of search_tips</code> returned full tip bodies for every match. A query like "ast" matched 30+ tips and returned 150k characters, enough to hit MCP's token limit outright and fill Claude's context window even when it didn't. The fix is a two-phase design: search returns id/title/tags only, get_tip</code> fetches the body for the specific tip Claude wants to show. Also use word-boundary matching (\bquery\b</code>) so short tokens don't match as substrings inside unrelated words. </li> </ul> To run it, add the Slack tokens and Anthropic API key to an .env</code> file in the project root. Also add .env to .gitignore so you don't accidentally commit secrets. SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... ANTHROPIC_API_KEY=sk-ant-...</code></pre> Run it: uv run python slack_bot.py</code></pre> The /tip how do generators save memory?</code> slash command in Slack gets a real Claude response, not a keyword match. Claude reads the tips and explains the relevant ones in context. Using respond()</code> instead of say()</code> keeps the reply only visible to you, so it works in any channel without spamming everyone. How to write a good decorator? /tip how to write a good decorator</code> in Slack: Check for tips about context managers with /tip context manager</code>: Check if there is any library recommendation for article scraping with /tip web scraping</code>: In case there is no matching tip, the bot still responds with a general answer based on the knowledge in the tips collection, rather than just saying "no results", for example: Why bother with MCP at all?</h2> You could point Claude at your notes directory directly, or grep in a shell script, or have the Slack bot do its own keyword matching. The difference is the reasoning layer. When /tip how do generators save memory?</code> arrives in Slack, Claude decides whether to call search_tips</code>, which query to use, whether to follow up with get_tip</code> for the best result, and how to synthesize the answer. That's not a grep, it's the same reasoning you get in Claude Code, reachable from a different interface. The MCP server is also a reusable contract. Claude Code uses it natively over stdio. Claude Desktop uses it. Any other MCP-compliant client uses it without any new integration code. Slack isn't an MCP client, so the bot bridges the gap with the Claude API. It still connects to the same MCP server via stdio, fetching tools dynamically rather than duplicating them. As more tools adopt MCP (editors, terminals, agents), your server becomes more valuable without changes on your end. The MCP server is 78 lines. The Slack bot is another 120. My 240 tips are now searchable from two places I work in every day. In both cases Claude is doing the reasoning through the same MCP server, not a keyword grep or a duplicated tool definition. Full source on GitHub: bbelderbos/mcp_tips_example</a>. What would you use MCP for? A personal knowledge base, a code snippet library, a recipe collection? Let me know when you build one. What Rust Structs Taught Me About State Ownership 2026-04-08T00:00:00+00:00 Python classes bundle data and behavior together. Rust separates them, and that separation taught me to ask a question I'd been skipping for years. Python classes</h2> In Python, when you need to track state across multiple operations, you reach for a class: class Tokenizer: def init(self, input: str): self.chars = list(input) self.position = 0 def advance(self): ch = self.chars[self.position] self.position += 1 return ch def peek(self): return self.chars[self.position]</code></pre> Every method receives self</code> and can read or mutate any field. The language doesn't distinguish between methods that observe state and methods that change it. That's convenient, but it hides something important. Rust separates data from behavior</h2> In Rust, you define data with struct</code> and behavior with impl</code>: struct Tokenizer { chars: Vec<char>, position: usize, } impl Tokenizer { fn advance(&mut self) -> Option<char> { let ch = self.chars.get(self.position).copied(); self.position += 1; ch } fn peek(&self) -> Option<char> { self.chars.get(self.position).copied() // char is Copy, returns a value not a reference } }</code></pre> Notice the difference in method signatures. advance</code> takes &mut self</code> because it modifies position</code>. peek</code> takes &self</code> because it only reads. This isn't a style choice. The compiler enforces it. What Rust is explicit about</h2> In Python, I never asked "does this method mutate state?" I'd look at the implementation if I cared. In Rust, the signature tells you before you read a single line of the method body. &self</code> means: this method borrows the struct immutably. You can call it while other code holds a reference. It's safe to call in parallel (unlike Python, where you'd need manual locking to guarantee the same). &mut self</code> means: this method borrows the struct mutably. No other code can access the struct while this method runs. It's changing something. Python doesn't model this distinction at all. You can write an observer method that quietly mutates state, and nothing stops you. In Rust, the signature is a contract: &self</code> means you cannot mutate, full stop. Why this matters</h2> When I converted a function-based parser to use structs, I had to answer questions Python never made me ask: Which methods need mutable access? Only advance</code>. The position changes.</li> Which methods are pure observers? peek</code> and is_at_end</code>. They look but don't touch.</li> What data does the struct actually need? Just the input and position. Nothing else.</li> </ul> In Python, I might have added a self._current_token</code> field to signal "internal only", but that's still at the class level, so any method can modify it indistinguishably. Rust's borrow checker would have forced me to think harder about whether that state was necessary. What Rust structs give you is clarity. Data lives in one place. Behavior lives in another. And every method signature tells you exactly how it interacts with the data. Python's flexibility is often what you want, but Rust takes explicit is better than implicit further, and it changes the questions you ask back in Python. Does this method need to mutate state, or am I just being lazy? Could this be a standalone function? Am I bundling state because it's necessary, or because self.x</code> is easy to type? Rust's struct + impl separation isn't about syntax. It's about forcing you to decide who owns data and who can change it. In our Rust cohort, this is often the first moment people think carefully about how data actually flows through a program. In Python, these decisions are often implicit. In Rust, they're in the signatures and the compiler enforces them. That explicitness is uncomfortable at first. Then it becomes a habit. Then you start applying it even when the compiler isn't watching. Build a Finite State Machine in Python 2026-04-07T00:00:00+00:00 Libraries like transitions</a> make using finite state machines (FSMs) easy. Maybe too easy. You wire up states, transitions, and callbacks, and it 'just' works. But when you need to customize behavior, debug a stuck workflow, or explain to a teammate why a transition silently failed, you need a deeper understanding. And what better way than building a simple FSM from scratch? I've used the transitions</code> library in production for years to manage content workflows: draft to review to approved to published, with callbacks that assign reviewers and send notifications. It looks something like this: from enum import StrEnum, auto from transitions import Machine class States(StrEnum): DRAFT = auto() REVIEW = auto() APPROVED = auto() PUBLISHED = auto() TRANSITIONS = [ {"trigger": "submit", "source": States.DRAFT, "dest": States.REVIEW, "after": "assign_reviewer"}, {"trigger": "approve", "source": States.REVIEW, "dest": States.APPROVED, "after": "notify_author"}, {"trigger": "publish", "source": States.APPROVED, "dest": States.PUBLISHED, "after": "clear_tasks"}, ] Machine(model=model, states=list(States), transitions=TRANSITIONS, initial=States.DRAFT)</code></pre> StrEnum</code> + auto()</code> gives each member a value equal to its lowercased name (States.DRAFT == "draft"</code>). Because StrEnum</code> instances are strings, you can use them directly as dict keys, in comparisons, and as arguments; no .value</code> unwrapping needed. </blockquote> Powerful. But what's actually happening when you call model.submit()</code>? How does it validate transitions, run guards, fire callbacks? Building one from scratch answers those questions and makes you better at using (and extending) the library. Build a simple FSM from scratch</h2> Let's model a GitHub pull request (PR) workflow, something every developer knows. Here's the state diagram: PRs move through states with rules: You can't merge without approval,</li> Closed PRs can reopen,</li> The merged state is terminal.</li> </ul> Start with the transition map. This is the core data structure: a dictionary where each state maps to its set of valid next states. TRANSITIONS = { "draft": {"open", "closed"}, "open": {"changes_requested", "approved", "closed"}, "changes_requested": {"open", "closed"}, "approved": {"merged", "open", "closed"}, "merged": set(), # terminal "closed": {"open"}, }</code></pre> An empty set means terminal, done. This makes it easy to check, relying on Python's truthiness: if not transitions[state]:</code> means "this state has no valid next states." Next, let's build the StateMachine</code> class. I often say: start with functions, but FSMs bundle state and behavior in a way that makes classes the right fit. sm.current</code>, sm.transition("open")</code>, sm.can_transition("merged")</code>: a clean interface that only a class gives you. The transition map is passed in rather than hardcoded. This keeps the class reusable for any workflow and makes the dependency explicit. class InvalidTransition(Exception): pass class StateMachine: def init(self, initial, transitions: dict[str, set[str]], *, guards=None, hooks=None, context=None): self._state = initial self._transitions = transitions self._guards = guards if guards is not None else [] self._hooks = hooks if hooks is not None else {} self._context = context if context is not None else {} self._history: list[tuple[str, str]] = [] @property def current(self): return self._state @property def context(self): return self._context @property def history(self): return list(self._history) def can_transition(self, to): return to in self._transitions.get(self._state, set()) def transition(self, to): if not self.can_transition(to): raise InvalidTransition(f"Cannot go from {self._state} to {to}") errors = [] for guard in self._guards: if not guard(self, to): errors.append(guard.name) if errors: raise InvalidTransition( f"Cannot go from {self._state} to {to} " f"due to failed guards: {', '.join(errors)}" ) previous = self._state self._state = to self._history.append((previous, to)) for hook in self._hooks.get(to, []): hook(self, previous, to)</code></pre> Less than 50 lines. Let's break down the four extension points: Guards are functions that say "not yet." They receive the machine and target state, returning a boolean. All must pass. For example, a PR can't be merged without approvals:</li> </ol> def require_approval(sm, to): return to != "merged" or sm.context.get("approvals", 0) >= 1 sm = StateMachine("draft", TRANSITIONS, guards=[require_approval], context={"approvals": 0}) sm.transition("open") sm.transition("approved") sm.transition("merged") # raises InvalidTransition: failed guard</code></pre> Hooks fire after a successful transition. They're callbacks keyed by destination state:</li> </ol> def notify_reviewers(sm, from_state, to_state): sm.context["notifications"] = sm.context.get("notifications", 0) + 1 sm = StateMachine("draft", TRANSITIONS, hooks={"open": [notify_reviewers]}) sm.transition("open") assert sm.context["notifications"] == 1</code></pre> Context is a dict guards and hooks can read and write: approval counts, assigned reviewers, timestamps. Not needed in this example, but in production it's where you track everything that doesn't belong in state itself. </li> History is an append-only audit trail. Every successful transition records (from_state, to_state)</code>. Failed guard names surface in the InvalidTransition</code> exception message. No instance state needed, no risk of stale data between calls. </li> </ol> The full implementation with tests is available as a GitHub Gist</a>, a single file you can run with uvx pytest fsm.py -v</code>. The functional alternative</h2> If you don't need guards, hooks, or history, Python's match/case</code> can offer a simpler state dispatcher: def next_state(current: str, action: str) -> str: match (current, action): case ("draft", "open"): return "open" case ("open", "approve"): return "approved" case ("approved", "merge"): return "merged" case _: raise ValueError(f"Invalid: {action} from {current}")</code></pre> Clean and readable for 3-4 states. But it doesn't scale. Add guards, hooks, and history, and it gets messy fast. That's when a class-based FSM is the better choice. FSMs enforce business logic around valid system transitions. No more "how did this PR end up merged without approval?" A simple implementation can be a class of less than 100 lines of code, and it makes you understand the patterns behind FSMs: the transition map, guards, hooks, context, and history. If you want to use another level of abstraction, the transitions</code> library is great. The next time you see a workflow with states and rules, implement your own FSM. How to Migrate Users Between Django Apps on Login 2026-04-06T00:00:00+00:00 Migrating users between two live Django apps sounds like it needs one big migration script and a maintenance window. It turns out it doesn't. As a user on the Pybites platform, you never had to do anything: just log in as usual, and if you had a v1 account, your premium status, exercise progress, and token balances were automatically imported into the new platform. No scripts, no maintenance window, just a series of API calls triggered by the login signal. Here's how it worked. The Problem: Two Platforms, One User Base</h2> October 2024 the original Pybites platform, codechalleng.es (v1), showed its age, the UX was no longer up to standards. My first intuition was to go full API and build a separate front-end, but it soon became clear this would add a lot of complexity. This was a major Django code base with many business logic decisions and hundreds of users with history. Complex user profiles; from free to exercise token access based to full premium access. So I built a new Django app (v2) with a clean slate, migrating the exercises and meta data, and using Tailwind CSS + HTMX for a much better front-end experience. However, I needed to migrate users from v1 to v2. Users data: premium status, completed/attempted bites, token balances (earned/unlocked). Ideally this transition would happen without asking them to do anything. The constraint that shaped everything</h3> What worked really well was deciding early on to use separate databases and treat them as separate apps. This meant I had to solve the migration problem, but it also meant I had a clean slate to design the v2 data model without worrying about legacy constraints. And users could try v2 before making the switch, which made the transition smoother. The naive approach and why I rejected it</h3> When you're dealing with a massive migration, the first instinct is to write a big batch script: export all users from v1, transform the data, import into v2. But this has some downsides: The data can become stale between export and import, especially if users are active during the migration window</li> Timing issues: you have to choose a cutover date, and any users who log in after the export but before the import will have inconsistent data</li> </ul> Instead I chose to migrate lazily, on first login. Each user migrated themselves when they logged in, one at a time. The data was always fresh, there was no need for a maintenance window. Users who never came back simply never migrated, no harm done. The "Lazy migration upon login" design</h2> This is the high-level flow I came up with: User logs in on V2 ↓ Django user_logged_in signal fires ↓ Check: v1_migration_done == False? ↓ POST V1:/api/v2/token/ ← prove you're the same user ↓ JWT access token returned ↓ PUT V1:/api/v2/bite-user-data/ (Bearer token) ↓ V1 returns: {profile, bite_tokens, bite_saves} V1 marks user inactive ↓ V2 imports data → marks v1_migration_done = True</code></pre> The key part was this Django signal handler in v2's accounts/models.py</code>: @receiver(user_logged_in) def social_account_logged_in_handler(request, user, kwargs): if settings.V1_MIGRATION_DISABLED: return if user.profile.v1_migration_done: return social = user.socialaccount_set.first() provider = social.provider # "github" or "google" uid = social.uid payload = {"provider": provider, "uid": uid} # ... POST to v1, get JWT, PUT for data, import</code></pre> There are three early returns here. The first two are shown above; the third bails out if the user has no social accounts, which brings us to the email/password case below. I ended up introducing an environment variable to temporarily re-open the migration process after the grace period expired. The v1_migration_done</code> flag is the most important one; it ensures that once a user has migrated, they won't try to do it again on every login. Email/password users needed a different hook. The signal only fired after a successful login, but these users didn't exist in v2 yet, so they never got that far. Instead, I overrode form_invalid</code> in a custom LoginView</code>. When login fails and the user doesn't exist in v2 yet, instead of immediately showing an error, it tries v1 with the same credentials. If v1 confirms them, it creates the account and imports the data on the spot. class CustomLoginView(LoginView): def form_invalid(self, form): if settings.V1_MIGRATION_DISABLED: return super().form_invalid(form) email = self.request.POST.get("login") password = self.request.POST.get("password") # user not in v2 yet, try v1 with the same credentials response = httpx.post(f"{settings.PYBITES_CC_API_URL}/token/", ...) if response.status_code == 200: user = User.objects.create_user(...) import_user_v1_data_into_v2(user, ...) login(self.request, user, ...) return super().form_valid(form) return super().form_invalid(form)</code></pre> Both paths call the same V1 endpoint, which returns: # V1: api_v2/views.py { "profile": { "premium": bool, "newbie_access": bool }, "bite_tokens": { "earned": int, "unlocked_bite_ids": [42, 77, 203, ...] }, "bite_saves": [ {"bite_id": int, "code": str, "ok": bool, "added": "2023-..."} ] } # Side effect: V1 user set inactive after successful data retrieval</code></pre> Error Handling</h2> I had to handle 3 failure modes gracefully, since this was happening on login and I didn't want to break the user experience: User not found on V1 (404): User never had a v1 account; mark migration done, move on, no noise</li> Auth failure: Log to a new MigrationErrorLog</code> table, email admin, show neutral message to user</li> Data import exception: Wrapped in transaction.atomic()</code>; rollback on any failure, log it</li> </ol> There was one silent failure that shows how the devil is always in the details. The Google provider name was different between v1 and v2 ("google-oauth2" vs "google"), causing every Google user to fail to match, which was a silent failure since the migration just wouldn't happen, but the user would never know why. The fix was simply to add a normalizer in the v1 API endpoint: if provider == "google": return "google-oauth2"</code> What made it work in practice</h2> The idempotency flag (v1_migration_done</code>) is the simplest, most important thing. Without it, every login retries the migration.</li> Lazy migration meant we could run both platforms in parallel for weeks, no hard cutover date</li> Using the user's own OAuth credential as the auth mechanism meant no separate credential store, no "import token" to manage</li> V1 side effect (inactivating the user) was intentional and semantic: PUT, not GET, because it changes state</li> </ul> Users migrated on first login with no manual steps, no downtime, no stale data, and almost no support tickets. When we shut down the process, users would still reach out asking why their progress didn't migrate, but that was expected and was easily handled by toggling the V1_MIGRATION_DISABLED</code> flag to allow exceptional late migrations (which also shows the power of the 12 Factor App's recommendation of separating config from code</a>). What's a challenging migration you've had to do, and how did you approach it? Reach out and let me know. How Modern Python Tooling Simplified My Setup 2026-03-30T00:00:00+00:00 A few years ago, setting up a Python project meant wiring together six or seven tools before writing a single line of code. Today that list has shrunk dramatically. The tools are faster, more ergonomic, and far simpler to configure. The Old Python Tooling Setup</h2> A "proper" Python project circa 2021 looked something like this: pyenv install 3.10.4 # manage Python versions python -m venv .venv # create virtualenv pip install -e ".[dev]" # install deps (slow) black . # format isort . # sort imports (separate tool!) flake8 . # lint mypy . # type check</code></pre> Seven commands, seven config sections. Each tool had its own config format. Sometimes tools needed a compatibility setting so they wouldn't step on each other's toes (for example black</code> and isort</code>). flake8</code> didn't support pyproject.toml</code> without a plugin. Pre-commit required much config just to wire these together. And releasing to PyPI? Even after pyproject.toml simplified packaging, you still need to choose a build backend like Hatchling, Flit, or Setuptools, and then, unless your tool has a built-in uploader, use Twine to publish. uv, ruff, and ty: The Modern Stack</h2> Nowadays we can just do: uv init myproject && cd myproject uv add fastapi sqlmodel uv add --dev ruff ty pytest uv run ruff check uv run ruff format uv run ty check uv run pytest</code></pre> uv</code> handles Python versions, virtualenvs, dependency resolution, locking, and building. If you've written Rust, this will feel familiar: uv</code> brings the cargo</code> experience to Python. ruff</code> replaces black, isort, and flake8 in a single binary. ty</code> is the new type checker from the same Astral team and is much faster than mypy. Here's a real pyproject.toml</code> from one of my projects</a>: [project] name = "mdweaver" version = "0.2.0" requires-python = ">=3.12" dependencies = [ "markdown>=3.5", "pygments>=2.17", "weasyprint>=60.0", ] [dependency-groups] dev = ["pytest>=8.0", "pytest-cov>=4.0", "ruff>=0.9.0", "tbump>=6.11.0", "ty>=0.0.12"] [build-system] requires = ["uv_build>=0.10.8,<0.11.0"] build-backend = "uv_build"</code></pre> No [tool.black]</code>, no [tool.isort]</code>, no [tool.mypy]</code>. Ruff works with sensible defaults. One file configures everything. And notice the build backend: uv_build</code> means even packaging is handled by uv, no separate hatchling</code> or setuptools</code> dependency needed. Pre-commit Shrinks Too</h2> The pre-commit config across my projects went from 30+ lines (black, isort, flake8, mypy hooks) to this: repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.6.4 hooks: - id: ruff args: [--fix, --extend-select=I] - id: ruff-format</code></pre> One tool does what three used to. And if you want the hook runner itself to be fast too, prek</a> is a Rust-based drop-in replacement for pre-commit. Same .pre-commit-config.yaml</code> config, faster execution. Releasing Got Simple Too</h2> Shipping a package to PyPI used to mean a build backend, twine upload</code>, and API token management. Now I use tbump</code> (ok this is a separate tool) and trusted publishing</a>. $ uv run tbump 0.2.0 :: Bumping from 0.1.0 to 0.2.0 => Would patch these files - pyproject.toml:3 version = "0.1.0" + pyproject.toml:3 version = "0.2.0" => Would run these git commands $ git add --update $ git commit --message chore: bump version to 0.2.0 $ git tag --annotate --message v0.2.0 v0.2.0 $ git push --atomic origin main v0.2.0 :: Looking good? (y/N) > y</code></pre> One command bumps the version, commits, tags, and pushes. The tag triggers a GitHub Action</a> that runs lint, tests, uv build</code>, and publishes to PyPI. No API tokens to manage, no twine. I learned this workflow from Automate Python package releases</a>, worth reading if you publish packages. A Note on Maturity</h2> Back to the Astral stack. These tools are still young: ty</code> is in beta at the time of writing. The pace of development is fast, and they already work well for most projects. Since switching to uv I've not looked back. Resources</h2> The Python Developer Tooling Handbook</a> has many useful short guides and tips, a resource to watch. I spoke with creator Charlie Marsh on the Pybites Podcast about the design decisions behind these tools: #175: Charlie Marsh on Ruff, uv and designing fast + ergonomic Python tooling</a></li> #199: Charlie Marsh on ty, uv, and the Python tooling renaissance</a></li> </ul> If you're still wiring together six tools to start a Python project, try this stack for your next one. The setup time alone will convince you. The Repository Pattern: Swap Data Sources in One Line 2026-03-27T00:00:00+00:00 Your live data source just broke. The API provider changed their auth overnight, no warning, no migration path. Now your entire app is blocked. When the live feed dies</h2> I'm coaching a developer building an F1 live race dashboard. The app streams driver positions in real time via Server-Sent (SSE) Events, using Datastar. The original plan was to use OpenF1's MQTT feed. Then, one day, F1 locked down their SignalR stream so this feed broke overnight. No warning, no migration path. If the app had been hardwired to that one data source, development would have stopped cold. If your code is coupled to one source, you inherit all of its instability. The fix: abstract your data source behind an interface. This allows you to swap implementations without touching your app code. This is the repository pattern. Define the contract</h2> Start with an abstract base class. Keep it minimal: just the methods your app actually calls. from abc import ABC, abstractmethod from dataclasses import dataclass @dataclass class Driver: name: str number: int team: str @dataclass class Position: driver_name: str driver_number: int position: int change: int = 0 class RaceDataSource(ABC): @abstractmethod async def get_positions(self, session_key: str) -> list[Position]: ... @abstractmethod async def get_drivers(self, session_key: str) -> list[Driver]: ...</code></pre> This is your contract. Every data source returns the same types. Your app code never knows or cares where the data comes from. (For a deeper dive into the pattern itself, the Cosmic Python</a> chapter on repositories is excellent.) One honest caveat on naming: a textbook repository abstracts a collection of domain objects you persist to and query (add</code>, get</code>, list</code>), like the expense repository</a> I cover elsewhere. This live, read-only feed is strictly closer to a gateway, an abstraction over an external system. I use "repository" here in the looser, everyday sense of a swappable data-source boundary; the swap mechanics are identical either way. ABC vs Protocol: An ABC enforces the contract through inheritance. Subclasses must implement the abstract methods or they fail at instantiation. Python's typing.Protocol</code> offers an alternative: structural subtyping. A class satisfies the protocol if it has the right methods, no inheritance required. For this example, ABC works well because we control all implementations. Protocol shines when you want third-party code to conform to your interface without inheriting from your base class. Build the implementations</h2> After the OpenF1 breakage, we evaluated alternatives. Sportmonks turned out to be the most reliable option: REST-based, 10-15 second latency, and it handles the SignalR complexity on their end. class SportmonksDataSource(RaceDataSource): async def get_positions(self, session_key: str) -> list[Position]: async with httpx.AsyncClient() as client: resp = await client.get( f"{BASE_URL}/fixtures/{session_key}/positions", headers={"Authorization": f"Bearer {self.api_key}"}, ) data = resp.json() return [Position(p) for p in data["positions"]] async def get_drivers(self, session_key: str) -> list[Driver]: async with httpx.AsyncClient() as client: resp = await client.get( f"{BASE_URL}/fixtures/{session_key}/drivers", headers={"Authorization": f"Bearer {self.api_key}"}, ) data = resp.json() return [Driver(**d) for d in data["drivers"]]</code></pre> But F1 races happen on weekends. Development happens anytime. You can't iterate on a live dashboard without live-shaped data. So we built a fake that simulates a race from recorded data: class FakeDataSource(RaceDataSource): def init(self, data_file: Path, delay_ms: int = 100): self.delay_ms = delay_ms drivers = self._load_drivers(data_file) self.simulator = RaceSimulator(drivers=drivers) async def get_positions(self, session_key: str) -> list[Position]: self.simulator.tick() return self.simulator.get_current_positions() async def get_drivers(self, session_key: str) -> list[Driver]: return self.simulator.drivers</code></pre> Notice that FakeDataSource</code> has an init</code> while the ABC doesn't. That's intentional: the ABC defines the contract (which methods your app can call), not how each implementation is constructed. Each data source needs different setup (file paths, API keys, simulators) and no super().init()</code> is needed because the base class has no state. The RaceSimulator</code> randomly swaps adjacent driver positions every few seconds. The dashboard looks alive even without a real race. You can develop the UI, test the SSE streaming, and demo to stakeholders, all without a live event. Wire it up with a factory</h2> A factory function selects the right implementation at startup based on an environment variable. We use the python-decouple package to read from .env</code> files, but you could use any config system. from decouple import config def get_data_source() -> RaceDataSource: source_type = config("DATA_SOURCE", default="fake") if source_type == "fake": return FakeDataSource( data_file=Path("data/replay.json"), delay_ms=config("FAKE_DELAY_MS", default=100, cast=int), ) elif source_type == "sportmonks": return SportmonksDataSource() else: raise ValueError(f"Unknown data source: {source_type}")</code></pre> And for local development, I have this in my .env</code>: # Development DATA_SOURCE=fake FAKE_DELAY_MS=100 # Race day (swap the above) # DATA_SOURCE=sportmonks # API_KEY=your_sportmonks_api_key</code></pre> The FastAPI endpoint stays the same regardless: @app.get("/live/stream") async def live_endpoint( request: Request, session_key: str, data_source: RaceDataSource = Depends(get_data_source), ): async def stream(): while True: positions = await data_source.get_positions(session_key) yield SSE.patch_elements(render_positions(positions)) await asyncio.sleep(SLEEP_INTERVAL) return DatastarResponse(stream())</code></pre> Same endpoint, same rendering code, same SSE streaming. The only thing that changes is where the positions come from. Why not just mock?</h2> Mocks verify that your code calls the right methods with the right arguments. They don't verify that your app works with real-shaped data. A fake implementation exercises the same code paths as the real one. Your SSE rendering, your position sorting, your lap counter, all running against data that looks like production. And unlike mocks, you can actually see it in action. Open the dashboard UI and watch fake drivers swap positions. It feels real, even if it's not. This is genuinely useful for development and demos. Adding a third source is now trivial</h2> When OpenF1 eventually comes back, or a new provider appears, you add one class and one elif</code>. No endpoint changes, no rendering changes, no test rewiring. That's the payoff: the pattern absorbs instability so your application code doesn't have to. The repository pattern isn't an abstract architecture concept. It's what kept a developer I'm coaching shipping features the week their data source died. Get the abstraction right early and external instability becomes a config change, not a rewrite. Learning Rust Made Me a Better Python Developer 2026-03-23T00:00:00+00:00 You might be writing Python that silently mutates data it shouldn't, swallows exceptions it shouldn't, and relies on type annotations as suggestions rather than contracts. Not because you're careless, because Python lets you. Rust doesn't. And six months of having a compiler refuse to let me move on changed how I write Python in ways no linter had managed before. Rust Is Already in Your Stack</h2> You're probably using Rust without knowing it. Polars is the faster Pandas alternative. Ruff replaced flake8, isort, and black in a single tool. Uv</a> now handles virtual environments, package installation, and Python versions, replacing five separate tools. Then there's Pydantic. Version 2 rebuilt its validation core in Rust and became 17 times faster. You still write Python. You still uv add pydantic</code>. But the performance-critical path runs compiled Rust code. Python for orchestration, Rust for speed. That's why the two languages aren't competitors. They're partners. PyO3 makes it straightforward to write Rust that exposes a Python API. You don't need to learn Rust to benefit from these tools, but understanding what's happening underneath changes how you think about your own code. Ownership Taught Me Data Flow</h2> In Python, you pass objects around without thinking about who owns them. A function can receive a list, mutate it, and the caller's data changes. Nobody asked permission. def process_items(items: list[str]) -> list[str]: items.append("extra") # mutates the caller's list return items</code></pre> In Rust, you have to be explicit about this. Does the function borrow the data or take ownership? Can it mutate? The compiler won't let you leave this ambiguous. Now when I write Python, I ask myself more often: does this function own the right to mutate the caller's data? The answer is usually no. So I return a new list instead of mutating the input: def process_items(items: list[str]) -> list[str]: return [*items, "extra"] # returns a new list</code></pre> This eliminates an entire class of bugs where mutation leaks across function boundaries. Result Types Taught Me Error Handling</h2> Python lets you ignore exceptions. A function can raise anything at any time, and if you don't catch it, your program might crash at runtime. Thinking about failure paths upfront comes down to your experience and discipline. Rust's Result<T, E></code> makes the choice explicit: this function can succeed with T</code> or fail with E</code>. You must handle both before the compiler lets you proceed. I can't port Result</code> to Python literally, but the mindset transfers. Instead of: def get_user(user_id: int) -> User: response = client.get(f"/users/{user_id}") return User(response.json()) # what if this fails?</code></pre> I now make failure explicit in the return type: def get_user(user_id: int) -> User | None: response = client.get(f"/users/{user_id}") if response.status_code == 404: return None response.raise_for_status() return User(response.json())</code></pre>The Compiler Won't Let You Move On</h2> Rust's compiler is famously strict, but because of that, also famously helpful. "Fighting the borrow checker" is a phrase you commonly hear from people learning Rust. But this "fight" teaches you so much: about data flow, lifetimes, who is responsible for what. In Python, a type checker warning is a suggestion. You can ignore it and ship. In Rust, the code doesn't compile. There's no "I'll fix that later." That changes your relationship with tooling. After months of a compiler that refuses to let you proceed with a half-understood problem, you stop treating ty</code> diagnostics as optional. Your Python toolchain becomes an approximation of Rust's compiler feedback loop. Pattern Matching Taught Me to Think in Cases</h2> Rust's match</code> is exhaustive. You handle every variant of an enum, or it won't compile. Add a new variant six months later? The compiler finds every match</code> that needs updating. Python has match</code> since 3.10, but it doesn't enforce exhaustiveness. You can leave out a case and nothing warns you. Rust taught me to ask: what are all the states this can be in? Am I handling each one? This applies beyond match</code> statements. Kobzol's article "Writing Python like it's Rust"</a> captures it well: model your states explicitly, make invalid states unrepresentable. Use small named types instead of dict[str, Any]</code>. Prefer Header | Payload | Trailer</code> over a string field that could be anything. We can do all of this in Python, but Rust's compiler trains the instinct. You Don't Need Rust to Apply This</h2> Python's type system can approximate a lot of this. Advanced type hints, Protocol</code>, TypeVar</code>, union types, match</code> statements. Pair those with a type checker (ty</code> or mypy</code>), and you catch a lot of what Rust catches at compile time. But there's a difference between knowing you should handle edge cases and having a compiler that forces you to do so. Rust builds that reflex. You develop a new instinct for Python. The AI Angle</h2> When you direct an AI to write code, vague thinking produces vague output. "Add error handling" gets you something that compiles and looks reasonable but silently swallows the failure cases you didn't think to name. Rust trains you to think about those cases upfront and that precision transfers directly to how you prompt and how you review what comes back. Rust trains that precision. Ownership, explicit errors, exhaustive matching. These aren't Rust-specific concepts, they're a way of thinking about what your code is actually doing. Once that thinking is a reflex, your AI prompts get tighter, your reviews of AI output get sharper, and you catch the places where the model glossed over a failure path. Key Takeaways</h2> Ownership thinking prevents mutation bugs. Ask "who owns this data?" before mutating it.</li> Model failure in the return type. User | None</code> communicates more than a docstring that says "may raise."</li> Treat your toolchain as a compiler. ty</code> warnings aren't suggestions if you stop treating them that way.</li> Think in cases. If a value has three states, handle three states.</li> You don't need to write Rust at work. The mindset transfer alone is worth the investment.</li> </ul> Resources</h2> I documented my early Rust learning journey at rsbit.es</a>. Try the intro exercises on the Rust Platform</a> to get a feel for the language. Related Pybites Podcast episodes: #169: Bridging Python and Rust: An Interview with PyO3 Maintainer David Hewitt</a></li> #218: Why Python developers are learning Rust</a></li> </ul> Rust doesn't replace Python for me, but learning it gave me a stricter lens to look at Python through. Same language, fewer surprises.

Bob Belderbos | Automation consulting and developer coaching - python

My bookkeeping runs on code now. AI only reads the PDFs.

Ship Your First Python App: a Free Course on the Local Dev Workflow

Protocol or ABC? Designing a pluggable provider interface

Why Rust makes you import a trait to use its methods

How Libraries Run Rust Inside Python (with PyO3)

The four steps from Rust to import</h2> Getting Rust code into Python takes four steps:</p>

Why Learn to Code If AI Can Code? 6 Reasons

Database-Driven RBAC with FastAPI and Azure Entra ID

5 design patterns used in my new habit tracker app

Why does Alembic need an import you never use?

Unsubscribe links without a login: Django signing

Guardrails Protect Your Codebase. What Protects Your Judgment?

Learning New Skills in the AI Era (vBrownBag)

One Core, Two Interfaces, No Rewrites

Lazy loading</h2> I am a proponent of imports at the top, but lazy loading is a serious performance consideration. It's coming in 3.15:</p>

Ask the Canon: Semantic Search Without a Vector Database

There Is No Magic: An AI Agent in 60 Lines of Python

Python Is Not Enough: Why Pythonistas Love Rust (Podcast)

Highlights from the episode</h2> Why Pythonistas reach for Rust</p>

Where to go from here</h2> Michal ends on a positive note:</p>

From Python to Rust: Master Iterators by Rebuilding 10 Unix Tools

Profile First: A 10x Faster Django Test Suite

End-to-End Testing Every Rust Exercise with Playwright

When to use classmethod, staticmethod, or instance method in Python

Building an AI Agent in 6 Weeks (and Finally Understanding How They Work)

Why Rust does not need OOP

How to Update Multiple Page Elements from One htmx Request

"Rust Is for People Who Want to Be Punished." Now Jochen Trusts It More Than Python.

The profiler told him where he was wrong</h2> Speed in Rust isn't automatic, and Jochen learned that the hard way. He'd swapped a list for a double-ended queue, proud of it.</p>

What changed</h2> Ask him how confident he feels starting a new Rust project and he says a 3 out of 10, and means it as a compliment to the language.</p>

How to Tell if Your Python Mock Is Actually Working

Unit vs integration: where does this test belong?</h2> All this then led to a related question:</p> How should you organize tests that hit real external services?</p> </blockquote> The convention that holds up in practice:</p>

AI Human-in-the-loop: News Digest Triage Telegram Bot