オススメのツール¶

Python パッケージングのランドスケープは、多くの異なったツール群からできています。多くのタスクについて、 Python パッケージングオーソリティ (PyPA とは多数のパッケージングツール群を包含するとともにこのガイド文書を維持管理しているワーキンググループ) は、一律に適用するような推奨ををしません; 例えば、数多くのビルドバックエンドが存在する理由は、既存のユニークなバックエンドである setuptools よりもうまく特定のユーザのニーズに応える新しいバックエンドの開発を可能とするためにランドスケープを開放しているということなのです。このガイド文書では、広く認知されている幾つかのツールを指し示していますが、また、非推奨であったり安全でなかったりするために 使うべきでない ものについても非推奨事項を記しています。

仮想環境¶

仮想環境を手動で作成して使用するための標準的なツールは、 virtualenv (PyPA project) と venv (virtualenv には備わっている幾つかの機能が欠けてはいるものの、Pythonの標準ライブラリの一部) です。

パッケージをインストールする¶

pip は PyPI からパッケージをインストールするための標準的なツールです。 pip の推奨事項については、セキュアなインストールを読むと良いでしょう。 pip は、標準ライブラリのパッケージ ensurepip を通じて、ほとんどの Python 環境でデフォルトで利用可能です。

別のやり方としては、 PyPI を通じて配布されてコマンドラインから実行される Python アプリケーションをインストールする特定のユースケースにおいては pipx を検討してください。 pipx は pip と、専用の仮想環境の中にそれぞれのアプリケーションをインストールする venv のラッパーとして動作します。これによって、異なるアプリケーションの間の依存関係上の衝突を避け、システムワイドのアプリケーションとの間で同じ Python インタープリタを使う際の衝突を避けることができます (特に Linux 環境で)。

特に科学計算ソフトウェア向けには conda や Spack を検討してください。

課題

ここか、新しい議論として、"pip vs. Conda" の比較を書くべし。

easy_install (Setuptools の一部) は、 pip の登場によって非推奨になっていますので、 使わない でください (詳しくは pip対easy_install を見てください)。同様に、 python setup.py install や python setup.py develop も非推奨になっていますので 使わない でください (背景については setup.py は非推奨になりましたか？を、移行するためのアドバイスについては setup.py 近代化プロジェクトを見てください)。

ロックファイル¶

pip-tools と Pipenv は、再現性を高める目的でロックファイル、そこにはその環境にインストールされたパッケージの正確なバージョンを含みますが、そのようなロックファイルを作成するためのツールとしてよく知られています。

ビルドバックエンド¶

重要

どうか覚えておいてください: このドキュメントは、読者に特定のツールへ向かって舵を切らせることを追求しているわけではなく、一般的なツール群を列挙しているだけです。異なるユースケースでは、しばしば、そのケースに特化したワークフローが必要になります。

純 Python のパッケージを取り扱うビルドバックエンドで人気のあるものは、アルファベット順に:

Flit-core -- flit とともに開発されたが別のもの。最小限で自己主張の強いビルドバックエンド。プラグインをサポートしない。
Hatchling -- hatch とともに開発されたが別のもの。プラグインをサポートする。
PDM-backend -- pdm とともに開発されたが別のもの。プラグインをサポート。
Poetry-core -- poetry とともに開発されたが別のもの。プラグインをサポート。

このリストの他のバックエンドとは異なって、 Poetry-core は標準的な [project] table をサポートしていません ([tool.poetry] テーブル内に別のフォーマットで書くことはできます)。
Setuptools は、以前は唯一のビルドバックエンドでした。プラグインをサポート。

注意

setuptools を使うのであれば、標準化の努力が為される前の幾つかの機能が今では非推奨になっていて互換性を保つために 一時的に継続使用 しているだけであることを忘れないでください。

とりわけ、 python setup.py のように直接に起動しては いけません 。他方で、可能であればいつでも近代的な [project] table in pyproject.toml (または setup.cfg) を使うことや、プログラム的な設定が必要とされる場合にのみ setup.py を使い続けることが推奨されてはいますが、 setup.py を使って setuptools に設定を渡すことは今も完全にサポートされています。 setup.py は非推奨になりましたか？を見てください。

非推奨となった機能の他の例としては、 setup() の setup_requires 引数を使うべきではなく (代わりに pyproject.toml 内の [build-system] テーブルを使ってください) 、また、 easy_install コマンドを使うことも非推奨になっています (cf. pip対easy_install) 。

distutils を 使わないで ください、というのも、これは非推奨になっていますし、まだ setuptools から利用可能ではありますが Python 3.12 で標準ライブラリから取り除かれたものです。

拡張モジュール用のビルドバックエンド¶

拡張モジュールを伴うパッケージについては、その拡張が書かれた言語用の専用サポートのあるビルドシステムを使うのが最善です、例えば:

Setuptools -- C 言語および C++ 言語をネイティブにサポート (サードパーティのプラグインで Go 言語と Rust 言語も)、
meson-python -- C 言語・ C++ 言語・ Fortran ・ Rust およびその他の言語が Meson によってサポートされています、
scikit-build-core -- C 言語・ C++ 言語・ Fortran やその他の言語が CMake によってサポートされています、
Maturin -- Rust 、 Cargo を経由して。

配布物をビルドする¶

PyPI へアップロードするためにソースコード配布物や wheels をビルドするための標準ツールは、ビルドです。pyproject.toml 内で 宣言された ビルドバックエンドが何であれ、それを起動することになります。

この作業のために python setup.py sdist や python setup.py bdist_wheel を 使わないで ください。setup.py を直接に起動することは非推奨になっています。

もし、拡張モジュールを使っていて複数のプラットフォーム向けに wheel ファイルを配布したいと考えているなら、配布可能な wheel ファイルをビルドする CI 環境の一部として cibuildwheel を使いましょう。

PyPIにアップロードする¶

サポート対象の CI/CD プラットフォームにホストされている、もしくは、そこから公開されているプロジェクトに関しては、手動で設定された API トークンなしで CI/CD ワークフローから PyPI へとパッケージを安全にアップロードすることができる Trusted Publishing を使うことが推奨されています。

2024 年 11 月の時点では、 PyPI は以下のプラットフォームを信頼ある公開 <Trusted Publishing> プロバイダとしてサポートしています:

(https://github.com における) GitHub Actions
(https://gitlab.com における) GitLab CI/CD
ActiveState
Google Cloud

利用可能なもうひとつの方法は、 twine を用いて手動でパッケージをアップロードすることです。

危険

このタスクを行うために python setup.py upload を使うことは 絶対にやめて ください。非推奨であることに加えて、危険 <insecure> です。

ワークフローツール¶

これらのツール群は、プロジェクトの仮想環境を自動的に管理する環境マネージャです。これらは、テストを走らせたり、説明文書をコンパイルしたり、何らかのファイルを再生成したり、その他のタスクを定義して起動するための "タスク実行係" としても動作します。これらのうちのいくつかは配布物をビルドしたり PyPI にアップロードするためのショートカットを提供しますし、あるいは、アプリケーション向けのロックファイルをサポートしています。これらは、往々にして、先述のツール群を内部的に呼び出しています。アルファベット順に: