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

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

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

ワークフローの履歴と変更#

ここで述べるメタデータは、 PEP 376 で初めて定義されたもので、後に PEP 627 (およびその他の PEP 群) で改訂されました。以前は インストール済みの Python 配布物のデータベース という名前で知られていました。他の PyPA 仕様と同様に、 GitHab の Pull リクエストのワークフローを通じて、機能の面に影響しない編集上の改訂を行うことが可能です。パッケージの作成やインストールツールを修正するであろう機能面での変更提案は、 PEP のプロセス (PEP 1 を見てください) を通じて行わなければなりません。

この説明文書が規範的な仕様書である一方で、その変更を導入するような PEP 群は、理論的根拠や後方互換性を保つための考慮点のような追加的な情報を含んでいても構いません。

.dist-info ディレクトリ#

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

This directory is named as {name}-{version}.dist-info, with name and version fields corresponding to コアとなるメタデータの仕様. Both fields must be normalized (see the name normalization specification and the version normalization specification), and replace dash (-) characters with underscore (_) characters, so the .dist-info directory always has exactly one dash (-) character in its stem, separating the name and version fields.

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

注釈

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

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

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

注釈

バイナリ配布物のフォーマット 仕様では、 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/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 ディストロにおけるシステムのパッケージ管理機構のような、それ以外の情報源に依存するツールには適用されません。)

注釈

It is strongly discouraged for an installed package to modify itself (e.g., store cache files under its namespace in site-packages). Changes inside site-packages should be left to specialized installer tools such as pip. If a package is nevertheless modified in this way, then the RECORD must be updated, otherwise uninstalling the package will leave unlisted files in place (possibly resulting in a zombie namespace package).

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 を記録する にあります。

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

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

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

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

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

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

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