パッケージの設定とメタデータにはpyproject.tomlファイルを使用します。#

pyproject.tomlから得られる重要なこと

  1. インストール可能なPythonパッケージに必要なテーブルは2つだけです: [build-system] と [project] です。 [project] テーブルにはパッケージのメタデータが格納されます。

  2. [project] テーブルの必須フィールドは2つだけです: **name=**と version= です。

  3. pyproject.toml ファイルにメタデータを追加することをお勧めします。 そうすることで、ユーザがPyPIであなたのプロジェクトを見つけやすくなります。

  4. [project] テーブルに分類を追加するときは、 PyPIの分類ページ にある有効な値のみを使用してください。 ここで無効な値を指定すると、パッケージをビルドするときやPyPIに公開するときにエラーが発生します。

  5. pyproject.toml ファイル内のテーブルには特定の順番はありません。 しかし、フィールドは正しいテーブルセクションに配置する必要があります。 例えば requires = は常に [build-system] テーブルと関連付ける必要があります。

  6. python-requires: pyproject.tomlファイルに記述することが重要です。 これはpipがパッケージをインストールするのに役立つからです。

pyproject.tomlファイルについて#

最近の Python パッケージには pyproject.toml ファイルが含まれているはずです。 もしあなたのプロジェクトが純粋な Python で、メタデータを記述するために setup.py や setup.cfg ファイルを使っているなら、メタデータとビルド情報を pyproject.toml ファイルに移行することを検討するべきです。

あなたのプロジェクトが純粋な Python でない場合、Python 以外の拡張機能をビルドするために setup.py ファイルが必要になるかもしれません。 しかし、プロジェクトのメタデータを保存するために pyproject.toml ファイルを使用する必要があります。

setup.pyに何が起こったのか、そしてどのようにpyproject.tomlに移行するのか？

2017年8月以前は、Pythonパッケージのメタデータは setup.py ファイルか setup.cfg ファイルに保存されていました。 近年、Python パッケージのメタデータは、よりユーザが読みやすい pyproject.toml フォーマットで保存されるようになりました。 すべてのメタデータを1つのファイルに持つことです:

  • パッケージ管理を簡素化します、

  • (flit-core, hatchling, pdm-build)のような一連の異なる ビルドバックエンド を使うことができます。

  • 現代のベストプラクティスに合致しています。

Python パッケージが ビルド要件とメタデータを指定するために使う標準のファイルは pyproject.toml と呼ばれます 。メタデータ、ビルド要件、パッケージの依存関係を pyproject.toml ファイルに追加することは、 setup.py や setup.cfg ファイルに情報を格納することに取って代わります。

.toml フォーマットについて#

pyproject.tomlファイルは TOML(Tom's Obvious, Minimal Language)フォーマット で書かれています。 TOMLは読みやすい構造で、キーと値のペアで成り立っています。 pyproject.toml ファイルの各セクションは [テーブル識別子] を含んでいます。 そのテーブル識別子の下には、その特定のテーブルの設定をサポートするキーと値のペアがあります。

  • [build-system] 以下はtoml言語ではテーブルとみなされます。

  • 以下の build-system テーブルの中で requires = がキーです。

  • requires に関連する値は、値 "hatchling" を含む配列です。

[build-system]
requires = ["hatchling"]

パッケージのビルド時にpyproject.tomlがどのように使用されるか#

PyPIに公開すると、各パッケージにメタデータがリストされていることに気づくでしょう。pyOpenSciパッケージ の一つである xclim を見てみましょう。PyPIのランディングページには、pythonやメンテナ情報など、パッケージに関するメタデータが表示されていることに注目してください。PyPIは、Xclimのメンテナ pyproject.toml file によって正しい構文と分類子を用いて定義されたメタデータを入力することができます。xclimパッケージがビルドされるとき、このメタデータは配布ファイルに変換され、PyPIがメタデータを読み込んでウェブサイトに出力できるようになります。

xclimパッケージのPyPI左サイドバーの画像です。一番上のセクションにはClassifierとあります。その下に、開発状況、対象読者、ライセンス、自然言語、オペレーティングシステム、プログラミング言語、トピックなどの項目があります。 これらの各セクションの下には、さまざまな分類オプションがあります。 " width="300px">

pyproject.tomlにclassifierセクションを追加してパッケージがビルドされると、ビルドツールはメタデータをPyPIが理解できる形式に整理し、PyPIのランディングページに表示します。 これらの分類子により、ユーザはサポートするpythonのバージョンやカテゴリなどでパッケージをソートすることもできます。#

pyproject.tomlファイルを使用する利点#

パッケージのメタデータを人間が読める pyproject.toml 形式で含めると、GitHubのリポジトリでプロジェクトのメタデータを見ることができます。

Setup.py は、複雑なパッケージのビルドに便利です。

パッケージのビルドとメタデータを管理するために setup.py を使うことは パッケージ開発に問題を引き起こす可能性があります 。 Python パッケージのビルドが複雑な場合、setup.py ファイルが必要になるかもしれません。 このガイドでは複雑なビルドは扱いませんが、将来的には複雑なビルドを扱うリソースを提供する予定です。

pyproject.toml ファイルのフィールドの任意と必須#

pyproject.toml ファイルを作成するとき、使用できるメタデータフィールドがたくさんあります。 以下では、PyPI での公開とユーザがあなたのパッケージを見つけることをサポートする、特定のフィールドを提案します。

プロジェクトの全メタデータ要素の概要は、こちらをご覧ください。

[project] テーブルの必須フィールド#

上述したように、 pyproject.toml ファイルはパッケージを適切にビルドするために name と version フィールドを持つ必要があります:

  • name: プロジェクトの名前を文字列で指定します。

  • version: プロジェクトのバージョンです。 バージョン管理に SCM ツール (git タグを使用してバージョンを決定する) を使用している場合は、このバージョンは動的なものになります (詳細は後述します)。

[project] テーブルに含めるオプションフィールド#

以下のメタデータキーも追加することを強くお勧めします。 これらのフィールドを追加することで、あなたのパッケージがどのような構造になっているのか、どのプラットフォームをサポートしているのか、どのような依存関係が必要なのかを明確にすることができます。

  • Description: これはあなたのパッケージの短い一行説明です。

  • Readme: 長い長い説明には README.md ファイルへのリンクが使われます。 この情報はあなたのパッケージのPyPIランディングページで公開されます。

  • Requires-python (pipで使用): これはpipが使用するフィールドです。 ここでは、Python 2.xと3.xのどちらを使っているかをインストーラに伝えます。 ほとんどのプロジェクトは3.xを使うでしょう。

  • ライセンス: 使用しているライセンス

  • Authors: パッケージの原作者です。 作者がメンテナと異なることもあります。 また、同じ場合もあります。

  • Maintainers: これを入力するかどうかを選択できます。 各作者やメンテナーの名前、Eメール、メールアドレスなどのサブ要素を持つリストを使って、この情報を入力することができます。

authors = [
    {name = "Some Maintainer", email = "some-email@pyopensci.org"},
]

  • dependencies: 依存関係はオプションですが、pyproject.tomlに含めることを強く推奨します。 依存関係はプロジェクトがインストールされるときにpipによってインストールされ、より良いユーザーエクスペリエンスを提供します。

  • [project.optional-dependencies]: 誰かが python -m pip install projectname[dev] を実行したときに、オプションまたは開発用の依存パッケージがインストールされます。 これは、あなたのプロジェクトに貢献したいユーザのために、開発用の依存関係を含める良い方法です。

  • keywords: これらはPyPIのランディングページに表示されるキーワードです。 人々があなたのパッケージを検索するときに使う言葉だと考えてください。

  • classifiers: メタデータのclassifiersセクションは、PyPIでのパッケージのランディングページや、PyPIでのパッケージのフィルタリングにも重要です。 分類子の全オプションはこちらです 。 以下のようなクラシファイアを検討する必要があります。

    • 開発状況

    • 対象読者

    • トピック

    • License

    • プログラミング言語

pyproject.tomlファイルの高度なオプション#

このページの下にある例には ...

  • [project.scripts] (Entry points): エントリーポイントは任意です。 パッケージでホストされている特定のスクリプトを実行するコマンドラインツールがある場合、そのスクリプトを(Pythonシェルではなく)コマンドラインで直接呼び出すためのエントリポイントを含めることができます 。

    • 以下は、エントリーポイントスクリプトを持つパッケージ の例である。 そのパッケージには、一連のタスクを実行するいくつかのコアスクリプトが定義されていることに注目してほしい。 pyOpenSciはこれらのスクリプトを使ってメタデータを処理しています。

  • ダイナミックフィールド: 動的に入力されるフィールドがある場合。 setuptooms_scmのようなツールでscm/バージョン管理ベースのバージョンを使用している場合、ダイナミックフィールドを使用することができます。 (scmを使用した)バージョンなど dynamic = ["version"]

pyproject.tomlファイルに依存関係を追加#

pyproject.tomlファイルは、従来pytestのような開発依存ファイル、Blackのようなコードフォーマッタ、sphinxのようなドキュメントツールを保存するために使われてきたrequirements.txtファイルの代わりとして使うこともできます。

ビルドに依存関係を追加するには、 [project.optional-dependencies] テーブルをpyproject.tomlファイルに追加します。

次に、依存グループを以下のように指定する:

[project.optional-dependencies]
tests = [
  "pytest",
  "pytest-cov"
]
lint = [
  "black",
  "flake8"
]
docs = [
    "sphinx",
    "pydata-sphinx-theme"
]

[tool.ruff]
select = [
    "E", # pycodestyle errors
    "W", # pycodestyle warnings
    "F", # pyflakes. "E" + "W" + "F" + "C90" (mccabe complexity) is equivalent to flake8
    "I", # isort
]

[tool.ruff.isort]
known-first-party = ["examplePy"]

上記の例に従って、依存関係を次のようにインストールします:

  • python -m pip install -e .[tests]

上記は、編集可能モードのパッケージと、 [project.optional-dependencies] テーブルのtestsセクションで宣言されたすべての依存関係の両方をインストールします。

すべての依存関係をインストールし、あなたのパッケージもインストールするには、次のようにします:

python -m pip install -e .[tests,lint,docs]

再帰的依存関係

再帰的依存関係のセットをセットアップすることもできます。 詳しくはこのブログ記事を参照。

hatchlingを使用してビルドするpyproject.tomlの例#

以下は Python プロジェクトのビルド設定の例です。 このパッケージの設定例では、 パッケージの sdist と wheel をビルドするのに hatchling を使っています。

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "examplePy"
authors = [
    {name = "Some Maintainer", email = "some-email@pyopensci.org"},
]
maintainers = [
    {name = "All the contributors"},
]
description = "An example Python package used to support Python packaging tutorials"
keywords = ["pyOpenSci", "python packaging"]
readme = "README.md"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
]
dependencies = [
    "dependency-package-name-1",
    "dependency-package-name-2",
]

このファイルには依存関係が指定されています。

setuptoolsを使ってビルドするpyproject.tomlの例#

作者やキーワードなどを含むパッケージのメタデータも読みやすいです。 下の図は、異なるビルドシステム(setuptools)を使った同じTOMLファイルです。 このパッケージのビルドに必要なツールを入れ替えるのがいかに簡単かに注目してください！

このパッケージのセットアップ例では:

  • パッケージのsdistとwheel をビルドするための setuptools 。

  • setuptools_scm は、バージョン管理タグを使ってパッケージのバージョン更新を管理します。

以下の例では、[build-system] が最初の値のテーブルです。 このテーブルには2つのキーがあり、ビルドバックエンドAPIとそれを含むパッケージを指定します:

  1. requires =

  2. build-back-end =

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

[project]
name = "examplePy"
authors = [
    {name = "Some Maintainer", email = "some-email@pyopensci.org"},
]
maintainers = [
    {name = "All the contributors"},
]
description = "An example Python package used to support Python packaging tutorials"
keywords = ["pyOpenSci", "python packaging"]
readme = "README.md"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: BSD License",
    "Operating System :: OS Independent",
]
dependencies = [
    "dependency-package-name-1",
    "dependency-package-name-2",
]

注釈

PDM、setuptools、Poetry、Hatch などのパッケージビルドツールについてはこちらをご覧ください。