Python の pyproject.toml: 概要

コードの共有とオープンソース ソフトウェアでのコラボレーションは、ソフトウェア開発において大きな変革をもたらしました。これにより、開発者は既存のパッケージとライブラリを使用して、より小規模なチームでより複雑なアプリケーションを構築できるようになりました。

Python エコシステムでは、ほとんどのパッケージが Python Package Index (PyPI) に登録されています。インデックスを使用すると、開発者は自分のコードを他の開発者用のパッケージとして共有できます。独自のパッケージを作成して PyPI にアップロードするには、pyproject.toml ファイルが必要です。この記事はその仕組みについてのガイドです。

pyproject.tomlとは何ですか?

ファイルが何であるかを理解する前に、まずファイルが埋めようとしているギャップを理解しましょう。パッケージを PyPI にアップロードすると、 pip 使用してインストール可能になります。たとえば、PyPI にアップロードした後のパッケージが example-package という名前の場合、次のコマンドを使用してインストールできます。

 pip install example-package

パッケージを Python Package Index に公開するときは、 .whl ファイルをアップロードします。しかし、コードを書くときは、主に .py ファイルを書きます。では、 .whl ファイルはどのように生成するのでしょうか? setuptools や poetry などのビルド ツールを使用します。

このツールはソース コードを取得し、アップロード可能な .whl ファイルに変換します。前述したように、 whl ファイルの生成に使用できるツールは複数あります。 Python で使用するツールを指定するには、それを pyproject.toml ファイルに記述します。

したがって、pyproject.toml ファイルは、Python プロジェクトをパッケージに組み込む方法を指定するファイルです。それに加えて、PyPI 上のパッケージのリストに表示されるパッケージのメタデータなどの追加情報を提供できます。

Python のビルド プロセス

ビルド プロセス ツールを実行するには、次のコマンドを使用します。

 python -m build

ただし、それを行う前に、インストールする必要があります

python -m pip install build

pyproject.toml ファイルを含むプロジェクトで build コマンドを実行すると、新しいファイルとディレクトリが作成されます。これらには、 sdist と呼ばれる圧縮アーカイブ ファイルと、PyPI で配布する .whl ファイルの 2 つのファイルが含まれる dist フォルダーが含まれます。

Python パッケージを生成するにはどうすればよいですか?

これまで学んだ内容を確実に理解していただくために、ここでは Python パッケージを生成するチュートリアルの例を示します。

#1. サンプルプロジェクトを作成する

まず、次のフォルダー構造を持つ単純なパッケージを作成します。

 example_package/
├─ example_package/
│  ├─ example_module.py
│  ├─ __init__.py
├─ pyproject.toml
├─ setup.cfg
├─ README.md

プロジェクトのルート ディレクトリは example_package と呼ばれます。そこにコードベース全体が含まれています。プロジェクトのルート内には、3 つのファイルと 1 つのディレクトリがあります。それらの内容は以下で説明されます。

pyproject.toml

このファイルには、プロジェクトをビルドするときに使用するビルド ツールに関する情報が含まれています。この簡単な例の内容は次のとおりです。

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

この場合、 setuptools.build_meta ビルド バックエンドとして宣言しています。ただし setuptools.build_meta は setuptools パッケージ内に含まれているため、まず、これを要件リストの要件としてリストします。この記事の後半では、指定できるその他のオプションについて説明します。

README.md

パッケージに関する情報が含まれます。これは、PyPI のパッケージのページにドキュメントとして表示されます。そのファイルには何でも書き込めます。

セットアップ.cfg

setup.cfg ファイルには、パッケージ名や現在のバージョンなどのプロジェクトのメタデータが含まれています。ここでは、次のコードを setup.cfg の内容として追加します。

 [metadata]
name = example-package
version = 1.0.0 

サンプルプロジェクト

ルート ディレクトリ内には、同じ名前の別のディレクトリが含まれています。このディレクトリにはソース コードが存在します。デモの目的で、次の 2 つのファイルを含めました。

• example_module.py – これにはダミー関数が含まれています。あなたも同じことができます。
• __init__.py – ディレクトリをインポートできるパッケージにします。空でもかまいません。

#2. ビルドコマンドを実行する

これで、プロジェクトのルート ディレクトリでビルド コマンドを実行できるようになりました。

 python -m build

まだインストールしていない場合は、次の手順を使用してツールをインストールしてください。

 pip install build

次のような出力が得られるはずです。

ご覧のとおり、最後の行は、 example-package-1.0.0.tar.gz と example-package-1.0.0-py3-none-any-whl ビルドしたことを示しています。以下の ls コマンドを使用してディレクトリの内容を一覧表示すると、新しいファイルが表示されるはずです。

 ls

出力は次のようになります。

 dist  example_package  example_package.egg-info  pyproject.toml  README.md  setup.cfg 

dist ディレクトリの内容をリストすると、 .whl ファイルと tar.gz ファイルが見つかるはずです。

 $ ls dist
example_package-1.0.0-py3-none-any.whl
example-package-1.0.0.tar.gz 

pyproject.toml ファイルの内容

この簡単な例では、Python プロジェクトのビルド システムのみを指定しました。ただし、pyproject.toml ファイルにさらに情報を追加することもできます。これらは一般的なオプションの一部です。

メタデータ

setup.cfg でメタデータを指定する代わりに、 pyproject.toml にメタデータを記述することができます。この情報は、パッケージ インデックスにパッケージのリストを作成するときに使用されます。

さらに、パッケージの依存関係とそのバージョンを指定して、パッケージのインストール時に依存関係もインストールできるようにすることができます。

 [project]
name = "hello-world"
version = "1.0.0"
description = "My first Python package"
requires-python = ">=3.8"
keywords = ["python", "first-project"]
authors = [
    {name = "John Doe", email = "john@example.com"},
]
dependencies = [
    "requests",
    "gidgethub[httpx]>4.0.0",
] 

ツール.<ツール名>

また tool.<tool_name> を使用して、使用するツールにさまざまな構成オプションを提供することもできます。<tool_name> はツールの名前です。

これは、この方法を使用した構成をサポートするツールでのみ実行できます。たとえば、構成オプションをコード リンターである Black に渡すことができます。

 [tool.black]
line-length = 88
target-version = ["py38", "py39"]

サンプルファイル

これまでに学んだことをまとめると、pyproject.toml ファイルの例が次のようになります。

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

[metadata]
name = "my-project"
version = "1.0.0"
description = "A sample project"
author = "Your Name"
author_email = "your.email@example.com"
license = "MIT"
keywords = ["sample", "project"]

[options]
python_requires = ">=3.6"

[tool.black]
line-length = 88
include = "\\.pyi?$"
exclude = '''
/(
  \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | buck-out
  | build
  | dist
)/
'''

[tool.blackd]
port = 45484
host = "localhost"

詳細については、この ページ をお読みください。

pyproject.tomlの利点

✅ Python プロジェクトの依存関係を管理する標準的な方法を提供します。依存関係
プロジェクトのその他の関連メタデータは、宣言的な方法で指定できます。

✅ また、作成者、ライセンス、GitHub URL などの有用な属性など、プロジェクト内の他のメタデータを指定する方法も提供します。

✅ さまざまなビルドシステムに適合し、ビルドシステムの切り替えが簡単です。

最後の言葉

pyproject.toml は、setup.py を使用する際の欠点を回避するのに役立つ便利な標準です。これは、配布用のパッケージを作成する場合に最も役立ちます。ほとんどの新しいプロジェクトでは、setup.py の代わりに pyproject.toml を使用する必要があります。

次に、Windows、Linux、macOS で Python のバージョンを確認する方法を確認してください。