ADR-013: Hatchling Build Backend
Status: Accepted
Date: 2025-08-15
Authors: Piotr Brzozowski
Reviewers: Piotr Brzozowski
Hatchling is adopted as the build backend for all Python packages in the Entirius ecosystem. This modern build system provides exceptional performance, clean pyproject.toml configuration, and full compatibility with modern Python packaging standards.
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "entirius-package-name"
dynamic = ["version"]
description = "Package description"
authors = [{name = "Author Name", email = "[email protected]"}]
license = {text = "MPL-2.0"}
requires-python = ">=3.11"
[tool.hatch.version]
path = "src/package/__init__.py"
[tool.hatch.build.targets.wheel]
packages = ["src/package"]
# Build package
python -m build
# Install in development mode
uv pip install -e .
# Build with specific target
python -m build --wheel
The Entirius project is a modern e-commerce AI platform built from the ground up with contemporary Python development practices. With our adoption of UV package manager and pyproject.toml standard (ADR-007, ADR-009), we need to select a modern Python build backend that aligns with our commitment to performance, simplicity, and modern standards.
Python packaging has evolved significantly with PEP 517/518, introducing pluggable build backends. The build backend is responsible for:
- Converting source code into distributable packages (wheels, sdists)
- Handling project metadata and dependencies
- Managing build-time dependencies
- Supporting modern packaging standards
Traditional build systems like setuptools, while widely used, represent older approaches with several limitations:
- Complex configuration across multiple files
- Slow build performance
- Legacy cruft and backwards compatibility overhead
- Inconsistent behavior across environments
- Limited support for modern Python features
As a greenfield project, Entirius requires a build backend that provides:
- Exceptional build performance from day one
- Modern, clean configuration via pyproject.toml
- Full compatibility with PEP 517/518 standards
- Minimal configuration complexity
- Strong integration with our UV-based workflow
- Description: Use setuptools as the build backend with pyproject.toml configuration
- Pros:
- Most widely used and established
- Maximum ecosystem compatibility
- Extensive documentation and community knowledge
- Well-tested across many environments
- Cons:
- Slower build performance
- Complex configuration options
- Legacy cruft and overhead
- Inconsistent behavior between versions
- Heavy build-time dependencies
- Impact on system: Accepts legacy build performance and complexity
- Description: Adopt Flit as a simple, lightweight build backend
- Pros:
- Minimal configuration required
- Fast and simple builds
- Good for pure Python packages
- Clean pyproject.toml integration
- Cons:
- Limited support for complex build requirements
- Less suitable for C extensions or complex builds
- Smaller ecosystem and community
- Limited customization options
- Impact on system: Works well for simple packages but may be limiting for complex projects
- Description: Adopt Hatchling as the modern, high-performance build backend
- Pros:
- Extremely fast build performance
- Modern design built for pyproject.toml from ground up
- Rich plugin system for extensibility
- Clean, intuitive configuration
- Excellent support for modern Python packaging standards
- Active development by PyPA (Python Packaging Authority)
- Built-in support for version management
- Strong integration with modern tooling ecosystem
- Cons:
- Relatively newer (though mature and stable)
- Team learning curve for advanced features
- Smaller community compared to setuptools
- Impact on system: Establishes modern, high-performance build workflow from project inception
Chosen option: Hatchling Build Backend
Key decision factors:
- Performance: Significantly faster builds compared to setuptools, improving developer productivity and CI/CD efficiency
- Modern design: Built specifically for pyproject.toml and PEP 517/518 standards from the ground up
- Simplicity: Clean configuration with sensible defaults, reducing complexity while maintaining powerful customization options
- Standards compliance: Full support for modern Python packaging standards and ecosystem compatibility
- Risk analysis: Low technical risk with PyPA backing and proven stability in production environments
- Business impact: Faster development cycles, reduced build complexity, and improved developer experience
- Compatibility: Excellent integration with UV package manager (ADR-007) and pyproject.toml standard (ADR-009)