New URL: https://decorator-factory.codeberg.page/typing-tips/
New repository URL: https://codeberg.org/decorator-factory/typing-tips
The Github Pages site still works, but redirects to the new Codeberg site.
https://docs.codeberg.org/getting-started/what-is-codeberg/
Codeberg is a democratic community-driven, non-profit software development platform operated by Codeberg e.V. and centered around Codeberg.org, a Forgejo-based software forge.
On Codeberg you can develop your own Free Software projects, contribute to other projects, browse through inspiring and useful free software, share your knowledge or build your projects a home on the web using Codeberg Pages, just to name a few.
This is the old README:
URL: https://decorator-factory.github.io/typing-tips/
This is a blob of writing about Python's optional type annotation system, including a tutorial and some one-off articles.
The Python documentation has recently started adopting the Diataxis framework for understanding different documentation genres. Python's type annotation system is quite deep and complex. The typing documentation site covers the "reference" quadrant well and has some "guide" articles. However, there isn't a high quality and up to date resource for the "tutorial" quadrant. The purpose of that would be to introduce the type system to someone who's familiar with Python, but unfamiliar with static typing and type systems.
My hope for this is to eventually teach all the concepts necessary to understand how typing is set up for any piece of Python code you find and annotate all of your own code. You should be able to understand messages from mypy/pyright/ty without the help of a colleague, even if they contains scary words like "invariant" or "overload". With how much content is needed for this to work, this is turning from a tutorial series into a mini-book.
The tutorial series is missing a few key pieces to be a complete resource. The goal is not
to explain every single item from typing, but to teach concepts that don't come easily from
reading the manual.
See TODO.md.
The main thing this project is lacking is feedback. What sort of documentation or teaching materials are you missing for yourself or your team? Do the articles in here actually work?
Feel free to open a pull request, issue or discussion on
GitHub, or message decorator_factory on Discord.
- Install Python 3.13+
- Create a new virtual environment and activate it
- In the virtual environment, run
python -m pip install -r requirements-lock.txt - Run
python -X dev -m mkdocs serve - Visit
http://127.0.0.1:8000/typing-tips/
This project is an LLM-free zone. Everything in the repository is created by a human.