Skip to content

About

A 999-lesson Python course where every lesson is runnable, tested and notebook-ready🐍

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

2,011 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

🐍 python-from-scratch

A 999-lesson Python course where every lesson is runnable, tested and notebook-ready

Python Lessons Tests Notebooks Sections License: MIT Last commit Stars Forks Issues


πŸ“‘ Table of Contents

# 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

πŸš€ Quick Start

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

Prefer clicking? Open any notebook straight from the site, or locally:

jupyter notebook lessons/013-variables/lesson.ipynb

New 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

πŸ“– How a Lesson 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.ipynb

🐍 What the code looks like

Short, 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}!"

πŸ““ What the notebook gives you

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

πŸ—ΊοΈ The Course Map

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.


✨ Why It Is Built This Way

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

βœ… Quality Gates

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 installed

tools/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 nbformat 4 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.


🧰 Project Layout

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.


πŸ› οΈ Tooling

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

🀝 Contributing

New lessons, fixes and extra exercises are all welcome. The short version:

  1. One idea per lesson. If the title needs an "and", it is two lessons.
  2. Two or three functions, with a full docstring and an Examples: block.
  3. One test per promise, named after the behaviour.
  4. A runnable main() that prints something you can check by eye.
  5. 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

πŸ—ΊοΈ Roadmap

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.


πŸ“„ License

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.

⬆ Back to top

About

A 999-lesson Python course where every lesson is runnable, tested and notebook-ready🐍

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages