How ninoseki/uv-dynamic-versioning works
To accurately represent the architecture of uv-dynamic-versioning, we will break down the system into its core components, show their interactions, and highlight how this plugin-based Python package integrates into the uv/hatch build pipeline and with the VCS (Git). Follow these steps:
Main Components
a. CLI Entrypoint (uv-dynamic-versioning script)
b. Core Library Modules (in src/uv_dynamic_versioning/)
• main.py / cli.py: argument parsing & command dispatch
• base.py: common base classes & utilities
• version_source.py: logic to compute version from VCS (via dunamai)
• metadata_hook.py: logic to dynamically adjust package metadata
• template.py: Jinja-based formatting of version strings
• schemas.py: pydantic models for configuration validation
• hooks.py: registration of plugins with uv/hatchling
c. External Systems
• Git (VCS): source of truth for tags/commits
• uv/hatchling Build Backend: invokes version source & metadata hook
• PyPI (or other package index): ultimate consumer of built artifacts
d. Examples & Documentation (not part of runtime but useful for context)
• examples/ demonstrating usage of both plugins
• docs/ for version-source & metadata-hook design details
Relationships & Data Flows
a. Build Invocation
• User runs uv build (or pip wheel, etc.) → hatchling.build → plugin hooks
b. Version Source Plugin Flow
1. hatchling calls the version-source hook (registered via hooks.py)
2. version_source.py uses dunamai to examine local Git history
3. Computed version string flows back into the build metadata
c. Metadata Hook Plugin Flow
1. After version is set, hatchling calls the metadata-hook
2. metadata_hook.py reads configured patterns / monorepo layout
3. Dynamically adjusts dependencies / optional-dependencies
4. Returns modified metadata to build backend
d. CLI Utility
• Offers a standalone uv-dynamic-versioning command (via main.py) for manual tasks (e.g., printing version, debugging templates)
Architectural Patterns & Principles
• Plugin Pattern: registration via entry points (hooks.py → pyproject.toml)
• Separation of Concerns: distinct modules for version computation, templating, schema validation, and hook registration
• Configuration Validation: pydantic schemas ensure correct user input
• Template-Driven Output: Jinja templates for maximum flexibility
Essential Elements to Capture
• Plugin registration via hooks.py & pyproject.toml entry points
• dunamai integration for VCS interrogation
• Runtime sequence: Build Backend invokes hooks in order
• Configuration schemas that drive both plugins