Virtual environment¶
これは、virtualenvまたはUVによる仮想環境を使用します。
Configuration¶
環境プラグイン名はvirtualです。
[tool.hatch.envs.<ENV_NAME>]
type = "virtual"
[envs.<ENV_NAME>]
type = "virtual"
Options¶
| Option | Default | Description |
|---|---|---|
python | システム上で検索し、その後環境の作成に使用するPythonのバージョン。デフォルトでは、HATCH_PYTHON環境変数に続いてnormal resolution logicが設定されます。HATCH_PYTHON環境変数をselfに設定すると、Hatchが実行されているPython実行可能ファイルが強制的に使用されます。詳細については、documentationを参照してください。 | |
python-sources | ['external', 'internal'] | これは、リテラルのinternalまたはexternalのいずれかの文字列の配列に設定できます。Externalは、すでにPATH上にあるPython実行可能ファイルのみを考慮します。Internalは、internally managed Python distributionsのみを考慮します。 |
path | 仮想環境への明示的なパス。パスは、プロジェクトのルートに対して絶対パスまたは相対パスにすることができます。このオプションを継承する環境も、このパスを使用します。環境変数HATCH_ENV_TYPE_VIRTUAL_PATHを使用することもできますが、これが優先されます。 | |
system-packages | false | 仮想環境にシステムのsite-packagesディレクトリへのアクセスを許可するかどうか。 |
installer | pip | uvに設定すると、仮想環境の作成と依存関係の管理にそれぞれvirtualenv&pipの代わりにUVが使用されます。UVを自分で提供する場合は、UVバイナリへの絶対パスであるHATCH_ENV_TYPE_VIRTUAL_UV_PATH環境変数を設定できます。この環境変数は、installerオプションを暗黙的にuvに設定します(設定されていない場合)。 |
Location¶
環境のlocationは、次のヒューリスティックな順序で決定されます。:
pathオプション- 設定された
virtualenvironment directory内の環境にちなんだ名前のディレクトリ(ディレクトリがプロジェクトルート内のどこかに存在する場合、またはユーザーのホームディレクトリ内の.virtualenvsディレクトリに設定されている場合) - それ以外の場合、環境は、複数のプロジェクトをサポートするために、構成された
virtualenvironment directory内に深くネストされた構造で保存されます。
また、pathオプションを使用しない場合、default環境のディレクトリ名は正規化されたプロジェクト名になり、より意味のあるdefaultshellプロンプトが表示されます。
Python resolution¶
仮想環境では、必ずPythonの親インストールが必要です。次の規則によって、親の解決方法が決まります。
Pythonの選択は、pythonoptionとそれに続くHATCH_PYTHON環境変数によって決定されます。環境変数を介して選択した場合、解決は停止し、そのパスが無条件に使用されます。
リゾルバはpython-sources optionに基づいており、解決されたすべてのインタプリタは、プロジェクトで定義されたPython supportとの互換性を確保します。
Pythonバージョンが選択されている場合、各リゾルバはそのバージョンを満たすインタプリタを見つけようとします。
バージョンが選択されていない場合、各リゾルバは、Hatchが現在実行されているPythonのバージョンと一致するバージョンを見つけようとします。見つからない場合、各リゾルバは互換性のある最も高いバージョンを見つけようとします。
Note
一部の外部Pythonパスは不安定と見なされ、解決時に無視されます。たとえば、HatchがHomebrew経由でインストールされている場合、インタープリタはいつでも変更または削除される可能性があるため、sys.executableは無視されます。
Note
解決でinternally managed distributionを使用して一致が検出され、更新が利用可能な場合、環境の作成前に最新の配布が自動的にダウンロードされます。
Internal distributions¶
Pythonの内部解像度では、次のオプションが認識されます。
Tip
ディストリビューションのカスタムソースを設定するには、HATCH_PYTHON_SOURCE_<NAME>環境変数を設定します。ここで、<NAME>はディストリビューション名の大文字バージョンで、ピリオドがアンダースコアに置き換えられています。たとえば、HATCH_PYTHON_SOURCE_PYPY3_10です。
CPython¶
| NAME |
|---|
3.7 |
3.8 |
3.9 |
3.10 |
3.11 |
3.12 |
ディストリビューションのソースは、python-build-standaloneプロジェクトです。
一部のディストリビューションにはvariantsがあり、HATCH_PYTHON_VARIANT_<PLATFORM>環境変数で設定できます。ここで、<PLATFORM>は次のいずれかの大文字バージョンです。:
| Platform | Options |
|---|---|
| Linux |
|
| Windows |
|
PyPy¶
| NAME |
|---|
pypy2.7 |
pypy3.9 |
pypy3.10 |
ディストリビューションのソースはPyPyプロジェクトです。
Troubleshooting¶
macOS SIP¶
DYLD_やLD_で始まるようなリンカ環境変数を設定する必要がある場合、running commands時に起動されるSystem Integrity Protectionによって保護された実行可能ファイルは、macOSが環境変数の変更を削除しても、それらの環境変数の変更を認識しません。
Hatchは、そのようなコマンドをシェルコマンドとして解釈しますが、保護されたシェルへのそのようなパスは意図的に無視します。この回避策は、ほとんどのユースケースには十分ですが、次の2つの状況では不十分です。:
- PATHには、保護されていない
sh、bash、zsh、およびfish実行可能ファイルはありません。 - 必要な実行可能ファイルがプロジェクトのscriptであり、環境のlocationにスペースが含まれているか、1241文字を超えています。この場合、
pipおよび他のインストーラは、shebangの制限を回避するために、shebangが/bin/sh(保護されています)を指すようなエントリポイントを作成します。場所を変更するのではなく、例えばpython-m pytestとしてスクリプトを呼び出すことができます(プロジェクトが__main__.pyを出荷することによってその呼び出し方法をサポートしている場合)。