Skip to content

Commit 2e73976

Browse files
Amogh-007-RinAmogh-007-Rin
committed
Enhance top-level README with detailed documentation, phase map, and usage guide
1 parent bd4c274 commit 2e73976

1 file changed

Lines changed: 217 additions & 29 deletions

File tree

‎README.md‎

Lines changed: 217 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,242 @@
11
# Stack.Python 🐍
22

3-
**A 0–100, linear, project-based Python learning sandbox for absolute beginners.**
3+
**A 0–100, linear, project-based Python learning sandbox for absolute beginners.**
4+
101 modules. 11 milestone projects. Zero assumed knowledge. One clear path from zero to deploy.
45

5-
Take a learner with zero programming experience from Module 0 (Python's history and philosophy) to Module 100 (full-stack application deployment). Every module builds on everything before it — no gaps, no forward references.
6+
Stack.Python is a complete, self-contained curriculum that takes a learner with **no programming experience** from writing their first `print()` statement in Module 002 to building a full-stack FastAPI application with SQLAlchemy, Jinja2 templates, and data pipelines in Module 099. Every module assumes only what was taught in the modules before it — no gaps, no leaps, no forward references.
67

7-
## Learning Path
8+
## Table of Contents
89

9-
| Phase | Modules | Topic |
10+
- [Who Is This For](#who-is-this-for)
11+
- [What Makes Stack.Python Different](#what-makes-stackpython-different)
12+
- [Learning Path (11 Phases)](#learning-path-11-phases)
13+
- [Milestone Projects](#milestone-projects)
14+
- [Module Format](#module-format)
15+
- [Quickstart](#quickstart)
16+
- [How to Use This Repo](#how-to-use-this-repo)
17+
- [Prerequisites](#prerequisites)
18+
- [Scripts & Tooling](#scripts--tooling)
19+
- [Project Structure](#project-structure)
20+
- [Contributing](#contributing)
21+
- [License](#license)
22+
23+
---
24+
25+
## Who Is This For
26+
27+
- **Complete beginners** — no programming background assumed or required
28+
- **Self-learners** — structured, linear curriculum you can follow on your own
29+
- **Bootcamp students** — supplemental reference to fill in knowledge gaps
30+
- **Instructors** — fork-ready curriculum you can teach from or adapt
31+
- **Career switchers** — learn modern Python with real-world applied projects
32+
33+
## What Makes Stack.Python Different
34+
35+
- **101 strictly linear modules** (000–100). No branching, no "choose your own adventure" confusion.
36+
- **Applied from day one.** Concepts are taught, then immediately used to build something tangible. Milestone projects appear roughly every 10 modules — you never go more than a few lessons without building.
37+
- **Full content, not stubs.** Every module includes a complete lesson, runnable Jupyter notebook, practice exercises, worked solutions, and a quiz — all generated and ready to use.
38+
- **Pedagogically intentional.** Code style conventions (PEP 8, Google-style docstrings, type hints) are introduced progressively. No forward references. Visual diagrams and ASCII art explain structural concepts.
39+
- **Python 3.12+.** Uses modern Python features: f-strings, union typing syntax, match statements (briefly), dataclasses, and more.
40+
41+
## Learning Path (11 Phases)
42+
43+
| Phase | Modules | Topics Covered | Milestone Project |
44+
|---|---|---|---|
45+
| **0. Orientation** | 000–001 | Python history & philosophy, environment setup | — |
46+
| **1. Fundamentals** | 002–010 | Print, variables, types, type conversion, I/O, operators, strings, string formatting, numbers | Calculator CLI |
47+
| **2. Control Flow & Data** | 011–020 | Booleans, conditionals, while/for loops, nested loops, lists, list comprehensions | To-Do List CLI |
48+
| **3. Data Structures** | 021–030 | Tuples, sets, dicts, collections (itertools, zip, enumerate), unpacking, shallow/deep copy | Contact Book |
49+
| **4. Functions** | 031–040 | Function arguments, scope (LEGB), lambdas, recursion, higher-order functions, decorators, generators, iterators | Text Adventure |
50+
| **5. OOP** | 041–050 | Classes, attributes, methods, inheritance, polymorphism, dunder methods, abstract base classes | Library System |
51+
| **6. Advanced OOP & Errors** | 051–060 | Composition, class/static methods, properties, dataclasses, enums, operator overloading, error handling, custom exceptions, file I/O, CSV | Expense Tracker |
52+
| **7. Modules, Stdlib & Testing** | 061–070 | JSON, context managers, modules/packages, venv/pip, stdlib (os, sys, datetime, random), regex, dates/times, logging | Log File Analyzer |
53+
| **8. Data, Web & APIs** | 071–080 | Functional patterns, comprehensions deep dive, type hints (mypy), unittest, pytest & TDD, requests (APIs), BeautifulSoup (scraping), pandas | Weather Dashboard |
54+
| **9. Databases & Web Apps** | 081–090 | matplotlib, SQLite, SQL, SQLAlchemy, Flask, FastAPI, Jinja2, automation (shutil) | Finance DB App + Automation Bot |
55+
| **10. Concurrency & Internals** | 091–098 | Threading, multiprocessing, asyncio, memory management/GC, metaclasses, ML intro (numpy, scikit-learn), packaging, profiling | — |
56+
| **11. Capstone** | 099–100 | Full-stack application (FastAPI + SQLAlchemy + Jinja2), career next steps | Full-Stack App |
57+
58+
## Milestone Projects
59+
60+
| Module | Project | Concepts Applied |
1061
|---|---|---|
11-
| **0. Orientation** | 000–001 | Introduction & Setup |
12-
| **1. Fundamentals** | 002–010 | First programs, variables, types, I/O, operators, strings, numbers |
13-
| **2. Control Flow & Data** | 011–020 | Booleans, conditionals, loops, lists |
14-
| **3. Data Structures** | 021–030 | Tuples, sets, dicts, collections |
15-
| **4. Functions** | 031–040 | Functions, scope, lambdas, recursion, decorators, generators |
16-
| **5. OOP** | 041–050 | Classes, inheritance, polymorphism, dunder methods |
17-
| **6. Advanced OOP & Errors** | 051–060 | Composition, properties, dataclasses, error handling, files |
18-
| **7. Modules, Stdlib & Testing** | 061–070 | JSON, context managers, regex, dates, logging |
19-
| **8. Data, Web & APIs** | 071–080 | Type hints, testing, APIs, pandas, web scraping |
20-
| **9. Databases & Web Apps** | 081–090 | SQLite, SQLAlchemy, Flask, FastAPI, automation |
21-
| **10. Concurrency & Internals** | 091–098 | Threading, multiprocessing, asyncio, memory management |
22-
| **11. Capstone** | 099–100 | Full-stack application & next steps |
23-
24-
Milestone projects appear roughly every 10 modules — build a calculator, a to-do app, a text adventure, an expense tracker, a weather dashboard, and more.
62+
| 010 | [Command-Line Calculator](modules/module-010-mini-project-calculator/project/README.md) | Variables, I/O, operators, type conversion, conditionals |
63+
| 020 | [To-Do List CLI](modules/module-020-mini-project-todo-cli/project/README.md) | Lists, loops, functions, menu-driven UI |
64+
| 030 | [Contact Book](modules/module-030-mini-project-contact-book/project/README.md) | Dictionaries, nested data, search/CRUD operations |
65+
| 040 | [Text Adventure Game](modules/module-040-mini-project-text-adventure/project/README.md) | Functions, dict-based world map, game loop, state management |
66+
| 050 | [Library Management System](modules/module-050-mini-project-library-system/project/README.md) | OOP, inheritance, class design, polymorphism |
67+
| 060 | [Expense Tracker](modules/module-060-mini-project-expense-tracker/project/README.md) | CSV persistence, error handling, file I/O, OOP design |
68+
| 070 | [Log File Analyzer](modules/module-070-mini-project-log-analyzer/project/README.md) | Regex, sys.argv, file parsing, summary statistics |
69+
| 080 | [Weather Dashboard](modules/module-080-mini-project-weather-dashboard/project/README.md) | requests (REST API), JSON parsing, API keys |
70+
| 085 | [Finance Database App](modules/module-085-mini-project-finance-database-app/project/README.md) | SQLAlchemy, SQLite, CRUD, data aggregation |
71+
| 090 | [Automation Bot / Mini API](modules/module-090-mini-project-automation-bot/project/README.md) | FastAPI, file automation, scheduling |
72+
| 099 | [Capstone: Full-Stack Application](modules/module-099-capstone-project/project/README.md) | FastAPI, SQLAlchemy, Jinja2, Pydantic, logging, deployment |
73+
74+
Each project includes a `README.md` with numbered requirements and stretch goals, `starter_code.py` with TODO markers, and a complete reference `solution/` implementation.
75+
76+
## Module Format
77+
78+
Every module (000–100) follows a consistent structure:
79+
80+
| File | Purpose |
81+
|---|---|
82+
| `README.md` | Full lesson: prerequisites, learning objectives, concept explanation (with analogies, diagrams, code examples), common pitfalls, hands-on walkthrough, key takeaways, further reading, next module link |
83+
| `notebook.ipynb` | Runnable Jupyter notebook mirroring the lesson — markdown explanations and executable code cells |
84+
| `exercises.md` | 4–6 exercises per module, ordered Warm-up → Core → Challenge → Stretch, with starter signatures and expected output |
85+
| `solutions.md` / `solutions.py` | Clearly labeled worked solutions for all exercises (`.py` for milestone modules) |
86+
| `quiz.md` | 5–8 questions: multiple-choice, "what does this output?", short answer, debugging — answer key under `## Answers` |
87+
| `project/` (milestones only) | Project brief, starter code, and full reference solution |
88+
89+
### Code Style Progression
90+
91+
- Modules 002–030: Basic PEP 8 conventions
92+
- Modules 031+: Google-style docstrings on all functions
93+
- Modules 073+: Type hints on all code (enforced with mypy conventions)
2594

2695
## Quickstart
2796

97+
### Prerequisites
98+
99+
- **Python 3.12+** — [Download](https://www.python.org/downloads/) | [Setup Guide](SETUP.md)
100+
- **Git** — [Download](https://git-scm.com/downloads)
101+
- **VS Code** (recommended) — [Download](https://code.visualstudio.com/)
102+
103+
### One-Line Install
104+
28105
```bash
106+
git clone https://github.com/your-org/Stack.Python.git && cd Stack.Python && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
107+
```
108+
109+
### Step by Step
110+
111+
```bash
112+
# 1. Clone the repository
29113
git clone https://github.com/your-org/Stack.Python.git
30114
cd Stack.Python
115+
116+
# 2. Create and activate a virtual environment
117+
# macOS/Linux:
31118
python3.12 -m venv venv
32-
source venv/bin/activate # Windows: venv\Scripts\activate
119+
source venv/bin/activate
120+
121+
# Windows (Command Prompt):
122+
python -m venv venv
123+
venv\Scripts\activate
124+
125+
# Windows (PowerShell):
126+
python -m venv venv
127+
.\venv\Scripts\Activate.ps1
128+
129+
# 3. Install dependencies
130+
pip install --upgrade pip
33131
pip install -r requirements.txt
132+
133+
# 4. Start learning!
134+
open modules/module-000-introduction-to-python/README.md
34135
```
35136

36-
Then open `modules/module-000-introduction-to-python/README.md` and start learning!
137+
### Verify Installation
138+
139+
```bash
140+
python -c "import jupyter, pytest, requests, pandas; print('All dependencies installed!')"
141+
```
37142

38143
## How to Use This Repo
39144

40-
1. **Go in order.** Each module assumes you know everything from all prior modules.
41-
2. **Read the lesson.** Start with `README.md` for each module.
42-
3. **Follow the notebook.** Open `notebook.ipynb` and run the examples interactively.
43-
4. **Do the exercises.** Attempt `exercises.md` before checking `solutions.py`/`solutions.md`.
44-
5. **Take the quiz.** `quiz.md` helps reinforce what you learned.
45-
6. **Build the projects.** Milestone modules have a `project/` folder with real builds.
46-
7. **Track progress.** Run `python scripts/check_progress.py` to see your completion status.
145+
### For Learners
146+
147+
1. **Go in order.** Each module assumes all prior knowledge. Skipping ahead will leave you lost.
148+
2. **Read the lesson first.** Start with `README.md` — it contains the full explanation.
149+
3. **Run the notebook.** Open `notebook.ipynb` and execute every cell. Experiment by changing values.
150+
4. **Do the exercises.** Open `exercises.md` and attempt every problem **before** looking at solutions.
151+
5. **Check your work.** Compare with `solutions.md` (or `solutions.py` for milestone modules).
152+
6. **Take the quiz.** `quiz.md` reinforces key concepts. Cover the answer key at the bottom.
153+
7. **Build the projects.** For milestone modules, the `project/` folder contains a real-world build.
154+
8. **Track your progress.** Run `python scripts/check_progress.py --completed 0 1 2 ...` to see your completion status.
155+
156+
### For Instructors
157+
158+
- Fork the repository and adapt any module to your teaching style.
159+
- Use modules as-is for a semester-long course (roughly 1 module per day).
160+
- Assign milestone projects as midterms or final projects.
161+
- Run `python scripts/run_all_notebooks.py` to verify all notebooks execute correctly.
162+
163+
### Tips
164+
165+
- **Code along.** Typing the examples yourself (rather than copy-pasting) builds muscle memory.
166+
- **Break things.** Modify code examples to see what happens. Errors are learning opportunities.
167+
- **Use the quizzes.** Each quiz is designed to reveal gaps in understanding — don't skip them.
168+
- **Compare solutions.** Your solution doesn't need to match exactly, but understand why approaches differ.
169+
- **Revisit modules.** If you're stuck on a later concept, the problem is often in a prerequisite module.
170+
171+
## Scripts & Tooling
172+
173+
| Script | Purpose |
174+
|---|---|
175+
| `scripts/new_module.py` | Scaffold a new module folder from the standard template |
176+
| `scripts/check_progress.py` | CLI progress tracker — shows completed/total modules by phase |
177+
| `scripts/run_all_notebooks.py` | Dev utility — executes all notebooks via papermill |
178+
179+
```bash
180+
# Create a new module scaffold
181+
python scripts/new_module.py --number 42 --title "My Module" --phase "My Phase"
182+
183+
# Check progress (mark modules 0, 1, 2, 3 as complete)
184+
python scripts/check_progress.py --completed 0 1 2 3
185+
186+
# Run all notebooks (CI use-case)
187+
python scripts/run_all_notebooks.py
188+
189+
# Run notebooks in parallel
190+
python scripts/run_all_notebooks.py --parallel
191+
192+
# Run a range
193+
python scripts/run_all_notebooks.py --start 0 --end 10
194+
```
195+
196+
### CI/CD
197+
198+
This repository includes GitHub Actions workflows:
199+
200+
- **notebook-check.yml** — Executes all notebooks headlessly via papermill on every push/PR
201+
- **link-check.yml** — Validates all internal markdown links resolve correctly
202+
203+
## Project Structure
204+
205+
```
206+
Stack.Python/
207+
├── README.md
208+
├── LICENSE
209+
├── CONTRIBUTING.md
210+
├── CURRICULUM.md # Full linked table of contents (all 101 modules)
211+
├── SETUP.md # Environment setup guide (Windows/macOS/Linux)
212+
├── requirements.txt # 17 base dependencies
213+
├── pyproject.toml # Black, ruff, mypy configuration
214+
├── .gitignore
215+
├── .github/workflows/
216+
│ ├── notebook-check.yml
217+
│ └── link-check.yml
218+
├── scripts/
219+
│ ├── new_module.py
220+
│ ├── check_progress.py
221+
│ └── run_all_notebooks.py
222+
├── assets/diagrams/
223+
└── modules/
224+
├── module-000-introduction-to-python/
225+
├── module-001-setting-up-your-environment/
226+
├── ...
227+
└── module-100-where-to-go-next/
228+
```
47229

48230
## Contributing
49231

50-
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose fixes, additions, or improvements.
232+
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
233+
234+
Quick summary:
235+
- **Issues:** Report bugs, content errors, or suggestions via GitHub Issues
236+
- **PRs:** Fork, create a feature branch, make changes, run quality checks (`black . && ruff check .`), submit a PR
237+
- **Content:** All code must be valid Python 3.12+, follow PEP 8, use Google-style docstrings (modules 031+), and include type hints (modules 073+)
238+
- **No forward references:** Never introduce a concept in module N that won't be taught until module N+X
51239

52240
## License
53241

54-
MIT — see [LICENSE](LICENSE).
242+
MIT — see [LICENSE](LICENSE). Free to use, modify, and distribute for teaching, learning, or commercial purposes.

0 commit comments

Comments
 (0)