Appendix I — Hatch - Modern Python Project Management

I.1 Introduction to Hatch

Hatch is a modern, extensible Python project management tool designed to simplify the development workflow through standardization and automation. Created by Ofek Lev and first released in 2017, Hatch has undergone significant evolution to become a comprehensive solution that handles environment management, dependency resolution, building, and publishing.

Unlike traditional tools that focus primarily on packaging or dependency management, Hatch takes a holistic approach to project management, addressing the entire development lifecycle. What sets Hatch apart is its flexibility, extensibility, and focus on developer experience through an intuitive CLI and plugin system.

I.2 Key Features of Hatch

I.2.1 Project Management

Hatch provides comprehensive project management capabilities:

  • Project initialization: Quickly set up standardized project structures
  • Flexible configuration: Standardized configuration in pyproject.toml
  • Version management: Easily bumper version numbers
  • Script running: Execute defined project scripts

I.2.2 Environment Management

One of Hatch’s standout features is its sophisticated environment handling:

  • Multiple environments per project: Define development, testing, documentation environments
  • Matrix environments: Test across Python versions and dependency sets
  • Isolated environments: Clean, reproducible development spaces
  • Environment synchronization: Keep environments updated

I.2.3 Build and Packaging

Hatch streamlines the packaging workflow:

  • Standards-compliant: Implements PEP 517/518 build system
  • Multiple build targets: Source distributions and wheels
  • Build hooks: Customize the build process
  • Metadata standardization: PEP 621 compliant metadata

I.2.4 Extensibility

Hatch is designed for extensibility:

  • Plugin system: Extend functionality through plugins
  • Custom commands: Add project-specific commands
  • Environment customization: Define environment-specific tools
  • Build customization: Extend the build process

I.3 Getting Started with Hatch

I.3.1 Installation

Hatch can be installed through several methods:

# Using pipx (recommended)
pipx install hatch

# Using pip
pip install hatch

# Using conda
conda install -c conda-forge hatch

# Using Homebrew on macOS
brew install hatch

Verify your installation:

hatch --version

I.3.2 Creating a New Project

Create a new project with Hatch:

# Interactive project creation
hatch new

# Non-interactive with defaults
hatch new my-project

# With specific options
hatch new my-project --init

The project structure might look like:

my-project/
├── src/
│   └── my_project/
│       └── __init__.py
├── tests/
│   └── __init__.py
├── pyproject.toml
└── README.md

I.3.3 Basic Configuration

Hatch uses pyproject.toml for configuration:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
readme = "README.md"
requires-python = ">=3.8"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your.email@example.com"},
]
dependencies = [
    "requests>=2.28.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]
dev = [
    "black>=23.0.0",
    "ruff>=0.0.220",
]

[tool.hatch.envs.default]
dependencies = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.0.220",
]

[tool.hatch.envs.test]
dependencies = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]

I.4 Essential Hatch Commands

I.4.1 Environment Management

# Create and activate the default environment
hatch shell

# Create and activate a specific environment
hatch shell test

# Run a command in the default environment
hatch run pytest

# Run a command in a specific environment
hatch run test:pytest

# List available environments
hatch env show

# Clean all environments
hatch env prune

I.4.2 Dependency Management

# Install project dependencies
hatch env create

# Update all dependencies
hatch env update

# Update dependencies in a specific environment
hatch env update test

# Show installed packages
hatch env show

I.4.3 Building and Publishing

# Build the package
hatch build

# Build specific formats
hatch build -t wheel

# Publish to PyPI
hatch publish

# Publish to TestPyPI
hatch publish -r test

I.4.4 Version Management

# Show current version
hatch version

# Bump the version (patch, minor, major)
hatch version patch
hatch version minor
hatch version major

# Set a specific version
hatch version 1.2.3

I.5 Advanced Hatch Features

I.5.1 Environment Matrix

Hatch can manage testing across multiple Python versions:

[tool.hatch.envs.test]
dependencies = [
    "pytest",
]

[[tool.hatch.envs.test.matrix]]
python = ["3.8", "3.9", "3.10", "3.11"]

Run commands across all environments:

# Run tests across all Python versions
hatch run test:all:pytest

I.5.2 Custom Scripts

Define project-specific scripts:

[tool.hatch.envs.default.scripts]
test = "pytest"
lint = "ruff check ."
format = "black ."

# Complex scripts
dev = [
    "format",
    "lint",
    "test",
]

Run these scripts:

# Run the test script
hatch run test

# Run the complete dev script
hatch run dev

I.5.3 Environment Features

Enable specific tools in environments:

[tool.hatch.envs.default]
features = ["dev", "test"]
dependencies = [
    "black",
    "pytest",
]

[tool.hatch.envs.default.scripts]
test = "pytest {args}"
format = "black {args:src tests}"

I.5.4 Build Hooks

Customize the build process:

[tool.hatch.build.hooks.vcs]
version-file = "src/my_project/_version.py"

[tool.hatch.build.hooks.custom]
path = "my_custom_build_hook.py"

I.6 Best Practices with Hatch

I.6.1 Project Structure

A recommended structure for Hatch projects:

my_project/
├── src/
│   └── my_package/      # Main package code
│       ├── __init__.py
│       └── module.py
├── tests/               # Test files
│   ├── __init__.py
│   └── test_module.py
├── docs/                # Documentation
├── pyproject.toml       # Project configuration
└── README.md            # Project documentation

To use this source layout:

[tool.hatch.build]
packages = ["src/my_package"]

I.6.2 Environment Management Strategies

  1. Specialized Environments: Create purpose-specific environments

    [tool.hatch.envs.default]
dependencies = ["pytest", "black", "ruff"]

[tool.hatch.envs.docs]
dependencies = ["sphinx", "sphinx-rtd-theme"]

[tool.hatch.envs.security]
dependencies = ["bandit", "safety"]

  2. Matrix Testing: Test across Python versions

    [[tool.hatch.envs.test.matrix]]
python = ["3.8", "3.9", "3.10", "3.11"]

  3. Feature Toggles: Organize functionality by feature

    [tool.hatch.envs.default]
features = ["test", "lint"]

I.6.3 Version Control Practices

  1. Configure version source: Use git tags or a version file

    [tool.hatch.version]
source = "vcs"  # or "file"

  2. Automate version bumping: Use Hatch’s version commands in your workflow

    # Before release
hatch version minor
git commit -am "Bump version to $(hatch version)"
git tag v$(hatch version)

I.6.4 Integration with Development Tools

Configure tools like Black and Ruff directly in pyproject.toml:

[tool.black]
line-length = 88
target-version = ["py39"]

[tool.ruff]
select = ["E", "F", "I"]
line-length = 88

I.7 Integration with Development Workflows

I.7.1 IDE Integration

Hatch environments work with most Python IDEs:

I.7.1.1 VS Code

  1. Create environments: hatch env create
  2. Find the environment path: hatch env find default
  3. Select the interpreter from this path in VS Code

I.7.1.2 PyCharm

  1. Create environments: hatch env create
  2. Find the environment path: hatch env find default
  3. Add the interpreter in PyCharm settings

I.7.2 CI/CD Integration

I.7.2.1 GitHub Actions Example

name: Python CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: "3.10"

    - name: Install Hatch
      run: pip install hatch

    - name: Run tests
      run: hatch run test:pytest

    - name: Run linters
      run: hatch run lint:all

I.8 Troubleshooting Common Issues

I.8.1 Environment Creation Failures

If environments fail to create:

# Show detailed errors
hatch env create -v

# Try creating with verbose output
hatch -v env create

# Check for conflicting dependencies
hatch dep show

I.8.2 Build Issues

For build-related problems:

# Verbose build output
hatch build -v

# Clean build artifacts
hatch clean

# Check configuration
hatch project metadata

I.8.3 Plugin Problems

If plugins aren’t working:

# List installed plugins
hatch plugin list

# Update plugins
pip install -U hatch-plugin-name

I.9 Comparison with Other Tools

I.9.1 Hatch vs. Poetry

  • Hatch: More flexible, multiple environments, standards-focused
  • Poetry: More opinionated, stronger dependency resolution
  • Key difference: Hatch’s multiple environments per project vs. Poetry’s single environment approach

I.9.2 Hatch vs. PDM

  • Hatch: Focus on the entire development workflow
  • PDM: Stronger focus on dependency management with PEP 582 support
  • Key difference: Hatch’s broader scope vs. PDM’s emphasis on dependencies

I.9.3 Hatch vs. pip + venv

  • Hatch: Integrated environment and project management
  • pip + venv: Separate tools requiring manual coordination
  • Key difference: Hatch’s automation vs. traditional manual approach

I.10 When to Use Hatch

Hatch is particularly well-suited for:

  1. Complex Development Workflows: Multiple environments, testing matrices
  2. Teams with Diverse Projects: Standardization across different project types
  3. Open Source Maintainers: Multiple environment testing and streamlined releases
  4. Projects Requiring Customization: Plugin system for specialized needs

Hatch might not be ideal for:

  1. Very Simple Scripts: Might be overkill for trivial projects
  2. Teams Heavily Invested in Poetry: Migration costs might outweigh benefits
  3. Projects with Unusual Build Systems: Some specialized build needs might require additional customization

I.11 Conclusion

Hatch represents a modern approach to Python project management that emphasizes flexibility, standards compliance, and developer experience. Its unique multi-environment capabilities, combined with comprehensive project lifecycle management, make it a powerful choice for both application and library development.

While newer than some alternatives like Poetry, Hatch’s strict adherence to Python packaging standards ensures compatibility with the broader ecosystem. Its plugin system and flexible configuration options allow it to adapt to a wide range of project needs, from simple libraries to complex applications.

For developers looking for a tool that can grow with their projects and adapt to various workflows, Hatch provides a compelling combination of power and flexibility. Its focus on standardization and automation helps reduce the cognitive overhead of project management, allowing developers to focus more on writing code and less on managing tooling.