ソースコード配布物のフォーマット#
ソースコード配布物のフォーマットに関する現在の標準フォーマットは、配布物のアーカイブに pyproject.toml ファイルが存在することで識別されます。そのような配布物のレイアウトは元々は PEP 517 で指定され、ここに公式にドキュメント化されています。
これとは別に従来のソースコード配布物のフォーマットが存在しており、それは標準ライブラリの distutils モジュールが setup.py sdist の形で実行される時の動作によって暗黙裡に定義されています。この説明文書では、この従来のソースコード配布物がバージョン 2.2 およびそれ以降のバージョンのメタデータを使った PKG-INFO ファイルを含んでいる場合には、メタデータの仕様で定義されたルールが該当のソースコード配布物にも適用されなければならないことを注記する以外には、このフォーマットの標準化を試みることはしません。
ソースコード配布物は、短く sdists としても知られています。
ソースコードツリー#
ソースツリー は、 -- バージョン管理システムからのチェックアウトのような -- ファイルとディレクトリの集合で、その中に書かれたファイルやディレクトリからソースコード配布物をビルドすることができるような pyproject.toml ファイルを含んでいるものです。何かをソースコードツリーであると見做すために pyproject.toml ファイルが含んでいなければならないものが何であるかの定義に合致するために要求されることは何であるかについては PEP 517 と PEP 518 が指定しています。
ソースコード配布物のファイル名#
sdist のファイル名は、 PEP 625 で標準化されています。ファイル名は {name}-{version}.tar.gz の形をしていなければならず、この中の {name} はバイナリ配布物のファイル名に関するルールと同様のルールに従って正規化されていなければならず (バイナリ配布物のフォーマット を見てください) 、かつ、 {version} はプロジェクトのバージョンの形に正規化されていなければなりません (バージョン指定子 を見てください) 。
ファイル名の name と version の部分は、ファイル内のメタデータに保存されている値に合致しなければなりません。
ソースコード配布物のファイルを生成するコードは、この仕様に適合する名前をファイルに与えなければなりません。これは、 ビルドバックエンド の build_sdist フックにも当てはまります。
ソースコード配布物を生成するソースコードは、 .tar.gz 拡張子がついていてファイル名の中に正確に ひとつ のハイフンが存在していることを以て、ソースコード配布物のファイルであると認識しても構いません。これを行うソースコードは、この場合には、ファイル名から得た配布物の名前とバージョンをそれ以上の検証をせずに使用しても構いません。
ソースコード配布物のファイルフォーマット#
.tar.gz ソースコード配布物 (sdist) には、トップレベルに {name}-{version} (例えば foo-1.0) と言う名前の単一のディレクトリがあって、そこにパッケージのソールファイル群を含んでいます。 name と version は、ファイル内のメタデータと合致していなければなりません。このディレクトリは、 pyproject.toml の仕様 で定義されたフォーマットで書かれた pyproject.toml ファイルや、 コアとなるメタデータの仕様 仕様内に記述されたフォーマットで書かれたメタデータを含んだ PKG-INFO ファイルも含んでいなければなりません。このようなメタデータは、少なくともバージョン 2.2 のメタデータ仕様を満足するものでなければなりません。
sdist の他の内容については必須でもなく定義もされていません。ビルドシステムは、プロジェクトをビルドするのに必要なものであればどんな情報でも sdist 内に保存しておくことができます。
tar ボールでは、ファイル名に UTF-8 を使える近代的な POSIX.1-2001 pax tar フォーマットを使用するべきです。とりわけ、ソースコード配布物のファイル群は、標準ライブラリの tarfile モジュールに open flag 'r:gz' を与えることで読み込めるものでなければなりません。
ソースコード配布物アーカイブの機能#
tar ファイルをそのまま展開することは危険を伴うため、また、展開結果がプラットフォーム依存になるため、ソースコード配布物アーカイブの機能は制限されています。
データフィルタしながらアンパックする#
ソースコード配布物を展開する時には、ツール類は、 tarfile.data_filter() (例えば TarFile.extractall(..., filter='data')) か、あるいは、後述する データフィルタなしでアンパックする<Unpacking without the data filter> 節に従うか、いずれかを行わなければなりません。
例外として、 hasattr(tarfile, 'data_filter') (PEP 706) を持たない Python インタープリタ上では、通常ならそのようなフィルタを使うはずのツール類はユーザに対して警告した上でこの仕様を無視しても構いません。利便性 (例えばアーカイブを完全に信頼すること) とセキュリティ (例えばアンパックすることを拒否すること) の間のトレードオフは、この場合にはツールに委ねられています。
データフィルタなしでアンパックする#
(例えば、後方互換性のためであったり、追加的な機能を許容するためであったり、あるいは Python を使わない場合であったりで) データ <data> フィルタを直接には使わないツール類は、この節の内容に従わなければなりません。(執筆時点では、 データ <data> フィルタもこの節の内容に従うものになっていますが、将来にはこの同期が外れるかもしれません。)
以下に述べるファイル群は、 sdist アーカイブの中に置くには不適格です。そのようなエントリに遭遇した場合には、ツール類はユーザに通知するべきであり、そのエントリをアンパックしてはならず、そして、エラー (failure) とともに処理を中断しても構いません:
宛先となるディレクトリの外側に置かれるファイル群。
宛先となるディレクトリの外側を指し示すリンク (シンボリックでもハードでも)。
デバイスファイル (パイプを含む)。
以下に示すものもまた、不適格です。ツール類はこれらを上記のように扱っても構いませんが、そうすることを要求されているわけではありません:
ファイル名の一部に
..を含むファイルまたはリンクのターゲット。当該アーカイブの一部ではないファイルを指し示すリンク。
ツール類は、アーカイブから得た内容を使って、リンク類 (シンボリックまたはハード) をアンパックしても構いません。
sdist アーカイブを展開する時:
ファイル名の先頭のスラッシュは、必ず削除しなければなりません。 (これは、
tarを展開する時の今日的な標準的な振る舞いです。)モード <mode>(UNIXでのパーミッション) の各ビットについて、ツール類は以下のうちのいずれかをしなければなりません:プラットフォームの既定値を新しく作るファイル/ディレクトリに (それぞれ) 適用するか、
アーカイブにおける (パーミッション) ビットに従って設定するか、または、
非実行ファイルには
rw-r--r--(0o644) の (パーミッション) ビットを設定し、実行ファイルとディレクトリにはrwxr-xr-x(0o755) を設定する。
特殊な
モード <mode>ビット (setups, setgid, sticky) については、削除 (クリア) しなければなりません。ユーザ (多分オーナのこと) 実行 ビットについては、そのまま保存することが推奨されています。
さらなるヒント#
ツールの作成者は、自分たちのツールに適用する tarfile 説明文書の中に、さらなる検証を行うためのヒント集 を含めることを検討するように推奨されています。