Python Learning Path -- Test-Driven Socratic Learning System

Why This Exists

This repository is an AI-powered adaptive teaching system for advanced Python concepts. It uses Socratic methodology to make runtime behavior observable and verifiable—you predict behavior, run instrumented code, and learn from evidence rather than from long explanations. The AI adapts to your skill level, asking targeted questions that build understanding through mechanism-based reasoning. All exercises work standalone without AI, but the full Socratic experience is available through Cursor IDE.

Who This Is For

Primary audience: Developers with solid Python fundamentals (or strong experience in another systems language such as C++) who want mechanism-level practice with asyncio, coroutines, and related topics.

If you are earlier in your career: Say "profile: junior" in Cursor chat for beginner-friendly depth, proactive hints, and scaffolding. The exercises are the same; the mentor behavior is gentler.

If you are new to programming or to Python: This repo is not a zero-to-hero introduction. Use an introductory Python course or book first, then use this path for mechanism-level practice.

The AI teaching system adapts across five skill levels (Junior → Intermediate → Senior → Staff → Principal) with configurable pacing, questioning style, and feedback depth. Default profile: Senior (see .cursor/rules/socratic-software-engineering.mdc).

AI Socratic Teaching System

• Q/A/R Pattern — Inline questions (# Q:), your answers (# A:), and AI feedback (# R:) written directly into code files. The AI validates your reasoning against actual test behavior.
• Evidence-Based Validation — Mental models are tested against observable runtime behavior via EventLog and assertions.
• Observable Instrumentation — EventLog captures named events so you can verify predictions.
• Adaptive Questioning — Questioning style, hint policy, verification rigor, and response depth follow your selected skill level.

Developer-driven questions (DQ/DR)

When you ask a question in code, use # DQ: for your question and # DR: for the mentor’s response. Questions asked only in chat are answered in chat.

Skill Profiles

Activate a profile by stating the exact override string (e.g., "profile: staff") in Cursor chat:

• Junior — "profile: junior"
• Intermediate — "profile: intermediate"
• Senior — "profile: senior" (default)
• Staff — "profile: staff"
• Principal — "profile: principal"

See Teaching Method and .cursor/rules/ for the full preference list.

Quickstart

1. Prerequisites — Python 3.11+
2. Install — python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
3. Try it — pytest examples/test_try_it_out.py -v
4. Next — Start with learning_asyncio or follow Full Curriculum.

Modules (high level)

Registered test counts are lesson files under each module’s tests/ directory (what pytest collects).

Module	Registered tests	Topic (short)
learning_asyncio	4	Coroutines, tasks/gather, Event/Queue, cancellation/timeouts/shield
examples	1	Onboarding test

Full curriculum and structure

• Curriculum, prerequisites, and order: docs/LEARNING_PATH.md
• Teaching method: docs/TEACHING_METHOD.md
• Install and pytest notes: docs/BUILDING.md

Repository layout

<repo_root>/
├── README.md
├── pyproject.toml
├── .cursor/rules/          # Socratic rules and profiles
├── common/                 # EventLog instrumentation package
├── docs/                   # BUILDING, LEARNING_PATH, TEACHING_METHOD
├── examples/
└── learning_*/             # One directory per topic

Building and running

pip install -e ".[dev]"
pytest -v
pytest learning_asyncio/tests/test_coroutine_basics.py -v --tb=short

Contributing

See .github/CONTRIBUTING.md.