Skip to content

Build hook plugins

A build hook provides code that will be executed at various stages of the build process. See the documentation for build hook configuration.

Known third-party

Overview

Build hooks run for every selected version of build targets.

The initialization stage occurs immediately before each build and the finalization stage occurs immediately after. Each stage has the opportunity to view or modify build data.

Build data

Build data is a simple mapping whose contents can influence the behavior of builds. Which fields exist and are recognized depends on each build target.

The following fields are always present and recognized by the build system itself:

Field Type Description
artifacts list[str] This is a list of extra paths to artifacts and should generally only be appended to
force_include dict[str, str] This is a mapping of extra explicit paths, with this mapping taking precedence in case of conflicts
build_hooks tuple[str, ...] This is an immutable sequence of the names of the configured build hooks and matches the order in which they run

Attention

While user-facing TOML options are hyphenated, build data fields should be named with underscores to allow plugins to use them as valid Python identifiers.

Built-in

Custom

This is a custom class in a given Python file that inherits from the BuildHookInterface.

Configuration

The build hook plugin name is custom.

[tool.hatch.build.hooks.custom]
[tool.hatch.build.targets.<TARGET_NAME>.hooks.custom]

[build.hooks.custom]
[build.targets.<TARGET_NAME>.hooks.custom]

An option path is used to specify the path of the Python file, defaulting to hatch_build.py.

Example

from hatchling.builders.hooks.plugin.interface import BuildHookInterface


class CustomBuildHook(BuildHookInterface):
    ...

If multiple subclasses are found, you must define a function named get_build_hook that returns the desired build hook.

Note

Any defined PLUGIN_NAME is ignored and will always be custom.

BuildHookInterface

Example usage:

from hatchling.builders.hooks.plugin.interface import BuildHookInterface


class SpecialBuildHook(BuildHookInterface):
    PLUGIN_NAME = 'special'
    ...

from hatchling.plugin import hookimpl

from .plugin import SpecialBuildHook


@hookimpl
def hatch_register_build_hook():
    return SpecialBuildHook
Source code in hatchling/builders/hooks/plugin/interface.py 
class BuildHookInterface:  # no cov
    """
    Example usage:

    === ":octicons-file-code-16: plugin.py"

        ```python
        from hatchling.builders.hooks.plugin.interface import BuildHookInterface


        class SpecialBuildHook(BuildHookInterface):
            PLUGIN_NAME = 'special'
            ...
        ```

    === ":octicons-file-code-16: hooks.py"

        ```python
        from hatchling.plugin import hookimpl

        from .plugin import SpecialBuildHook


        @hookimpl
        def hatch_register_build_hook():
            return SpecialBuildHook
        ```
    """

    PLUGIN_NAME = ''
    """The name used for selection."""

    def __init__(self, root, config, build_config, metadata, directory, target_name, app=None):
        self.__root = root
        self.__config = config
        self.__build_config = build_config
        self.__metadata = metadata
        self.__directory = directory
        self.__target_name = target_name
        self.__app = app

    @property
    def app(self):
        """
        An instance of [Application](utilities.md#hatchling.bridge.app.Application).
        """
        if self.__app is None:
            from ....bridge.app import Application

            self.__app = Application().get_safe_application()

        return self.__app

    @property
    def root(self):
        """
        The root of the project tree.
        """
        return self.__root

    @property
    def config(self):
        """
        The cumulative hook configuration.

        === ":octicons-file-code-16: pyproject.toml"

            ```toml
            [tool.hatch.build.hooks.<PLUGIN_NAME>]
            [tool.hatch.build.targets.<TARGET_NAME>.hooks.<PLUGIN_NAME>]
            ```

        === ":octicons-file-code-16: hatch.toml"

            ```toml
            [build.hooks.<PLUGIN_NAME>]
            [build.targets.<TARGET_NAME>.hooks.<PLUGIN_NAME>]
            ```
        """
        return self.__config

    @property
    def metadata(self):
        # Undocumented for now
        return self.__metadata

    @property
    def build_config(self):
        """
        An instance of [BuilderConfig](utilities.md#hatchling.builders.config.BuilderConfig).
        """
        return self.__build_config

    @property
    def directory(self):
        """
        The build directory.
        """
        return self.__directory

    @property
    def target_name(self):
        """
        The plugin name of the build target.
        """
        return self.__target_name

    def clean(self, versions):
        """
        This occurs before the build process if the `-c`/`--clean` flag was passed to
        the [`build`](../cli/reference.md#hatch-build) command, or when invoking
        the [`clean`](../cli/reference.md#hatch-clean) command.
        """

    def initialize(self, version, build_data):
        """
        This occurs immediately before each build.

        Any modifications to the build data will be seen by the build target.
        """

    def finalize(self, version, build_data, artifact_path):
        """
        This occurs immediately after each build and will not run if the `--hooks-only` flag
        was passed to the [`build`](../cli/reference.md#hatch-build) command.

        The build data will reflect any modifications done by the target during the build.
        """

PLUGIN_NAME

The name used for selection.

app property readonly

An instance of Application.

build_config property readonly

An instance of BuilderConfig.

config property readonly

The cumulative hook configuration.

[tool.hatch.build.hooks.<PLUGIN_NAME>]
[tool.hatch.build.targets.<TARGET_NAME>.hooks.<PLUGIN_NAME>]

[build.hooks.<PLUGIN_NAME>]
[build.targets.<TARGET_NAME>.hooks.<PLUGIN_NAME>]

directory property readonly

The build directory.

root property readonly

The root of the project tree.

target_name property readonly

The plugin name of the build target.

clean(self, versions)

This occurs before the build process if the -c/--clean flag was passed to the build command, or when invoking the clean command.

Source code in hatchling/builders/hooks/plugin/interface.py 
def clean(self, versions):
    """
    This occurs before the build process if the `-c`/`--clean` flag was passed to
    the [`build`](../cli/reference.md#hatch-build) command, or when invoking
    the [`clean`](../cli/reference.md#hatch-clean) command.
    """

finalize(self, version, build_data, artifact_path)

This occurs immediately after each build and will not run if the --hooks-only flag was passed to the build command.

The build data will reflect any modifications done by the target during the build.

Source code in hatchling/builders/hooks/plugin/interface.py 
def finalize(self, version, build_data, artifact_path):
    """
    This occurs immediately after each build and will not run if the `--hooks-only` flag
    was passed to the [`build`](../cli/reference.md#hatch-build) command.

    The build data will reflect any modifications done by the target during the build.
    """

initialize(self, version, build_data)

This occurs immediately before each build.

Any modifications to the build data will be seen by the build target.

Source code in hatchling/builders/hooks/plugin/interface.py 
def initialize(self, version, build_data):
    """
    This occurs immediately before each build.

    Any modifications to the build data will be seen by the build target.
    """
Last update: May 15, 2022