| # | Section | What you find |
|---|---|---|
| 1 | π Quick Start | Get running in four commands |
| 2 | π How a Lesson Works | The four files in every folder |
| 3 | πΊοΈ The Course Map | All 24 sections, in order |
| 4 | β¨ Why It Is Built This Way | The rules every lesson follows |
| 5 | β Quality Gates | How every lesson is checked |
| 6 | π§° Project Layout | The repository at a glance |
| 7 | π οΈ Tooling | Generator, scaffolder, verifier |
| 8 | π€ Contributing | Write or improve a lesson |
| 9 | πΊοΈ Roadmap | What is finished, what is next |
| 10 | π License | MIT |
You need Python 3.11 or newer. Nothing else is required to read the lessons; the extras below are for running the tests and the notebooks.
# 1. clone the course
git clone https://github.com/matkecn/python-from-scratch.git
cd python-from-scratch
# 2. create a virtual environment (optional, but tidy)
python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. install the tools used by the tests and notebooks
python3 -m pip install -r requirements-dev.txt
# 4. run one lesson
python lessons/013-variables/lesson_013_variables.pyPrefer clicking? Open any notebook straight from the site, or locally:
jupyter notebook lessons/013-variables/lesson.ipynbNew here? Read these three folders in order:
| Order | Folder | What it does |
|---|---|---|
| 1οΈβ£ | 000-welcome |
Your first program, one line of Python |
| 2οΈβ£ | 001-getting-started |
Install Python and learn to run a file |
| 3οΈβ£ | 020-first-program |
A small quiz program that actually works |
Every one of the 999 lessons is one folder with the same four files, so you always know where to look:
lessons/013-variables/
βββ README.md π the lesson, written to be read
βββ lesson_013_variables.py π tiny runnable example
βββ test_lesson_013_variables.py π§ͺ tests that prove it works
βββ lesson.ipynb π the same lesson as a notebook
A lesson always asks the same four things:
# 1οΈβ£ run it and see what it prints
python lessons/013-variables/lesson_013_variables.py
# 2οΈβ£ read the code (it is also inside the README)
cat lessons/013-variables/lesson_013_variables.py
# 3οΈβ£ run the tests
pytest lessons/013-variables
# 4οΈβ£ open the notebook and try the exercises
jupyter notebook lessons/013-variables/lesson.ipynbShort, typed, and documented. Every function says what it expects, what it returns and what can go wrong, with examples that run as tests:
def make_greeting(name: str) -> str:
"""Build a greeting for someone.
Args:
name: The person's name.
Returns:
A greeting ending with an exclamation mark.
Examples:
>>> make_greeting("Ada")
'Hello, Ada!'
"""
return f"Hello, {name}!"| Cell | What it does |
|---|---|
| 1 | The lesson summary and what you will learn |
| 2 | Runs the finished example with !python |
| 3 | Imports the functions so you can call them |
| 4 | The full source, plus a Your turn cell |
| 5 | The command to check your own work, plus links to the neighbours |
999 lessons, 24 sections, ordered so that nothing appears before you need it.
| # | Lessons | Section | Level | Start here |
|---|---|---|---|---|
| 1 | 001β020 | π’ Getting started and first programs | 1 | 001-getting-started |
| 2 | 021β050 | π’ Data types and conversions | 1 | 021-integers |
| 3 | 051β070 | π’ Conditionals and loops | 2 | 051-if |
| 4 | 071β100 | π’ Lists, tuples, sets and dictionaries | 2 | 071-lists |
| 5 | 101β120 | π‘ Strings, encodings and regular expressions | 2 | 101-string-indexing |
| 6 | 121β160 | π‘ Functions, arguments and scope | 2 | 121-functions |
| 7 | 161β200 | π‘ Modules, imports and exceptions | 3 | 161-modules |
| 8 | 201β250 | π Object oriented programming | 3 | 201-classes |
| 9 | 251β300 | π Iterators, generators and collections | 3 | 251-iterables |
| 10 | 301β350 | π Decorators, context managers, descriptors | 4 | 301-decorators |
| 11 | 351β400 | π‘ Type hints, dataclasses, pattern matching | 3 | 351-type-hints |
| 12 | 401β450 | π΄ The Python data model, dunder by dunder | 4 | 401-dunder-methods |
| 13 | 451β500 | π’ Files, paths and serialization | 2 | 451-files |
| 14 | 501β580 | π’ Standard library tour | 2 | 501-os |
| 15 | 581β600 | π‘ Command line tools and logging | 3 | 581-argparse |
| 16 | 601β650 | π΄ Networking, APIs and databases | 4 | 601-sockets |
| 17 | 651β700 | π΄ Web concepts, scraping and security | 4 | 651-web-concepts |
| 18 | 701β740 | π‘ Debugging and testing | 3 | 701-debugging |
| 19 | 741β800 | π‘ Packaging, style, CI and documentation | 3 | 741-virtual-environments |
| 20 | 801β840 | π΄ Concurrency and asyncio | 4 | 801-concurrency |
| 21 | 841β900 | π΄ Performance, memory and CPython internals | 5 | 841-performance |
| 22 | 901β950 | π΄ Practical Python applications | 4 | 901-cli-apps |
| 23 | 951β999 | π΄ Projects, challenges and mastery | 5 | 951-beginner-project-01 |
π’ beginner Β· π‘ early intermediate Β· π intermediate Β· π΄ advanced
The full topic list lives in structure.a and the progress of
each section lives in 000-meta/ROADMAP.md.
| πΎ Toddler sized | Two or three tiny functions per lesson. Nothing is longer than a screen, so the whole idea fits in your head. |
| π Real docstrings | Every function has a summary line, Args:, Returns:, Raises: where relevant, and at least one runnable Examples: block. |
| π§ͺ Tests everywhere | Each lesson ships with tests, and every docstring example runs as a test too. If a lesson breaks, the suite says so. |
| π Notebook included | Every lesson also exists as lesson.ipynb if you would rather click Run than type commands. |
| π§ No surprises | One folder per topic, numbered, in teaching order. structure.a is the original plan and nothing was renumbered. |
| π·οΈ Honest status | Generated lessons are labelled draft in the README and the notebook. Nothing pretends to be finished. |
pytest # 2075 unit tests + 214 docstring examples
python3 tools/verify.py # runs all 999 examples, validates all 999 notebooks
python3 tools/scaffold.py --report
ruff check . # style, when ruff is installedtools/verify.py is the strict one. For every lesson it checks that:
- β the example module compiles and runs as a script;
- β the module, every function and every class has a docstring;
- β
the notebook is valid
nbformat4 JSON with code cells, and mentions its module; - β the test module has a docstring and at least one test;
- β all four files are present.
There is also a test for the course itself,
000-meta/test_course_integrity.py, which
confirms there are exactly 999 numbered lessons, that folder and module names
are unique, that no lesson module shadows the standard library, and that the
previous and next links in every README point at folders that exist.
python-from-scratch/
βββ π README.md this file
βββ π structure.a the original 999 topic plan, source of truth
βββ βοΈ pyproject.toml pytest and ruff configuration
βββ π§ͺ Makefile test, verify, scaffold, lint
βββ π¦ requirements-dev.txt pytest, jupyterlab, ruff
βββ π lessons/ all 999 lessons, one folder each
β βββ π 000-welcome/ your first program
β βββ π§ 000-meta/ roadmap, contributing guide, licence, integrity test
β βββ 001-getting-started/ β¦
β βββ 999-final-python-capstone/
βββ π οΈ tools/ the machinery that builds the course
βββ build_curriculum.py structure.a β curriculum.py
βββ curriculum.py generated course data
βββ lesson_model.py the Lesson data model
βββ templates.py README and notebook renderers
βββ synth.py generates runnable drafts
βββ written/ hand written lessons, always win
βββ scaffold.py writes the four files per lesson
βββ notebook.py rebuilds a notebook from its example
βββ verify.py checks every lesson
Why are the modules called lesson_013_variables.py? About 25 topic names
are also standard library names (copy, operator, glob, jsonβ¦). A
prefixed module name keeps import copy meaning the real copy, and keeps
999 lessons from colliding with each other when pytest imports them.
| Command | What it does |
|---|---|
make help |
List every shortcut |
make test |
Run all 2289 tests |
make lesson SLICE=101-120 |
Run the tests for one slice of the course |
make verify |
Check that all 999 lessons are healthy |
make report |
Show how many lessons are hand written and how many are drafts |
python3 tools/scaffold.py --only 13 --force 13 |
Rewrite one lesson |
python3 tools/notebook.py 013-variables |
Rebuild one notebook from its code |
New lessons, fixes and extra exercises are all welcome. The short version:
- One idea per lesson. If the title needs an "and", it is two lessons.
- Two or three functions, with a full docstring and an
Examples:block. - One test per promise, named after the behaviour.
- A runnable
main()that prints something you can check by eye. - Short code. If an example passes thirty lines, it is two lessons.
Full instructions, including how to add a topic to structure.a, are in
000-meta/CONTRIBUTING.md. In short:
# 1. add your topic to structure.a, then
python3 tools/build_curriculum.py
# 2. write the lesson in tools/written/
# 3. generate its four files
python3 tools/scaffold.py --only 13 --force 13
# 4. prove it works
pytest lessons/013-variables && python3 tools/verify.py --only 13| Phase | What happens | State |
|---|---|---|
| 1οΈβ£ Scaffold | All 999 folders exist, every example runs, every test passes, every notebook opens | β done |
| 2οΈβ£ Hand write | One section at a time, replacing drafts with real lessons | π 20 of 999 |
| 3οΈβ£ Exercises | Add an exercises/ folder to finished lessons |
β³ planned |
| 4οΈβ£ Capstones | The last 49 lessons become real projects with briefs and marking schemes | β³ planned |
See 000-meta/ROADMAP.md for the section by section
table, and run python3 tools/scaffold.py --report for the live count.
Released under the MIT License. Use it, learn from it, teach with
it, fork it. A copy also lives at
000-meta/LICENSE.
Made with π and β for everyone who ever wondered what // really means.