Advanced environment configuration¶

Context formatting¶

すべての環境で、次の追加のcontext formattingフィールドがサポートされています。:

フィールド	説明
`env_name`	環境名
`env_type`	環境のtype
`matrix`	この修飾子は、その行列変数の値を選択します。環境が行列の一部でない場合、または変数を使用して生成されていない場合は、`{matrix:version:v1.0.0}`のように、追加の修飾子としてデフォルト値を指定する必要があります。
`verbosity`	Hatchの整数の冗長値です。値をCLIフラグとしてレンダリングする`flag`修飾子がサポートされています。たとえば、`-2`は`-qq`になり、`1`は`-v`になり、`0`は空の文字列になります。追加のフラグ整数修飾子を使用して、冗長レベルを調整できます。たとえば、コマンドをデフォルトで静かにしたい場合は、コマンド内で`{verbosity:flag:-1}`を使用できます。
`args`	executed commandsの場合のみ、追加のコマンドライン引数と、オプションのデフォルト修飾子(指定されていない場合)

Matrix¶

環境では、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"]

そうすることで、各変数の組み合わせの積が独自の環境になります。

Naming¶

生成される環境の名前は、各組み合わせの変数値をハイフンで区切ったものになり、全体に<ENV_NAME>.という接頭辞が付きます。たとえば、次のように設定します。:

pyproject.toml hatch.toml

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

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

は、次の固有の環境を示します。:

test.42-foo
test.42-bar

この形式の例外については、以下で説明します。

Python variables¶

変数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

この変数の値は、Python versionを設定します。

Name formatting¶

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

次の環境が作成されます。:

test.version_42-feature_foo
test.version_42-feature_bar

デフォルトでは、このオプションは{value}に設定されています。

Default environment¶

デフォルト環境で行列が定義されている場合、生成される名前には環境名の接頭辞が付きません。これは、スタンドアロン環境がなく、一連の行列のみが必要なプロジェクトに役立ちます。

Selection¶

単一の生成された環境をselectingするのではなく、ルート環境を選択してすべての環境をターゲットにすることができます。たとえば、次のように構成します。:

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

次の4つの環境すべてでテストを連続して実行できます。:

hatch run test:cov

Option overrides¶

各宣言にdotted key構文を使用して、overridesテーブルでmatrix variablesのようなさまざまなソースの条件に基づいてオプションを変更できます。:

pyproject.toml hatch.toml

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

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

選択したオプションのtypeによって、値のタイプが決まります。

Platform overrides¶

オプションは、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"',
]

次のプラットフォームがサポートされています。:

linux
windows
macos

Environment variable overrides¶

環境変数は、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¶

各環境の生成に使用されるmatrix変数は、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¶

matrixが定義されている場合、生成された名前の正規表現マッチングには、default以外の環境のプレフィックスを除いた「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¶

=== ":octicons-file-code-16: pyproject.toml"
    ```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,
    ]
    ```

=== ":octicons-file-code-16: hatch.toml"
    ```toml
    [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.

dependenciesやcommandsなどの配列タイプは、文字列の配列またはインラインテーブルを使用して追加できます。次に例を示します:

pyproject.toml hatch.toml

[tool.hatch.envs.test.overrides]
matrix.foo.dependencies = [
  "httpx",
  { value = "cryptography" },
]

[envs.test.overrides]
matrix.foo.dependencies = [
  "httpx",
  { value = "cryptography" },
]

environment variablesやscriptsなどのマッピングタイプでは、文字列、文字列の配列、またはインラインテーブルを使用してキーを設定できます。例:
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" }, ]
値が存在しない場合(文字列の場合は=がなく、インラインテーブルの場合はvalueキーがありません)、値はソース条件の値に設定されます。

Overwriting¶

マッピングタイプや配列タイプ内の値を補完するのではなく、名前の前に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"]

マッピング内のオプションまたはキー全体を上書きする場合、オーバーライドソースは次の順序で適用されます。:

platform
environment variables
matrix variables
names

Conditions¶

任意のインライン・テーブルに対して、そのエントリを適用するかどうかを決定する特定の追加キーを指定できます。これらの修飾子は他の修飾子と組み合わせることができ、負の評価があるとすぐにエントリがスキップされます。

Allowed values¶

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¶

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¶

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