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

pyproject.toml takeaways

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

  2. There are two required fields in the [project] table: name= and version=.

  3. Add metadata to the classifiers section of your pyproject.toml file to make it easier for users to find your project on PyPI.

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

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

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

Every modern Python package should include a pyproject.toml file. For pure Python packages, this file replaces the setup.py and/or setup.cfg file to describe project metadata.

If your project isn’t pure Python, you might still require a setup.py file to build the non-Python extensions. However, a pyproject.toml file should still be used to store your project’s metadata.

Tutorial

If you are migrating from a setup.py or setup.cfg file, and want help, check out this tutorial. specify build requirements and metadata is called a pyproject.toml

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

The pyproject.toml file is written in TOML (Tom's Obvious, Minimal Language) format. TOML is an easy-to-read structure based on key/value pairs. Each section in the pyproject.toml file contains a [table identifier]. Below that table identifier are key/value pairs that support configuration for that particular table.

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

  • Within the build-system table, requires = is a key.

  • 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 ファイルが必要になるかもしれません。 このガイドでは複雑なビルドは扱いませんが、将来的には複雑なビルドを扱うリソースを提供する予定です。

Optional vs. required pyproject.toml file fields#

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"},
]

  • project.dependencies: The dependency group is optional because not all packages require dependencies. However, if your project has specific dependencies, include this section in your pyproject.toml. Dependencies declared in the pyproject.toml file will be installed by uv or pip when your project is installed.

  • project.optional-dependencies: Optional or feature dependencies will be installed if someone runs python -m pip install projectname[feature]. Use this array to declare dependencies that add specific features to your package that are not installed by default when a user runs uv sync or python -m pip install packagename.

  • dependency-groups: Dependency groups organize packages and tools that a contributor or developer would need to work on your package. These dependencies may include tools for building and running tests, linters, and code formatters. This is an optional but highly suggested way to organize and install dependencies. This section can replace a requirements.txt file. Learn more about adding these to your package in the PyPA guide here.

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

  • classifiers: The classifiers section of your metadata is also important for the landing page of your package in PyPI and for filtering of packages in PyPI. A list of all options for classifiers can be found here. Some of the classifiers that you should consider including

    • 開発状況

    • 対象読者

    • トピック

    • プログラミング言語

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

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

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

  • Use Dynamic Fields If you have fields that are dynamically populated. For example, you may wish to automatically update your package's version using Git tags (SCM/version control-based versioning). Example: dynamic = ["version"]

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

The pyproject.toml file is a modern replacement for the requirements.txt file, which has been traditionally used to store development dependencies and also configuration for tools such as pytest, black, and others.

To add development dependencies to your build, add a [dependency-groups] array to your pyproject.toml file.

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

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

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

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

  • pip install --group test # requires pip 25.1 or greater

上記は、編集可能モードのパッケージと、 [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"
license = "BSD-3-Clause"
classifiers = [
    "Programming Language :: Python :: 3",
    "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"
license = "BSD-3-Clause"
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]
dependencies = [
    "dependency-package-name-1",
    "dependency-package-name-2",
]

注釈

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