Managing dependencies
Dependency groups
Poetryは、依存関係をグループ別に整理する方法を提供します。たとえば、プロジェクトのテストやドキュメントの構築にのみ必要な依存関係がある場合があります。
新しい依存関係グループを宣言するには、tool.poetry.group.<group>セクションを使用します。ここで、<group>は依存関係グループの名前です(例えばtest)。
[tool.poetry.group.test] # This part can be left out
[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"
Note
すべての依存関係は、インストールに必要かどうかにかかわらず解決されるため、グループ間で相互に互換性がある必要があります(Installing group dependenciesを参照)。
依存関係グループは、依存関係に関連付けられたラベルと考えることができます。依存関係がデフォルトで解決されてインストールされるかどうかには何の関係もなく、単に依存関係を論理的に整理するための手段にすぎません。
Note
tool.poetry.dependenciesで宣言された依存関係は、暗黙的なmainグループの一部です。
[tool.poetry.dependencies] # main dependency group
httpx = "*"
pendulum = "*"
[tool.poetry.group.test.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"
Note
暗黙的なmainグループ以外の依存関係グループには、開発プロセスで必要な依存関係のみを含める必要があります。インストールするには、Poetryを使用する必要があります。
実行時にプロジェクトに追加機能を追加する一連の依存関係を宣言するには、代わりにextrasを使用します。extrasはpipを使用してエンドユーザがインストールできます。
Note
dev依存関係グループの定義に関する注意
Poetry 1.2.0以降、dev依存関係グループを定義する適切な方法は次のとおりです。
[tool.poetry.group.dev.dependencies]
pytest = "^6.0.0"
pytest-mock = "*"
このグループ表記はPoetry 1.2.0以降で推奨されており、以前のバージョンでは使用できません。
古いバージョンのPoetryとの下位互換性のために、dev-dependenciesセクションで宣言された依存関係は自動的にdevグループに追加されます。
したがって、上記の表記と次の表記は同じです。
# Poetry pre-1.2.x style, understood by Poetry 1.0–1.2
[tool.poetry.dev-dependencies]
pytest = "^6.0.0"
pytest-mock = "*"
Poetryは、まもなく廃止されるdev-dependencies表記から徐々に移行するので、既存の開発依存関係を新しいgroup表記に移行することをお勧めします。
Optional groups
依存性グループはオプションとして宣言できます。これは、特定の環境または特定の目的でのみ必要な依存性のグループがある場合に意味があります。
[tool.poetry.group.docs]
optional = true
[tool.poetry.group.docs.dependencies]
mkdocs = "*"
installコマンドの--withオプションを使用すると、default依存関係に加えてオプションのグループをインストールできます。
poetry install --with docs
Warning
オプションのグループの依存関係は、他の依存関係とともに引き続き解決されるため、相互に互換性があることを確認するために特別な注意が必要です。
Adding a dependency to a group
addコマンドは、グループに依存関係を追加するための推奨される方法です。これは--group(-G)オプションを使用して行います。
poetry add pytest --group test
グループがまだ存在しない場合は、自動的に作成されます。
Installing group dependencies
デフォルトでは、poetry installを実行すると、すべての非オプショングループ間の依存関係がインストールされます。
Note
プロジェクトのデフォルトの依存関係セットには、tool.poetry.dependenciesで定義された暗黙的なmainグループと、optional groupとして明示的にマークされていないすべてのグループが含まれます。
--withoutオプションを使用すると、1つ以上のグループを除外できます。
poetry install --without test,docs
--withオプションを使用して、optional groupsをオプトインすることもできます。
poetry install --with docs
Warning
一緒に使用すると、--withoutは--withよりも優先されます。
たとえば、次のコマンドは、オプションのtestグループで指定された依存関係のみをインストールします。
poetry install --with test,docs --without docs
最後に、デフォルトの依存関係セットをインストールせずに、特定のグループのみの依存関係をインストールしたい場合があります。そのためには、--onlyオプションを使用できます。
poetry install --only docs
Note
プロジェクトの実行時依存関係のみをインストールする場合は、--only main表記を使用します。
poetry install --only main
Note
プロジェクトのルートをインストールし、他の依存関係をインストールしない場合は、--only-rootオプションを使用できます。
poetry install --only-root
Removing dependencies from a group
removeコマンドは、特定のグループからパッケージを削除する--groupオプションをサポートしています。
poetry remove mkdocs --group docs
Synchronizing dependencies
Poetryは依存性同期と呼ばれるものをサポートしています。依存性同期は、poetry.lockファイル内のロックされた依存性のみが環境内に存在することを保証し、不要なものを削除します。
これは、installコマンドの--syncオプションを使って行います。
poetry install --sync
--syncオプションは、任意のdependency groups関連オプションと組み合わせて、環境を特定のグループと同期させることができます。エクストラは別であることに注意してください。
インストール対象として選択されなかったエクストラは、--syncに関係なく常に削除されます。
poetry install --without dev --sync
poetry install --with docs --sync
poetry install --only dev
Note
--syncオプションは、現在廃止されている--remove-untrackedオプションに代わるものです。
Layering optional groups
--syncオプションを省略すると、すでにインストールされているものを削除せずに、任意のオプショングループのサブセットをインストールできます。これは、例えば、複数ステージのDockerビルドで、異なるビルドステージでpoetry installを複数回実行する場合に非常に便利です。