パッケージングの流れ#
文書は、大抵は Python パッケージインデックス (PyPI) への 配布パッケージ の公開や配布に必要な作業の流れをおおまかに描き出すことを目的としています。パッケージの作者と目される、パッケージを公開する人向けに書かれました。
チュートリアル ではシンプルなプロジェクトについてリリースの準備を行うプロセスを一通り実行しますが、どのステップでどのようなファイルが必要になり、その目的は何かという部分については必ずしも完全に列挙はしていません。
パッケージを公開するには、作者のソースコードからエンドユーザの Python 環境に至る流れが必要とされます。これを実現するためのステップとしては:
パッケージを含むソースツリーを入手します。これは、典型的にはバージョン管理システム (VCS) からのチェックアウトのことです。
パッケージのメタデータ (名前・バージョン・その他) とビルド成果物を作成するための方法を記述した設定ファイルを用意してください。ほとんどのパッケージ向けには、これは、ソースツリー内で手動で維持管理される
pyproject.tomlファイルを準備するということになるでしょう。パッケージ配布サービス (通常は PyPI) へ送るビルド成果物を作成してください; 普通ならこれらは ソースコード配布物 ("sdist") と、ひとつまたはそれ以上の ビルド済配布物 ("wheels") ということになるでしょう。これらは、前のステップで作成した設定ファイルを使ってビルドツールによって作成されます。純 Python パッケージの場合には、共通の wheel がひとつだけ存在するということもしばしばあります。
ビルド成果物をパッケージ配布サービスへアップロードしてください。
その時点で、パッケージがパッケージ配布サービス上に存在することになります。そのパッケージを使うためにエンドユーザは次のことをしなければなりません:
そのパッケージのビルド成果物をパッケージ配布サービスからダウンロードしてください。
それをエンドユーザの Python 環境の通常であれば
site-packagesディレクトリにインストールしてください。もしそれが必要ならパッケージのメタデータにその方法が記述されていなければなりませんが、このステップにはビルド/コンパイルのステップを含むことがあります。
これら最後のふたつのステップは、典型的な場合には、エンドユーザが pip install を走らせた時に pip によって実行されます。
上記のステップについては、以下にもっと詳しく記述してあります。
ソースコードツリー#
ソースコードツリーには、パッケージのソースコード (通常なら VCS からのチェックアウト) が含まれます。
設定ファイル#
ビルド成果物を作成するのに用いるツールによって設定ファイルは変わります。TOML フォーマット で書かれた pyproject.toml ファイルを使うのが標準的な慣習です。
pyproject.toml ファイルには、少なくとも、採用したビルドツールを指定する [build-system] テーブルがなければなりません。ビルドツールとして使えるものには、 flit ・ hatch ・ pdm ・ poetry ・ Setuptools ・ trample ・ whey を含めて他にもさまざまなものがあります。それぞれのツールの説明文書には、 [build-system] に何を書けば良いかが示されていることでしょう。
例えば、 hatch を使う場合のテーブルは次のようになります:
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
pyproject.toml ファイルの中のそのようなテーブルを用いることで、 ビルド のような "フロントエンド" のツールが、ビルド成果物を作成するためにあなたが選んだビルドツールの "バックエンド" を実行することができます。あなたが選んだビルドツールが独自のフロントエンドを提供しても構いません。 pip のようなインストールツールもまた、ソースコード配布物からインストールする時にあなたのビルドツールバックエンドを走らせることで、フロントエンドとして振る舞うことができます。
あなたが選択した特定のビルドツールに応じてどんな追加の情報を pyproject.toml ファイルに記述しなければならないかがきまります。例えば、以下のように指定することができます:
コアとなるメタデータ (名前・バージョン・作者・その他) を含む
[project]、ツール特有の設定オプションを含んだ
[tool]テーブル。
pyproject.toml の設定に関する完全なガイド文書としては、 pyproject.toml ガイド文書 を参照してください。
ビルド成果物#
ソースコード配布物 (またはsdist)#
ソースコード配布物には、エンドユーザの Python 環境でソースコードからパッケージをインストールするのに十分なものが含まれています。そのためには、パッケージのソースコードが必要であり、テストや説明文書が含まれているかもしれません。これらは、自身でソースコードを開発したいと考えるエンドユーザにとっては便利であり、ローカルでコンパイルを行うステップが必要とされる (C 拡張など) エンドユーザのシステムで役に立つことでしょう。
ビルド パッケージは、次のうちのいずれかを生成するためにあなたの選んだビルドツールをどのように呼び出すのかを知っています:
python3 -m build --sdist source-tree-directory
あるいは、あなたの選んだツールが、 sdist を生成するためのツール独自のインタフェースを提供しているかもしれません。
ビルド済み配布物 (wheels)#
ビルド済配布物は、エンドユーザの Python 環境に必要とされるファイル群だけを含んでいます。インストールの際にコンパイル工程は不要で、 wheel ファイルの内容を site-packages ディレクトリに単純に展開することができます。これによってインストールが素早く行われ、エンドユーザにとってより便利であると言えるでしょう。
純 Python パッケージでは、典型的には、ひとつの "万能型" の wheel さえあれば十分です。コンパイル済みのバイナリ拡張を伴うパッケージでは、そのパッケージがサポートする Python インタプリタ・オペレーティングシステム・ CPU アーキテクチャの組み合わせのそれぞれについて wheel ファイルが必要になります。適切な wheel ファイルが利用できない場合には、 pip のようなツールはソースコード配布物からのインストールにフォールバックします。
ビルド パッケージは、次のうちのいずれかを生成するためにあなたの選んだビルドツールをどのように呼び出すのかを知っています:
python3 -m build --wheel source-tree-directory
あるいは、あなたの選んだビルドツールが wheel を生成するための独自のインタフェースを提供しているかもしれません。
注釈
ビルド のデフォルトの動作は、カレントディレクトリにあるソースコードから sdist と wheel の両方を作成することです; 上記の例は意図的に特定の動作をさせています。
パッケージ配布サービスへアップロードする#
ツールの twine の以下のようなコマンドを使って、配布のためにビルド成果物を PyPI へアップロードすることができます:
twine upload dist/package-name-version.tar.gz dist/package-name-version-py3-none-any.whl
あるいは、あなたの選んだビルドツールにアップロードのための独自のインタフェースが備わっているかもしれません。
ダウンロードとインストール#
今やパッケージが公開されたので、エンドユーザがそのパッケージをダウンロードして自分の Python 環境へインストールすることができるようになりました。典型的には、これは、次のようなコマンドを使って pip で行われます:
python3 -m pip install package-name