Pythonプロジェクトをパッケージ化やビルドする際、pyproject.tomlは必須の設定ファイルです。Python 3.11以降では、このファイルが標準として採用され、プロジェクトのビルドツールや依存関係を明示的に管理することが求められています。

この記事では、pyproject.tomlの基本構造や使い方、さらに推奨されるベストプラクティスについて初心者にもわかりやすく解説します。

pyproject.tomlとは

概要

pyproject.tomlは、Pythonプロジェクトのビルドツールや依存関係を記述するための設定ファイルです。このファイルは、Pythonエコシステム全体で統一された形式を提供し、プロジェクト管理を効率化します。

pyproject.tomlの主な目的

1. ビルドツールの指定
   setuptoolsやpoetryなど、プロジェクトのビルドに必要なツールを記述します。
2. 依存関係の管理
   プロジェクトで必要なライブラリやバージョンを明示的に記述できます。
3. プロジェクト情報の提供
   パッケージの名前、バージョン、ライセンスなど、メタデータを含めることができます。

pyproject.tomlの基本構造

pyproject.tomlは、以下のようなセクションで構成されています：

[build-system]

ビルドツールとその依存関係を指定するセクションです。

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

設定項目の説明

• requires: ビルドに必要なライブラリをリスト形式で指定します。
• build-backend: 使用するビルドバックエンドを指定します。

[tool.<tool_name>]

プロジェクトで使用する特定のツールの設定を記述します。例えば、poetryやblackの設定を追加できます。

例：Poetryの設定

[tool.poetry]
name = "my_project"
version = "0.1.0"
description = "サンプルプロジェクト"
authors = ["Your Name <your.email@example.com>"]

[project]

Pythonプロジェクトのメタデータを記述します。これは、PEP 621によって定義された標準です。

[project]
name = "my_project"
version = "0.1.0"
description = "サンプルプロジェクト"
authors = [
    {name = "Your Name", email = "your.email@example.com"}
]
license = {text = "MIT"}
dependencies = ["numpy>=1.21", "pandas>=1.3"]

設定項目の説明

• name: プロジェクト名。
• version: プロジェクトのバージョン。
• description: プロジェクトの説明文。
• authors: 作者情報。辞書形式で記述します。
• license: ライセンス情報。
• dependencies: プロジェクトで使用する依存ライブラリ。

pyproject.tomlの応用例

プロジェクトに依存関係を追加する

以下の例では、numpyとpandasを指定しています：

[project]
dependencies = [
    "numpy>=1.21",
    "pandas>=1.3",
]

開発環境用の依存関係

開発時にのみ必要なライブラリを指定します。例えば、pytestを追加する場合：

[project.optional-dependencies]
dev = ["pytest>=6.0"]

3. フォーマッタやリンターの設定

例えば、blackの設定を追加する場合：

[tool.black]
line-length = 88
target-version = ["py311"]

pyproject.tomlを使う際の注意点

1. PEP規格を確認
   PEP 621やPEP 517に準拠して記述することで、互換性を保つことが重要です。
2. 正しい構文を使用
   TOML形式では、文字列は二重引用符で囲む必要があります。
3. バージョン管理の徹底
   requiresやdependenciesで明示的にバージョンを指定すると、依存関係の競合を防げます。

pyproject.tomlを活用したプロジェクト管理のベストプラクティス

1. 明確な依存関係の定義
   • すべての依存ライブラリを明確に記述し、不要なライブラリを削除する習慣をつけましょう。
2. 環境ごとに設定を分ける
   • 開発、テスト、本番環境ごとにoptional-dependenciesを活用して設定を分離すると便利です。
3. ドキュメントを添える
   • プロジェクトのREADMEやドキュメントでpyproject.tomlの役割や設定方法を説明することで、チーム内での理解が深まります。

まとめ

pyproject.tomlは、Pythonプロジェクトを効率的に管理するための強力なツールです。この記事で紹介した基本構造や応用例を活用し、プロジェクトの設定を明確かつ簡潔に保ちましょう。また、PEP規格に従った記述を心がけることで、Pythonエコシステム全体との互換性が向上します。