How hynek/hatch-fancy-pypi-readme works
Project Type and Purpose
• This is an open-source Python library and Hatch plugin named hatch-fancy-pypi-readme.
• It provides a dynamic readme builder for PyPI projects: concatenating fragments from text, files, or regex-sliced sections, then applying regex substitutions.
• It exposes two interfaces:
• As a Hatch metadata hook when building a package
• As a standalone CLI tool (hatch-fancy-pypi-readme or python -m hatch_fancy_pypi_readme)
File Structure Analysis
• Top-level directories and files:
• .github/ – CI workflows and contribution guidelines
• src/hatch_fancy_pypi_readme/ – core package code
• tests/ – unit and end-to-end tests plus fixtures
• pyproject.toml – build system config (Hatch, plugin installation, CLI entry points)
• tox.ini, pre-commit config – development tooling
• Inside src/hatch_fancy_pypi_readme/:
• _cli.py & __main__.py – CLI entry point and argument parsing
• _config.py – parsing TOML configuration from pyproject.toml
• _builder.py – orchestrates fragment assembly and substitutions
• _fragments.py – logic for each fragment type (text, file, slicing by markers or regex)
• _substitutions.py – regex-based search & replace engine
• hooks.py – Hatch hook implementations to inject into the packaging pipeline
• exceptions.py – custom error types
• Tests mirror these modules, verifying behavior end-to-end and per component.
Architectural Components
a. Interfaces
• CLI Interface
• Hatch Metadata Hook
b. Core Modules
• Configuration Parser
• Builder / Orchestrator
• Fragment Processor
• Substitution Processor
c. External Integrations
• File System (reading fragment source files)
• Regex Engine (re module)
• Hatch build backend (invokes hooks.py)
• STDOUT or file output (CLI)
d. Data Flow
1. User runs CLI or invokes Hatch build →
2. Configuration Parser loads pyproject.toml fragment & substitution definitions →
3. Builder iterates fragments:
• Text fragments: pass through
• File fragments: File System → optionally slice via _fragments logic
4. Builder assembles full readme string → passes it to Substitution Processor →
5. Final readme emitted to STDOUT (CLI) or returned to Hatch for packaging.
Key Architectural Patterns and Principles
• Single-Responsibility: each module handles exactly one aspect (parsing, building, fragment logic, substitution).
• Dependency Injection: CLI and Hatch hook both depend on the same core builder logic.
• Modular Extensibility: new fragment types or substitution behaviors can be added without modifying the orchestrator.
• Minimal side-effects: I/O is confined to specific modules (_fragments for file I/O, CLI for output).