インストール済みのプロジェクトを記録する

この説明文書では、ある環境にインストールされた Python プロジェクト に関する情報を記録するための共通フォーマットについて指定します。共通メタデータフォーマットがあれば、プロジェクトがどのようにインストールされたかに関わりなく、ツールがプロジェクトについて問い合わせを行い、管理し、あるいはアンインストールすることが可能になります。

ほとんど全ての情報が必須ではないものです。これによって、Linux のパッケージ管理機構のような Python のエコシステムの外にあるツールを Python のツールの使い方と最大限に統合することができます。例えば、ある Python ツールに特化したフォーマットで書かれたインストール済みファイルのリストをインストーラがすぐには提供できない場合でさえも、インストール済みのプロジェクトの名前とバージョンを記録するべきです。

.dist-info ディレクトリ

配布物からインストールされた各プロジェクトは、一連のファイルの他に、インポート可能なモジュールやパッケージの隣に位置する ".dist-info" ディレクトリもインストールします (通常は site-packages ディレクトリ) 。

このディレクトリは {name}-{version}.dist-info という名前で、 name と version のフィールドが コアとなるメタデータ に対応しています。両方のフィールドは正規化 (各フィールドにおける正規化の定義については、それぞれ 名称正規化の仕様 と バージョン正規化の仕様 を見てください) されていなければならず、かつ、ダッシュ (-) の文字をアンダースコア (_) で置き換えることで .dist-info ディレクトリが常に正確にひとつだけのダッシュ (-) 文字をそのファイル名基幹部に持ち、それによって name と version フィールドを分割していなければなりません。

歴史的には、ツール類はドット文字の置換や name フィールドにおける大文字小文字の正規化に失敗すしたり、 version フィールドの正規化をしなかったり、ということを繰り返してきました。 .dist-info ディレクトリを利用する側のツールは、そのようなフィールドが正規化されていることを期待するべきではなく、それらを対応する正規化済みのものと同じものだと考えて取り扱うべきです。 .dist-info ディレクトリに書き込むツールをこれから作るなら、そのツールは name と version の両方のフィールドを上記の規則に従って正規化しなければならず、既存のツールもこれらのフィールドの正規化を始めることが推奨されています。

注釈

.dist-info ディレクトリの名前は、曖昧さのない形で配布物をファイルシステム上のパスとして表現するためにフォーマットされています。配布物の名前をユーザに提示するツールは、正規化された名前を使うのを避け、 (インストール済みパッケージへの名前解決より前に必要な場合には) 代わりに指定された名前を提示するか、または、コアとなるメタデータの適切なフィールドの値はエスケープ処理もされておらず配布物を正確に反映しているのでそこから読み取った名前を提示するべきです。ライブラリは、配布物の情報を表示する時にツールが正規化されていない名前にアクセスできるように、そのようなツール群が利用できるような API を提供するべきです。

この .dist-info ディレクトリには、以下に詳細を述べるこれらのファイルを置くことができます:

METADATA ファイルは必須です。これ以外の全てのファイルは、インストールツールの最良で省略可能です。インストーラ独自のファイルが他に存在しても構いません。

この .dist-info/ ディレクトリには、以下に詳細を述べるディレクトリを置くことができます:

  • licenses/: ライセンスファイルを含みます。

  • sboms/: ソフトウェア部品表 (SBOMs) を含みます。

注釈

バイナリ配布物のフォーマット 仕様では、 Wheel の .dist-info ディレクトリに出現するかもしれない追加のファイルについて記述しています。そのようなファイルをインストールされたプロジェクトの .dist-info ディレクトリにコピーしても構いません。

この仕様の以前のバージョンでは、 REQUESTED ファイルも指定していました。このファイルは、現在ではツール特有の拡張であると見做されていますが、いつか再び標準化されるかもしれません。その元々の意味するところについては、 PEP 376 を見てください。

METADATA ファイル

METADATA ファイルには、 コアとなるメタデータ 仕様のバージョン 1.1 またはそれ以降で記述されているようなメタデータを含みます。

METADATA ファイルは必須のものです。このファイルを作成することができない場合や、必須のコアとなるメタデータが入手できない場合には、インストーラはエラーを発生させてプロジェクトのインストールを失敗させなければなりません。

RECORD ファイル

RECORD ファイルには、インストールされたファイル群を列挙します。CSV ファイルで、インストールされたファイルを１行に一つずつ書き込みます。

CSV の亜種としては、 Python の csv モジュールの reader で読めるものでなければなりません:

  • フィールド区切り文字: , (コンマ)、

  • 引用符: " (ストレートダブルクォート)、

  • 行末文字: \r\n か \n のいずれか一方。

各レコードは３個の要素から構成されます: ファイルの パス 、内容の ハッシュ値 、そして、その サイズ です。

パス は .dist-info ディレクトリを含むディレクトリ (通常は site-packages ディレクトリ) へのパスで、絶対パスでも相対パスでも構いません。 Windows では、ディレクトリはスラッシュで区切ってもバックスラッシュで区切っても構いません (/ または \) 。

hash は、空文字列または hashlib.algorithms_guaranteed から取ったハッシュアルゴリズムの名前の後ろに等号 = を付けて、ファイルの内容のハッシュ値を urlsafe-base64-nopad エンコーディング (base64.urlsafe_b64encode(digest) の結果から末尾の = を取り除いたもの) で記したものです。

size は、空文字列か、または、ファイルサイズを 10 進数のバイト数で書いたものです。

どのファイルについても、 hash フィールドと size フィールドの片方もしくは両方が空欄になっていても構いません。通常は、 .pyc ファイルと RECORDS ファイル自身については hash フィールドと size フィールドの両方が空欄になっています。その他のファイルについては、インストールされたプロジェクトに関する完全性を検証するために情報を与えておくことが推奨されています。

もし RECORD ファイルが存在するなら、 RECORD に記入された .py ファイルに対応する .pyc ファイルを記入することはオプションですが、それを除いてそのプロジェクトからインストールされたファイルの全てについて列挙していなければなりません。特に、 .dist-info ディレクトリ の内容 (RECORD ファイル自身を含む) については、書いておかなければなりません。ディレクトリについては記入してはなりません。

パッケージを完全にアンインストールするためには、ツールは、 RECORD に列挙された全てのファイルと、 .py ファイルに対応する (あらゆる最適化状態の) .pyc ファイルと、アンインストールによって空になったすべてのディレクトリを削除する必要があります。

ありうる RECORD ファイルの一部を切り出した例をここに掲げます

/usr/bin/black,sha256=iFlOnL32lIa-RKk-MDihcbJ37wxmRbE4xk6eVYVTTeU,220
../../../bin/blackd,sha256=lCadt4mcU-B67O1gkQVh7-vsKgLpx6ny1le34Jz6UVo,221
__pycache__/black.cpython-38.pyc,,
__pycache__/blackd.cpython-38.pyc,,
black-19.10b0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
black-19.10b0.dist-info/licenses/LICENSE,sha256=nAQo8MO0d5hQz1vZbhGqqK_HLUqG1KNiI9erouWNbgA,1080
black-19.10b0.dist-info/METADATA,sha256=UN40nGoVVTSpvLrTBwNsXgZdZIwoKFSrrDDHP6B7-A0,58841
black-19.10b0.dist-info/RECORD,,
black.py,sha256=45IF72OgNfF8WpeNHnxV2QGfbCLubV5Xjl55cI65kYs,140161
blackd.py,sha256=JCxaK4hLkMRwVfZMj8FRpRRYC0172-juKqbN22bISLE,6672
blib2to3/__init__.py,sha256=9_8wL9Scv8_Cs8HJyJHGvx1vwXErsuvlsAqNZLcJQR0,8
blib2to3/__pycache__/__init__.cpython-38.pyc,,
blib2to3/__pycache__/pygram.cpython-38.pyc,sha256=zpXgX4FHDuoeIQKO_v0sRsB-RzQFsuoKoBYvraAdoJw,1512
blib2to3/__pycache__/pytree.cpython-38.pyc,sha256=LYLplXtG578ZjaFeoVuoX8rmxHn-BMAamCOsJMU1b9I,24910
blib2to3/pygram.py,sha256=mXpQPqHcamFwch0RkyJsb92Wd0kUP3TW7d-u9dWhCGY,2085
blib2to3/pytree.py,sha256=RWj3IL4U-Ljhkn4laN0C3p7IRdfvT3aIRjTV-x9hK1c,28530

RECORD ファイルが存在しない場合、 .dist-info に依存するツールは、アンインストールやアップグレードを試みてはなりません。(この制約は、 Linux ディストロにおけるシステムのパッケージ管理機構のような、それ以外の情報源に依存するツールには適用されません。)

注釈

インストール済みのパッケージが自分自身を修正すること (例えば、 site-packages 内の名前空間の下にキャッシュファイルを保存すること) は、 強い非推奨 事項です。 site-packages の内側での変更は、 pip のような特別なインストールツールに委ねられるべきです。それにも関わらず、パッケージがこのようなやり方で修正された場合には必ず RECORD を更新しなければならず、そうしなければパッケージをアンインストールの時に、リストに洩れているファイルがその場に残されてしまうでしょう (おそらくはゾンビ状態の名前空間パッケージになるでしょう)。

INSTALLER ファイル

もし存在するなら、 INSTALLER は、プロジェクトのインストールに使われたツールを名指しする１行のテキストファイルです。インストーラがコマンドラインから起動されるなら、 INSTALLER はそのコマンドの名前を含んでいるべきです。そうでなければ印刷可能な ASCII 文字を含んでいるべきです。

ファイルは、0個またはそれ以上の ASCII 空白文字で終端することができます。

INSTALLER ファイルについて、二つの可能な例を示します:

pip

MegaCorp Cloud Install-O-Matic

この値は情報提供目的にのみ使用されるべきです。例えば、あるツールでプロジェクトのアンインストールをしようとしたが RECORD ファイルを見つけられなかった場合には、そのツールは INSTALLER ファイルに書いてある (別の) ツールを使えばアンインストールができるかもしれないと示唆しても構いません。

entry_points.txt ファイル

インストーラが (他者から) 実行できる状態にするコンソールスクリプトや他のアプリケーションを含めて、 (他者から) 発見されたり他のソースコードから利用されたりすることを意図したコンポーネントを当該パッケージが含んでいる場合には、インストーラがその由を表示するためにこのファイルを作っても構いません。

その詳細な仕様は エントリポイントの仕様 にあります。

direct_url.json ファイル

このファイルは、要求事項が指定するダイレクト URL (VCS の URL を含む) から配布物をインストールする際に、インストーラによって生成されなければなりません。

他のタイプの要求事項 (すなわち、名前とバージョン指定子) から配布物をインストールする際には、このファイルを生成してはなりません。

その詳細な仕様は インストールされた配布物の配布元へ直接アクセスする URL を記録する にあります。

licenses/ サブディレクトリ

メタデータバージョンが 2.4 またはそれ以上で、かつ、一つ以上の License-File フィールドが指定されている場合、 .dist-info/ ディレクトリには、 METADATA ファイル内の License-File フィールドに列挙されたファイル群を licenses/ ディレクトリに対する相対パスにそれぞれ収容した licenses/ サブディレクトリが存在していなければなりません。このディレクトリ内のファイルはすべて、インストールツールによって wheel からコピーされなければなりません。

sboms/ サブディレクトリ

.dist-info/sboms/ ディレクトリ内に含まれるすべてのファイルは、インストールされたパッケージに含まれるソフトウェアを記述するソフトウェア部品表 (SBOM) ファイルでなければなりません。このディレクトリ内のすべてのファイルは、インストールツールによって wheel からコピーされなければなりません。

インストール済みのパッケージ群への変更を意図的に防ぐ

(Python エコシステムでの依存関係に加えて外部の依存関係を管理する必要がある場合など) いくつかの場合には、 Python 環境にパッケージをインストールするツールが、そのインストール済みパッケージを他のツールがアンインストールも修正もしていないことを、もしそんなことをしていればより広範な環境に互換性問題を引き起こしかねないので、しっかりと確認することが望ましいです。

これを達成するために、影響を被るツール群は次のような段階を踏むべきです:

  • 他のツール類を経由した変更を抑止するために、RECORD ファイルを別の名前にするか、削除するか (このファイル内の情報が必要なら、例えば標準的でない名前の RECORD.tool というファイルを作成するために拡張子を追加すること、あるいは、パッケージの内容物を他の手段で追跡・管理しているのであればファイルを完全に除外しておくこと) してください

  • そのパッケージを管理するのに使用されるべきツールの名前を示すように INSTALLER ファイルを書いてください (これによって、 RECORD を参照できるツール群が影響を被るパッケージを修正するように言われた時により良いエラー通知を提供できます)

Python ランタイムの提供者は、デフォルトの Python パッケージのインストレーションスキームを修正してプラットフォームが提供するパッケージ群で使われるものとは別の場所を使うようにすることで、プラットフォームが提供するパッケージ群を意図せずに修正してしまうことを防いでも構いません。

いくつかの環境では、 Python 特有のツール群を経由した追加パッケージのインストールさえもブロックすることが望ましいかもしれません。このようなケースについては 外部から管理される環境 を参照してください

歴史

  • 2009年6月: PEP 376 を通じてこの仕様の元々のバージョンが承認されました。当時は、 インストール済みの Python 配布物のデータベース という名前でした。

  • 2020年3月: PEP 610 を通じて direct_url.json ファイルの仕様が承認されました。これは、このページで言及されるのみです; 完全な定義については インストールされた配布物の配布元へ直接アクセスする URL を記録する を見てください。

  • 2020年9月: PEP 627 を通じて、さまざまな修正や明確化が承認されました。

  • 2022年12月: PEP 639 を通じて、 .dist-info/licenses/ ディレクトリが仕様化された。