Hi all — I’ve been working on a Python 3.14 typing guide and am sharing it publicly in hopes that other people find it useful and/or can make it better.
It’s not a reference manual or a PEP summary. It’s an attempt to explain how Python’s typing system behaves as a system — how inference, narrowing, boundaries, and async typing interact, and how typing can be used as a way of reasoning about code rather than just silencing linters.
It’s long, but modular; you can drop into any section. The main chunks are:
What Python typing is (and is not) good at
How checkers resolve ambiguity and refine types (and why inference fails)
If you’ve ever felt that typing “mostly works but feels opaque,” this is aimed at that gap.
If you notice errors, confusing explanations, or places where it breaks down in real usage, I’d appreciate hearing about it — even partial or section-level feedback helps.
To be honest, both the partially incorrect formatting, not using line-breaks, and as it seems like, — as a - (pretty typical for LLMs, as well as the missing history for the file itself, compared to the big history for the readme are suspicious.
In spite of that, I think the development would have only been aided by LLMs, although it is hard to tell these days.
Either way, the idea behind the project is something I support, although it might be beneficial to split the file (or maybe make a simple website, so it is easier to navigate the file).
The file was uploaded once as a complete document. It was not developed on Github.
The readme was developed for GitHub on GitHub and I was trying to insert a table of contents that was hyperlinked. It isn’t my skill set and still isn’t done properly. Not to mention the source file itself having some markdown issue that makes the table of contents harder to work with.
Other people have suggested splitting it up into multiple files - that is something that I am likely to do after the first round of comments. It is unlikely that the document will survive in “book” format.
I used LLM feedback while developing the guide (from several different models). That title is a bit bullshitty-sounding, but it served its purpose at the time. Conveying the idea mattered more than landing on a perfectly pithy formulation.
The point of that section is to give a primary motivation for using Python’s type system and the static-analysis ecosystem around it. I get why “Typing as Epistemic Resolution and Semantic Fidelity” might hit the ear wrong, but I’m hoping it doesn’t stop you from engaging with the substance. The guide is conceptual all the way through. The conceptual layer has its own complexity that is different from, rather than subordinate to, the syntactic and implementation complexity. I used some terminology that isn’t typical in popular CS writing because it’s better suited to describing the underlying ideas, though I agree that in a final version “epistemic” is unlikely to be helpful even if the concept is ultimately about tracking what we know and how we know that we know.
I am not sure why people are so concerned with who is responsible for my language, but for what it is worth, my background is theoretical, not programming: epistemology, logic, semiotics, linguistics, theories of representation, computational thinking, etc. The guide is not “about” programming, the guide is about how we use programming languages to solve actual problems that people have and how Python’s typing system enables us to solve problems better. That is why it has a narrative voice - that is why it has an opinion. It is why it begins in type theory and then sets it aside to deal with what Python actually delivers - a static analysis ecosystem that enables type analysis.
At no point did I present the guide as “An introduction to Python type syntax with exhaustive examples for common programming patterns.”
FWIW, I read the section in question and thought it was great. It really captured the essence of why I like types so much. I plan to read more, if I can find the time.
I’m not sure why people are hating on the prose so much. I have no problem with it and would encourage you not to change it. It’s probably a more advanced read, but I don’t put much stock in that perspective when the average reading level, at least here in the US, is something like 6th grade. We could use more attempts to raise the bar.
Wasnt meaning to dig on you, just pointing out that your language style here is consistent with the document, so I don’t think the thing was written by an LLM.
I thought it was pretty good as long as don’t think of it as a beginner’s tutorial. Some of the language is a little inaccessible – even though I’m a native English speaker I still struggled to parse bits of it.
Thanks. My hope was that it wouldn’t be a niche document (more than any Python guide on typing is going to be niche), but it may end up that way unless I try to turn it into something that it isn’t.
Is there any language in particular that you thought interfered with understanding/substance? The goal is to be clear, not to lose people because I picked a word or phrase that is too foreign/dense.
Would I be better off just reposting it? With all due humility, the long term goal is for this to be a Python community document, not just something I wrote.
To be completely honest, my brain wanted to read it as a somewhat-contrived acronym. Any chance you can change the last word to start with an E? At least then it will be TERSE.
