Overview

Relevant source files

• .gitignore
• README.md
• afterpython/doc/overview.md

This document provides a high-level introduction to the afterpython system, explaining its purpose, core components, and how they interact. For detailed information about specific subsystems, see the child pages: System Architecture, Key Features and Concepts, Technology Stack, and Project Roadmap.

Purpose and Scope

afterpython is a CLI tool that automates Python package maintenance and generates dedicated project websites. It addresses the complexity barrier that prevents developers from efficiently publishing and maintaining Python packages by providing zero-configuration orchestration of modern development tools.

Scope: This system handles:

• Project initialization and configuration management
• Content authoring in MyST Markdown and Jupyter Notebooks
• Static website generation and deployment
• Version management and release automation
• Code quality enforcement and CI/CD workflows

Out of scope: afterpython does not provide package hosting (relies on PyPI) or custom build backends beyond what uv_build provides.

What is AfterPython

AfterPython is implemented as a Python package that exposes two main entry points defined in pyproject.toml59-61:

• ap - The primary CLI for all package maintenance operations
• pcu - Python Check Updates utility for dependency management

The system integrates multiple tools into a cohesive workflow, abstracting their individual complexities behind simple commands. It manages configuration synchronization across multiple formats (pyproject.toml, afterpython.toml, myst.yml, authors.yml) and orchestrates build processes for both content (via MyST) and websites (via SvelteKit).

Sources: pyproject.toml1-74 README.md29-38

Core System Components

Component Descriptions:

Component	File/Directory	Purpose
Primary CLI	ap entry point	Main command interface for all operations
Update Utility	pcu entry point	Dependency version checking and updating
Core Config	pyproject.toml	Package metadata, dependencies, build system
Extended Config	afterpython.toml	Company info, website URL
System Dependencies	pixi.toml	Cross-platform system packages
Python Lock	uv.lock	~150+ Python packages with hashes
System Lock	pixi.lock	Python + Node.js + system tools
Content Directories	afterpython/{doc,blog,tutorial,example,guide}/	Source files for each content type
MyST Configs	{content-type}/myst.yml	Per-type build configuration
Author Database	authors.yml	Centralized author metadata
Website Base	afterpython/_website/	SvelteKit application
Static Assets	afterpython/static/	Logos, favicons, images
MyST Output	_build/	Intermediate HTML from MyST
Final Site	_website/build/	Deployable static website

Sources: pyproject.toml1-74 uv.lock1-150 pixi.lock1-300 Diagram 1 and Diagram 3 from high-level architecture

Command Flow and Operations

Command Categories:

Category	Commands	Module Location
Initialization	ap init, ap init-branch-rules	afterpython.cli.commands.init
Configuration	ap sync	afterpython.cli.commands.sync
Development	ap dev, ap start, ap doc, ap blog, etc.	afterpython.cli.commands.dev
Building	ap build, ap preview	afterpython.cli.commands.build
Dependencies	ap install, ap lock, ap update	afterpython.cli.commands.install
Quality	ap check, ap format, ap pre-commit	afterpython.cli.commands.lint
Versioning	ap commit, ap bump, ap release	afterpython.cli.commands.bump

Sources: src/afterpython/cli/commands/bump.py1-119 Diagram 2 and Diagram 4 from high-level architecture

Configuration Synchronization Flow

Configuration Details:

The ap sync command serves as the configuration reconciliation system. It reads from pyproject.toml (using pyproject_metadata library) and afterpython.toml, then generates:

1. authors.yml: Centralized author database extracted from pyproject.toml authors field
2. Five myst.yml files: One per content type (doc, blog, tutorial, example, guide), each containing:
   • Project metadata (name, version, description)
   • Website URL from afterpython.toml
   • Author references pointing to authors.yml
   • Content-type-specific settings

The synchronization is controlled by:

• AP_AUTO_SYNC environment variable: When set, automatically runs ap sync before builds
• Manual invocation: ap sync command can be run explicitly

Sources: pyproject.toml1-74 Diagram 3 and Diagram 5 from high-level architecture

Package Dependencies

AfterPython uses a dual dependency management strategy:

Python Dependencies (via uv):

• Managed in pyproject.toml34-52
• Locked in uv.lock with ~150+ transitive dependencies
• Key dependencies: click, trogon, mystmd, pdoc, ruff, pre-commit, commitizen, pygithub, httpx, tomlkit, ruamel-yaml, gitpython, python-dotenv, pyproject-metadata
• Build system: uv_build pyproject.toml67-73

System Dependencies (via pixi):

• Managed in pixi.toml
• Locked in pixi.lock with cross-platform packages
• Includes: Python interpreters (3.11-3.13), Node.js, gh CLI, mystmd conda package, uv
• Supports multiple environments and task definitions

Dependency Override: The system overrides restrictive version constraints from mystmd package for platformdirs and nodeenv pyproject.toml63-65

Sources: pyproject.toml34-52 pyproject.toml63-73 uv.lock1-150 pixi.lock1-300

Build and Deployment Pipeline

Pipeline Stages:

1. Pre-build: Cleaning and optional badge injection based on AP_MOLAB_BADGE environment variable
2. Content Build: Parallel MyST builds for each content type, producing HTML in _build/
3. Website Assembly: Copying MyST outputs and static assets into _website/, then running pnpm build
4. Deployment: GitHub Actions workflow uploads artifact and deploys to GitHub Pages

Environment Variables:

• BASE_PATH: Derived from website URL for correct routing in subdirectories
• BASE_URL: Full website URL from afterpython.toml
• AP_MOLAB_BADGE: Controls Molab badge injection
• AP_AUTO_SYNC: Controls automatic config synchronization

Sources: Diagram 3 from high-level architecture, README.md1-97

Version Management System

The version management system in AfterPython uses semantic versioning with PEP 440 compliance:

Version Bump Logic src/afterpython/cli/commands/bump.py26-98:

1. Development versions (e.g., 0.1.0.dev3): By default, increments dev number (0.1.0.dev4)
2. Pre-releases (e.g., 0.1.0a1): Increments within phase (0.1.0a2)
3. Release versions (e.g., 0.1.0): Uses commitizen's semantic bump

Command Options:

• ap bump: Default behavior (stay in current phase)
• ap bump --pre: Transition to/increment pre-release
• ap bump --release: Bump to stable version and auto-push tag

Post-Bump Actions src/afterpython/cli/commands/bump.py93-118:

1. Update pixi.lock via pixi install (for editable installs)
2. Auto-commit pixi.lock changes with conventional commit message
3. For release bumps: Auto-push tag to trigger GitHub release workflow

Sources: src/afterpython/cli/commands/bump.py1-119 Diagram 4 from high-level architecture

CI/CD Integration

AfterPython includes three GitHub Actions workflows:

Workflow	Trigger	Purpose	File Location
ci.yml	Push to main, PRs	Linting, testing (Python 3.11-3.13), package building	.github/workflows/ci.yml
deploy.yml	Push to main (content changes)	Build website, deploy to GitHub Pages	.github/workflows/deploy.yml
release.yml	Tags matching v*	Build package, publish to PyPI, create GitHub release	.github/workflows/release.yml

Branch Protection: The ap init-branch-rules command configures GitHub branch protection rulesets to require CI passage before merging.

Sources: Diagram 2 from high-level architecture, README.md19-27