Hatchling Auto Extras Hook (Custom Metadata Hook Pattern)

0.1.3 · active · verified Tue Apr 14

This entry describes a common pattern for creating a custom metadata hook within Hatchling (version 1.x), enabling automatic generation or modification of project extras. While 'hatchling-autoextras-hook' exists as a PyPI package, its low version and lack of dedicated documentation suggest it's more of an illustrative or niche implementation rather than a widely used standalone plugin. The typical approach involves implementing a custom metadata hook using `hatchling` itself, which allows dynamic modification of project metadata during the build process, including `optional-dependencies` (extras). Hatchling is a modern, extensible build backend for Python projects, with a rapid release cadence.

Warnings

breaking Hatchling 1.16.0 changed how environment dependency resolution interacts with metadata hooks. Previously, metadata hooks might be inadvertently triggered during dependency resolution. This was rectified, meaning dynamic dependencies set via a metadata hook are not available for the build environment's own dependency resolution unless explicitly handled.
Fix: If your custom metadata hook dynamically adds dependencies that are required *by the build environment itself*, you must ensure these are either statically declared in `build-system.requires` or that your hook explicitly manages adding them to the build environment's path/dependencies if that's your intended use case, typically by manually adjusting `sys.path` within the hook or using a build hook in conjunction for runtime dependencies.
gotcha For `hatchling` to respect dynamically set metadata fields (like `optional-dependencies`), they must be explicitly listed in the `[project] dynamic = [...]` array in your `pyproject.toml`.
Fix: Always declare any metadata fields that your hook modifies (e.g., `optional-dependencies`, `dependencies`, `authors`) in the `[project] dynamic = [...]` section of your `pyproject.toml`. Failure to do so will result in your dynamic changes being ignored. If a field is declared `dynamic`, it must *not* have a static definition in `pyproject.toml`.
gotcha When creating a custom metadata hook by specifying `path = "your_hook.py"` under `[tool.hatch.metadata.hooks.custom]`, the `PLUGIN_NAME` attribute within your `MetadataHookInterface` subclass is ignored. The plugin name will always be `custom`.
Fix: Be aware that for custom hooks defined by path, the logical name for configuration purposes is always `custom`. Any `PLUGIN_NAME` defined in your Python class will not alter this behavior. This also means you can only have one `custom` metadata hook per project defined this way.
gotcha Importing your own package's code within a metadata hook can lead to circular dependency issues or incorrect behavior because the package is not yet fully built or installed in the isolated build environment.
Fix: If your metadata hook needs to access code from your package, avoid direct `import your_package`. Instead, consider adding your package's source directory (e.g., `src/`) to `sys.path` within the hook, or refactor the logic to be standalone and not depend on the partially built package. If the dependencies are truly build-time only, they should be in `build-system.requires`.

Install

pip install hatchling Install Hatchling (core library)
pip install hatchling-autoextras-hook Install the specific PyPI package (if used as a dependency)

Imports

MetadataHookInterface

from hatchling.metadata.plugin.interface import MetadataHookInterface

CustomMetadataHook
wrong:
```
from hatchling_autoextras_hook import AutoExtrasHook
```
correct:
```
from hatch_build import CustomMetadataHook
```
The most common pattern is to write a custom hook in your project (e.g., `hatch_build.py`), rather than importing a specific `AutoExtrasHook` from a third-party package, if 'autoextras' is a custom logic for your project.

Quickstart

This example demonstrates how to set up a custom metadata hook (`hatch_build.py`) to dynamically add or modify extras (optional-dependencies) in your `pyproject.toml`. The `dynamic = ["optional-dependencies"]` declaration is crucial. The hook's `update` method receives the project's metadata and can modify it in-place. Configuration can be passed to the hook via `pyproject.toml`.

# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "0.1.0"
dynamic = ["optional-dependencies"]

[tool.hatch.metadata.hooks.custom]
path = "hatch_build.py"

# hatch_build.py
from hatchling.metadata.plugin.interface import MetadataHookInterface

class CustomMetadataHook(MetadataHookInterface):
    PLUGIN_NAME = 'custom' # This name is fixed for custom hooks defined via `path`

    def update(self, metadata: dict) -> None:
        # Example: dynamically generate 'docs' extra
        if 'docs' not in metadata.get('optional-dependencies', {}):
            metadata.setdefault('optional-dependencies', {})
            metadata['optional-dependencies']['docs'] = [
                "sphinx>=5.0",
                "myst-parser",
            ]
        
        # Example: dynamically generate 'testing' extra based on some logic
        if 'TEST_ENV' in self.config: # Access hook configuration
            metadata.setdefault('optional-dependencies', {})
            metadata['optional-dependencies']['testing'] = [
                "pytest>=7.0",
                "pytest-cov",
            ]

# To see effect, you would typically run:
# hatch build

view raw JSON →