This document provides a high-level introduction to the afterpython system architecture, explaining its purpose as a unified CLI tool for Python package maintenance and project website generation. It describes the major subsystems, their interactions, and how they work together to automate common package maintenance tasks.
For detailed information about specific subsystems, see:
afterpython is a command-line tool that orchestrates multiple external tools to automate Python package maintenance workflows. The system provides two primary capabilities:
uv and pixi), version bumping (via commitizen), code quality (via ruff and pre-commit), and automated releasesThe tool follows a "zero-config orchestration" philosophy—it provides opinionated defaults and abstracts tool-specific complexity behind a unified ap command interface.
Sources: README.md29-48 afterpython/doc/overview.md17-31
The afterpython system consists of four major subsystems orchestrated by a central CLI:
Figure 1: Complete System Architecture
The central ap CLI (entry point at src/afterpython/main.py60) orchestrates four major subsystems. Each subsystem wraps one or more external tools and provides simplified commands. Configuration flows from standard Python files (pyproject.toml1-73) through extended configs (afterpython.toml) to content-specific configs (myst.yml files). Quality assurance operates at three levels: pre-commit hooks for immediate feedback, CI workflows for validation, and deployment/release workflows for production.
Sources: pyproject.toml1-73 README.md84-95 High-level diagram 1
The system provides two CLI entry points defined in pyproject.toml59-61:
| Entry Point | Command | Purpose | Implementation |
|---|---|---|---|
ap | Main CLI | Primary interface for all operations | src/afterpython/main.py60 |
pcu | Dependency updater | Check and update package versions | src/afterpython/main.py76 |
Figure 2: CLI Architecture and Command Routing
The ap command uses Click framework for command-line parsing. Each command in src/afterpython/cli/commands/ wraps and orchestrates one or more external tools. The ap bump command (src/afterpython/cli/commands/bump.py25-119) demonstrates this pattern: it parses version metadata from pyproject.toml invokes commitizen with calculated arguments, and updates pixi.lock after successful bumps.
Sources: pyproject.toml59-61 src/afterpython/cli/commands/bump.py1-119
The package management subsystem uses a dual-strategy approach:
| Tool | File | Purpose |
|---|---|---|
uv | uv.lock1-3 | Python package resolution and build backend |
pixi | pixi.lock1-10 | Multi-environment testing (py311-314) and conda packages |
pnpm | _website/pnpm-lock.yaml | Node.js dependencies for website |
The uv package manager (pyproject.toml66-68) serves as the build backend and handles Python dependencies. The pixi package manager provides environment isolation for testing across Python versions and includes system-level dependencies like the gh CLI (pixi.lock16).
Sources: pyproject.toml34-52 pyproject.toml66-68 uv.lock1-3 pixi.lock1-37 High-level diagram 6
The versioning subsystem uses commitizen for semantic version management:
The ap bump command provides three modes:
--pre: Transitions from dev to pre-release or advances pre-release type--release: Bumps to stable release and auto-pushes tags to trigger workflowsSources: src/afterpython/cli/commands/bump.py25-119 pyproject.toml3 High-level diagram 2
The content system processes five content types, each with independent configuration:
Figure 3: Content Type System
Each content type directory contains MyST Markdown or Jupyter Notebook files. The myst build --html command processes each type independently, generating HTML into _build/html/ directories. The postbuild phase consolidates these artifacts into _website/static/ where the SvelteKit application consumes them.
Sources: High-level diagram 7, afterpython/doc/overview.md24
The website generator uses SvelteKit for static site generation:
pnpm build produces static outputThe website integrates all content types and provides navigation, search (planned via PageFind), and AI chatbot capabilities (planned via WebLLM).
Sources: README.md51-59 afterpython/doc/overview.md25-30 High-level diagram 7
The system implements unidirectional configuration flow:
Figure 4: Configuration Synchronization Flow
The ap sync command (src/afterpython/cli/commands/sync.py) reads metadata from pyproject.toml1-73 (project name, authors, URLs) and afterpython.toml (company info, website config) and propagates it to derived configurations. This ensures all MyST builds use consistent metadata for project identification, author attribution, and site branding.
Sources: pyproject.toml1-73 High-level diagram 4
The system enforces quality through three progressive gates:
| Stage | Tool | Trigger | Configuration |
|---|---|---|---|
| Pre-commit | ruff, commitizen | git commit | .pre-commit-config.yaml |
| CI | GitHub Actions | git push | .github/workflows/ci.yml |
| Deployment | GitHub Actions | Content changes | .github/workflows/deploy.yml |
| Release | GitHub Actions | Version tags | .github/workflows/release.yml |
Pre-commit hooks (.pre-commit-config.yaml) run before each commit to check code formatting, trailing whitespace, file sizes, and commit message format. The CI workflow (.github/workflows/ci.yml) runs comprehensive tests across Python versions. Deployment and release workflows trigger conditionally based on file changes or git tags.
Sources: High-level diagram 5, .gitignore168-170
The following table maps major system functions to their implementation:
| Function | Primary File(s) | External Tools |
|---|---|---|
| CLI entry point | src/afterpython/main.py60-76 | Click |
| Project initialization | src/afterpython/cli/commands/init.py | uv, pixi, pnpm |
| Version bumping | src/afterpython/cli/commands/bump.py25-119 | commitizen |
| Content building | src/afterpython/cli/commands/build.py | myst, pnpm |
| Development server | src/afterpython/cli/commands/dev.py | myst, pnpm |
| Config synchronization | src/afterpython/cli/commands/sync.py | - |
| Metadata reading | src/afterpython/tools/pyproject.py | pyproject-metadata |
| Dependency updates | src/afterpython/main.py76 (pcu) | - |
Sources: pyproject.toml59-61 src/afterpython/cli/commands/bump.py1-119
The typical development workflow follows this sequence:
.md or .ipynb files in content type directoriesap dev to start development serversap bump to increment versionThe ap CLI orchestrates these steps by wrapping external tools with simplified commands. For example, ap init (src/afterpython/cli/commands/init.py) runs uv sync, pixi install, and pnpm install in sequence to bootstrap a complete development environment.
Sources: High-level diagram 5, README.md63-80
Refresh this wiki