Architecture Tour

Architecture Tour

Pythonlings separates command handling and terminal UI from the reusable core so curriculum and verification behavior can be exercised without loading Textual.

flowchart LR
    CLI[CLI] --> Workspace[Workspace resolution]
    Workspace --> Data[Manifest and state]
    Data --> TUI[Textual UI]
    TUI --> Runner[Runner and checks]
    Runner --> Progress[Progress]
    Progress --> Data

Loading

Entry points and workspace

pythonlings/cli.py parses commands and keeps Textual imports out of one-shot command paths. pythonlings/core/workspace.py resolves a workspace in this order: an explicit --root, the current directory when it contains info.toml, then the default workspace. Commands that launch the UI can create that default workspace when needed.

pythonlings/core/curriculum.py creates and updates workspaces from the packaged curriculum. An update refreshes the manifest, checks, solutions, and reset snapshots while leaving existing learner exercise files in place. That preservation is intentional.

Core modules

• manifest.py loads info.toml, validates exercise paths, and derives mirrored check paths.
• exercise.py defines an exercise and its completion marker.
• runner.py runs an exercise and its check together in an isolated subprocess with the default timeout.
• state.py records completed exercises and resume information with atomic writes. If state cannot be read, it is moved to a .bak file for corrupt-state recovery before a fresh state is used.
• reset.py restores an exercise from a saved original snapshot.
• solutions.py locates the reference-solution loader for verification.
• docs.py loads bundled documentation snippets and returns no snippet when no bundled match is available.

Textual application and curriculum

pythonlings/app.py owns the application state and chooses a resume or first-pending target. pythonlings/screens/track.py writes edits, runs checks, records completion, and advances within the selected topic. The Textual documentation screen displays local material when available and opens the exercise's official documentation URL separately.

The curriculum lives in exercises/, checks/, solutions/, and info.toml. Bundled reference material lives under pythonlings/docs/. The Curriculum Authoring Guide describes the synchronization rules that keep these sources coherent.