Metadata Hooks

Metadata Hooks

Metadata hooks provide mechanisms for dynamically injecting and modifying project metadata during the build process. Hatchling includes built-in hooks and supports custom implementations for advanced use cases.

Navigation

• Metadata Hooks System - Hook configuration, built-in hooks, execution flow
• Custom Metadata Hooks - Implementing custom hooks with MetadataHookInterface

When to Use Metadata Hooks

Metadata hooks are appropriate when:

• Dynamic version injection from source files is needed
• Classifiers or other fields require computation at build time
• Metadata should be sourced from external files or configurations
• Custom metadata validation or transformation is required
• Metadata needs to vary based on build environment

Quick Start

Configure a metadata hook in pyproject.toml:

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

Implement the MetadataHookInterface in the specified file:

from hatchling.metadata.plugin.interface import MetadataHookInterface

class CustomMetadataHook(MetadataHookInterface):
    def update(self, metadata):
        # Modify metadata in-place
        metadata["version"] = "1.0.0"

Key Concepts

Hook Configuration: Hooks are configured in [tool.hatch.metadata.hooks.*] sections in pyproject.toml.

Execution Timing: Hooks execute during:

• Building distributions
• Running hatch project metadata command
• Installing the project
• IDE operations requiring metadata

Metadata Dictionary: The update() method receives a mutable metadata dictionary that reflects the current project metadata state. Modifications are applied in-place.

Hook Interface: All metadata hooks implement MetadataHookInterface, providing update(metadata) as the primary method and get_known_classifiers() as an optional method.

Related Topics

• Dynamic Metadata Fields - Declaring fields as dynamic
• Metadata Options - Configuration options
• Custom Build Hooks - Build-time hook system (different from metadata hooks)