the stories
Python libraries, each told as a story that follows its data through one real run of the library's intended use. The page you open has three panes: a control-flow chart of that run, the story, and the code it cites, side by side. Every claim links to lines at a pinned commit; every chapter ends in a proof you can run. The stories were written by Claude and checked by code; the comparison that decided their fate, preregistered and run against DeepWiki, is in the repository.
-
pallets/itsdangerous
A Token and Its Word: One Round Trip Through ItsDangerous
A web app wants to hand a user's identity —
{"id": 5, "name": "itsdangerous"}— to an untrusted place (a URL, a cookie, an email link) and get it back later without having stored anything server-side. The data must survive the trip in a form that is safe for URLs, and any tampering must be detectable on return.URLSafeSerializer("secret key", "auth")is the promise; this story follows the dict out to a token and back again, and notes exactly what that promise covers and what it does not. -
psf/requests
One GET, End to End: What Requests Promises and Where It Trusts You
A caller has a URL and a pair of credentials:
requests.get('http://127.0.0.1:54897/basic-auth/user/pass', auth=('user','pass')). Between that line and a parsed JSON dict lies every decision Requests makes on your behalf — which headers it adds, whether it checks a certificate, how long it will wait, where it will send your password next, and what it does with a response body it has not yet read. This story follows that URL and that password through the library, stopping wherever a guarantee is made or a default quietly decides something for you. -
pallets/flask
One Request Through Flask: What the Framework Promises Between `environ` and `200 OK`
A ten-line application
app = Flask(__name__), one route returning"Hello, World!"is the smallest thing anyone can be asked to sign off on. Nothing is configured: no secret key, no error handlers, no blueprints, no before/after hooks. Everything that happens between the client'sGET /and the200 OKit gets back is Flask's own behaviour, running on its defaults. This story follows one WSGI environ dict from the moment the test client builds it to the moment the response iterator closes, and asks at each step: what is guaranteed here, what are the defaults, and what happens when something goes wrong. -
pallets/click
Hello, Click: one value's round trip through a command line
A caller has a Python function,
hello(count, name), and wants it to behave like a real command line program:--count=3typed on the command line, a name asked for interactively, output captured so a test can assert on it. Nothing in the function knows about argv, prompts, encodings, or exit codes. The data that arrives u2014 the argument list['--count=3']and the keystrokes'Click\n'u2014 has to cross from an untrusted outside world into a typed Python call, and a result has to come back out with an exit code that means something. This is the story of that crossing, and of the guarantees Click makes along the way. -
encode/httpx
A Request That Never Touches the Network
A caller wants to exercise a plain Python WSGI application through the real httpx client — same headers, same cookie jar, same response model — but with no socket, no DNS and no TLS anywhere in the path. The input is modest: the string "/" and one custom header, handed to
client.get(). Everything interesting is what the client does to that input on the way down, and what it guarantees about what comes back up. The reader following it is the person who has to sign off on that stack: which defaults are in force, where a failure would surface, and what the transport boundary does and does not promise. - Textualize/rich What Actually Reaches the Terminal: Two Strings and a Table Through Rich A caller wants styled, laid-out text on a terminal: colours, markup tags like [bold cyan]…[/bold cyan], and a four-column table that fits the available width — without hand-writing ANSI escape sequences, without overflowing the line, and with the option to capture whatever was produced for later inspection. The data handed in is ordinary Python: two plain strings, one markup string, and a table of cell strings. Everything between that data and the bytes on the file object is Rich's job, and the owner of this code has to vouch for it: what it promises, where it decides on the caller's behalf, and how it fails.
-
python-attrs/attrs
The Class That Was Rewritten: One Run Through attrs
Writing a Python class with a handful of data fields means hand-writing nine or more dunder methods
__init__,__repr__,__eq__,__ne__, ordering, hashing, pickling and keeping them in sync forever. *attrs* offers to write them for you. The price is that a decorator gets to inspect your class body at import time and, for slotted classes, hand you back a *different class object* than the one you wrote. This story follows one real run of the README example: a class body with two annotated fields walks into@define, comes out as a finished, slotted, unhashable class; an instance of it is compared and serialized to a dict; and finally a second class is conjured at runtime from nothing but two strings. The reader is the person who has to sign off on all of that: what is guaranteed, what is silently decided, and where it can bite. -
pallets/jinja
The Template That Knew Its Parent
A web page is two files: a layout with holes in it, and a member list that fills the holes. Jinja's job is to turn that pair of strings into one correct, injection-safe HTML document
i
and to do it fast enough to be worth caching. The story follows one string, the source of
members.html, from the moment a DictLoader hands it over, through lexing, parsing, code generation andexec, until it comes back as rendered HTML with an ampersand safely escaped. Along the way it passes every decision an owner has to vouch for: what gets cached and when it goes stale, when the autoescape question is actually asked, what the generated Python is allowed to do, and who decides which file a template may pull in. -
pallets/markupsafe
Nothing Gets Out Unescaped: A Run Through MarkupSafe
A web page wants to show a comment somebody posted:
<script>alert(document.cookie);</script>. Printed as-is into HTML, that string stops being text and starts being code — it is a cross-site scripting payload. MarkupSafe exists to make the difference between "text" and "markup" a property of the value itself, carried in its type, so that a template can mix trusted and untrusted pieces and the untrusted ones can only ever arrive as inert characters. This story follows that one untrusted comment from the moment it is handed toescape()until it comes back out of a rendered fragment as plain text again, and notes at each step exactly what is guaranteed, what is merely trusted, and who is responsible for which. -
tqdm/tqdm
Four Characters and a Progress Bar: What tqdm Promises While It Prints
A caller has a four-item list and a loop that does real work, and wants to see progress without writing any printing logic. The list is handed to
tqdm(...): from that moment it is no longer just a list but the payload of a progress meter that must allocate a global write lock, start a background thread, probe the terminal, render a frame, throttle itself, and clean up after the loop ends — all onsys.stderr, all without changing what the loop iterates over. This story follows that list through one real run and asks, at each step, what is guaranteed and what could go wrong. -
hukkin/tomli
Two Players and a Parser: What `tomli.loads` Promises
A caller hands Tomli a TOML string — a document with two
[[players]]records — and expects back a plain Python dict of builtin types, or a cleanTOMLDecodeErrorif the document is malformed. Nothing else: no partial results, no custom classes, no surprises. The string is the protagonist; the story follows it from the public entry point, through the single-pass statement loop, into the nested dict that is handed back, and notes at every branch what would have happened had the input been hostile or merely wrong.
reading them
The three panes need a window about 1,360 pixels wide; on a narrower screen the code opens as a sheet from the text.
Each page is a single static file with the cited code embedded from the repository at the pinned commit, so nothing on it
can drift from what the story was checked against. The proofs live beside each story as proofs/NN.py.