Build configuration¶ビルド構成¶

Build targets are defined as sections within tool.hatch.build.targets:ビルドターゲットは、tool.hatch.build.targets内のセクションとして定義されます:

pyproject.toml hatch.toml

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

[build.targets.<TARGET_NAME>]

Tipヒント

Although not recommended, you may define global configuration in the tool.hatch.build table. Keys may then be overridden by target config.推奨はされませんが、tool.hatch.buildテーブル内にグローバル構成を定義することができます。キーはターゲット構成によって上書きされる場合があります。

Build system¶ビルドシステム¶

To be compatible with the broader Python packaging ecosystem, you must define the build system as follows:より広範なPythonパッケージエコシステムと互換性を持たせるために、次のようにビルドシステムを定義する必要があります:

pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

The version of hatchling defined here will be used to build all targets.ここで定義されたhatchlingのバージョンは、すべてのターゲットをビルドするために使用されます。

Hatchling is a standards-compliant¹ build backend and is a dependency of Hatch itself.Hatchlingは標準準拠の¹ビルドバックエンドであり、Hatch自体の依存関係です。

File selection¶ファイル選択¶

VCS¶VCS¶

By default, Hatch will respect the first .gitignore or .hgignore file found in your project's root directory or parent directories. Set ignore-vcs to true to disable this behavior:デフォルトでは、Hatchはプロジェクトのルートディレクトリまたは親ディレクトリで見つかった最初の.gitignoreまたは.hgignoreファイルを尊重します。この動作を無効にするには、ignore-vcsをtrueに設定します:

pyproject.toml hatch.toml

[tool.hatch.build.targets.sdist]
ignore-vcs = true

[build.targets.sdist]
ignore-vcs = true

Note注意

For .hgignore files only glob syntax is supported..hgignoreファイルでは、グロブ構文のみがサポートされています。

Patterns¶パターン¶

You can set the include and exclude options to select exactly which files will be shipped in each build, with exclude taking precedence. Every entry represents a Git-style glob pattern.各ビルドに含まれるファイルを正確に選択するために、includeおよびexcludeオプションを設定できます。excludeが優先されます。各エントリはGitスタイルのグロブパターンを表します。

For example, the following configuration:例えば、次の設定は:

pyproject.toml hatch.toml

[tool.hatch.build.targets.sdist]
include = [
  "pkg/*.py",
  "/tests",
]
exclude = [
  "*.json",
  "pkg/_compat.py",
]

[build.targets.sdist]
include = [
  "pkg/*.py",
  "/tests",
]
exclude = [
  "*.json",
  "pkg/_compat.py",
]

will exclude every file with a .json extension, and will include everything under a tests directory located at the root and every file with a .py extension that is directly under a pkg directory located at the root except for _compat.py..json拡張子を持つすべてのファイルを除外し、ルートにあるtestsディレクトリ内のすべてのファイルと、ルートにあるpkgディレクトリ直下の.py拡張子を持つすべてのファイル（_compat.pyを除く）を含めます。

Artifacts¶アーティファクト¶

If you want to include files that are ignored by your VCS, such as those that might be created by build hooks, you can use the artifacts option. This option is semantically equivalent to include.ビルドフックによって作成される可能性のある、VCSによって無視されるファイルを含めたい場合は、artifactsオプションを使用できます。このオプションはincludeと意味的に同等です。

Note that artifacts are not affected by the exclude option. Artifacts can be excluded by using more explicit paths or by using the ! negation operator. When using the ! operator, the negated pattern(s) must come after the more generic ones.アーティファクトはexcludeオプションの影響を受けないことに注意してください。アーティファクトは、より明示的なパスを使用するか、!否定演算子を使用することで除外できます。!演算子を使用する場合、否定されたパターンはより一般的なものの後に来る必要があります。

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel]
artifacts = [
  "*.so",
  "*.dll",
  "!/foo/*.so",
]

[build.targets.wheel]
artifacts = [
  "*.so",
  "*.dll",
  "!/foo/*.so",
]

Explicit selection¶明示的選択¶

Generic¶一般的¶

You can use the only-include option to prevent directory traversal starting at the project root and only select specific relative paths to directories or files. Using this option ignores any defined include patterns.only-includeオプションを使用して、プロジェクトのルートからのディレクトリトラバーサルを防ぎ、特定の相対パスのディレクトリやファイルのみを選択できます。このオプションを使用すると、定義されたincludeパターンは無視されます。

pyproject.toml hatch.toml

[tool.hatch.build.targets.sdist]
only-include = ["pkg", "tests/unit"]

[build.targets.sdist]
only-include = ["pkg", "tests/unit"]

Packages¶パッケージ¶

The packages option is semantically equivalent to only-include (which takes precedence) except that the shipped path will be collapsed to only include the final component.packagesオプションは、only-include（こちらが優先されます）と意味的に同等ですが、出荷されるパスは最終コンポーネントのみを含むように圧縮されます。

So for example, if you want to ship a package foo that is stored in a directory src you would do:例えば、srcディレクトリに保存されているパッケージfooを出荷したい場合は、次のようにします：

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel]
packages = ["src/foo"]

[build.targets.wheel]
packages = ["src/foo"]

Forced inclusion¶強制的な含め方¶

The force-include option allows you to select specific files or directories from anywhere on the file system that should be included and map them to the desired relative distribution path.force-includeオプションを使用すると、ファイルシステム上の任意の場所から特定のファイルやディレクトリを選択して含め、それらを希望する相対配布パスにマッピングできます。

For example, if there was a directory alongside the project root named artifacts containing a file named lib.so and a file named lib.h in your home directory, you could ship both files in a pkg directory with the following configuration:例えば、プロジェクトルートの隣にartifactsという名前のディレクトリがあり、その中にlib.soというファイルと、ホームディレクトリにlib.hというファイルがある場合、次の設定で両方のファイルをpkgディレクトリに出荷できます：

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"

[build.targets.wheel.force-include]
"../artifacts" = "pkg"
"~/lib.h" = "pkg/lib.h"

Note注意

Files must be mapped exactly to their desired paths, not to directories.ファイルは、希望するパスに正確にマッピングされなければなりません。ディレクトリにはマッピングできません。
The contents of directory sources are recursively included.ディレクトリソースの内容は再帰的に含まれます。
To map directory contents directly to the root use / (a forward slash).ディレクトリの内容をルートに直接マッピングするには、/（スラッシュ）を使用します。
Sources that do not exist will raise an error.存在しないソースはエラーを引き起こします。

Warning警告

Files included using this option will overwrite any file path that was already included by other file selection options.このオプションを使用して含まれるファイルは、他のファイル選択オプションによって既に含まれているファイルパスを上書きします。

Default file selection¶デフォルトファイル選択¶

If no file selection options are provided, then what gets included is determined by each build target.ファイル選択オプションが提供されていない場合、含まれるものは各ビルドターゲットによって決定されます。

Excluding files outside packages¶パッケージ外のファイルを除外する¶

If you want to exclude non-artifact files that do not reside within a Python package, set only-packages to true:Pythonパッケージ内に存在しない非-アーティファクトファイルを除外したい場合は、only-packagesをtrueに設定します:

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel]
only-packages = true

[build.targets.wheel]
only-packages = true

Rewriting paths¶パスの書き換え¶

You can rewrite relative paths to directories with the sources option. For example, the following configuration:sourcesオプションを使用して、ディレクトリへの相対パスを再書き換えることができます。例えば、次の構成:

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel.sources]
"src/foo" = "bar"

[build.targets.wheel.sources]
"src/foo" = "bar"

would distribute the file src/foo/file.ext as bar/file.ext.は、ファイルsrc/foo/file.extをbar/file.extとして配布します。

If you want to remove path prefixes entirely, rather than setting each to an empty string, you can define sources as an array:パスプレフィックスを完全に削除したい場合は、各プレフィックスを空文字列に設定するのではなく、sourcesを配列として定義できます:

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel]
sources = ["src"]

[build.targets.wheel]
sources = ["src"]

If you want to add a prefix to paths, you can use an empty string. For example, the following configuration:パスにプレフィックスを追加したい場合は、空文字列を使用できます。例えば、次の構成:

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel.sources]
"" = "foo"

[build.targets.wheel.sources]
"" = "foo"

would distribute the file bar/file.ext as foo/bar/file.ext.は、ファイルbar/file.extをfoo/bar/file.extとして配布します。

The packages option itself relies on sources. Defining packages = ["src/foo"] for the wheel target is equivalent to the following:packages オプション自体はソースに依存しています。packages = ["src/foo"] を wheel ターゲットに対して定義することは、以下と同等です：

pyproject.toml hatch.toml

[tool.hatch.build.targets.wheel]
only-include = ["src/foo"]
sources = ["src"]

[build.targets.wheel]
only-include = ["src/foo"]
sources = ["src"]

Performance¶パフォーマンス¶

All encountered directories are traversed by default. To skip non-artifact directories that are excluded, set skip-excluded-dirs to true:デフォルトでは、遭遇したすべてのディレクトリがトラバースされます。除外された非アーティファクトディレクトリをスキップするには、skip-excluded-dirs を true に設定します：

pyproject.toml hatch.toml

[tool.hatch.build]
skip-excluded-dirs = true

[build]
skip-excluded-dirs = true

Warning警告

This may result in not shipping desired files. For example, if you want to include the file a/b/c.txt but your VCS ignores a/b, the file c.txt will not be seen because its parent directory will not be entered. In such cases you can use the force-include option.これにより、望ましいファイルが出荷されない可能性があります。たとえば、a/b/c.txt ファイルを含めたいが、あなたのVCSが a/b を無視している場合、親ディレクトリに入らないため、ファイル c.txt は見えなくなります。このような場合は、force-include オプションを使用できます。

Reproducible builds¶再現可能なビルド¶

By default, build targets will build in a reproducible manner provided that they support that behavior. To disable this, set reproducible to false:デフォルトでは、ビルドターゲットは、その動作をサポートしている限り、再現可能な方法でビルドされます。これを無効にするには、reproducible を false に設定します：

pyproject.toml hatch.toml

[tool.hatch.build]
reproducible = false

[build]
reproducible = false

When enabled, the SOURCE_DATE_EPOCH environment variable will be used for all build timestamps. If not set, then Hatch will use an unchanging default value.有効にすると、すべてのビルドタイムスタンプに SOURCE_DATE_EPOCH 環境変数が使用されます。設定されていない場合、Hatch は変わらないデフォルト値を使用します。

Output directory¶出力ディレクトリ¶

When the output directory is not provided to the build command, the dist directory will be used by default. You can change the default to a different directory using a relative or absolute path like so:出力ディレクトリがbuild コマンドに提供されていない場合、デフォルトで dist ディレクトリが使用されます。相対パスまたは絶対パスを使用して、デフォルトを別のディレクトリに変更できます：

pyproject.toml hatch.toml

[tool.hatch.build]
directory = "<PATH>"

[build]
directory = "<PATH>"

Dev mode¶開発モード¶

By default for dev mode environment installations or editable installs, the wheel target will determine which directories should be added to Python's search path based on the selected files.デフォルトでは、dev mode 環境インストールまたはeditable installsの場合、wheel ターゲットは選択されたファイルに基づいて、Python の検索パスに追加すべきディレクトリを決定します。

If you want to override this detection or perhaps instruct other build targets as well, you can use the dev-mode-dirs option:この検出をオーバーライドしたり、他のビルドターゲットにも指示を出したい場合は、dev-mode-dirsオプションを使用できます:

pyproject.toml hatch.toml

[tool.hatch.build]
dev-mode-dirs = ["."]

[build]
dev-mode-dirs = ["."]

If you don't want to add entire directories to Python's search path, you can enable a more targeted mechanism with the mutually exclusive dev-mode-exact option:Pythonの検索パスにディレクトリ全体を追加したくない場合は、相互排他的なdev-mode-exactオプションを使用して、よりターゲットを絞ったメカニズムを有効にできます:

pyproject.toml hatch.toml

[tool.hatch.build]
dev-mode-exact = true

[build]
dev-mode-exact = true

Warning警告

The dev-mode-exact mechanism is not supported by static analysis tools & IDEs, therefore functionality such as autocompletion is unlikely to work.dev-mode-exactメカニズムは、静的解析ツールやIDEではサポートされていません。したがって、オートコンプリートなどの機能は動作しない可能性が高いです。

Build targets¶ビルドターゲット¶

A build target can be provided by any builder plugin. There are three built-in build targets: wheel, sdist, and custom.ビルドターゲットは、任意のビルダープラグインによって提供できます。組み込みのビルドターゲットは3つあります: wheel、sdist、およびcustom。

Dependencies¶依存関係¶

You can specify additional dependencies that will be installed in each build environment, such as for third party builders:サードパーティビルダー用など、各ビルド環境にインストールされる追加の依存関係を指定できます:

pyproject.toml hatch.toml

[tool.hatch.build.targets.your-target-name]
dependencies = [
  "your-builder-plugin"
]

[build.targets.your-target-name]
dependencies = [
  "your-builder-plugin"
]

You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option:プロジェクトのランタイム依存関係に対する依存をrequire-runtime-dependenciesオプションで宣言することもできます:

pyproject.toml hatch.toml

[tool.hatch.build.targets.your-target-name]
require-runtime-dependencies = true

[build.targets.your-target-name]
require-runtime-dependencies = true

Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option:さらに、require-runtime-featuresオプションを使用して、プロジェクトの特定のランタイム機能に対する依存を宣言することもできます:

pyproject.toml hatch.toml

[tool.hatch.build.targets.your-target-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

[build.targets.your-target-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

Versions¶バージョン¶

If a build target supports multiple build strategies or if there are major changes over time, you can specify exactly which versions you want to build using the versions option:ビルドターゲットが複数のビルド戦略をサポートしている場合や、時間の経過とともに大きな変更がある場合は、versionsオプションを使用して、ビルドしたいバージョンを正確に指定できます:

pyproject.toml hatch.toml

[tool.hatch.build.targets.<TARGET_NAME>]
versions = [
  "v1",
  "beta-feature",
]

[build.targets.<TARGET_NAME>]
versions = [
  "v1",
  "beta-feature",
]

See the wheel target for a real world example.実際の例についてはwheelターゲットを参照してください。

Build hooks¶ビルドフック¶

A build hook defines code that will be executed at various stages of the build process and can be provided by any build hook plugin. There is one built-in build hook: custom.ビルドフックは、ビルドプロセスのさまざまな段階で実行されるコードを定義し、任意のビルドフックプラグインによって提供されることができます。組み込みのビルドフックは1つあります: custom。

Build hooks can be applied either globally:ビルドフックは、グローバルに適用することができます:

pyproject.toml hatch.toml

[tool.hatch.build.hooks.<HOOK_NAME>]

[build.hooks.<HOOK_NAME>]

or to specific build targets:または特定のビルドターゲットに適用することができます:

pyproject.toml hatch.toml

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

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

Dependencies¶依存関係¶

You can specify additional dependencies that will be installed in each build environment, such as for third party build hooks:サードパーティのビルドフックなど、各ビルド環境にインストールされる追加の依存関係を指定できます:

pyproject.toml hatch.toml

[tool.hatch.build.hooks.your-hook-name]
dependencies = [
  "your-build-hook-plugin"
]

[build.hooks.your-hook-name]
dependencies = [
  "your-build-hook-plugin"
]

You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option:プロジェクトのランタイム依存関係に対する依存をrequire-runtime-dependenciesオプションで宣言することもできます:

pyproject.toml hatch.toml

[tool.hatch.build.hooks.your-hook-name]
require-runtime-dependencies = true

[build.hooks.your-hook-name]
require-runtime-dependencies = true

Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option:さらに、プロジェクトの特定のランタイム機能に対する依存をrequire-runtime-featuresオプションで宣言することができます:

pyproject.toml hatch.toml

[tool.hatch.build.hooks.your-hook-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

[build.hooks.your-hook-name]
require-runtime-features = [
  "feature1",
  "feature2",
]

Order of execution¶実行順序¶

For each build target, build hooks execute in the order in which they are defined, starting with global hooks.各ビルドターゲットに対して、ビルドフックは定義された順序で実行され、グローバルフックから始まります。

As an example, for the following configuration:次の構成の例として：

pyproject.toml hatch.toml

[tool.hatch.build.targets.foo.hooks.hook2]

[tool.hatch.build.hooks.hook3]
[tool.hatch.build.hooks.hook1]

[build.targets.foo.hooks.hook2]

[build.hooks.hook3]
[build.hooks.hook1]

When target foo is built, build hook hook3 will be executed first, followed by hook1, and then finally hook2.ターゲット foo がビルドされると、ビルドフック hook3 が最初に実行され、その後に hook1、最後に hook2 が実行されます。

Conditional execution¶条件付き実行¶

If you want to disable a build hook by default and control its use by environment variables, you can do so by setting the enable-by-default option to false:ビルドフックをデフォルトで無効にし、環境変数によってその使用を制御したい場合は、enable-by-default オプションを false に設定することで可能です：

pyproject.toml hatch.toml

[tool.hatch.build.hooks.<HOOK_NAME>]
enable-by-default = false

[build.hooks.<HOOK_NAME>]
enable-by-default = false

Environment variables¶環境変数¶

Variable変数	Defaultデフォルト	Description説明
`HATCH_BUILD_CLEANHATCH_BUILD_CLEAN`	`falsefalse`	Whether or not existing artifacts should first be removed既存のアーティファクトを最初に削除するかどうか
`HATCH_BUILD_CLEAN_HOOKS_AFTERHATCH_BUILD_CLEAN_HOOKS_AFTER`	`falsefalse`	Whether or not build hook artifacts should be removed after each build各ビルド後にビルドフックアーティファクトを削除するかどうか
`HATCH_BUILD_HOOKS_ONLYHATCH_BUILD_HOOKS_ONLY`	`falsefalse`	Whether or not to only execute build hooksビルドフックのみを実行するかどうか
`HATCH_BUILD_NO_HOOKSHATCH_BUILD_NO_HOOKS`	`falsefalse`	Whether or not to disable all build hooks; this takes precedence over other optionsすべてのビルドフックを無効にするかどうか; これは他のオプションよりも優先されます
`HATCH_BUILD_HOOKS_ENABLEHATCH_BUILD_HOOKS_ENABLE`	`falsefalse`	Whether or not to enable all build hooksすべてのビルドフックを有効にするかどうか
`HATCH_BUILD_HOOK_ENABLE_<HOOK_NAME>HATCH_BUILD_HOOK_ENABLE_<HOOK_NAME>`	`falsefalse`	Whether or not to enable the build hook named `<HOOK_NAME><HOOK_NAME>`という名前のビルドフックを有効にするかどうか
`HATCH_BUILD_LOCATIONHATCH_BUILD_LOCATION`	`distdist`	The location with which to build the targets; only used by the `build` commandターゲットを構築するための場所; `build` コマンドによってのみ使用されます。

Support for PEP 517 and PEP 660 guarantees interoperability with other build tools. ↩PEP 517 と PEP 660 のサポートは、他のビルドツールとの相互運用性を保証します。 ↩