Pythonパッケージングツール#

パッケージ構築のためのツール#

Python パッケージの sdist ディストリビューションと wheel ディストリビューションを作成するために使えるビルドツールはいくつかあります。以下では、最もよく使われる Python パッケージングツールの機能、利点、制限について説明します。このガイドでは純粋な Python パッケージに焦点を当てます。しかし、現在C/C++やその他の言語拡張を含むパッケージをサポートしているツールも紹介します。

さまざまなフロントエンドとバックエンドのパッケージングツールを示すデシジョンツリー図。どのパッケージングツールを使うかは、どんな機能が必要かを考えることで決めることができます。 PDMとHatchは、異なるビルドバックエンドを使用しているため、現在のところ最も柔軟なツールです。 PDMとHatchは初心者に最も喜ばれるツールで、Poetryはその次です。 Poetryは純粋なPythonプロジェクトに適しています。 — Pythonパッケージのエコシステムで利用可能な、さまざまなフロントエンドビルドツールを示す図です。この図に含めるツールは、エコシステムで最も利用されているツールを理解するのに役立ったPyPI調査に基づいて選択しました。各ツールには、以下のように異なる特徴があります。#

他の言語で書かれた拡張機能を持つPythonパッケージについてもっと知りたい場合は、複雑なパッケージのビルドのページをチェックしてください

ここでレビューするツール#

このセクションでは、PyPAのアンケートで最も人気のあったパッケージングツールを紹介します。このページでは以下のツールについて詳しく説明します:

ツールまとめ Hatch vs PDM vs Poetry (と setuptools)#

簡単な要約をお探しの方は、以下をお読みください。

一般的に、このページから選択した最新のツールは、パッケージを構築するのに適しています。ツールの選択は、ワークフローに求める機能によって決まります。
初心者の方は、 setuptools の複雑な操作ではなく、PDMのような最新のワークフローツールから始めることをお勧めします。
Poetryを使うのであれば (最も人気のあるツールであり、最高のドキュメントを持っています) 、依存関係の追加上限値に注意し、依存関係を追加する際にオーバーライドすることを検討してください。そうすれば、Poetryは純粋なPythonビルドでもうまく動くでしょう！また、Poetryには活発な discord があり、質問をすることができます。

以下は、ハッチとPDMが提供し、Poetryが提供しない機能です。

PDM:

他のバックエンドをサポートしているので、純粋な Python ではないビルドに最適です。つまり、PDMはmeson-pythonや他のビルドバックエンドをサポートしているので、純粋なPythonにも、より複雑なPythonビルドにも最適なオプションです。
依存関係の管理に柔軟性があります
必要に応じてファイルをロックすることも可能です

Hatch:

Pythonのバージョンにまたがってテストを実行できるマトリックス環境管理を提供します。もしこの機能があなたにとって重要なら、Hatch が明らかに勝者です。
ビルドワークフローを効率化するNox/Makeファイルのようなツールを提供します。ワークフローにおけるツールの数を減らしたいのであれば、Hatchはうってつけかもしれません。

フロントエンド構築ツールとバックエンド構築ツール#

Pythonパッケージのビルドに関して、あなたの選択肢をよりよく理解するためには、まずビルドツールのフロントエンドとビルドのバックエンドの違いを理解することが重要です。

バックエンドのビルド#

ほとんどのパッケージングツールには、パッケージをビルドし、関連する (sdistとwheel)配布ファイルを作成するバックエンドビルドツールがあります。 Flit のようないくつかのツールは、純粋なPythonパッケージのビルドのみをサポートしています。純粋な Python のビルドとは、他のプログラミング言語 (C や C++ など) で書かれた拡張機能を持たないパッケージのビルドを指します。

C や C++の拡張を持つ他のパッケージ(あるいは fortran のような他の言語を包含するパッケージ)は、ビルド時に追加のコードコンパイルステップを必要とします。 setuptools.build 、 meson.build 、 scikit-build などのバックエンドは、カスタムステップによる複雑なビルドをサポートしています。ビルドが特に複雑な場合（つまり C/C++ 拡張モジュールが数個以上ある場合）は、 meson.build または scikit-build を使用することをお勧めします。

Pythonパッケージビルドフロントエンド#

パッケージングフロントエンドツールとは、同様のコマンドを使用して一般的なパッケージングタスクを簡単に実行できるようにするツールのことです。これらのタスクには以下のようなものがあります:

パッケージのビルド (sdist と wheel ディストリビューションの作成)
開発モードでパッケージをインストールします (コードを更新したときに更新されるようにします)
PyPIへの公開
テストの実行
ドキュメントの作成
テストの実行やパッケージの開発が必要な環境、または複数の環境の管理

純粋な Python のビルドに使える Python パッケージングツールがいくつかあります。以下で説明する各フロントエンドツールは、少しずつ異なる Python パッケージングタスクをサポートしています。

例えば、パッケージングツールの Flit、Hatch、PDM を使って、パッケージのビルドと PyPI への公開の両方を行うことができます。しかし、HatchとPDMはバージョン管理と環境管理をサポートしていますが、 Flit はサポートしていません。依存性ロックをサポートするツールが欲しい場合は、PDMやPoetryを使うことができますが、 Hatch は使えません。パッケージのsdistとwheelの配布ファイルをビルドするだけなら、PyPAのBuildで十分です。その後、Twineを使ってPyPIに公開します。

注釈

Setuptools を使用している場合、複数のタスクを実行するデフォルトのユーザーフレンドリーなビルドフロントエンドはありません。パッケージをビルドするには build を、PyPI に公開するには twine を使う必要があります。

フロントエンドツールを使って簡略化できるビルド手順の例#

以下に、ビルドツールがパッケージングをどのように効率化するかを示します。 Hatch でパッケージをビルドする例です:

# Build your sDist and .whl files
hatch build

# Example to publish to PyPI:
hatch publish --repo test

setuptools バックエンドと build を使用したビルド手順の例:

# Build the package
python3 -m build

# Publish to test PyPI using twine
twine upload -r testpypi dist/*

ビルドバックエンドの選択#

ほとんどのフロントエンドパッケージングツールは、独自のバックエンドビルドツールを持っています。ビルドツールはパッケージの (sdistやwheelの) 配布ファイルを作成します。純粋なPythonパッケージの場合、以下で説明するビルドバックエンド間の主な違いは以下の通りです:

設定可能性 - 例えば、Python以外の拡張機能をサポートするビルドステップを追加することはできますか？
正しいファイルがsdistとwheelディストリビューションに含まれていることを確認するために、どの程度設定する必要があるか。

純粋なPythonパッケージ以外のバックエンドサポートの構築#

Flit-core のようないくつかのビルドバックエンドは、純粋なPythonビルドしかサポートしていないことに注意することが重要です。その他のバックエンドは、以下のようにCとC++の拡張をサポートしています:

setuptools は、C / C++ 拡張モジュールを使用したビルドをサポートします。
Hatchling (hatchのバックエンド) は、開発者がビルドをカスタマイズするために作成するプラグインによって、C/C++の拡張機能をサポートしています。
PDMのバックエンドは、setuptoolsを使用してC / C++拡張をサポートしています。
PoetryのバックエンドはC/C++拡張をサポートしていますが、この機能は現在ドキュメント化されていません。そのため、ドキュメント化されるまでは、複雑なビルドや純粋なPython以外のビルドにPoetryを使うことはお勧めしません。

以下では、より複雑なビルドについては説明しませんが、どのツールがC / C++の拡張機能を文書でサポートしているかを確認します。

Pythonビルドツールのエコシステム#

以下では、最もよく使われる Python パッケージングビルドフロントエンドツールをいくつか紹介します。どのツールがあなたのワークフローに最適かを決める手助けとして、各ツールが提供する機能を強調します。

setuptools の使用はお勧めしません

setuptoolsは、正しくセットアップするためにいくつかの追加知識を必要とするため、setuptoolsではなく、上記の近代的なツールのいずれかを選択することをお勧めします。

バックエンドとしてsetuptoolsをレビューするのは、今でも人気があるからです。しかし、それは最もユーザーフレンドリーなオプションではありません。

エコシステムで最もよく使われるツールは、setuptoolsのバックエンド（ビルド機能付き）とPoetry（多数の機能と優れたドキュメントを備えたフロントエンドツール）です。

2022年のPyPAによるPythonパッケージングツールの調査結果を示すグラフです。 X軸は回答率、Y軸はツールです。 — Python developers survey results (n=>8,000 PyPI users)では、最もよく使われているPythonパッケージングツールとしてsetuptoolsとpoetryが挙げられています。科学コミュニティで使用されているコアツールはここに含まれています。ここをクリックすると、調査結果の全文を見ることができます。注意: このデータはドメイン全体のメンテナを表しており、ウェブ開発関係者が多く含まれているようです。これはより広い Python エコシステム全体のスナップショットを表しています。#

ビルドワークフローツールの選択#

以下にレビューするツールは以下の通り:

Twine, Build + setuptools
Flit
Hatch
PDM
Poetry

ツールを選ぶ際には、このような一般的な質問の流れを考慮するとよいでしょう:

あなたのツールは純粋なパイソンですか？はい？ お好きなツールをお使いください！あなたのビルドワークフローで使いたい機能を持つツールを選んでください。お勧めは:

Flit、Hatch、PDM、またはPoetry (詳しくは以下をお読みください)

あなたのツールはCやC++の拡張機能をいくつか持っていますか？ 当面は PDM を使うことをお勧めします。以下のリストの中で、このような拡張をサポートするワークフローが文書化されており、ビルドフックだけではワークフローが不十分な場合に他のバックエンドをサポートする唯一のツールです。 PDMは、scikit-buildやmeson-pythonなどの他のバックエンドをサポートしており、パッケージのビルドを完全にカスタマイズすることができます。

注: 純粋なpython以外のビルドにもHatchを使うことができます。 Hatch は PDM と同様に、独自のビルドフックやプラグインを書くことができます。しかし現在、hatchは他のビルドバックエンドをサポートしていない。コアな科学パッケージの多くは、パッケージをビルドするために meson-pythonに移行しています。したがって、PDMが特にmeson-pythonと連携できることはありがたいです。

Pythonパッケージングツールまとめ#

以下に、最も人気のあるビルドフロントエンドツールが提供する機能を要約します。これらのフロントエンドツールは、あなたのワークフローにおいて他のコアツールを使う必要性をなくすということを覚えておくことが重要です。例えばsetuptoolsを使う場合、パッケージをビルドしてPyPIに公開するためにBuildとTwineも使う必要があります。しかし、PoetryやHatch、PDMを使う場合は、同じツールを使ってこれらすべてを行うことができます (例：hatch build、hatch publish、pdm build、pdm publish) 。

setuptoolsはフロントエンドインターフェースを提供していないので、この表には含まれていないことに注意してください。

パッケージツール機能一覧表#

機能	Flit	Hatch	PDM	Poetry
デフォルトのビルドバックエンド	Flit-core	hatchling	PDM	Poetry-core
他のビルドバックエンドを使う	✖	✅	✅	✖
依存関係の管理	✖	✖	✅	✅
PyPIに公開する	✅	✅	✅	✅
バージョン管理ベースのバージョニング ( `git tags` を使用)	✖	✅	✅	✅
バージョンバンプ	✖	✅	✅	✅
環境マネジメント	✖	✅	✅	✅
メンテナンス担当者が複数いるか？ (バスファクター)	✖	✖	✖	✅

注釈:

Hatch は将来的に従属性管理をサポートする予定です
Poetry はセマンティックバージョニングをサポートしています。したがって、Python Semantic Releaseのようなツールを使えば、コミットメッセージに続くバージョンバンプをサポートします。

PDM#

PDM は Python のパッケージングと依存関係管理ツールです。PDM は純粋な Python プロジェクトのビルドをサポートします。また、C や C++ の拡張を持つプロジェクトに対しても多層的なサポートを提供します。

CおよびC++拡張のPDMサポート

PDMはPDM-back-endとsetuptoolsの同時使用をサポートしています。つまり、setuptools を実行して C 拡張モジュールをコンパイルビルドすることができます。 PDMのビルドバックエンドはコンパイルされた拡張ファイル(.so, .pyd)を受け取り、純粋なPythonファイルと一緒にパッケージ化します。

PDM の特徴#

機能	PDM	注釈
他のビルドバックエンドを使う	✅	PDMをセットアップする際、いくつかのビルドバックエンドから1つを選択することができます: PDM-core、flit-core、hatchlingなどです。 PDMはまた、複雑なPythonビルドをサポートするMeson-Pythonとも連携できます。
依存仕様	✅	PDM は依存関係の管理を柔軟にサポートしています。PDM はデフォルトでオープンバウンド(例えば `requests >=1.2`)のアプローチを使用します。しかし、Poetry のような上限を使用する別のアプローチを好む場合、依存関係の追加方法をカスタマイズできます。**
環境ロックファイル	✅	PDMとPoetryは現在、環境ロックファイルを作成する唯一のツールです。ロックファイルは、一貫したユーザーエクスペリエンスのために環境をロックすることが重要なウェブアプリを作成する開発者にとって、しばしば最も有用です。コミュニティで使われるパッケージでは、ロックファイルを使うことはないでしょう。
環境マネジメント	✅	PDMは環境管理のサポートを提供します。 Python仮想環境、conda、そしてPythonエコシステムの新しいオプションであるローカルの `__pypackages__` 環境をサポートしています。このサポートに拡張は必要ありません。
インストール時に環境タイプを選択	✅	`PDM init` を実行すると、PDMがあなたのシステム上にある環境を検出し、プロジェクトに使用する環境を選択できるようになります。
PyPIに公開する	✅	PDM は test PyPI と PyPI の両方への公開をサポートしています
バージョン管理ベースのバージョニング	✅	PDMには setuptools_scm のようなツールが組み込まれており、gitタグに依存したダイナミックバージョニングを使うことができます。
バージョンバンプ	✅	PDMは、標準的なセマンティックバージョニングである patch; minor; major を使って、パッケージのバージョンをバンプすることをサポートしています。
現行のパッケージング基準に従う	✅	PDMは pyproject.toml ファイルにメタデータを追加するための現在のパッケージング標準をサポートしています。
編集可能モードでパッケージをインストールする	✅	PDMは編集可能モードでのパッケージのインストールをサポートしています。
sdistとwheelディストリビューションの構築	✅	他のツール同様、PDMはパッケージのsdistとwheelファイルをビルドしてくれます。

PDM vs. Poetry

PDMの機能はPoetryに似ています。しかし、PDMはC拡張やバージョン管理ベースのバージョニングを文書でサポートしています。そのため、純粋なPython以外のパッケージで作業する場合は、PDMを使うことをお勧めします。

もしあなたがPoetryとPDMのどちらを選ぶか決めているのであれば、より小さな違いは依存関係をpyproject.tomlファイルに追加するデフォルトの方法です。

Poetryはデフォルトで、pyproject.tomlファイルに上界制約(^)を使って依存関係を追加する、厳密なセマンティックバージョニングに従っています。アッパーバウンズロックとは、ポエトリーが依存関係を次のメジャーバージョン（1.2から2.0など）にバンプさせないことを意味します。しかし、次のように明示的にパッケージを追加することで、Poetryにオープンバウンドのアプローチを使うように指示することができる： poetry add requests >= 1.2` のように明示的にパッケージを追加することで、Poetry にオープンバウンドのアプローチを使うように指示することができます (すなわち、アッパーバウンドロックとは、リクエスト2.0が出たとしてもインストールされることはなく、あなたのパッケージはその恩恵を受けることができるということです) 。
PDMのデフォルトはオープンバウンド(>=)依存性の追加で、これは科学的なpythonのエコシステムでは好ましいアプローチです。しかし、PDMではデフォルトで依存関係を追加する方法を指定することもできます。そのため、その方法が必要であれば、PDMを使用して上限 (^) を指定することもできます。

最後に、両ツールのロックファイルの作成方法には微妙な違いがありますが、ここでは詳しく説明しません。

PDMの課題#

PDMはフル機能のパッケージングツールです。しかし、課題がないわけではありません:

PDMのドキュメントは、特に初めてパッケージングを行う場合、混乱する可能性があります。例えば、PDMのドキュメントには、最初から最後までのワークフローが記載されていません。
また、PDMには現在1人のメンテナしかいません。私たちは、個々のメンテナチームは潜在的なリスクであると考えています。もしメンテナがプロジェクトに取り組む時間がなくなったら、ユーザーにはサポートのギャップが残ります。 HatchとFlitにも、一人のメンテナチームがあります。

PDMを使用したパッケージの例はこちらからご覧いただけます。このREADMEファイルでは、PDMコマンドラインインターフェイスを使用する際にどのように見えるかの概要を直接説明しています。

Flit#

Flitは、最新のPythonパッケージング標準をサポートする、飾り気のない、合理的なパッケージングツールです。 Flitは、ローカル・ワークフローで使用する基本的なパッケージを構築し、高度な機能を必要としない場合に最適な選択です。また、パッケージ構造がすでに作成されている場合。詳しくは後述します。

Flit の特徴#

機能	Flit	注釈
PyPIとtest PyPIに公開する	✅	Flit は test PyPI と PyPI の両方への公開をサポートしています
pyproject.toml ファイルにメタデータを追加するのに役立ちます。	✅	Flitは pyproject.toml ファイルにメタデータを追加することをサポートしています。
現行のパッケージング基準に従う	✅	Flitは、 pyproject.toml ファイルにメタデータを追加する現在のパッケージング標準をサポートしています。
編集可能モードでパッケージをインストールする	✅	Flitは編集可能モードでのパッケージのインストールをサポートしています。**
sdistとwheelディストリビューションの構築	✅	Flitはsdistとwheelのディストリビューションパッケージのビルドに使用できます。

注: 最新バージョンのpipを使用している場合、シンボリックリンクを使った flit install -s と python -m pip install -e . の両方をサポートしています。

flitについてもっと知る

なぜflitを使うのか？

Flitを使いたくない理由#

Flitは飾り気がないので、基本的で素早いビルドに最適です。初心者の方は、一般的な操作をよりサポートしてくれるHatchやPDMを選ぶとよいでしょう。

次のような場合は、flitを使用しない方がよいです:

より高度なバージョン追跡と管理をセットアップしたい場合 (バージョン管理を使ってバージョンバンプを行う)
依存性のあるバージョンを処理するツールが必要（代わりにPDMやPoetryを使用する）
純粋なPythonではないプロジェクトを持っている（Hatch、PDM、またはsetuptoolsを使用する）
環境を管理したい（PDM、Hatch、またはPoetryを使用する）

Hatch#

Hatch は、ポエトリーやPDMと同様、統一されたコマンドラインインターフェイスを提供する。HatchをPoetryやPDMから切り離すために、Pythonの異なるバージョン間でローカルにテストを実行しやすくするテスト用の環境マネージャーも提供しています。また、nox / makefileのような機能もあり、ドキュメントをローカルでビルドするようなカスタムビルドワークフローを作成することができる。つまり、ワークフローから Make や Nox のようなツールを削除して、代わりにHatchを使うことができる可能性があるということだ。

Hatchの特徴#

機能	Hatch	注釈
他のビルドバックエンドを使う	✅	HatchはデフォルトでHatchlingバックエンドと一緒に使われますが、pyproject.tomlの宣言を切り替えることで別のバックエンドを使うことができます。
依存関係の管理	✖	現在のところ、Hatchを使って手動で依存関係を追加する必要があります。しかし、依存関係の管理をサポートする機能が将来のリリースで追加されるかもしれません。
環境マネジメント	✅	HatchはPython仮想環境をサポートしています。 Condaのような他の環境を使いたい場合は、 condaをサポートするhatch-condaのようなプラグインをインストールする必要があります。
PyPIとtest PyPIに公開する	✅	Hatch は test PyPI と PyPI の両方への公開をサポートしています
バージョン管理ベースのバージョニング	✅	Hatch が提供する `hatch_vcs` は setuptools_scm を使って git タグを使ったバージョン管理をサポートするプラグインです。 hatch_vcs`を使ったワークフローは`setuptools_scm` を使ったワークフローと同じです。
バージョンバンプ	✅	Hatchは、標準的なセマンティックバージョニングである patch; minor; major を使って、パッケージのバージョンをバンプすることをサポートしています。
現行のパッケージング基準に従う	✅	Hatchは、 pyproject.toml ファイルにメタデータを追加する現在のパッケージング標準をサポートしています。
編集可能モードでパッケージをインストールする	✅	Hatchはデフォルトで編集可能なモードで、あなたのパッケージをどの環境にもインストールします。 `python -m pip install -e .` を使って、編集可能モードでパッケージを手動でインストールできます。Hatchは editable installs に言及していますが、ドキュメントではpipを参照しています。
sdistとwheelディストリビューションの構築	✅	Hatchはsdistとホイールのディストリビューションを構築します
✨Pythonのバージョンをまたいだテストをサポートするためのマトリックス環境の構築✨	✅	マトリックス環境の作成は、パッケージングエコシステムにおける Hatch 独自の機能です。この機能は、（tox のようなツールを使う代わりに）Python のバージョンにまたがってパッケージをローカルでテストしたい場合に便利です。
✨Nox / MAKEFILEのような機能性✨	✅	これもHatchならではの特徴だ。この機能により、pyproject.toml 設定にワークフローを作成し、ドキュメントをローカルに提供したり、パッケージのビルドディレクトリをクリーニングしたりすることができます。これは、ビルドワークフローのツールが1つ減ることを意味します。
✨柔軟なビルドバックエンド: hatchling✨	✅	**Hatchのメンテナが提供するhatchlingビルドバックエンドは、開発者がパッケージング時にカスタムビルドステップをサポートするプラグインを簡単にビルドすることを可能にします。

このアプローチは、メンテナにカスタムビルドシステムを作る負担を強いるという議論があリマス。しかし、柔軟性を高く評価する人もいます。ハッチのビルドフックアプローチは、PDMが提供する機能にも匹敵します。

ハッチを使いたくない理由#

hatchには、一部の人にとって重要かもしれないいくつかの機能が欠けています。それは以下のようなものです:

Hatchは依存関係の追加をサポートしていません。手動で追加する必要があります。
HatchはプラグインなしではデフォルトでConda環境を認識しません。
PDMと同様、Hatchのドキュメントを読みこなすのは難しいです。特にパッケージの作成を始めたばかりであればなおさらです。
Hatchは、PDMやFlitと同様、現在1人のメンテナしかいません。

Poetry#

Poetry はフル機能のビルドツールです。また、（PyPAの調査に基づく）2番目に人気のあるフロントエンドパッケージングツールでもあります。 Poetry はユーザーフレンドリーで、きれいで読みやすいドキュメントを持っています。

注釈

C/C++ 拡張を含む Python のビルドに Poetry を使っている人もいますが、このサポートは現在のところ文書化されていません。したがって、より複雑なビルドに Poetry を使うことはお勧めしません。

Poetryの特徴#

機能	Poetry	注釈
pyproject.tomlファイルに依存関係を追加	✅	Poetry は `pyproject.toml` メタデータへの依存関係の追加をサポートします。
依存仕様	✅	Poetryはパッケージのpyproject.tomlファイルに追加する依存関係のバージョンを指定することができます。しかし、デフォルトの上限アプローチはパッケージによっては問題があります(依存関係を追加するときはデフォルトの設定を上書きすることをお勧めします)。詳しくは以下をお読みください。
環境マネジメント	✅	Poetryでは、ビルトイン環境を使用するか、パッケージ管理に使用する環境タイプを選択することができます。内蔵された環境管理オプションについての詳細はこちら。
ファイルのロック	✅	Poetryは poetry.lock ファイルを作成するので、ビルドにロックファイルが必要な場合に使用します。
PyPIとtest PyPIに公開する	✅	Poetry は test PyPI と PyPI の両方への公開をサポートしています
バージョン管理ベースのバージョニング	✅	Poetry dynamic versioning プラグインは、Poetryでgitタグを使ったバージョン管理をサポートします。
バージョンバンプ	✅	Poetryでは、標準的なセマンティックバージョン用語である patch; minor; major を使ってパッケージのバージョンを上げることができます。
現行のパッケージング基準に従う	✅	バージョン 2.0 以降、Poetry は最新のプロジェクトメタデータ標準をサポートしています。ただし、すべての標準がサポートされているわけではなく、従来の Poetry 形式もサポートされています。詳細については以下をお読みください。
編集可能モードでパッケージをインストールする	✅	Poetry は編集可能モードでのパッケージのインストールをサポートします。
sdistとwheelディストリビューションの構築	✅	Poetry は `poetry build` を使って sdist と wheel ディストリビューションをビルドします。

Poetryの課題#

Poetryの課題には次のようなものがある:

Poetry has its own format for grouped dependencies ([tool.poetry.group.<name>.dependencies]), which predates the dependency groups standard (PEP 735). Poetry 2.2 and later also support the standard [dependency-groups] table, which this guide suggests for development dependencies. Grouped dependencies should not be confused with "optional" dependencies (poetry add --optional=EXTRA_NAME DEPENDENCY), which are standardised and let you group your dependencies into several optional groups.
Poetry はデフォルトで「上限」制限(レガシーフォーマットでは ^ 記号で指定)を使って依存関係をピン留めします。しかし、この動作は poetry add を使うときに依存関係を次のように指定することで上書きできます: poetry add "requests>=2.1" 上限によるピン留めをめぐる問題については、以下の解説を参照してください。

Poetry は人気のあるパッケージングツールで、非常に便利な多くの機能を導入しました。しかし、使用する場合は依存関係の追加時に注意してください。Poetry のピン留めのアプローチは多くのビルドで問題になる可能性があります。Poetry を使う場合は、デフォルトの上限依存関係オプションをオーバーライドすることを強くお勧めします。

Poetry依存のピン留めの課題

デフォルトでは、Poetry は ^ を使って依存関係をピン留めします。このシンボル ^ は依存関係に "上限" があることを意味します。従って、poetryは依存バージョンを新しいメジャーバージョンにバンプすることはありません。したがって、あなたのパッケージがバージョン1.2.3の依存関係を使用している場合、Poetryは、パッケージの新しいメジャーバージョンがあっても、依存関係を2.0にバンプすることはありません。 Poetryは代わりに1.9.xにアップグレードします。

Poetryは、メジャーバージョンアップ（例えば1.0から2.0へ）は、ツールに破壊的な変更があることを意味するという、厳密なセマンティックバージョニングを遵守しているからです。しかし、すべてのツールが厳密なセマンティックバージョニングに従っているわけではありません。このアプローチは、私たちのコアとなる科学パッケージの多くによって問題があることが判明しています

例えば、 calver を使って、日付に基づいて新しいバージョンを作成するツールもある。

Setuptools バックエンドを Build フロントエンドと共に使って Python パッケージングを行う#

Setuptoolsは最も成熟したPythonパッケージングビルドツールで、開発は2009年以前にさかのぼります。また、（PyPAの調査によると）Setuptoolsは最も多くのコミュニティユーザを抱えています。 Setuptoolsは、Flit、Poetry、Hatchのようなユーザーフロントエンドを提供していません。そのため、パッケージの配布を作成するには build を、PyPI に公開するには twine などの他のツールを使用する必要があります。

setuptoolsは最もよく使われるツールですが、パッケージメンテナには、PoetryやHatch、PDMなど、パッケージングにもっとモダンなツールを使うことを検討することをお勧めします。

ここでsetuptoolsについて説明するのは、それがエコシステムでよく見られるものであり、貢献者がそれを理解することで恩恵を受けるかもしれないからです。

Setuptools の特徴#

setuptoolsの機能には次のようなものがあります:

完全にカスタマイズ可能なビルドワークフロー
多くの科学的Pythonパッケージがこれを使用しています。
setuptools_scm を使用したバージョン管理ベースのパッケージのバージョン管理を提供します。
メタデータに pyproject.toml を使用した最新のパッケージングをサポートしています。
古いパッケージングアプローチの下位互換性をサポートします。

setuptoolsの課題#

Setuptoolsにはいくつかの課題があります:

Setuptoolsは、VSCODEのようなIDEで作業し、編集可能なインストーラを開発に使用している場合、デフォルトでは自動/タブ補完のようなインタラクティブな機能をサポートしていません。 pylanceのサポートについてはこちらを参照。それに比べて、flit、hatch、PDMのようなツールは、VSCODEやpycharmのようなIDE（pipのバージョンが最新である限り!）を使っているときに、タブや自動補完のようなインタラクティブな機能をサポートしています。
setuptools は様々なパッケージの後方互換性を維持しなければならないため、最新のPythonパッケージング標準を採用する柔軟性がありません。
上記の後方互換性は、より複雑なコードベースとなります。
このページで説明する他のツールに比べ、setuptoolsを使用した場合、ユーザーとしての体験は合理的でシンプルなものではなくなります。

また、setuptoolsを使用する際にユーザーが注意すべき、問題のあるデフォルト設定がいくつかあります。例えば:

メタデータを保存するために pyproject.toml ファイルを使用していない場合、setuptoolsは名前やバージョンなしでプロジェクトをビルドします。
setuptoolsは、 MANIFEST.in ファイルを使ってファイルを除外するように明示的に指示しなければ、パッケージリポジトリ内のすべてのファイルも含めます。