| # | 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.