trekhleb/learn-python: a test-file cheatsheet for Python syntax

What trekhleb/learn-python actually is

This is a repository of Python scripts organised by topic. The README describes it as "a collection of Python scripts that are split by topics and contain code examples with explanations, different use cases and links to further readings". The table of contents runs from Getting Started and Operators through Data Types, Control Flow, Functions, Classes, Modules, Errors and Exceptions, and Files. Each entry points at a file under src/, and almost every entry is a test file: src/data_types/test_lists.py, src/control_flow/test_if.py, src/functions/test_function_decorators.py, and so on. Two entries are Markdown instead: src/getting_started/what_is_python.md and src/getting_started/python_syntax.md.

The audience is narrow and worth stating plainly. It is not for someone who has never opened a terminal. It assumes you can install Python packages, run a test command, and read a traceback without help. It is for the developer who knows another language, or who learned Python casually and wants the exact behaviour of slicing, `nonlocal`, `*args`, or multiple inheritance confirmed by executable code rather than prose. The README's own framing supports that: it calls the repository a playground because you can change the code and test it, and a cheatsheet because you can return to it to recap "the syntax of standard Python statements and constructions".

Assertions instead of printed output

The mechanism is simple and it is the reason the format works. Each file is a pytest module. Sub-topics are test functions, and each function contains comments explaining an action followed by an `assert` that encodes the expected result. The README gives this example from the lists topic, where `squares = [1, 4, 9, 16, 25]` is followed by `assert squares[0] == 1` and `assert squares[-3:] == [9, 16, 25]`. The assertion is the documentation. You do not have to run anything to read the expected output, and if you do run it, a wrong expectation fails loudly.

That has a practical consequence the README does not dwell on. Because the examples are executable, they can only go stale in ways that a test runner will detect. A syntax change or a behavioural change in a supported Python version turns a green file red. A prose tutorial can quietly become wrong for years; this one cannot, provided someone runs pytest. The trade-off is coverage. Assertions are good at showing what an expression evaluates to and bad at explaining why a language feature exists, when to prefer one construct over another, or what happens at scale. The docstrings and the linked further-reading URLs carry that load, and they are not verified by the test run.

Installing it and running one topic

There is no package on an index and no CLI. The README's usage section points at running tests and linting, and the repository ships a requirements.txt at the root. The pinned versions in that file are old: pytest 3.7.2, pylint 2.1.1, flake8 3.5.0, astroid 2.0.4, six 1.11.0. Installing them into a modern interpreter is the first thing to expect trouble with, so use a virtual environment.

git clone https://github.com/trekhleb/learn-python.git
cd learn-python
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

With the dependencies installed, run a single topic rather than the whole suite. The README's testing section uses pytest, and because the files are named test_*.py, pytest discovers them without configuration.

pytest src/data_types/test_lists.py -v

You should see the individual test functions inside that file reported one by one, with the sub-topic names from their docstrings in the verbose output. To run everything, `pytest` from the repository root is enough. The README also mentions linting the code you write, and the repository carries .flake8 and pylintrc at the root, so `flake8` and `pylint` pick up project settings rather than defaults. The intended loop is: open a file, change an assertion or add one, rerun pytest, and see whether your mental model of the language matches the interpreter's.

Where the format breaks down

The pinned dependency set is the first real limitation. A requirements.txt frozen at pytest 3.7.2 and pylint 2.1.1 dates from a period when Python 3.7 was current. On a newer interpreter, a straight `pip install -r requirements.txt` may fail to build or resolve, and the fix is to install modern pytest, flake8 and pylint yourself and accept that the lint configuration may no longer match the installed linters. The README does not document a supported Python version range, so you are on your own there.

The second limitation is scope. The table of contents stops at files and exceptions. There is nothing on virtual environments, packaging, type checking with mypy, async and await, decorators beyond a single file, context managers beyond the `with` statement on files, or the standard library outside `import` and packages. If your goal is to build and ship something, this repository will not take you there. It teaches the grammar of the language, and grammar is not a program.

A third point is stylistic rather than technical. The tests are written in a single flat style, close to the official tutorial's examples. That is deliberate for a cheatsheet, but it means you will not see the same problem solved two ways, and you will not see the idioms that experienced Python developers actually write. Treat the files as a specification of behaviour, not as a style guide.

Compared with the official tutorial and Learn Python the Hard Way

The obvious alternative is the official Python tutorial, which covers the same ground in prose with an interpreter session format. The difference is execution. The official tutorial shows you a session and its output; you read it and trust it. trekhleb/learn-python gives you the same material as assertions you can run, break and rerun, which is a different learning loop and a better one if you learn by poking at code. The cost is that prose explains and tests do not. For the question of why a feature exists, the official tutorial is still the better source, and the README links out to learnpython.org for exactly that kind of further reading.

Learn Python the Hard Way takes the opposite approach: exercises you type out, with deliberate errors and a strong opinion about how to practise. It is a course with a sequence. This repository has no sequence and no exercises; it has a table of contents you jump around in. If you need to be told what to do next, the course format is a better fit. If you need to look up how set methods behave and confirm it in ten seconds, this repository is faster.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-06. There are no releases to track, so there is no version to upgrade to and no changelog to read. Your upgrade cost is therefore the dependency set, not the project: the requirements.txt pins are the thing that will need attention on a new interpreter, and the repository does not document a migration path. Watch the Travis CI badge in the README, which points at travis-ci.org and is a historical build signal rather than a description of current CI.

The licence is MIT, stated in the LICENSE file and in the repository metadata. In practical terms that is a permissive licence, so copying examples into your own code or teaching material is within its terms, subject to keeping the copyright notice. That is a summary of what the licence file says, not legal advice; read LICENSE yourself if you plan to redistribute the content.

The README also opens with a statement about the war in Ukraine and links to three charities. It is part of the project's presentation, not part of its technical content, and it does not change how the code works.

Editorial conclusion

Adopt it if you want a runnable syntax reference next to a real interpreter and you are comfortable with pytest. Do not adopt it if you need guided lessons, exercises with grading, or material on packaging, async, or the standard library beyond files, modules and exceptions. Before relying on it, check the pinned versions in requirements.txt against your interpreter and run pytest on a single file to confirm the assertions still pass.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. trekhleb/learn-python on GitHub