どうすれば setup.py ベースのプロジェクトを近代化できるでしょうか?#

pyproject.toml を追加するべきですか?#

pyproject.toml ファイルは強く推奨されています。pyproject.toml ファイルが存在すること自体は多くをもたらすものではありません。 [1] 実際に強く推奨されているものは、pyproject.toml の中の [build-system] テーブルです。

setup.py は削除されるべきですか?#

いいえ、 setup.py は、近代的な Setuptools ベースのプロジェクトにあっても構いません。 setup.py ファイルは、たまたま Python で書かれている setuptools 向けの正当な設定ファイルなのです。しかしながら、以下のコマンド群は非推奨になっていてもはや実行することは 許されず 、その代わりに以下のようなコマンドを使用するべきです:

非推奨

推奨事項

python setup.py install

python -m pip install .

python setup.py develop

python -m pip install --editable .

python setup.py sdist

python -m build

python setup.py bdist_wheel

より詳しくは:

どこから始めましょうか?#

プロジェクト のソースコードツリーのルート部分には、次に示すように、 [build-system] テーブルを含む pyproject.toml がなければなりません:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

これは、 ビルドフロントエンド にこのプロジェクトの ビルドバックエンドSetuptools だと知らせるための標準化されたやり方です。

(空のファイルであっても) pyproject.toml ファイルが存在していれば、 pipビルド隔離 <build isolation> を取り扱うデフォルトの動きが変わることに注意してください。

より詳しくは:

追加的なビルド時の依存関係をどのように扱うのですか?#

setuptools それ自体の上に、もし setup.py が他の (Python の標準ライブラリの外側の) 第三者のライブラリに依存しているのであれば、 配布物 をビルドする際にビルドフロトンエンドがそれらをインストールする必要があることを知るために、 [build-system] テーブルの require リストに挙げられていなければなりません。

例えば、このような setup.py ファイルがあれば:

import setuptools
import some_build_toolkit  # comes from the `some-build-toolkit` library

def get_version():
    version = some_build_toolkit.compute_version()
    return version

setuptools.setup(
    name="my-project",
    version=get_version(),
)

pyproject.toml ファイルはこのようであることが要求されます (setup.py には変更なし):

[build-system]
requires = [
    "setuptools",
    "some-build-toolkit",
]
build-backend = "setuptools.build_meta"

より詳しくは:

ビルド隔離機能とは何でしょうか?#

典型的な場合、ビルドフロントエンドは、 build-system.requires の下に列挙されているビルド時の依存関係 (と、その依存関係)だけをインストールする先としての一時的な仮想環境を作成し、その環境内でビルドを開始します。

この隔離が不要な一部のプロジェクト向けには、以下のようにすれば (隔離を) 非活性化することができます:

  • python -m build --no-isolation

  • python -m pip install --no-build-isolation

より詳しくは:

パッケージのメタデータをどのように扱えば良いでしょうか?#

静的なメタデータはすべて、 pyproject.toml[project] テーブルへ移しても構いません。

例えば、このような setup.py ファイルがあれば:

import setuptools

setuptools.setup(
    name="my-project",
    version="1.2.3",
)

このように pyproject.toml ファイルで完全に置き換えることも可能です:

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "my-project"
version = "1.2.3"

[project] テーブルで許される内容の完全な仕様については、 <pyproject-project-table> を読んでください。

動的なメタデータをどのように取り扱いますか?#

パッケージングであるメタデータフィールドが静的ではないならば、 [project] テーブルの dynamic に列挙する必要があります。

例えば、このような setup.py ファイルがあれば:

import setuptools
import some_build_toolkit

def get_version():
    version = some_build_toolkit.compute_version()
    return version

setuptools.setup(
    name="my-project",
    version=get_version(),
)

以下のように近代化することができるでしょう:

[build-system]
requires = [
    "setuptools",
    "some-build-toolkit",
]
build-backend = "setuptools.build_meta"

[project]
name = "my-project"
dynamic = ["version"]
import setuptools
import some_build_toolkit

def get_version():
    version = some_build_toolkit.compute_version()
    return version

setuptools.setup(
    version=get_version(),
)

より詳しくは:

変更不能ななにかが setup.py ファイルがあるものと期待していたらどうしますか?#

例えば、簡単には変更することができないプロセスが存在していて、それが python setup.py --name のようなコマンドの実行を必要としてる場合。

たとえ全ての内容が pyproject.toml へ移された後であっても、プロジェクトのソースコードツリーに setup.py を残すことは完全に問題のないことです。このファイルの最小限の姿はこのようになります:

import setuptools

setuptools.setup()

これについて、どこでもっと読めますか?#