Skip to content

Environment configuration

すべての環境は、tool.hatch.envsテーブル内のセクションとして定義されます。

[tool.hatch.envs.<ENV_NAME>]

[envs.<ENV_NAME>]

環境のstorage locationは、完全に設定可能です。

コマンドラインで環境が明示的に選択されていない限り、default環境が使用されます。この環境のtypeのデフォルトはvirtualです。

Info

hatch-で始まる環境は、testingのように特殊な目的で使用されます。

Inheritance

すべての環境は、そのテンプレートオプションで定義された環境を継承します。デフォルトはデフォルトです。

したがって、次のように設定します。:

[tool.hatch.envs.foo]
type = "baz"
skip-install = true

[tool.hatch.envs.bar]
template = "foo"
skip-install = false

[envs.foo]
type = "baz"
skip-install = true

[envs.bar]
template = "foo"
skip-install = false

環境barのタイプはbazになり、skip-installはfalseに設定されます。

Note

環境はmatricesを継承しません。

Self-referential environments

継承を無効にするには、templateを環境独自の名前に設定します。:

[tool.hatch.envs.foo]
template = "foo"

[envs.foo]
template = "foo"

Detached environments

一般的なユースケースは、継承やプロジェクトのインストールを必要としないスタンドアロン環境で、リンティングや時にはドキュメントの構築などに使用されます。detachedオプションを有効にすると、環境はself-referentialになり、skip project installation:

[tool.hatch.envs.lint]
detached = true

[envs.lint]
detached = true

Dependencies

project's metadataで定義されたものに加えて、dependenciesをインストールできます。エントリはcontext formattingをサポートします。

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

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

inherited environmentsとわずかに異なる依存関係を持つ環境を定義する場合は、extra-dependenciesオプションを使用してdependenciesオプションの再宣言を避けることができます。:

[tool.hatch.envs.default]
dependencies = [
  "foo",
  "bar",
]

[tool.hatch.envs.experimental]
extra-dependencies = [
  "baz",
]

[envs.default]
dependencies = [
  "foo",
  "bar",
]

[envs.experimental]
extra-dependencies = [
  "baz",
]

Tip

Hatchはpipを使用して依存関係をインストールするため、Hatchをサポートする任意のconfigurationも同様にインストールします。たとえば、プライベートリポジトリのみを使用したい場合は、PIP_INDEX_URL環境変数を設定できます。

Installation

Features (extras)

プロジェクトにoptional dependenciesが定義されている場合は、featuresオプションを使用してインストールするグループを選択できます。:

[tool.hatch.envs.nightly]
features = [
  "server",
  "grpc",
]

[envs.nightly]
features = [
  "server",
  "grpc",
]

Note

機能/オプションの依存関係は、他のツールではエキストラとも呼ばれます。

Dev mode

デフォルトでは、環境は常にディスク上のプロジェクトの現在の状態を反映します。たとえば、Python環境で編集可能モードでインストールします。この動作を無効にし、新しい環境の作成時にのみプロジェクトをインストールするには、dev-modeをfalseに設定します。それ以降は、プロジェクトのインストールを手動で管理する必要があります。

[tool.hatch.envs.static]
dev-mode = false

[envs.static]
dev-mode = false

Skip install

デフォルトでは、環境は作成中にプロジェクトをインストールします。この手順を無視するには、skip-installをtrueに設定します。:

[tool.hatch.envs.lint]
skip-install = true

[envs.lint]
skip-install = true

Environment variables

Defined

環境変数はenv-varsオプションで定義できます。:

[tool.hatch.envs.docs]
dependencies = [
  "mkdocs"
]
[tool.hatch.envs.docs.env-vars]
SOURCE_DATE_EPOCH = "1580601600"

[envs.docs]
dependencies = [
  "mkdocs"
]
[envs.docs.env-vars]
SOURCE_DATE_EPOCH = "1580601600"

値はcontext formattingをサポートします。

Filters

デフォルトでは、環境はすべての環境変数にアクセスできます。env-include/env-excludeオプションを使用して、ワイルドカードパターンでフィルタリングできます。:

[tool.hatch.envs.<ENV_NAME>]
env-include = [
  "FOO*",
]
env-exclude = [
  "BAR",
]

[envs.<ENV_NAME>]
env-include = [
  "FOO*",
]
env-exclude = [
  "BAR",
]

除外パターンが優先されますが、defined環境変数には影響しません。

Scripts

他のスクリプトの先頭でexecutedまたは参照される名前付きスクリプトを定義できます。Context formattingがサポートされています。

たとえば、次の設定では:

[tool.hatch.envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]
[tool.hatch.envs.test.scripts]
run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=tests"
run = "run-coverage --no-cov"

[envs.test]
dependencies = [
  "coverage[toml]",
  "pytest",
  "pytest-cov",
  "pytest-mock",
]
[envs.test.scripts]
run-coverage = "pytest --cov-config=pyproject.toml --cov=pkg --cov=tests"
run = "run-coverage --no-cov"

runスクリプトは次のように展開されます。:

pytest --cov-config=pyproject.toml --cov=pkg --cov=tests --no-cov

スクリプトは、文字列の配列として定義することもできます。

[tool.hatch.envs.style]
detached = true
dependencies = [
  "flake8",
  "black",
  "isort",
]
[tool.hatch.envs.style.scripts]
check = [
  "flake8 .",
  "black --check --diff .",
  "isort --check-only --diff .",
]
fmt = [
  "isort .",
  "black .",
  "check",
]

[envs.style]
detached = true
dependencies = [
  "flake8",
  "black",
  "isort",
]
[envs.style.scripts]
check = [
  "flake8 .",
  "black --check --diff .",
  "isort --check-only --diff .",
]
fmt = [
  "isort .",
  "black .",
  "check",
]

makeと同様に、-(ハイフン)で始まるコマンドの終了コードは無視できます。たとえば、次の設定で定義されているスクリプトerrorは、終了コードとして3を持つ2番目のコマンドの後で停止します。:

[tool.hatch.envs.test.scripts]
error = [
  "- exit 1",
  "exit 3",
  "exit 0",
]

[envs.test.scripts]
error = [
  "- exit 1",
  "exit 3",
  "exit 0",
]

Extra scripts

個々のスクリプトは、オプションと同様に親環境からinheritします。個々のスクリプトが親環境で定義されたスクリプトを上書きしないようにするには、代わりに「extra-scripts」オプションを使用します。このオプションでは、定義されていないスクリプトしか追加できません。

Commands

すべてのコマンドは、定義された任意のscriptsを使用できます。また、スクリプトと同様に、context formattingもサポートされており、ハイフンで始まるコマンドの終了コードは無視されます。

Pre-install

プロジェクトのenvironmentsinstallの直前にコマンドを実行できます。

[tool.hatch.envs.<ENV_NAME>]
pre-install-commands = [
  "...",
]

[envs.<ENV_NAME>]
pre-install-commands = [
  "...",
]

Post-install

プロジェクトをenvironmentsinstallした直後にコマンドを実行できます。

[tool.hatch.envs.<ENV_NAME>]
post-install-commands = [
  "...",
]

[envs.<ENV_NAME>]
post-install-commands = [
  "...",
]

Python version

pythonオプションは、使用するPythonのバージョン、またはPythonインタプリタへの絶対パスを指定します。:

[tool.hatch.envs.<ENV_NAME>]
python = "3.10"

[envs.<ENV_NAME>]
python = "3.10"

すべてのenvironment typesは、このオプションに従う必要があります。

Supported platforms

platformsオプションは、環境と互換性のあるオペレーティングシステムを示します。:

[tool.hatch.envs.<ENV_NAME>]
platforms = ["linux", "windows", "macos"]

[envs.<ENV_NAME>]
platforms = ["linux", "windows", "macos"]

The following platforms are supported:

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

  • linux
  • windows
  • macos

指定しない場合、環境はすべてのプラットフォームと互換性があると見なされます。

Description

descriptionオプションは単なる情報であり、env showコマンドの出力に表示されます。:

[tool.hatch.envs.<ENV_NAME>]
description = """
Lorem ipsum ...
"""

[envs.<ENV_NAME>]
description = """
Lorem ipsum ...
"""

Type

環境の「タイプ」によって、どのenvironment pluginが管理に使用されるかが決まります。唯一の組み込み環境タイプはvirtualで、仮想Python環境を使用します。