Skip to content

Commit 4e0c7b4

Browse files
committed
Add optional tracks (Data Analysis, Automation, Web & APIs), offline PWA, accessibility and mobile pass
- Add 3 optional tracks (16 lessons): Data Analysis (NumPy, pandas, Matplotlib), Automation & scripting, Web & APIs. Optional modules via "optional": true; lessons can declare packages (numpy, pandas, matplotlib) loaded in the browser. - learn CLI: `tracks` command, `next <track>`, core vs track progress. - Placement test and fast track now only cover the core path. - Offline PWA: manifest, icons, service worker with build-generated precache list, "Download for offline" button (Pyodide + packages cached from CDN). - Accessibility: high-contrast code themes, accessible dark editor theme, line-wrapped editor, reduced-motion and forced-colors styles, main focus target. - Mobile layout: stacked header, wrapping buttons, 44px tap targets on touch. - Worker now fails clearly when a package download does not complete. - Contributor onboarding: tools/new_lesson.py scaffold (validator rejects unfinished scaffolds), rewritten CONTRIBUTING.md, style guide and README updates. Issue/PR templates and the ci.yml change must be added by hand. - Review bank: 104 questions covering 79 lessons.
1 parent 81b4d7c commit 4e0c7b4

159 files changed

Lines changed: 7792 additions & 103 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## What does this change?
2+
3+
<!-- One or two sentences. For a lesson: which one, and why it teaches things in this order. -->
4+
5+
## Checklist
6+
7+
- [ ] `python tools/validate_content.py` is clean
8+
- [ ] `python tools/build_exercises.py` was run and its output is committed
9+
- [ ] `python tools/check_solutions.py` and `python -m pytest tools/tests` pass
10+
- [ ] `cd web && npm test` passes (only needed if lessons or the runner changed)
11+
- [ ] I read the lesson in the browser (`npm run dev`) and it makes sense to a complete beginner
12+
- [ ] Every new `assert` in a lesson test has a message that tells the learner what to do
13+
- [ ] A new lesson has one or two review questions in `content/review/questions.json`
14+
- [ ] Site changes: keyboard use, 360 px width and light/dark contrast still work

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
with:
1919
python-version: "3.13"
2020
cache: pip
21-
- run: pip install -r requirements.txt
21+
- run: pip install -r requirements.txt -r requirements-tracks.txt
2222
- name: Validate lesson files
2323
run: python tools/validate_content.py
2424
- name: Local-track exercises are up to date

‎.github/workflows/config.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
blank_issues_enabled: true

‎.github/workflows/lesson-idea.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Idea for a lesson or track
2+
description: Suggest a topic, an exercise or a new optional track.
3+
labels: ["idea"]
4+
body:
5+
- type: input
6+
id: topic
7+
attributes:
8+
label: Topic
9+
validations:
10+
required: true
11+
- type: textarea
12+
id: why
13+
attributes:
14+
label: Who is it for and why does it matter?
15+
description: What would a learner be able to do afterwards that they cannot do now?
16+
validations:
17+
required: true
18+
- type: textarea
19+
id: exercise
20+
attributes:
21+
label: A small exercise (optional)
22+
description: What would the learner write, and how would we check it?
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
name: Problem with a lesson
2+
description: Something is wrong, unclear or hard to follow in a lesson, or a check rejects a correct answer.
3+
labels: ["lesson"]
4+
body:
5+
- type: input
6+
id: lesson
7+
attributes:
8+
label: Which lesson?
9+
description: The title, or the folder name such as 03-data-structures/01-lists.
10+
validations:
11+
required: true
12+
- type: dropdown
13+
id: kind
14+
attributes:
15+
label: What kind of problem is it?
16+
options:
17+
- The explanation is confusing or wrong
18+
- A check rejects a correct answer
19+
- A check accepts a wrong answer
20+
- A hint or message is unhelpful
21+
- It does not work in my browser or on my computer
22+
- Something else
23+
validations:
24+
required: true
25+
- type: textarea
26+
id: details
27+
attributes:
28+
label: What happened?
29+
description: If it is a checking problem, paste the code you wrote and the message you saw. Confusing wording counts as a bug, so please say where you got stuck.
30+
validations:
31+
required: true
32+
- type: input
33+
id: where
34+
attributes:
35+
label: Where are you using it?
36+
description: Browser and device, or "own computer" with your Python version.

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,6 @@ workspace/
2323
# Local-track progress written by `python -m learn`
2424
.learn-progress.json
2525
.learn-progress.json.tmp
26+
27+
# Claude output files (staging folder, not part of the project)
28+
Claude outputs/

‎CONTRIBUTING.md‎

Lines changed: 85 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,116 @@
11
# Contributing
22

3-
Thanks for helping people learn Python! The goal is lessons that are **short, correct, kind to beginners and machine-verified**.
3+
Thanks for helping people learn Python! The goal is lessons that are **short, correct, kind to beginners and machine-verified**. You do not need to be an expert: fixing a confusing sentence is as welcome as writing a lesson.
4+
5+
## Ways to help
6+
7+
- **Report a problem.** Confusing wording, a wrong explanation or a check that rejects a correct answer all count as bugs. Open an issue and name the lesson.
8+
- **Review a lesson.** Lessons are drafted with AI help and then checked by people. Read one as a beginner and tell us where you got stuck.
9+
- **Write or improve a lesson.** See below.
10+
- **Improve the site.** Accessibility, mobile layout and offline use matter here. See [Working on the website](#working-on-the-website).
11+
12+
Look for issues labelled `good first issue`.
13+
14+
## Get set up
15+
16+
You need Python 3.11+ and, for the website, Node 22+.
17+
18+
```bash
19+
git clone https://github.com/Adutchguy/Learn-Python.git
20+
cd Learn-Python
21+
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
22+
pip install -r requirements.txt -r requirements-tracks.txt
23+
cd web && npm ci && cd ..
24+
```
25+
26+
Confirm everything works before you change anything:
27+
28+
```bash
29+
python tools/validate_content.py && python tools/check_solutions.py
30+
```
31+
32+
## How the repository fits together
33+
34+
| Folder | What it is | Edit it? |
35+
| --- | --- | --- |
36+
| `content/` | Every lesson, plus placement, review and fast-track questions. **The single source of truth.** | Yes |
37+
| `exercises/` | The "work on your own computer" track, generated from `content/`. | No, run `python tools/build_exercises.py` |
38+
| `web/` | The website (Astro). It reads `content/` directly and runs Python in the browser with Pyodide. | For site changes |
39+
| `learn/` | The small `python -m learn` command-line helper for the local track. | For CLI changes |
40+
| `tools/` | Validators, generators and the new-lesson scaffold. | For tooling changes |
41+
| `docs/` | The plan and the [content style guide](docs/CONTENT-STYLE-GUIDE.md). | Yes |
442

543
## Ground rules
644

7-
1. **`content/` is the only place lessons are edited.** `exercises/` is generated; the website reads `content/` directly.
45+
1. **`content/` is the only place lessons are edited.** `exercises/` is generated.
846
2. **Every exercise is machine-checked in CI.** The solution must pass its tests and the starter must fail them.
947
3. **Every `assert` in a lesson test carries a helpful message** that tells the learner what to do, not just that they were wrong. CI enforces this.
1048
4. Follow the [content style guide](docs/CONTENT-STYLE-GUIDE.md) for tone, structure and what the browser runner supports.
1149
5. Claims about current versions, tools or prices should be checked against official sources when written.
1250

1351
## Adding a lesson
1452

15-
1. Pick the module folder in `content/` (or create `content/NN-name/module.json` with a `title` and `description`).
16-
2. Create `content/<module>/NN-lesson-name/` containing:
17-
- `lesson.md`: YAML frontmatter plus the lesson text
18-
- `starter.py`: what the learner sees
19-
- `solution.py`: a reference answer
20-
- `test_exercise.py`: pytest-style checks
53+
Let the scaffold create the files and numbering for you:
54+
55+
```bash
56+
python tools/new_lesson.py "Sets and frozensets" --module 03-data-structures
57+
```
58+
59+
It creates `content/03-data-structures/NN-sets-and-frozensets/` with `lesson.md`, `starter.py`, `solution.py` and `test_exercise.py`, and sets the prerequisite to the previous lesson. Useful options:
60+
61+
| Option | When to use it |
62+
| --- | --- |
63+
| `--minutes N` | The lesson takes about N minutes (1 to 60). |
64+
| `--local-only` | It needs real network, subprocesses or threads, so it cannot run in a browser. |
65+
| `--packages numpy pandas` | It needs a third-party package (`numpy`, `pandas` or `matplotlib`). |
66+
| `--new-module "Title"` | Start a new module. Add `--optional` to make it an optional track. |
67+
68+
Then:
69+
70+
1. Replace every placeholder. The validator refuses lessons that still contain the `SCAFFOLD` line, so an unfinished lesson cannot be merged by accident.
71+
2. Add one or two questions for the lesson to `content/review/questions.json` (see the style guide). You do not work out the answer key by hand: the validator runs each program and tells you the right answer.
2172
3. Run the checks:
2273

2374
```bash
2475
python tools/validate_content.py
2576
python tools/build_exercises.py
2677
python tools/check_solutions.py
78+
python -m pytest tools/tests
2779
cd web && npm test
2880
```
2981

30-
4. Preview it in the browser: `cd web && npm run dev`.
82+
4. Read your lesson in the browser as a beginner would: `cd web && npm run dev`.
3183
5. Commit **both** `content/` and the regenerated `exercises/` files.
3284

85+
### Optional tracks
86+
87+
Data Analysis, Automation and Web & APIs are **optional tracks**: modules whose `module.json` has `"optional": true`. They are not part of the core path, the placement test or the fast track. A core lesson may never require an optional lesson (the validator checks), but a track lesson may build on core lessons. Track lessons that use `numpy`, `pandas` or `matplotlib` declare them in `packages:`. In the browser they are downloaded on first use; locally they come from `requirements-tracks.txt`.
88+
89+
## Working on the website
90+
91+
```bash
92+
cd web
93+
npm run dev # live preview
94+
npm run build # production build, including the offline service worker
95+
```
96+
97+
Please keep these in mind; they are the things a visitor on a phone, with a screen reader or without a connection relies on:
98+
99+
- **Accessibility.** Keep the skip link, headings and landmarks; every interactive element needs a visible focus state and a name; never rely on colour alone to show pass or fail. Code and UI colours need at least 4.5:1 contrast in both light and dark mode. Run an [axe](https://github.com/dequelabs/axe-core) audit if you change styles or markup.
100+
- **Mobile.** The layout must work at 360 px wide with no sideways page scroll, and tap targets should be at least 44 px on touch screens.
101+
- **Offline.** `web/public/sw.js` is a template: `web/integrations/pwa.mjs` fills in the file list when the site is built. New files in `web/public/` are picked up automatically. Test offline behaviour in a production build (`npm run build && npm run preview`), because the service worker is off in `npm run dev`.
102+
33103
## Pull requests
34104

35105
- One lesson or one fix per pull request keeps review quick.
36106
- CI must be green. It validates content, checks `exercises/` is up to date, runs every lesson through real pytest *and* through the in-browser runner on real Pyodide, and builds the site.
37107
- Explain *why* the lesson teaches things in this order if the ordering is not obvious.
108+
- The pull request template has a short checklist; please tick it honestly.
109+
110+
## Licensing
111+
112+
By contributing you agree that code is released under the [MIT license](LICENSE) and lesson text under [CC BY-SA 4.0](LICENSE-CONTENT.txt).
38113

39114
## Reporting problems
40115

41-
Open an issue and include the lesson name and, if it is a checking problem, the code you wrote. Confusing wording counts as a bug.
116+
Open an issue and include the lesson name and, if it is a checking problem, the code you wrote.

‎README.md‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,21 @@ A free, open-source way to learn Python quickly and thoroughly, with **no sign-u
77

88
Both tracks come from the same lesson files, so they always match.
99

10-
> **Status:** early but usable. 72 lessons are written, from Start Here through Pythonic Python (iterators, generators, decorators, `functools`, type hints, async) and Testing & Quality (pytest, fixtures, linting, Git, packaging), with five projects: a number-guessing game, a quiz engine, an expense tracker, a bank system and a capstone where you build, test and publish a small package. There is a placement test that suggests where to start, a [fast track](web/src/pages/fast-track.astro) for people who already code in another language (it skips the lessons you do not need), and a spaced-review queue that brings finished lessons back at growing gaps. Optional tracks and polish are next; see [docs/PLAN.md](docs/PLAN.md) for the full roadmap.
10+
> **Status:** usable and feature-complete for the first release. 72 core lessons take you from Start Here through Pythonic Python (iterators, generators, decorators, `functools`, type hints, async) and Testing & Quality (pytest, fixtures, linting, Git, packaging), with five projects: a number-guessing game, a quiz engine, an expense tracker, a bank system and a capstone where you build, test and publish a small package. Three **optional tracks** add 16 more lessons: Data Analysis (NumPy, pandas, charts), Automation & scripting, and Web & APIs. There is a placement test that suggests where to start, a [fast track](web/src/pages/fast-track.astro) for people who already code in another language, and a spaced-review queue that brings finished lessons back at growing gaps. The site works on phones, has had an accessibility pass, and can be installed and used offline. See [docs/PLAN.md](docs/PLAN.md) for the roadmap.
11+
12+
## Optional tracks
13+
14+
After the core path (or any time you want a practical detour) there are three optional tracks. They are not part of the core progress count, the placement test or the fast track.
15+
16+
- **Data Analysis:** NumPy, pandas (selecting, grouping, cleaning), a small sales-analysis project and Matplotlib charts.
17+
- **Automation & scripting:** command-line programs with `argparse`, files and folders in bulk, `subprocess`, retries and scheduling, and a file-organiser project.
18+
- **Web & APIs:** how HTTP works, JSON APIs, calling a web service and building a tiny JSON API with only the standard library.
19+
20+
In the browser, the Data Analysis lessons download NumPy and pandas the first time (a few megabytes). Lessons that need real network, subprocesses or a chart you can see are marked as needing your own computer.
21+
22+
## Use it offline
23+
24+
On the home page, **Download for offline** saves Python itself (about 15 MB with NumPy and pandas). After that the whole course, including running and checking code, works without a connection, and your browser can install it as an app. Your progress always stays in your browser.
1125

1226
## How learning works here
1327

@@ -28,6 +42,9 @@ source .venv/bin/activate
2842
.venv\Scripts\Activate.ps1
2943

3044
pip install -r requirements.txt
45+
46+
# Only if you want the optional Data Analysis track (NumPy, pandas, Matplotlib):
47+
pip install -r requirements-tracks.txt
3148
```
3249

3350
Each lesson is a folder under `exercises/`:
@@ -47,6 +64,7 @@ python -m learn check # run the checks for your current lesson (a pass
4764
python -m learn hint # reveal one hint at a time
4865
python -m learn status # your progress, module by module
4966
python -m learn list # every lesson, with the finished ones ticked
67+
python -m learn tracks # the optional tracks; "python -m learn next data" continues one
5068
```
5169

5270
`check` and `hint` also accept a lesson number from `list`, or a word from its name (`python -m learn check variables`). Your progress is saved in `.learn-progress.json`, which Git ignores.
@@ -67,7 +85,7 @@ Tip: work on your own branch (`git switch -c my-answers`) or in a fork, so your
6785
| `exercises/` | Local track, **generated** from `content/` (do not edit by hand, except `conftest.py`) |
6886
| `web/` | The website (Astro) and the in-browser Python runner (Pyodide) |
6987
| `learn/` | The `python -m learn` command-line guide for the local track |
70-
| `tools/` | Python scripts that validate lessons and generate `exercises/` |
88+
| `tools/` | Python scripts that validate lessons, generate `exercises/` and scaffold new lessons (`new_lesson.py`) |
7189
| `docs/` | Plan, content style guide |
7290

7391
## Contributing
@@ -77,7 +95,8 @@ Lessons, fixes and ideas are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and
7795
Quick start for contributors:
7896

7997
```bash
80-
pip install -r requirements.txt
98+
pip install -r requirements.txt -r requirements-tracks.txt
99+
python tools/new_lesson.py "Title" --module 03-data-structures # start a new lesson from a template
81100
python tools/validate_content.py # are all lessons well formed? (also runs the placement and review questions to verify their answers)
82101
python tools/build_exercises.py # regenerate exercises/ after editing content/
83102
python tools/check_solutions.py # every solution passes, every starter fails
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "NumPy Arrays: Maths on Whole Lists at Once"
3+
minutes: 20
4+
prereqs: ["03-data-structures/08-comprehensions"]
5+
concepts: ["numpy", "array", "vectorised operations", "boolean mask", "shape", "axis", "mean"]
6+
local_only: false
7+
packages: ["numpy"]
8+
hints:
9+
- "celsius_to_fahrenheit: put the values in an array with np.array(temps) and use ordinary arithmetic on the whole array: array * 9 / 5 + 32. No loop is needed."
10+
- "normalise: low = values.min() and high = values.max(); then (values - low) / (high - low). above_average: a comparison on the whole array, values > values.mean(), gives a True/False array; index with it: values[values > values.mean()]."
11+
- "column_means: grid = np.array(rows) makes a 2D array. grid.mean(axis=0) averages down each column (axis=1 would average across each row)."
12+
---
13+
14+
## Why this matters
15+
16+
Data work means doing the same calculation on thousands or millions of numbers. A Python `for` loop over a list is slow and wordy for that. **NumPy** gives you an **array**: a fixed-type grid of numbers where one expression works on every element at once. It is the base that pandas, machine-learning libraries and scientific code are built on.
17+
18+
## The idea
19+
20+
```python
21+
import numpy as np
22+
23+
prices = np.array([4.0, 10.0, 6.5])
24+
print(prices * 2) # [ 8. 20. 13. ] every element doubled
25+
print(prices + prices) # [ 8. 20. 13. ] element by element
26+
print(prices.mean()) # 6.833333333333333
27+
print(prices.max()) # 10.0
28+
```
29+
30+
Arithmetic on an array applies to every element (this is called **vectorising**). Compare with a plain list, where `[1, 2] * 2` repeats the list instead.
31+
32+
**Comparisons give a mask** of `True`/`False`, and a mask picks out elements:
33+
34+
```python
35+
prices > 5 # [False True True]
36+
prices[prices > 5] # [10. 6.5]
37+
```
38+
39+
**Shape and axis.** A list of lists becomes a 2D array. `shape` tells you its size, and `axis` says which direction a calculation runs:
40+
41+
```python
42+
grid = np.array([[1, 2, 3],
43+
[4, 5, 6]])
44+
grid.shape # (2, 3): 2 rows, 3 columns
45+
grid.mean(axis=0) # [2.5 3.5 4.5] one result per column
46+
grid.mean(axis=1) # [2. 5.] one result per row
47+
```
48+
49+
Other handy tools: `np.arange(5)` (like `range`, but an array), `np.zeros(3)`, `np.round(x, 2)` and `np.sum`.
50+
51+
## Try it
52+
53+
Make an array of five numbers. Multiply it by 10, take its `.mean()`, and use a mask to keep only the values greater than the mean.
54+
55+
## Your turn
56+
57+
Write four functions. Each should return a NumPy array and avoid loops:
58+
59+
- `celsius_to_fahrenheit(temps)`: convert a list of Celsius temperatures (F = C × 9 / 5 + 32).
60+
- `normalise(values)`: rescale a list so the smallest becomes 0 and the largest becomes 1: `(x - min) / (max - min)`.
61+
- `above_average(values)`: only the values greater than the average of all of them.
62+
- `column_means(rows)`: the average of each column of a list of equal-length rows.
63+
64+
## Recap
65+
66+
- An array applies arithmetic to every element at once; no loop needed.
67+
- A comparison gives a True/False mask, and `array[mask]` keeps the matching elements.
68+
- `shape` is the size; `axis=0` works down columns and `axis=1` across rows.
69+
- Arrays hold one type of number, which is what makes them fast.
70+
71+
## Common mistakes
72+
73+
- **Expecting list behaviour:** `[1, 2] * 2` repeats the list, while `np.array([1, 2]) * 2` doubles the numbers.
74+
- **Mixing up the axes:** `axis=0` collapses the rows, leaving one value per column.
75+
- **Writing a loop anyway.** If you are looping over an array, there is usually a one-line array expression instead.
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
import numpy as np
2+
3+
4+
def celsius_to_fahrenheit(temps):
5+
return np.array(temps) * 9 / 5 + 32
6+
7+
8+
def normalise(values):
9+
values = np.array(values, dtype=float)
10+
return (values - values.min()) / (values.max() - values.min())
11+
12+
13+
def above_average(values):
14+
values = np.array(values)
15+
return values[values > values.mean()]
16+
17+
18+
def column_means(rows):
19+
return np.array(rows).mean(axis=0)

0 commit comments

Comments
 (0)