ダイレクト URL データ構造 <Direct URL Data Structure>#

この説明文書では、python プロジェクトや VCS 上のソースツリーやローカルのソースツリーやソースコード配布物や wheel ファイルのような配布物アーティファクトに対してURLを表現することを可能とする、 JSON のシリアル化抽象データ構造の仕様を定義します。

The representation of the components of this data structure as a RFC 1738 URL is not formally specified at time of writing. A common representation is the pip URL format. Other examples are provided in the Version specifier specification.

仕様#

直接 URL データ構造は辞書でなければならず、 RFC 8259 に従って JSON にシリアライズできなければなりません。

それは少なくともふたつのフィールドを含んでいなければなりません。第１のフィールドは string 型の url です。 url が何を参照しているかによって、第２のフィールドは、 (url が VCS への参照であるなら) vcs_info であるか、 (url がソースコードのアーカイブまたは wheel を参照しているなら) archive_info であるか、または、 (url がローカルのディレクトリを参照しているなら) dir_info であるかのうちのひとつでなければなりません。これらの情報フィールドは、 (空であることも可能ですが) 以下に定義するような取り得るキーを持った下位の辞書を値に取ります。

固持する場合には、url は、セキュリティ上の理由から、機微に関わる認証情報をすべて削除しておかなければなりません。

しかしながら、次に述べる正規表現に合致する形で URL の user:password の部分を環境変数から構成しても構いません:

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

さらに、 URL の user:password 部分は、広く知られたセキュリティ的に問題のない文字列であっても構いません。典型的な例としては、 ssh://git@gitlab.com/user/repo のような URL における git を挙げることができます。

VCS URL群#

url が VCS リポジトリを参照している場合、以下のキー群を伴った vcs_info キーが辞書に存在していなければなりません:

(git ・ hg ・ bzr ・ svn のいずれかのような) VCS の名前を含んだ vcs キー (string 型) が存在していなければなりません。その他の VCS については、この仕様を修正するための PEP を書くことによって登録されるべきです。当該 VCS の checkout/download コマンドへの翻訳をしなくてもインストーラが手を離してしまえるようにするために、 url の値は対応する VCS と齟齬のないものでなければなりません。
requested_revision キー (string 型) は、ブランチ・タグ・リファレンス・コミット・リビジョンその他を指定するために存在していても構いません (VCS と互換性を持つフォーマットにて)。
commit_id キー (string 型) は、正確にどのコミットまたはリビジョンがインストールされた/されるかを示すもので、必須のキーです。 VCS がリビジョン識別子に基づくコミットハッシュをサポートしているなら、インストールされたもののソースコードの不変のバージョンを指し示す目的で、そのようなコミットハッシュを commit_id として使わなければなりません。

アーカイブ URL 群#

url がソースコードのアーカイブや wheel ファイルを指し示す場合には、 archive_info キーが次のようなキーを持つ辞書の形で存在しなければなりません:

hashes キーは、ハッシュ名から16進数表記のファイルハッシュ値への対応を保持する辞書として存在するべきです。

複数のハッシュ値を含めることが可能で、そのような複数のハッシュ値を使って何をするか (すべてのハッシュ値を検証しても一部だけを検証しても構いませんし、何もしなくても構いません) については利用する側次第です。

これらのハッシュの名前は、常に小文字に正規化されているべきです。

hash lib 経由で利用可能なハッシュアルゴリズム (とりわけ、 hashlib.new() に渡すことができて、かつ、追加的なパラメータを必要としないもの) はどれでも、ハッシュ値を格納する辞書のキーとして用いることができます。 hashlib.algorithms_garanteed から安全なアルゴリズムを少なくともひとつ選択して (訳注、ハッシュ値格納用辞書に) 含めるべきです。執筆時点では、 sha256 が特に推奨されています。
非推奨となった hash キー (string 型) は、後方互換性を保つ目的でなら <hash-algorithm>=<expected-hash> を値に取る形で存在していても構いません。

データ構造を生成する側では、ひとつまたは複数のハッシュが利用できるなら hashes キーを生成するべきです。以前からそうしていたので既存のクライアントのために後方互換性を保つためなら、生成側は hash キーの生成を継続するべきです。

hash と hashes の両方のキーが存在する時は、 hash キーの中に現れるハッシュは、 hashes の辞書の中にも存在しなければならず、そうすることで利用する側では hashes キーがあればそれだけを考慮し、なければ hash にフォールバックすることが可能になります。

ローカルディレクトリ#

url がローカルのディレクトリを参照している場合には、以下のキーを含む辞書として dir_info キーが存在していなければなりません。

配布物が編集可能モードでインストールされた/される場合には editable (boolean 型): true 、そうでなければ false 。存在していない場合のデフォルトは false です。

url がローカルのディレクトリを参照している場合、 :rfc:8089` に適合する ``file スキームが存在していなければなりません。特にパス部分は絶対パスでなければなりません。相対パスを絶対パスに変換する際には、シンボリックリンクはそのまま保存されているべきです。

サブディレクトリ内のプロジェクト群#

トップレベルの subdirectory フィールドは、 pyproject.toml または setup.py が存在する場所を指定するために、 VCS リポジトリやソースコードのアーカイブやローカルのディレクトリのルートディレクトリに対する相対パスとして示したディレクトリパスを値とするものとして存在することが許されています。

登録済みの VCS#

この節では登録済み VCS; vcs や requested_revision やその他の vcs_info 内のフィールドや、さらにある場合には特定の VCS に特有のフィールドなどの使い方のような拡張された VCS 特有の情報の一覧を示します。 PEP を書くことでこの仕様を修正する形で別の VCS を登録することが推奨されていますが、ツールの側で他の VCS を (訳注、VCS 登録作業抜きで) サポートしても構いません。 vcs フィールドの値は、 (小文字の) コマンド名であるべきです。当該 VCS をサポートするのに必要であると思われるその他のフィールドについては、当該 VCS のコマンド名で始まる名前にするべきです。

Git#

ホームページ

https://git-scm.com/

vcs コマンド

git

vcs フィールド

git

requested_revision フィールド

タグ名・ブランチ名・Git 参照・コミットハッシュ・短縮型コミットハッシュ・その他のコミットハッシュ的なもの。

commit_id フィールド

コミットハッシュ (16進数で40文字のSHA1)。

注釈

ツールは、 requested_revision が Git 参照に対応しているか否かを判断するために git show-ref や git symbolic-ref コマンドを使うことができます。さらに、 refs/tags/ で始まる参照はタグに対応し、クローンした後に refs/remotes/origin/ で始まる参照はブランチに対応します。

Mercurial#

ホームページ

https://www.mercurial-scm.org/

vcs コマンド

hg

vcs フィールド

hg

requested_revision フィールド

タグ名・ブランチ名・チェンジセット ID ・短縮型チェンジセット ID。

commit_id フィールド

チェンジセット ID (16 進数で 40 文字)。

Bazaar#

ホームページ

https://www.breezy-vcs.org/

vcs コマンド

bzr

vcs フィールド

bzr

requested_revision フィールド

タグ名・ブランチ名・リビジョン id 。

commit_id フィールド

リビジョン id 。

Subversion#

ホームページ

https://subversion.apache.org/

vcs コマンド

svn

vcs フィールド

svn

requested_revision フィールド

requested_revision は、 svn checkout --revision オプションと互換でなければなりません。 Subversion では、ブランチまたはタグは url の一部です。

commit_id フィールド

Subversion は大域的にユニークな識別子をサポートしていないので、このフィールドは当該リポジトリにおける Subversion のリビジョン番号です。

例#

ソースコードアーカイブ:

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hashes": {
            "sha256": "2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
        }
    }
}

タグおよびコミットハッシュ付きの Git のURL:

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

ローカルディレクトリ:

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

編集可能モード状態にあるローカルディレクトリ:

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

歴史#

2020年3月: このデータ構造は、当初は PEP 610 で direct_url.json メタデータファイルの一部として仕様を指定されていましたが、ここで正式に文書化されました。
2023年1月: archive_info.hashes キーを追加しました ([議論] (https://discuss.python.org/t/22299)) 。