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既知のサードパーティ

• hatch-argparse-manpage - generate man pages for argparse-based CLIshatch-argparse-manpage - argparseベースのCLI用のマニュアルページを生成します。
• hatch-autorun - used to inject code into an installation that will automatically run before the first importhatch-autorun - 最初のインポートの前に自動的に実行されるコードをインストールに注入するために使用されます。
• hatch-build-scripts - run arbitrary shell commands that create artifactshatch-build-scripts - アーティファクトを作成する任意のシェルコマンドを実行します。
• hatch-cython - build Cython extensionshatch-cython - Cython拡張をビルドします。
• hatch-gettext - compiles multi-lingual messages with GNU gettext toolshatch-gettext - GNU gettextツールを使用して多言語メッセージをコンパイルします。
• hatch-jupyter-builder - used for packages in the Project Jupyter ecosystemhatch-jupyter-builder - Project Jupyterエコシステムのパッケージに使用されます。
• hatch-mypyc - compiles code with Mypychatch-mypyc - Mypycを使用してコードをコンパイルします。
• hatch-odoo - package Odoo add-ons into the appropriate namespacehatch-odoo - Odooアドオンを適切な名前空間にパッケージ化します。
• scikit-build-core - build extension modules with CMakescikit-build-core - CMakeを使用して拡張モジュールをビルドする

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説明
artifactsartifacts	list[str]list[str]	This is a list of extra artifact patterns and should generally only be appended toこれは追加のartifactパターンのリストであり、一般的には追加されるべきです。
force_includeforce_include	dict[str, str]dict[str, str]	This is a mapping of extra forced inclusion paths, with this mapping taking precedence in case of conflictsこれは追加の強制的なインクルージョンパスのマッピングであり、競合が発生した場合はこのマッピングが優先されます。
build_hooksbuild_hooks	tuple[str, ...]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.ユーザー向けのTOMLオプションはハイフンで区切られていますが、ビルドデータフィールドはアンダースコアで命名する必要があります。これにより、プラグインが有効なPython識別子として使用できるようになります。

Notesノート

In some cases it may be necessary to use force_include rather than artifacts. For example, say that you want to install a lib.so directly at the root of site-packages and a project defines a package src/foo. If you create src/lib.so, there will never be a match because the directory traversal starts at src/foo rather than src. In that case you must do either:場合によっては、artifactsの代わりにforce_includeを使用する必要があるかもしれません。たとえば、lib.soを直接site-packagesのルートにインストールしたいとします。そして、プロジェクトがパッケージ src/fooを定義しています。src/lib.soを作成すると、ディレクトリトラバーサルがsrcではなくsrc/fooから始まるため、一致することは決してありません。その場合、次のいずれかを行う必要があります：

build_data['force_include']['src/lib.so'] = 'src/lib.so'

or

build_data['force_include']['/absolute/path/to/src/lib.so'] = 'src/lib.so'

BuildHookInterface BuildHookInterface

Example usage:使用例:

plugin.py hooks.py

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(Generic[BuilderConfigBound]):  # no cov
    """
    Example usage:

    ```python tab="plugin.py"
    from hatchling.builders.hooks.plugin.interface import BuildHookInterface


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

    ```python tab="hooks.py"
    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: str,
        config: dict[str, Any],
        build_config: BuilderConfigBound,
        metadata: ProjectMetadata,
        directory: str,
        target_name: str,
        app: Application | None = None,
    ) -> 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) -> Application:
        """
        An instance of [Application](../utilities.md#hatchling.bridge.app.Application).
        """
        if self.__app is None:
            from hatchling.bridge.app import Application

            self.__app = cast(Application, Application().get_safe_application())

        return self.__app

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

    @property
    def config(self) -> dict[str, Any]:
        """
        The cumulative hook configuration.

        ```toml config-example
        [tool.hatch.build.hooks.<PLUGIN_NAME>]
        [tool.hatch.build.targets.<TARGET_NAME>.hooks.<PLUGIN_NAME>]
        ```
        """
        return self.__config

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

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

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

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

    def dependencies(self) -> list[str]:  # noqa: PLR6301
        """
        A list of extra [dependencies](../../config/dependency.md) that must be installed
        prior to builds.

        !!! warning
            - For this to have any effect the hook dependency itself cannot be dynamic and
                must always be defined in `build-system.requires`.
            - As the hook must be imported to call this method, imports that require these
                dependencies must be evaluated lazily.
        """
        return []

    def clean(self, versions: list[str]) -> None:
        """
        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: str, build_data: dict[str, Any]) -> None:
        """
        This occurs immediately before each build.

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

    def finalize(self, version: str, build_data: dict[str, Any], artifact_path: str) -> None:
        """
        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 = '' class-attribute instance-attribute PLUGIN_NAME = '' class-attribute instance-attribute

The name used for selection.選択に使用される名前。

app: Application property app: Application property

An instance of Application.Applicationのインスタンス。

root: str property root: str property

The root of the project tree.プロジェクトツリーのルート。

config: dict[str, Any] property config: dict[str, Any] property

The cumulative hook configuration.累積フック設定。

pyproject.toml hatch.toml

[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>]

build_config: BuilderConfigBound property build_config: BuilderConfigBound property

An instance of BuilderConfig.BuilderConfigのインスタンス。

target_name: str property target_name: str property

The plugin name of the build target.ビルドターゲットのプラグイン名。

directory: str property directory: str property

The build directory.ビルドディレクトリ。

dependencies() -> list[str] dependencies() -> list[str]

A list of extra dependencies that must be installed prior to builds.ビルドの前にインストールする必要がある追加の依存関係のリスト。

Warning警告

• For this to have any effect the hook dependency itself cannot be dynamic and must always be defined in build-system.requires.これが効果を持つためには、フックの依存関係自体が動的であってはならず、常にbuild-system.requiresで定義されている必要があります。
• As the hook must be imported to call this method, imports that require these dependencies must be evaluated lazily.フックをインポートしてこのメソッドを呼び出す必要があるため、これらの依存関係を必要とするインポートは遅延評価されなければなりません。

Source code in hatchling/builders/hooks/plugin/interface.py

def dependencies(self) -> list[str]:  # noqa: PLR6301
    """
    A list of extra [dependencies](../../config/dependency.md) that must be installed
    prior to builds.

    !!! warning
        - For this to have any effect the hook dependency itself cannot be dynamic and
            must always be defined in `build-system.requires`.
        - As the hook must be imported to call this method, imports that require these
            dependencies must be evaluated lazily.
    """
    return []

clean(versions: list[str]) -> None clean(versions: list[str]) -> None

This occurs before the build process if the -c/--clean flag was passed to the build command, or when invoking the clean command.buildコマンドに-c/--cleanフラグが渡された場合、またはcleanコマンドを呼び出すときに、ビルドプロセスの前にこれが発生します。

Source code in hatchling/builders/hooks/plugin/interface.py

def clean(self, versions: list[str]) -> None:
    """
    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.
    """

initialize(version: str, build_data: dict[str, Any]) -> None initialize(version: str, build_data: dict[str, Any]) -> None

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: str, build_data: dict[str, Any]) -> None:
    """
    This occurs immediately before each build.

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

finalize(version: str, build_data: dict[str, Any], artifact_path: str) -> None finalize(version: str, build_data: dict[str, Any], artifact_path: str) -> None

This occurs immediately after each build and will not run if the --hooks-only flag was passed to the build command.これは各ビルドの直後に発生し、--hooks-onlyフラグがbuildコマンドに渡された場合は実行されません。

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: str, build_data: dict[str, Any], artifact_path: str) -> None:
    """
    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.
    """