PythonパッケージをPyPIに対応させる - pyproject.toml#

インストール可能なコードのレッスンでは、 pyproject.toml ファイルに最低限の情報を追加してインストール可能にする方法を学びました。その後、 PyPIにパッケージの最小限のバージョンを公開する方法を学びました。

それに続いて、あなたは以下の追加方法を学びました:

プロジェクトディレクトリのルートに。

PyPI 上でのパッケージの可視性を高め、Python のバージョンとの互換性、プロジェクトの開発状況、プロジェクトのメンテナーについてより多くの情報を提供するために、 pyproject.toml ファイルに追加のメタデータを追加する必要があります。このレッスンでは、そのプロセスについて説明します。

学習目標

このレッスンで学ぶこと:

pyproject.toml ファイルの詳細と、パッケージに関するさまざまな種類のメタデータを格納するためにどのように使用されるかについて
ユーザーがPyPIでプロジェクトを見つけ、理解しやすくするために、プロジェクトに関する情報 (メタデータ) を宣言する方法。

pyproject.toml フォーマットについて詳しく知りたい方は、こちらのページをご覧ください。

pyproject.tomlファイルとは何ですか？#

pyproject.toml ファイルは人間や機械が読めるファイルで、Pythonパッケージの主要な設定ファイルとして機能します。

Tip

パッケージのビルドは、PyPIに公開するために必要な配布ファイルを作成するステップです。

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

pyproject.toml ファイルは TOML (Tom's Obvious, Minimal Language) format で書かれています。TOMLは、キーと値のペアに基づいた読みやすい構造です。 pyproject.toml ファイルの各セクションには [table identifier] が含まれています。TOMLフォーマットは、 .json などの他の構造化フォーマットと比較することができます。しかし、TOMLフォーマットは人間が読みやすいように設計されています。

以下に [build-system] テーブルを示す。そのテーブルの中には、2つのキーと値のペアが必要です。

requires = がキーで、値は角括弧 [] で指定された [build-system] 配列内の ["hatchling"] です。

[build-system] # <- This is a table
requires = ["hatchling"]
# The build backend defines the tool that should be used to build your package distribution files.
build-backend = "hatchling.build"

pyproject.tomlは何に使うのですか？#

pyproject.tomlファイルは、ビルドツールに次のように指示します:

パッケージのビルドに使用するビルドバックエンド (このチュートリアルでは hatchling を使用していますが、他にも多くの選択肢があります)。
パッケージのバージョンの取得方法と場所:
- 静的ここで、バージョン version = "0.1.0" または
- 動的このツールは、現在のバージョンを決定するために、履歴の最新のタグを検索します。
パッケージが必要とする依存関係
パッケージがサポートするPythonのバージョン (ユーザーにとって重要）。

また、 pyproject.toml ファイルを使うことで、GitHub リポジトリを閲覧している人が次のようなパッケージの構造をすぐに理解できるようになります:

パッケージの作り方、
サポートするPythonのバージョンとオペレーティングシステム
何をするのか？
誰がメンテナンスするのか

最後に、pyproject.tomlファイルは、静的タイプチェッカー (mypyなど) やコードフォーマッタ/リンタ (blackやruffなど) のようなツールを設定するためにもよく使われます。

Tip

他のツールのビルド設定の設定に興味があれば、 PyPAのドキュメントをチェックしてください。

ビルドツールによっては、プロジェクトのメタデータを保存する方法が異なる場合があります。そのため、Hatch とhatchling以外のツールを使用する場合は、それらのドキュメントを参照することをお勧めします。このチュートリアルでは、PyPAのルールとガイドラインに準拠したツールであるhatchlingとhatchを選択しました。

pyproject.tomlのメタデータはどのように使用されますか？#

pyproject.tomlファイルは、PyPIに公開されるPythonの配布ファイルに含まれる METADATA を生成するためにビルドツールが使用するファイルです。この METADATA ファイルは、PyPI によってあなたのパッケージの PyPI ランディングページに入力され、そこで公開されている何万ものパッケージの中からユーザをフィルタリングするのに使われます。

xclimパッケージのPyPI左サイドバーの画像です。一番上のセクションにはClassifierとあります。その下に、開発状況、対象読者、ライセンス、自然言語、オペレーティングシステム、プログラミング言語、トピックなどの項目があります。これらの各セクションの下には、さまざまな分類オプションがあります。 " width="300px"> — pyproject.tomlにclassifierセクションを追加してパッケージがビルドされると、ビルドツールはメタデータをPyPIが理解できる形式に整理し、PyPIのランディングページに表示します。これらの分類子により、ユーザはサポートするpythonのバージョンやカテゴリなどでパッケージをソートすることもできます。#

Tip

pyproject.tomlファイルのより詳細な概要

ガイドブックページでは、このファイルについてより詳しく説明しています

pyproject.tomlファイルを更新する方法#

最後のレッスンでは、パッケージのビルドに必要なコア要素を含む、素のpyproject.tomlファイルを作成しました:

プロジェクトのバックエンドビルドツールを定義した [build-system] テーブル (hatchling)
プロジェクトのバージョンと名前を定義した [project] テーブル。

あなたが作成した pyproject.toml ファイルは次のようなものです:

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

[project]
name = "pyospackage"
version = "0.1.0"

次のステップでは、PyPI であなたのパッケージを見つけるのに役立ち、またあなたのパッケージの範囲をよりよく説明するために、推奨されるメタデータフィールドを追加します。一度このメタデータを追加すれば、もう二度と追加する必要はありません。これらのメタデータ・フィールドが定期的に更新されるのは、あなたが次のようなことをしたときだけです:

パッケージ依存の削除
パッケージがサポートしているPythonのバージョンを変更します。

Hatchlingの詳細

Hatchlingのバックエンドのドキュメントはこちらです。

ステップ1: 作者、メンテナ、プロジェクトの説明を追加する#

インストール可能なコードのチュートリアルを完了すると、 [project] テーブルにプロジェクト名とバージョンを持つpyproject.tomlファイルができるはずです。

[project]
name = "pyospackage"
version = "0.1.0"

テーブルに以下を追加します:

パッケージの説明これは1行で、可能な限り専門用語を使わず、あなたのパッケージの目標を簡潔に記述してください！
パッケージ著者
パッケージ メンテナー

description は、設定した他の値と同じように単なる文字列です:

# you can use """ for multiline strings like in python!

description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""

作者とメンテナを追加するときは、Pythonのリストに辞書を追加したような書式を使う必要があります:

authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]

maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]

著者名とEメール

PyPIには、pyproject.tomlに名前があってもメールがない作者のための癖があります。もし、1人以上の作者やメンテナのEメールが見つからない場合は、次のようにしてください:

maintainers = [
    { name = "Firstname lastname", email = "email@pyopensci.org" },
    { name = "Firstname lastname" }
]

PyPIページですべてが正しく表示されるようにするために、名前のリストには名前のみを入力することをお勧めします - このように:

maintainers = [
    { name = "Firstname lastname"},
    { name = "Firstname lastname" }
]

全員のEメールを持っていない場合は、名前だけを追加することをお勧めします。

これで pyproject.toml ファイルは以下の例のようになるはずです。作者が1人しかおらず、同じ作者がパッケージのメンテナでもある場合は問題ありません:

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]

ステップ2: READMEとライセンスの追加#

前のレッスンでは、 README.md ファイルと LICENSE の両方をパッケージリポジトリーに追加しました。これらのファイルを手に入れたら、以下の例に従ってpyproject.tomlファイルにリンクとして追加します。

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = "LICENSE"}

ステップ 3: `requires-python` でPythonのバージョンを指定します#

pyproject.toml の [project] テーブルに requires-python フィールドを追加します。 requires-python フィールドは、pipがあなたのパッケージがサポートする Pythonのバージョンを特定するのに役立ちます。単一の値に設定されます。パッケージング仕様では、 requires-python をバージョン指定の文字列として定義している。ほとんどのプロジェクトは、そのパッケージがサポートする最も古いPythonのバージョンを指定します。いくつかの高度なケースでは、どの将来のPythonバージョンがサポートされるかを示す上限が設定されます。

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"

ステップ4: 依存関係の指定#

次に、依存関係テーブルをプロジェクトテーブルに追加します。 dependencies = セクションには、あなたのパッケージがPython環境で正しく動作するために必要なPythonパッケージのリスト（toml言語では配列）を記述します。上記の [build-system] の表に記載されている要件と同様です:

[build-system] # <- this is a table
requires = ["hatchling"] # this is an array (or list) of requirements

依存関係は配列（Pythonのリストに似ている）構造で追加されます。

dependencies = ["numpy", "requests", "pandas", "pydantic"]

依存関係は、 バージョン指定子 を使って特定のバージョンに限定することができます。依存関係の名前の後にバージョン指定子がない場合、あなたのパッケージは依存パッケージのどのバージョンでも使うことができます。コードは時間の経過とともに変化し、バグが修正され、APIが変更されます。そのため、コードを書いた依存関係がどのバージョンと互換性があるのかを明確にしておくことは良いことです - あなたが今年書いたパッケージは、おそらくnumpy v0.0.1とは互換性がありません！

パッケージバージョンの範囲を指定する様々な方法については、こちらをご覧ください。

最も一般的なバージョン指定子は lower bound で、指定されたバージョンより上位のバージョンを許可します。理想的には、あなたのパッケージとまだ互換性のある最も低いバージョンに設定すべきですが、実際には新しいパッケージの場合、パッケージが書かれた時点での最新バージョンに設定されることがよくあります [^lowerbound] 。

下限は次のようになります:

dependencies = [ "numpy>=1.0" ]

カンマは、個々の依存関係を区切るために使用します、そして、dependencies セクションの各パッケージは異なるタイプのバージョン指定子を使うことができます:

dependencies = [
  "numpy>=1.0",      # Greater than or equal to 1.0
  "requests==10.1",  # Exactly 10.1
  "pandas",          # Any version
  "pydantic>=1.7,<2" # Greater than or equal to 1.7, but less than 2
]

これで pyproject.toml ファイルは次のようになります:

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"

dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]

依存関係のピン止めは慎重に

依存関係を "Pinning" することは、次のように特定のバージョンに設定することを意味します:

numpy == 1.0 。

他の開発者が依存するライブラリパッケージを構築する場合、正確な依存バージョンに固定する前に慎重にならなければなりません。本番用ウェブサイトのようなアプリケーションは、他のパッケージがそのプロジェクトに依存しないため、依存関係を固定することが多いです。なぜなら、ユーザーはあなたのパッケージをさまざまな環境にインストールするからです。特定のバージョンに固定された依存関係は、Python環境の解決をより困難にします。そのため、依存関係を特定のバージョンに固定するのは、どうしても必要な場合に限られます。

同様に、パッケージの上限を指定する場合にも注意が必要です。これら2つの仕様は同等です:

pydantic>=1.10,<2
pydantic^1.10

依存関係をデフォルトで上限値に固定するビルドツールとして知っておくべきもののひとつに、Poetryがあります。 Poetryで依存関係を安全に追加する方法については、こちらをお読みください。

ステップ5: PyPI classifiersを追加する#

次に、pyproject.tomlファイルに分類子を追加します。 pyproject.toml ファイルに追加する各分類子の値は、ここにあるPyPIで認められている分類子の一覧から選ぶ必要があります。スペルや書式に逸脱があると、PyPIに公開するときに問題が発生します。

間違った分類子を使うとどうなりますか？

もし標準的な分類器の値を使うのでなければ、 PyPIでパッケージを公開しようとすると拒否されます。最初のトライでPyPIに拒否されても心配しないでください！それは私たち全員に起こったことです。

そのリストを見て、以下の項目を pyproject.toml ファイルに追加します:

開発状況
対象読者
トピック
ライセンスと
プログラミング言語サポート

classifierのキーは、下の例のようになるはずです。いくつか注意点があります:

分類器の値は、パッケージに選択したライセンスによって異なる場合があります、あなたの意図する読者、パッケージの開発状況とサポートしている Python のバージョンです。
指定されたPyPIの分類子の値を使う限り、好きなだけ分類子を追加できます。

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"

dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]

classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]

分類子は pyproject.toml ファイルでは必須ではありませんが、ユーザーがあなたのパッケージを見つけるのに役立つことに注意してください。そのため、追加することを強くお勧めします。

ステップ 6: `[project.urls]` テーブルを追加する#

最後に、pyproject.tomlファイルにproject.urlsテーブルを追加します。

project.urls には、プロジェクトに関連するリンクが含まれています。以下を含めるとよいでしょう:

ホームページ: プロジェクトの公開ドキュメントへのリンク。このチュートリアルを進めているのであれば、このリンクはまだ持っていないかもしれません。大丈夫、当分は飛ばしてもいいです。
バグ報告: 課題 / ディスカッションへのリンク、またはユーザーがバグを報告できる場所です。
ソース: プロジェクトのGitHub / GitLabリンク。

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"

dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]

classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    ]

[project.urls] # Optional
"Homepage" = "https://www.pyopensci.org"
"Bug Reports" = "https://github.com/pyopensci/pyosmeta/issues"
"Source" = "https://github.com/pyopensci/pyosmeta/"

Tip

ここに追加できるURLは他にもたくさんある。概要についてはこちらのREADMEファイルをチェックしてください。

すべてをまとめます - 完成したpyproject.tomlファイル#

以下は、上で説明したすべてのセクションがコメントされた pyproject.toml ファイルの完全な例です。

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

[project]
name = "pyospackage"
version = "0.1.0"
description = """
Tools that update the pyOpenSci contributor and review metadata
that is posted on our website
"""
authors = [
  { name = "Firstname Lastname", email = "email@pyopensci.org"},
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" }
]
maintainers = [
  { name = "Secondperson Fullname", email = "email2@pyopensci.org" },
  { name = "New Friend", email = "newbie@pyopensci.org" }
]
readme = "README.md"
license = {file = 'LICENSE'}
requires-python = ">=3.10"

dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]

classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3 :: Only",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    ]

[project.urls] # Optional
"Homepage" = "https://www.pyopensci.org"
"Bug Reports" = "https://github.com/pyopensci/pyosmeta/issues"
"Source" = "https://github.com/pyopensci/pyosmeta/"

付録 - 完全にコメントされたpyproject.tomlファイルを見るにはクリックしてください

参考にしたいのであれば、以下は、完全にコメントされたpyproject.tomlファイルです。

# You can delete all of the comments once you have created your own pyproject.toml file.

# The build system table. Here we use hatchling as the build back end tool.
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

# The [project] section contains your package's metadata
# notice that the version is setup to be dynamically generated using dynamic=[“version”]

[project]
name = "pyospackage"
# dynamic = ["version"] # you will learn how to dynamically set the version in a future lesson
version = "0.1.0" # manually assign version (not preferred)
description = "Tools that update the pyOpenSci contributor and review metadata that is posted on our website"
authors = [{ name = "Firstname lastname", email = "email@pyopensci.org" }]

# maintainers section is optional but suggested.
maintainers = [
    { name = "firstname lastname", email = "admin@pyopensci.org" }, # Optional
]

# Classifiers have set values - be sure to only use classifier values from the
# PyPI page here: https://PyPI.org/classifiers/

classifiers = [
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    "Development Status :: 4 - Beta",

    # Indicate who your project is intended for
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Build Tools",

    # Pick your license (using syntax from the classifier page). We suggest MIT, BSD3 or Apache if you are corporate
    "License :: OSI Approved :: MIT License",

    # Specify the Python versions ensuring that you indicate you support Python 3.
    # this is only for PyPI and other metadata associated with your package - for your users to see
    "Programming Language :: Python :: 3 :: Only", # BE sure to specify that you use python 3.x
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]


dependencies = ["numpy>=1.0", "requests==10.1", "pandas", "pydantic>=1.7,<2"]
# This is the metadata that pip reads to understand what versions your package supports
requires-python = ">=3.10"
readme = "README.md"
license = { file = "LICENSE" }

# Add urls for your home page, issue tracker and source code
[project.urls] # Optional
"Homepage" = "https://www.pyopensci.org"
"Bug Reports" = "https://github.com/pyopensci/pyospackage/issues"
#"Funding" = ""
"Source" = "https://github.com/pyopensci/pyospackage"

例 `pyproject.toml` ファイル#

以下は、scientificとpyOpenSciエコシステムの様々なパッケージの pyproject.toml ファイルの例です。

まとめ#

この時点であなたは以下を作成しました:

パッケージの README.md ファイル
ユーザーコミュニティをサポートする CODE_OF_CONDUCT.md ファイル
LICENSE ファイルは、人々があなたのソフトウェアをどのように使用できるか、また使用できないかに関する法的な境界線を提供します。

また、パッケージを(test)PyPIに公開する方法も学びました。

新しいバージョンのパッケージをPyPIに公開する#

これで、Pythonパッケージの新しいバージョンを(test)PyPIに公開する準備ができました。そうすると、パッケージのランディングページに、より多くの情報が掲載されていることがわかります。

今すぐ再公開を試みます。

まず、pyprojectのtomlファイルでパッケージのバージョンを更新します。以下のバージョンが 0.1 から 0.1.1 に更新されました。

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

[project]
name = "pyospackage"
version = "0.1.1"

次に hatch を使って、新しいバージョンのパッケージを test.PyPI.org に公開します。

> hatch publish -r test

次のステップ(オプション) - conda-forgeに公開します。#

これであなたのパッケージをPyPIに公開するために必要なスキルはすべて揃いました。

あなたのパッケージを(condaエコシステム内のチャンネルである)conda-forgeで公開したい場合、その方法は次のレッスンで学びます。