This section provides quick reference materials for working with the afterpython system. It includes configuration architecture diagrams, package entry points, core dependencies, build pipelines, file paths, Python version support, and links to detailed subsections for file listings, environment variables, and terminology.
For detailed configuration file documentation, see Configuration Files.
For comprehensive CLI command documentation, see CLI Commands.
For build system details, see Build System Architecture.
The afterpython system uses a layered configuration architecture with multiple interconnected files:
Diagram: Configuration File Relationships
The configuration system has three layers:
pyproject.toml, afterpython.toml, and .envauthors.yml and myst.yml files via ap syncuv.lock and pixi.lockSources: pyproject.toml1-74 afterpython/afterpython.toml1-8 .env.example1-3
The afterpython package provides two CLI entry points:
| Entry Point | Module | Purpose |
|---|---|---|
ap | afterpython.main:run_cli | Main CLI interface for all project operations including ap init, ap dev, ap build, etc. |
pcu | afterpython.main:run_pcu | Python Check Updates utility for dependency version checking and updates |
The ap command is the primary entry point for all afterpython functionality, while pcu can be invoked as a standalone tool (aliased to ap update deps).
Sources: pyproject.toml59-61
Diagram: CLI Command Hierarchy with Code Locations
All commands are accessed via the ap entry point defined in afterpython.main:run_cli. Each command is implemented in its own module under src/afterpython/cli/commands/.
Sources: src/afterpython/cli/commands/init.py src/afterpython/cli/commands/dev.py src/afterpython/cli/commands/bump.py
The afterpython system integrates several key tools as core dependencies:
| Package | Purpose | Usage in Codebase |
|---|---|---|
click | CLI framework | Command definitions in src/afterpython/cli/commands/ |
trogon | TUI interface | ap tui command |
mystmd | Content processing | MyST Markdown to HTML conversion for all content types |
pdoc | API documentation | Planned API reference generation |
ruff | Linting and formatting | ap lint and ap format commands |
pre-commit | Git hook management | .pre-commit-config.yaml enforcement |
commitizen | Conventional commits | ap commit and ap bump commands, cz.toml configuration |
httpx | HTTP client | API interactions and external requests |
gitpython | Git operations | Repository interaction in build/release workflows |
pygithub | GitHub API | Branch protection rules setup |
tomlkit | TOML manipulation | Reading/writing pyproject.toml, afterpython.toml, cz.toml |
ruamel-yaml | YAML manipulation | Reading/writing myst.yml, authors.yml |
pyproject-metadata | Metadata extraction | Parsing project metadata from pyproject.toml |
python-dotenv | Environment variables | Loading .env files for AP_AUTO_SYNC, AP_MOLAB_BADGE |
Sources: pyproject.toml34-52 README.md84-95 afterpython/doc/overview.md45-58
Diagram: Package Manager Ecosystem
The system uses three package managers for different dependency types, each with its own configuration, lock file, and installation location.
Sources: pyproject.toml1-74
The version management system supports different bump strategies:
Diagram: Version Bump Strategy Decision Tree
The ap bump command intelligently detects the current version type and applies appropriate bumping logic:
--pre transitions from dev to pre-release--release creates stable versions and auto-pushes git tagsSources: src/afterpython/cli/commands/bump.py25-98
Diagram: Build Pipeline Stages
The build process follows a strict sequential order with dependencies between phases.
| Path Pattern | Type | Purpose | Generated/Manual |
|---|---|---|---|
pyproject.toml | File | Primary project metadata (Python standard) | Manual |
afterpython.toml | File | Extended configuration (company, website) | Manual |
.env | File | Runtime environment variables | Manual |
uv.lock | File | Python dependency lock (via uv) | Generated |
pixi.lock | File | System dependency lock (via pixi) | Generated |
pixi.toml | File | Pixi workspace configuration | Manual |
.pre-commit-config.yaml | File | Pre-commit hook configuration | Manual |
cz.toml | File | Commitizen configuration | Manual |
afterpython/ | Directory | Main content root directory | Manual |
afterpython/doc/ | Directory | Documentation content (MyST) | Manual |
afterpython/blog/ | Directory | Blog posts (MyST) | Manual |
afterpython/tutorial/ | Directory | Tutorial content (MyST) | Manual |
afterpython/example/ | Directory | Example code/notebooks (MyST) | Manual |
afterpython/guide/ | Directory | How-to guides (MyST) | Manual |
afterpython/_website/ | Directory | SvelteKit website source | Manual |
afterpython/_website/static/ | Directory | Aggregated content from all types | Generated |
afterpython/_website/build/ | Directory | Production build output | Generated |
afterpython/static/ | Directory | Global static assets (images, etc.) | Manual |
afterpython/authors.yml | File | Author metadata | Generated (ap sync) |
afterpython/doc/myst.yml | File | MyST config for docs | Generated (ap sync) |
afterpython/blog/myst.yml | File | MyST config for blog | Generated (ap sync) |
afterpython/tutorial/myst.yml | File | MyST config for tutorials | Generated (ap sync) |
afterpython/example/myst.yml | File | MyST config for examples | Generated (ap sync) |
afterpython/guide/myst.yml | File | MyST config for guides | Generated (ap sync) |
src/afterpython/ | Directory | Package source code | Manual |
src/afterpython/cli/commands/ | Directory | CLI command implementations | Manual |
src/afterpython/builders/ | Directory | Build system modules | Manual |
.venv/ | Directory | Python virtual environment (uv) | Generated |
.pixi/ | Directory | Pixi environment | Generated |
_build/ | Directory | MyST build output (temporary) | Generated |
.gitignore | File | Git ignore patterns | Manual |
Sources: .gitignore1-215 afterpython/afterpython.toml1-16 .env.example1-3
The project supports the following Python versions:
| Version | Status | Testing Environment |
|---|---|---|
| 3.11 | ✅ Supported | py311 pixi environment |
| 3.12 | ✅ Supported | py312 pixi environment |
| 3.13 | ✅ Supported | py313 pixi environment |
| 3.14 | 🧪 Experimental | py314 pixi environment |
Minimum required version: Python 3.11
The pixi.toml file defines separate environments for each Python version, enabling multi-version testing via pixi run -e py311 test, pixi run -e py312 test, etc. The CI workflow uses a matrix strategy to test across all supported versions.
Sources: pyproject.toml28-33 pixi.toml
Afterpython orchestrates several external command-line tools:
| Tool | Package Manager | Usage in Commands | Configuration File |
|---|---|---|---|
uv | Self-contained | ap install, ap lock, ap build | pyproject.toml (dependencies) |
pixi | Self-contained | ap install, ap lock, multi-version testing | pixi.toml |
pnpm | Node.js package manager | Website build (ap build, ap dev) | _website/package.json |
mystmd | Python package | Content build for all types | */myst.yml files |
ruff | Python package | ap lint, ap format | pyproject.toml (tool.ruff) |
commitizen | Python package | ap commit, ap bump | cz.toml |
pre-commit | Python package | Git hooks | .pre-commit-config.yaml |
gh (GitHub CLI) | System package | ap init-branch-rules | N/A |
The dual dependency strategy uses uv for Python packages (fast, Python-focused) and pixi for system-level packages and multi-version environments (Conda + PyPI).
Sources: README.md84-96 pyproject.toml63-65
| Field | Value | Purpose |
|---|---|---|
requires | ["uv_build>=0.9.13,<0.10.0"] | Build backend dependency |
build-backend | "uv_build" | Backend to use for package building |
module-name | "afterpython" | Package name |
module-root | "src" | Source code location (src-layout) |
The project uses a src-layout structure where package code resides in src/afterpython/ rather than directly in the repository root. This is a Python packaging best practice that prevents accidental imports of the development version.
The uv_build backend is used for building distributions, configured in the [build-system] section of pyproject.toml.
Sources: pyproject.toml67-73
This section contains the following reference materials:
AP_AUTO_SYNC, AP_MOLAB_BADGE, BASE_PATH, BASE_URLSources: pyproject.toml1-74 afterpython/afterpython.toml1-8 .env.example1-3 src/afterpython/cli/commands/bump.py1-119 afterpython/doc/references/environment_variables.md1-9
Refresh this wiki