Advanced environment configuration¶高度な環境設定¶

Context formatting¶コンテキストフォーマット¶

All environments support the following extra context formatting fields:すべての環境は、以下の追加コンテキストフォーマットフィールドをサポートしています:

Fieldフィールド	Description説明
`env_nameenv_name`	The name of the environment環境の名前
`env_typeenv_type`	The type of environment環境のタイプ
`matrixmatrix`	Its modifier selects the value of that matrix variable. If the environment is not part of a matrix or was not generated with the variable, you must specify a default value as an additional modifier e.g. `{matrix:version:v1.0.0}`.その修飾子は、その行列変数の値を選択します。環境が行列の一部でない場合や、変数で生成されていない場合は、追加の修飾子としてデフォルト値を指定する必要があります。例えば、`{matrix:version:v1.0.0}`のように。
`verbosityverbosity`	The integer verbosity value of Hatch. A `flag` modifier is supported that will render the value as a CLI flag e.g. `-2` becomes `-qq`, `1` becomes `-v`, and `0` becomes an empty string. An additional flag integer modifier may be used to adjust the verbosity level. For example, if you wanted to make a command quiet by default, you could use `{verbosity:flag:-1}` within the command.Hatchの整数の冗長性値。`flag`修飾子がサポートされており、値をCLIフラグとして表示します。例えば、`-2`は`-qq`になり、`1`は`-v`になり、`0`は空の文字列になります。冗長性レベルを調整するために、追加のフラグ整数修飾子を使用できます。例えば、デフォルトでコマンドを静かにしたい場合は、コマンド内で`{verbosity:flag:-1}`を使用できます。
`argsargs`	For executed commands only, any extra command line arguments with an optional default modifier if none were provided実行されたコマンドのみ、提供されていない場合のオプションのデフォルト修飾子を持つ追加のコマンドライン引数。

Matrix¶Matrix¶

Environments can define a series of matrices with the matrix option:環境はmatrixオプションを使用して、一連の行列を定義できます：

pyproject.toml hatch.toml

[tool.hatch.envs.test]
dependencies = [
  "pytest"
]

[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11"]
version = ["42", "3.14"]

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["9000"]
feature = ["foo", "bar"]

[envs.test]
dependencies = [
  "pytest"
]

[[envs.test.matrix]]
python = ["3.10", "3.11"]
version = ["42", "3.14"]

[[envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["9000"]
feature = ["foo", "bar"]

Doing so will result in the product of each variable combination being its own environment.これを行うと、各変数の組み合わせの積がそれぞれ独自の環境になります。

Naming¶Naming¶

The name of the generated environments will be the variable values of each combination separated by hyphens, altogether prefixed by <ENV_NAME>.. For example, the following configuration:生成された環境の名前は、各組み合わせの変数値をハイフンで区切ったもので、全体が<ENV_NAME>.でプレフィックスされます。例えば、次の構成:

pyproject.toml hatch.toml

[[tool.hatch.envs.test.matrix]]
version = ["42"]
feature = ["foo", "bar"]

[[envs.test.matrix]]
version = ["42"]
feature = ["foo", "bar"]

would indicate the following unique environments:は、次のユニークな環境を示します:

test.42-foo
test.42-bar

The exceptions to this format are described below.この形式の例外は以下に説明されています。

Python variables¶Python変数¶

If the variables py or python are specified, then they will rank first in the product result and will be prefixed by py if the value is not. For example, the following configuration:pyまたはpythonが指定されている場合、それらは製品結果の最初にランク付けされ、値がない場合はpyでプレフィックスされます。例えば、次の構成:

pyproject.toml hatch.toml

[[tool.hatch.envs.test.matrix]]
version = ["42"]
python = ["3.9", "pypy3"]

[[envs.test.matrix]]
version = ["42"]
python = ["3.9", "pypy3"]

would generate the following environments:は、次の環境を生成します:

test.py3.9-42
test.pypy3-42

Note注意

The value of this variable sets the Python version.この変数の値は、Pythonバージョンを設定します。

Name formatting¶名前のフォーマット¶

You can set the matrix-name-format option to modify how each variable part is formatted which recognizes the placeholders {variable} and {value}. For example, the following configuration:matrix-name-formatオプションを設定することで、各変数部分のフォーマット方法を変更できます。このオプションは、プレースホルダー{variable}と{value}を認識します。例えば、次の構成:

pyproject.toml hatch.toml

[tool.hatch.envs.test]
matrix-name-format = "{variable}_{value}"

[[tool.hatch.envs.test.matrix]]
version = ["42"]
feature = ["foo", "bar"]

[envs.test]
matrix-name-format = "{variable}_{value}"

[[envs.test.matrix]]
version = ["42"]
feature = ["foo", "bar"]

would produce the following environments:は、次の環境を生成します:

test.version_42-feature_foo
test.version_42-feature_bar

By default this option is set to {value}.デフォルトでは、このオプションは{value}に設定されています。

Default environment¶デフォルト環境¶

If the default environment defines matrices, then the generated names will not be prefixed by the environment name. This can be useful for projects that only need a single series of matrices without any standalone environments.もしdefault環境が行列を定義している場合、生成された名前は環境名で接頭辞が付けられません。これは、スタンドアロン環境なしで単一の行列系列のみを必要とするプロジェクトにとって便利です。

Selection¶選択¶

Rather than selecting a single generated environment, you can select the root environment to target all of them. For example, if you have the following configuration:単一の生成環境を選択するのではなく、ルート環境を選択してすべての環境をターゲットにすることができます。たとえば、次の構成がある場合：

pyproject.toml hatch.toml

[tool.hatch.envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
]

[tool.hatch.envs.test.scripts]
cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests'

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["42", "3.14"]

[envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
]

[envs.test.scripts]
cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests'

[[envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["42", "3.14"]

you could then run your tests consecutively in all 4 environments with:その後、すべての4つの環境でテストを連続して実行できます：

hatch run test:cov

Dependency Groups¶依存関係グループ¶

Environments can use dependency groups¹ using the environment dependency-groups array:環境は、環境dependency-groups配列を使用して依存関係グループ¹を使用できます：

pyproject.toml hatch.toml

[dependency-groups]
test = [
  "pytest>=7.0.0",
  "pytest-cov>=4.1.0",
]
lint = [
  "black",
  "ruff",
  "mypy",
]
# Groups can include other groups
dev = [
  {"include-group": "test"},
  {"include-group": "lint"},
  "pre-commit",
]

[tool.hatch.envs.test]
dependency-groups = ["test"]

[tool.hatch.envs.lint]
dependency-groups = ["lint"]

[tool.hatch.envs.dev]
dependency-groups = ["dev"]

[dependency-groups]
test = [
  "pytest>=7.0.0",
  "pytest-cov>=4.1.0",
]
lint = [
  "black",
  "ruff",
  "mypy",
]
# Groups can include other groups
dev = [
  {"include-group": "test"},
  {"include-group": "lint"},
  "pre-commit",
]

[envs.test]
dependency-groups = ["test"]

[envs.lint]
dependency-groups = ["lint"]

[envs.dev]
dependency-groups = ["dev"]

The dependency-groups array specifies which dependency groups to include in the environment's dependencies. This is particularly useful for organizing related dependencies and including them in appropriate environments.dependency-groups配列は、環境の依存関係に含める依存関係グループを指定します。これは、関連する依存関係を整理し、適切な環境に含めるのに特に便利です。

Combining with Other Dependencies¶他の依存関係との組み合わせ¶

Dependency groups can be combined with other dependency mechanisms:依存関係グループは、他の依存関係メカニズムと組み合わせることができます：

pyproject.toml hatch.toml

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
  "requests>=2.28.0",
]

[dependency-groups]
test = ["pytest>=7.0.0"]
docs = ["sphinx>=7.0.0"]

[tool.hatch.envs.test]
# Include the test dependency group
dependency-groups = ["test"]
# Add environment-specific dependencies
dependencies = [
  "coverage[toml]>=7.0.0",
]

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
  "requests>=2.28.0",
]

[dependency-groups]
test = ["pytest>=7.0.0"]
docs = ["sphinx>=7.0.0"]

[envs.test]
# Include the test dependency group
dependency-groups = ["test"]
# Add environment-specific dependencies
dependencies = [
  "coverage[toml]>=7.0.0",
]

In this example, the test environment would include: 1. Project dependencies (requests>=2.28.0) 2. The test dependency group (pytest>=7.0.0) 3. Environment-specific dependencies (coverage[toml]>=7.0.0)この例では、テスト環境には以下が含まれます： 1. プロジェクト依存関係 (requests>=2.28.0) 2. テスト依存関係グループ (pytest>=7.0.0) 3. 環境特有の依存関係 (coverage[toml]>=7.0.0)

Option overrides¶オプションのオーバーライド¶

You can modify options based on the conditions of different sources like matrix variables with the overrides table, using dotted key syntax for each declaration:異なるソースの条件に基づいてオプションを変更できます。例えば、マトリックス変数を使用して、overridesテーブルを使い、各宣言に対してドットキー構文を使用します：

pyproject.toml hatch.toml

[tool.hatch.envs.<ENV_NAME>.overrides]
<SOURCE>.<CONDITION>.<OPTION> = <VALUE>

[envs.<ENV_NAME>.overrides]
<SOURCE>.<CONDITION>.<OPTION> = <VALUE>

The type of the selected option determines the types of values.選択したオプションのタイプが値のタイプを決定します。

Platform overrides¶プラットフォームのオーバーライド¶

Options can be modified based on the current platform using the platform source.現在のプラットフォームに基づいてオプションを変更できます。platformソースを使用します。

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
platform.windows.scripts = [
  'run=pytest -m "not io_uring"',
]

[envs.test.overrides]
platform.windows.scripts = [
  'run=pytest -m "not io_uring"',
]

The following platforms are supported:以下のプラットフォームがサポートされています：

linuxlinux
windowswindows
macosmacos

Environment variable overrides¶環境変数のオーバーライド¶

Environment variables can modify options using the env source.環境変数は、envソースを使用してオプションを変更できます。

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
env.GITHUB_ACTIONS.dev-mode = { value = false, if = ["true"] }

[envs.test.overrides]
env.GITHUB_ACTIONS.dev-mode = { value = false, if = ["true"] }

Matrix variable overrides¶マトリックス変数のオーバーライド¶

The matrix variables used to generate each environment can be used to modify options within using the matrix source.各環境を生成するために使用されるマトリックス変数は、matrixソースを使用してオプションを変更するために使用できます。

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
matrix.version.env-vars = "PRODUCT_VERSION"
matrix.auth.features = [
  { value = "oauth", if = ["oauth2"] },
  { value = "kerberos", if = ["kerberos"] },
]

[[tool.hatch.envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["legacy", "latest"]
auth = ["oauth2", "kerberos", "noauth"]

[envs.test.overrides]
matrix.version.env-vars = "PRODUCT_VERSION"
matrix.auth.features = [
  { value = "oauth", if = ["oauth2"] },
  { value = "kerberos", if = ["kerberos"] },
]

[[envs.test.matrix]]
python = ["3.11", "3.12"]
version = ["legacy", "latest"]
auth = ["oauth2", "kerberos", "noauth"]

Name overrides¶名前のオーバーライド¶

When a matrix is defined, the name source can be used for regular expression matching on the generated name, minus the prefix for non-default environments.マトリックスが定義されている場合、nameソースは、非デフォルト環境のプレフィックスを除いた生成された名前に対して正規表現マッチングに使用できます。

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
name."^0".env-vars = "TESTING_UNSTABLE=true"

[[tool.hatch.envs.test.matrix]]
version = ["0.1.0", "0.2.0", "1.0.0"]

[envs.test.overrides]
name."^0".env-vars = "TESTING_UNSTABLE=true"

[[envs.test.matrix]]
version = ["0.1.0", "0.2.0", "1.0.0"]

Types¶タイプ¶

Literal types like strings for the Python version or booleans for skipping installation can be set using the value itself, an inline table, or an array. For example:Pythonバージョンのような文字列や、インストールをスキップするためのブーリアンのようなリテラルタイプは、値自体、インラインテーブル、または配列を使用して設定できます。例えば：
pyproject.toml hatch.toml
[tool.hatch.envs.test.overrides] matrix.foo.python = "3.10" matrix.bar.skip-install = { value = true, if = ["..."] } env.CI.dev-mode = [ { value = false, if = ["..."] }, true, ]
[envs.test.overrides] matrix.foo.python = "3.10" matrix.bar.skip-install = { value = true, if = ["..."] } env.CI.dev-mode = [ { value = false, if = ["..."] }, true, ]
For arrays, the first allowed value will be used.配列の場合、最初に許可された値が使用されます。
Array types like dependencies or commands can be appended to using an array of strings or inline tables. For example:依存関係やコマンドのような配列タイプは、文字列の配列やインラインテーブルを使用して追加できます。例えば：
pyproject.toml hatch.toml
[tool.hatch.envs.test.overrides] matrix.foo.dependencies = [ "httpx", { value = "cryptography" }, ]
[envs.test.overrides] matrix.foo.dependencies = [ "httpx", { value = "cryptography" }, ]
Mapping types like environment variables or scripts can have keys set using a string, or an array of strings or inline tables. For example:環境変数やスクリプトのようなマッピングタイプは、文字列、文字列の配列、またはインラインテーブルを使用してキーを設定できます。例えば：
pyproject.toml hatch.toml
[tool.hatch.envs.test.overrides] matrix.foo.env-vars = "KEY=VALUE" matrix.bar.env-vars = [ "KEY1=VALUE1", { key = "KEY2", value = "VALUE2" }, ]
[envs.test.overrides] matrix.foo.env-vars = "KEY=VALUE" matrix.bar.env-vars = [ "KEY1=VALUE1", { key = "KEY2", value = "VALUE2" }, ]
If the value is missing (no = for strings, no value key for inline tables), then the value will be set to the value of the source condition.値が欠落している場合（文字列に=がない、インラインテーブルにvalueキーがない）、その値はソース条件の値に設定されます。

Overwriting¶上書き¶

Rather than supplementing the values within mapping types or array types, you can overwrite the option as a whole by prefixing the name with set-:マッピングタイプや配列タイプ内の値を補完するのではなく、名前の前にset-を付けることでオプション全体を上書きできます：

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
matrix.foo.set-platforms = ["macos", "linux"]

[envs.test.overrides]
matrix.foo.set-platforms = ["macos", "linux"]

When overwriting entire options or keys within mappings, override sources are applied in the following order:マッピング内の全オプションやキーを上書きする際には、上書きソースが以下の順序で適用されます：

platformプラットフォーム
environment variables環境変数
matrix variablesマトリックス変数
names名前

Conditions¶条件¶

You may specify certain extra keys for any inline table that will determine whether or not to apply that entry. These modifiers may be combined with others and any negative evaluation will immediately cause the entry to be skipped.インラインテーブルに対して、エントリを適用するかどうかを決定するための特定の追加キーを指定できます。これらの修飾子は他のものと組み合わせることができ、いずれかの否定的評価があれば、エントリは即座にスキップされます。

Allowed values¶許可された値¶

The if key represents the allowed values for that condition. If the value of the condition is not listed, then that entry will not be applied:ifキーは、その条件に対する許可された値を表します。条件の値がリストに含まれていない場合、そのエントリは適用されません:

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
matrix.version.python = { value = "pypy", if = ["3.14"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[tool.hatch.envs.test.matrix]]
version = ["42", "3.14"]

[envs.test.overrides]
matrix.version.python = { value = "pypy", if = ["3.14"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[envs.test.matrix]]
version = ["42", "3.14"]

Specific platforms¶特定のプラットフォーム¶

The platform key represents the desired platforms. If the current platform is not listed, then that entry will not be applied:platformキーは、希望するプラットフォームを表します。現在のプラットフォームがリストに含まれていない場合、そのエントリは適用されません:

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
env.EXPERIMENTAL.python = { value = "pypy", if = ["1"], platform = ["macos"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"], platform = ["linux"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[tool.hatch.envs.test.matrix]]
version = ["42", "3.14"]

[envs.test.overrides]
env.EXPERIMENTAL.python = { value = "pypy", if = ["1"], platform = ["macos"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"], platform = ["linux"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[envs.test.matrix]]
version = ["42", "3.14"]

Required environment variables¶必須環境変数¶

The env key represents the required environment variables. If any of the listed environment variables are not set or the defined value does not match, then that entry will not be applied:envキーは、必須の環境変数を表します。リストに含まれる環境変数のいずれかが設定されていないか、定義された値が一致しない場合、そのエントリは適用されません:

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
platform.windows.python = { value = "pypy", env = ["EXPERIMENTAL"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"], env = ["FOO", "BAR=BAZ"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[tool.hatch.envs.test.matrix]]
version = ["42", "3.14"]

[envs.test.overrides]
platform.windows.python = { value = "pypy", env = ["EXPERIMENTAL"] }
matrix.version.env-vars = [
  { key = "KEY1", value = "VALUE1", if = ["42"], env = ["FOO", "BAR=BAZ"] },
  { key = "KEY2", value = "VALUE2", if = ["3.14"] },
]

[[envs.test.matrix]]
version = ["42", "3.14"]

PEP 735 – Dependency Groups in pyproject.toml ↩PEP 735 – pyproject.tomlにおける依存関係グループ ↩