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 CLI tool that abstracts away the complexity of content writing, website deployment, and package release/maintenance by providing an opinionated set of modern tools. It allows developers to go from writing code to publishing a package and a dedicated project website in minutes.
The system provides two primary capabilities:
uv and pixi), version bumping (via commitizen), code quality (via ruff and pre-commit), and automated releases.Sources: README.md31-51 pyproject.toml4-21
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 pyproject.toml60) 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).
Sources: pyproject.toml1-73 README.md86-99
The system provides two CLI entry points:
| Entry Point | Command | Purpose | Implementation |
|---|---|---|---|
ap | Main CLI | Primary interface for all operations | pyproject.toml60 |
pcu | Dependency updater | Check and update package versions | pyproject.toml61 |
Figure 2: CLI Architecture and Tool Orchestration
The ap command uses the Click framework for command-line parsing and trogon for a Terminal User Interface (TUI). It orchestrates modern tools like uv for dependency resolution pyproject.toml66-68 ruff for linting pyproject.toml48 and mystmd for content processing pyproject.toml46
Sources: pyproject.toml35-61 README.md75-84
Uses a dual-strategy approach with uv and pixi. uv serves as the build backend pyproject.toml66-68 and handles Python-specific dependencies pyproject.toml34-52 pixi (if configured) handles multi-environment testing and system-level dependencies. Node.js dependencies for the website are managed via pnpm.
Leverages commitizen pyproject.toml50 for semantic version management. It enforces conventional commits via pre-commit hooks and automates version bumping in pyproject.toml pyproject.toml3
Processes five content types (doc, blog, tutorial, example, guide) using mystmd pyproject.toml46 It allows writing content directly in [MyST Markdown] or [Jupyter Notebook] README.md44 These are then integrated into a SvelteKit-based website template README.md88
The system enforces quality through three progressive gates:
ruff and commitizen validation before each commit pyproject.toml48-50Sources: README.md86-96 pyproject.toml22-32
The typical development workflow follows this sequence:
ap init sets up the project structure and tools README.md70ap dev for live-reloading of content and website.ap sync to ensure metadata is consistent across configs.ap commit (via commitizen) for conventional commits.ap bump and ap release to publish the package and website.Sources: README.md64-84 pyproject.toml59-61