インストールされた配布物の配布元へ直接アクセスする URL を記録する#

この説明文書では、インストール済みの配布物の *.dist-info ディレクトリにある direct_url.json ファイルによって配布物の配布元へ直接アクセスする URL を記録する方法を指定します。 *.dist-info ディレクトリの一般的な構造と使用方法は、 インストール済みパッケージを記録する に記述されています。

仕様#

direct_url.json ファイルは、要求事項が指定するダイレクト (VCS の URL を含む) 参照 URL からインストールしている時に、インストーラによって *.dist-info ディレクトリに生成されなければなりません。

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

この JSON ファイルは、 RFC 8259 に準拠するように UTF-8 で符号化されていなければならず、シリアル化の方法は ダイレクト URL データ構造 <Direct URL Data Structure> でなければなりません。

注釈

要求された URL が file:// スキームであって VCS からチェックアウトしたものを含むローカルディレクトリを指し示している場合には、インストーラはいかなる VCS 情報をも推定してはならず、従って、いかなる (vcs_info のような) VCS 関連情報をも direct_url.json に出力してはなりません。

注釈

一般的な規則として、 direct_url.json を生成する際には、インストーラは可能な限り要求された URL に含まれる情報を保存するべきです。例えば、 user:password を環境変数から読み込むなら環境変数を参照するような URL として保存されるべきであり、 requested_revision は要求された URL の中に出現するものを極力そのまま反映するべきです。しかしながら、この情報は (commit_id のような) もっと精密なデータを使って 精製 されます。

pip コマンドの例と direct_url.json に与える影響#

direct_url.json を生成するコマンド:

  • pip install https://example.com/app-1.0.tgz

  • pip install https://example.com/app-1.0.whl

  • pip install "app @ git+https://example.com/repo/app.git#subdirectory=setup"

  • pip install ./app

  • pip install file:///home/user/app

  • pip install --editable "app @ git+https://example.com/repo/app.git#subdirectory=setup" (この場合、 url は git リポジトリのクローン先のローカルディレクトリになり、 dir_info"editable": true という形で存在し、 vcs_info は設定されないということになるでしょう)

  • pip install -e ./app

direct_url.json生成しない コマンド

  • pip install app

  • pip install app --no-index --find-links https://example.com/

歴史#

  • 2020年3月: PEP 610 を通じてこの仕様が承認されました。