pypa/hatch
github.com/pypa/hatch ↗ · 526 files · 2.9 MB
Hatch | | | | --- | --- | | CI/CD | | | Docs | | | Package | | | Meta | | ----- Hatch is a modern, extensible Python project manager.
Overview
Hatch is a Python developer CLI for creating projects, managing interpreters and environments, running scripts and quality checks, building distributions, and publishing packages. Its separately packaged Hatchling backend implements standard and editable builds, with shared metadata and pluggy-based extension machinery. At commit 7c26ebeaf8b83f5f0374a2545bb15e36c87db0d0, distinctive capabilities include workspace builds, environment matrices, dependency-source overrides, and pluggable PEP 751 lockfile handling.
System map
The repository ships a project-management frontend and an independently packaged build backend. Hatch coordinates configuration, environments, subprocesses, and publishing, while Hatchling owns distribution construction and packaging metadata. Runtime state resides in configured filesystem locations, and integrations include installers, package indices, keyring, and downloaded Python distributions. Release workflows produce Python packages, standalone executables, installers, and documentation.
- The Hatch distribution requires Python >=3.10 and exposes hatch = hatch.cli:main; src/hatch/__main__.py delegates module execution to that same main function.
- Hatchling is a separate distribution bootstrapped through hatchling.ouroboros with backend-path=['src']; it exposes hatchling.cli:hatchling and standard build/editable backend functions.
- The frontend uses Click command registration and Application(Terminal); the backend CLI uses argparse and dispatches build, dep, metadata, and version handlers.
- Project lazily owns PluginManager, ProjectConfig, ProjectMetadata, a selected build environment, and BuildFrontend; get_environment constructs the plugin selected by configuration type.
- Global configuration defaults to platformdirs' Hatch config.toml; environment hashes use JSON beneath data_dir/env/.metadata, and virtual environments support configured external paths.
- VirtualEnvironment selects VirtualEnv or UVVirtualEnv, PackageIndex uses HTTPX2, AuthenticationCredentials uses keyring, and PythonManager downloads and installs interpreter archives.
- Repository workflows use hatch test, hatch fmt --check, and hatch run types:check; hatch.toml defines backend builds, coverage reporting, and strict documentation build/link checks.
- Hatch release automation builds wheels/sdists, PyApp binaries, Windows installers, and signed/notarized macOS packaging; Hatchling releases publish backend/dist, while documentation workflows publish GitHub Pages.
Feature catalog
Hatch exposes developer workflows through commands rather than application routes or screens. Its main capabilities cover project generation, environment execution, dependency management, interpreter installation, packaging, and publishing. Quality commands add pytest-based testing, Ruff checks, and Pyrefly type checking. Configuration and diagnostic commands support local operation and troubleshooting.
- hatch new supports interactive details, CLI scaffolding, initialization of existing projects, and attempted setuptools metadata migration; selected template plugins generate the resulting files.
- hatch env registers create, find, lock, prune, remove, run, and show; hatch run adds ENV: command selection and matrix inclusion/exclusion, with an empty environment prefix selecting system execution.
- hatch run recognizes existing .py files with inline metadata, merges their dependencies into a skip-install environment, defaults its installer to uv, and selects a compatible known Python distribution when needed.
- hatch dep provides lock, sync, hash, and dependency display commands; source types include path, Git, URL, index, and workspace, while locked synchronization through the pip locker is explicitly unsupported.
- hatch python registers find/install/remove/show/update; hatch test offers interpreter/matrix selection, randomization, parallel workers, retries, and coverage through the hatch-test environment.
- hatch check runs code, fmt, then types when no subcommand is given; Ruff supplies lint/format scripts, Pyrefly supplies default type checks, and the separate fmt command remains registered.
- hatch build defaults to sdist and wheel, supports target versions and hook/clean controls, and consolidates workspace builds with --all; clean delegates to build's clean-only path, and publishing supports PyPI, TestPyPI, or custom repositories.
- Administrative commands display/update configuration, inspect project metadata and status, view/set versions, enter shells, and manage Hatch through report/update/restore; the self-management command name follows PYAPP_COMMAND_NAME.
Data flow
CLI arguments and environment variables first select application configuration, project location, and execution environment. Project metadata and environment settings are evaluated lazily and transformed into installer requirements or shell commands. Filesystem state records configuration, dependency hashes, interpreter installations, and build artifacts. Build helpers exchange JSON across subprocess boundaries, while publishing transforms archive metadata into authenticated HTTP requests.
- Root CLI inputs become Application state: active-environment inheritance applies only when --env retains its default source; configuration supplies data/cache directories unless CLI options override them.
- Project.find_project_root walks parents for pyproject.toml or setup.py; raw_config parses the detected TOML and synthesizes a project name when metadata is absent, then ProjectMetadata feeds ProjectConfig.
- Source tables normalize dependency names, reject normalization collisions, and replace inherited entries by normalized name; path and Git sources render file:// and git+ direct-reference URLs.
- run partitions environment/matrix selectors before env run resolves selected environments; runner_context yields an ExecutionContext for command population, then prepares and executes it after the caller resumes iteration.
- dependency_hash hashes all complex dependencies; Project compares it with persisted metadata, conditionally generates a lockfile and synchronizes installations, then writes the resulting hash to environment JSON.
- BuildFrontend writes generated helper scripts into an environment filesystem context, executes Python there, synchronizes output locally, reads output.json, and moves the returned wheel or sdist into the destination.
- WheelBuilder streams selected source files into WheelArchive, records SHA-256 hashes and sizes, writes distribution data and RECORD, then replaces the temporary archive with the final tagged wheel.
- Publishing reads wheel METADATA or sdist PKG-INFO into upload fields; PackageIndex adds protocol fields and three digests before multipart POST, and prompted credentials persist as cached usernames plus keyring passwords.
Behavior traces
The source supports ordered walkthroughs of startup, command execution, environment persistence, artifact builds, and publishing. Conditions such as existing environments, skip-install, backend selection, and already-uploaded artifacts materially change the sequence. Environment execution is driven by a generator that prepares and runs work after the command handler populates its context. These are source traces, not observed execution results.
- Startup: main → hatch → Application → ConfigFile.restore if the default file is missing → ConfigFile.load → style initialization → storage directory selection → explicit or current-directory Project selection.
- Normal command execution: run parses ENV:ARGS → ctx.invoke(env.run) → parse_matrix_variables/select_environments → Application.runner_context → Project.get_environment → compatibility check only if the environment does not exist.
- Missing-environment preparation: managed_environment → metadata.reset → environment.create → optional pre-install commands → normal/editable project installation → optional post-install commands; skip-install bypasses the installation block.
- Persistence after preparation: dependency_hash → EnvironmentMetadata.dependency_hash → optional generate_lockfile for locked inputs → dependencies_in_sync → optional sync_dependencies → update_dependency_hash → JSON write.
- Shell execution: execute_context applies context.env_vars → run_shell_commands enters command_context → resolve_commands/expand_command formats scripts → run_shell_command invokes the platform; parent SIGINT handling is restored in finally and exit-code policy is applied.
- Hatchling build: build → _build_project → prepare_build_environment → python -m hatchling build → build_impl selects builder → BuilderInterface.build validates metadata and initializes hooks → WheelBuilder.build_standard → finalize hooks → artifact yield.
- Alternative-backend build: prepare_build_environment gathers backend get_requires results → _build_project accepts only sdist/wheel → BuildFrontend generates and executes a hook script → output.json identifies the artifact → the frontend moves it to the requested directory.
- Publish: CLI selects and checks the publisher → IndexPublisher resolves repository and credentials → recurse_artifacts reads metadata → simple API lookup skips existing filenames → upload_artifact sends new files → successful versions print URLs → write_updated_data persists prompted authentication.
Testing signals
Tests and CI were inspected, not executed; no passing result or measured coverage is asserted. The inspected suite uses pytest, Click testing helpers, isolated storage, mocks, and capability-dependent integration tests. It exercises environment creation, signals, builds, credentials, and locking, but some tests deliberately replace process or activation boundaries. This inventory is bounded and does not establish exhaustive coverage.
- The default test environment specifies pytest, pytest-mock, pytest-randomly, pytest-rerunfailures, pytest-xdist, and coverage; tests/conftest.py wraps Click CliRunner and defaults catch_exceptions to False.
- The session isolation fixture redirects Hatch data/cache directories into temporary storage and controls shell, color, and active-environment state; marker handling skips unavailable network, OS, Git, Docker, and Cargo capabilities.
- test_automatic_creation asserts environment storage layout and the child's interpreter path; test_interrupt_signal_not_inherited checks the child's default SIGINT handler and restoration of the parent handler.
- Build tests include Flit backend artifact assertions and wheel archive-content/timestamp assertions; the CLI build module applies mock_backend_process, and process-output fixtures explicitly bypass mocking under allow_backend_process.
- Dependency-lock tests compare top-level lock with dep lock and exercise pip apply-lock rejection; the inspected uv sync test uses mock_locker and replaces safe_activation, so it does not validate a real activation layout.
- Publishing CLI tests require Docker/internet and a devpi fixture, with keyring calls replaced by an in-memory store; separate auth tests use a fake home to check .pypirc repository-name and URL matching.
- Coverage configuration requests branch coverage but omits module entrypoints, backend bridge code, migration, frontend helper scripts, and shell utilities; presence of other tests does not establish coverage of these omitted boundaries.
- Inspected CI defines Linux/Windows/macOS testing across Python 3.10–3.14 and 3.14t, randomized parallel tests with retries, combined coverage reports, downstream builds, and a separate Hyperfine CLI benchmark workflow; none was executed or its results verified.
Risk map
The main sensitive boundaries are executable project configuration, plugin loading, credentials, downloads, and filesystem operations beyond the checkout. These findings describe source behavior and review priorities, not confirmed vulnerabilities. Error handling and persistence choices also affect operational reliability. Tests provide useful signals, but mocks and conditional skips limit what their existence proves.
- Configured scripts are formatted into command strings and EnvironmentInterface.run_shell_command defaults shell=True; pre/post-install commands use this executor, making project command configuration an execution trust boundary.
- Third-party plugin discovery loads installed hatch entry points, custom plugin loaders execute Python modules, and environment plugin requirements may be installed into Hatch's own interpreter through uv or PyApp management.
- Authentication can read user configuration, .pypirc, and keyring; config show --all bypasses scrubbing, HATCH_DEBUG enables traceback locals, and upload errors mask the exact authentication string through replacement.
- Environment paths may be absolute outside the project and removal deletes both execution/build environments; wheel clean removes every .whl in its selected directory, and force-includes can package external files.
- EnvironmentMetadata writes JSON directly with write_text and reads with json.loads, whereas ConfigFile.save uses write_atomic. Hypothesis: interrupted or concurrent metadata writes merit targeted recovery testing; no corruption was observed. (inferred)
- IndexPublisher treats any exception during the simple API existence lookup as an empty artifact set, then attempts uploads; this branch is marked no cov and can conceal the original lookup failure.
- PipLocker.apply_lock raises LockerUnsupportedError and install_matches_lock returns False; locked pip environments therefore have a documented synchronization limitation, with a corresponding CLI failure assertion.
- PythonManager.install follows redirects, unpacks downloaded archives, and replaces the interpreter installation; custom distribution sources are supported, and tar extraction explicitly applies filter='data'. This is a remote-content-to-local-executable boundary.
Extension points
The principal extension mechanism is pluggy registration of named classes. Hatch adds environment, collector, publisher, template, and locker registries to Hatchling's build and version registries. Builders expose artifact-version functions and ordered hooks, while environments and lockers expose lifecycle contracts. CLI command lists and dependency-source parser tables provide additional explicit dispatch points.
- Plugins declare registration hooks with hatchling.plugin.hookimpl, return one or more classes carrying PLUGIN_NAME, and advertise their hook module through project.entry-points.hatch.
- Hatch's PluginManager extends Hatchling's manager and registers environment, environment_collector, publisher, template, and locker hook providers; backend registries cover builders, build hooks, metadata hooks, version sources, and schemes.
- New environment types enter through project.config type selection and plugin_manager.environment.get; their contract includes command execution, dependency hashing, filesystem contexts, compatibility checks, and typed override options.
- LockerInterface defines supports/generate/in_sync/apply_lock plus optional installation conformance checks; resolution prefers environment locker, then project locker, then uv/pip based on the environment, and built-in hooks register both implementations.
- BuilderInterface.get_version_api maps version names to artifact-producing functions, get_config_class supplies target configuration, and hooks receive shared build_data through initialize/finalize; WheelBuilder maps standard and editable variants.
- Metadata hooks update core_raw_metadata and contribute known classifiers; dynamically introduced fields must appear in project.dynamic, while custom script loaders select a get_<plugin_id> factory or a unique interface subclass.
- Publisher selection instantiates a registered class with application, root, cache, project configuration, and user configuration; templates are ordered by PRIORITY and expose initialize_config/get_files/finalize_files stages.
- CLI additions attach to explicit Click add_command lists or argparse registration calls; dependency-source parsing uses _SOURCE_PARSERS after enforcing exactly one recognized source-type key.
Contributor handoff
Begin with the two package manifests and hatch.toml, then follow the relevant command through Application and Project before changing a backend or plugin contract. Preserve lazy evaluation, cross-platform filesystem behavior, lifecycle ordering, and backend-specific branches. Tests and CI were inspected, not executed; use their definitions to plan separately authorized validation without treating them as passing evidence. The investigation is bounded, and upstream contribution rules require disclosed AI assistance and informed human review.
- Read pyproject.toml, backend/pyproject.toml, and hatch.toml first: Hatch and Hatchling have separate build bootstraps, and the repository test environment includes backend/ as a workspace member.
- For execution changes, read Application.runner_context and Project.prepare_environment together: command handlers populate yielded contexts before preparation, and preparation preserves create/install/lock/sync ordering.
- Preserve lazy imports and platform abstractions: Ruff explicitly permits lazy imports for CLI responsiveness, while Path IDs casefold on Windows/macOS and Platform formats subprocess calls.
- Build edits must account for both Hatchling subprocess invocation and alternative-backend helper scripts; backend metadata-only hooks are conditionally defined when PIP_BUILD_TRACKER is absent because build hooks can change dependency metadata.
- Read tests/conftest.py before choosing validation: fixtures isolate storage, some backend calls run through mocks, and capability markers control skips. Tests and CI were inspected only, so no pass status is available from this brief.
- When execution is authorized, repository guidance provides hatch test, hatch test --cover, and hatch check; target test paths can be forwarded through hatch test's variadic arguments before expanding validation.
- Distinguish the type-checking paths: CI invokes the types environment's Mypy script, whereas hatch check types uses the hatch-check-types environment and defaults to Pyrefly; pip locking likewise differs from uv because pip cannot apply locks.
- Upstream contribution documentation requires disclosure of all AI usage, human understanding of contributed code, and human review/editing of AI-assisted issue or discussion content; its commit/submission instructions do not authorize actions in this read-only investigation.
Languages
| Language | Files | Share of source |
|---|---|---|
| Python | 397 | 98% |
| Markdown | 86 | docs/config |
| YAML | 15 | docs/config |
| TOML | 7 | 2% |
| JSON | 3 | docs/config |
| CSS | 1 | docs/config |
| HTML | 1 | docs/config |
| Shell | 1 | 0% |
Start reading here
Probable source entrypoint: pyproject.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (136 files)
Repository structure
| Top-level path | Files |
|---|---|
tests/ | 180 |
src/ | 136 |
docs/ | 95 |
backend/ | 76 |
.github/ | 12 |
scripts/ | 9 |
release/ | 5 |
Docs found: README.mddocs/blog/index.mddocs/blog/posts/release-hatch-1100.mddocs/blog/posts/release-hatch-1160.mddocs/blog/posts/release-hatch-1170.mddocs/blog/posts/release-hatch-1180.mddocs/blog/posts/release-hatch-160.mddocs/blog/posts/release-hatch-180.mddocs/blog/posts/release-hatch-190.mddocs/build.md
Package
pyproject.toml — hatch vsrc/hatch/_version.py, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme.github/workflows/docs-release.yml— GitHub Actions workflow.github/workflows/docs-dev.yml— GitHub Actions workflow.github/workflows/build-hatch.yml— GitHub Actions workflow.github/workflows/build-distributions.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/auto-merge.yml— GitHub Actions workflow.github/workflows/cli.yml— GitHub Actions workflow.github/workflows/build-hatchling.yml— GitHub Actions workflow
Structural health signals
Average score 7.4/10 across 96 analyzed source files; 12 hotspots surfaced.
backend/src/hatchling/metadata/core.py— 1286 lines, score 5.7 (Large file, Deep nesting)src/hatch/env/plugin/interface.py— 1284 lines, score 5.7 (Large file, Deep nesting)src/hatch/cli/fmt/core.py— 928 lines, score 5.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
7c26ebeaf8b82026-09-20 — Fix `hatch.cli.application.Application.ensure_plugin_dependencies` PyApp Compatibility (#2390)c4abc454f9082026-09-20 — release Hatchling v1.32.4 (#2441)cd57f6890dd02026-09-18 — Revert type changes for BuildHookInterface (#2440)5c6dc6c67ff92026-09-18 — Strip surrounding whitespace from version metadata (#2438)0941887cd24b2026-09-17 — release Hatchling v1.32.3 (#2436)