pyproject.toml

問題の背景

GitHubからダウンロードしたPythonパッケージをインストールしようとした際、setup.pyファイルがないために以下のコマンドが使えなかった経験はありませんか？

pip install -e <folder>

代わりに見つけたのはpyproject.tomlファイルで、そこには通常setup.pyに含まれるような設定情報が記述されていました。これはいったい何なのでしょうか？

pyproject.tomlとは

pyproject.tomlは、PEP 518とPEP 517で導入された新しい設定ファイル形式です。このファイルは、Pythonパッケージのビルドシステム要件を指定するために使用されます。

従来の問題点

従来のPythonパッケージングには以下の問題がありました：

1. setuptools依存性: setuptoolsベースのパッケージでは、ソースからのインストールやディストリビューションのビルドが、setuptoolsがインストールされていない場合に失敗する
2. pipの限界: pipは他のパッケージングツールを使用するパッケージのソースからのインストールをサポートしておらず、互換性のためにsetup.pyファイルを生成する必要があった
3. ツール変更のコスト: パッケージ作者がパッケージングツールを変更すると、ワークフローもツール固有のコマンドに合わせて変更する必要があった

解決策としてのpyproject.toml

pyproject.tomlはこれらの問題を解決するために設計されました：

1. ビルドシステムのインストール（PEP 518がカバー）
2. ビルドシステムの実行（PEP 517がカバー）

任意のツールはこのファイルを拡張してツール固有のオプションを追加できますが、必須ではありません。

setup.pyとの関係

pyproject.tomlはsetup.pyを完全に置き換えるのでしょうか？

INFO

setuptoolsベースのパッケージでは、pyproject.tomlはsetup.pyを置き換えるというよりも、必要に応じてその正しい実行を確保するためのものです。しかし他のパッケージングツールでは、実際にsetup.pyを置き換える役割を果たします。

PEP 621では、パッケージのコアメタデータを静的でツールに依存しない方法で指定するためにpyproject.tomlを使用することが推奨されています。

主要バックエンドのサポート状況

以下の表は、主要なパッケージングバックエンドのPEP 621サポート状況を示しています：

バックエンド	PEP 621サポート
enscons	0.26.0+
flit_core	3.2+
hatchling	0.3+
pdm-backend	0.3.0+
poetry-core	2.0.0+
setuptools	61.0.0+

編集可能モードでのインストール

元々「編集可能インストール」（editable install）はsetuptools固有の機能でした。PEP 660がこの概念をpyproject.tomlを使用するパッケージに拡張しました。

現代的な方法

フロントエンド（pip）とバックエンドの両方がPEP 660をサポートしている必要があります。

• pipはバージョン21.3（2021年10月11日）以降でサポート
• 以下のコマンドでインストール：

pip install -e .

レガシーな方法

パッケージングツールがdevelopコマンドをサポートするsetup.pyファイルを提供している必要があります。

pipはバージョン21.1（2021年4月24日）以降、setup.cfgファイルのみを使用するパッケージも編集可能モードでインストールできます。

バックエンド別の編集可能インストールサポート

バックエンド	編集可能インストールサポート
enscons	0.28.0+
flit_core	3.4+
hatchling	0.3+
pdm-backend	0.8.0+
poetry-core	1.0.8+
setuptools	64.0.0+

Poetryを使用した編集可能インストール

Poetryを使用している場合、以下の設定で編集可能インストールが可能です：

[build-system]
requires = ["poetry-core>=1.0.8"]
build-backend = "poetry.core.masonry.api"

pyproject.tomlのその他の用途

pyproject.tomlはパッケージング以外の目的でも使用されます：

• pytest: テストの場所や実行方法、pythonpathの変更指示を保存
• その他多くのツール: 様々な開発ツールが設定情報をpyproject.tomlに保存

実践的な使用例

setuptoolsを使用する場合

[build-system]
requires = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "0.1.0"
description = "My awesome package"
authors = [{name = "Your Name", email = "your.email@example.com"}]

Poetryを使用する場合

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "my-package"
version = "0.1.0"
description = "My awesome package"
authors = ["Your Name <your.email@example.com>"]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.25.1"

[tool.poetry.dev-dependencies]
pytest = "^6.2.0"

まとめ

pyproject.tomlは現代的なPythonパッケージングの中心的な設定ファイルです。従来のsetup.pyの代替としてだけでなく、より統一された標準的な設定方法を提供します。主要なパッケージングツールのほとんどがサポートしており、編集可能インストールも可能です。

新しいプロジェクトを始める場合は、pyproject.tomlの使用を検討することをお勧めします。既存のプロジェクトでも、段階的に移行することが可能です。

TIP

常に使用しているパッケージングツールの最新のベストプラクティスと、pyproject.tomlのサポート状況を確認してください。ツールによってサポートされている機能や設定方法が異なる場合があります。