ソースコード配布物のフォーマット¶
The current standard source distribution format is identified by the
presence of a pyproject.toml file in the distribution archive. The layout
of such a distribution was originally specified in PEP 517 and is formally
documented here.
これとは別に従来のソースコード配布物のフォーマットが存在しており、それは標準ライブラリの distutils モジュールが setup.py sdist の形で実行される時の動作によって暗黙裡に定義されています。この説明文書では、この従来のソースコード配布物がバージョン 2.2 およびそれ以降のバージョンのメタデータを使った PKG-INFO ファイルを含んでいる場合には、メタデータの仕様で定義されたルールが該当のソースコード配布物にも適用されなければならないことを注記する以外には、このフォーマットの標準化を試みることはしません。
ソースコード配布物は、短く sdists としても知られています。
ソースコードツリー¶
A source tree is a collection of files and directories -- like a version
control system checkout -- which contains a pyproject.toml file that
can be used to build a source distribution from the contained files and
directories. PEP 517 and PEP 518 specify what is required to meet the
definition of what pyproject.toml must contain for something to be
deemed a source tree.
ソースコード配布物のファイル名¶
sdist のファイル名は、 PEP 625 で標準化されています。ファイル名は {name}-{version}.tar.gz の形をしていなければならず、この中の {name} はバイナリ配布物のファイル名に関するルールと同様のルールに従って正規化されていなければならず (バイナリ配布物のフォーマット を見てください) 、かつ、 {version} はプロジェクトのバージョンの形に正規化されていなければなりません (バージョン指定子 を見てください) 。
ファイル名の name と version の部分は、ファイル内のメタデータに保存されている値に合致しなければなりません。
ソースコード配布物のファイルを生成するコードは、この仕様に適合する名前をファイルに与えなければなりません。これは、 ビルドバックエンド の build_sdist フックにも当てはまります。
ソースコード配布物を生成するソースコードは、 .tar.gz 拡張子がついていてファイル名の中に正確に ひとつ のハイフンが存在していることを以て、ソースコード配布物のファイルであると認識しても構いません。これを行うソースコードは、この場合には、ファイル名から得た配布物の名前とバージョンをそれ以上の検証をせずに使用しても構いません。
ソースコード配布物のファイルフォーマット¶
A .tar.gz source distribution (sdist) contains a single top-level directory
called {name}-{version} (e.g. foo-1.0), containing the source files of
the package. The name and version MUST match the metadata stored in the file.
This directory must also contain a pyproject.toml in the format defined in
pyproject.toml の仕様, and a PKG-INFO file containing
metadata in the format described in the コアとなるメタデータの仕様 specification. The
metadata MUST conform to at least version 2.2 of the metadata specification.
If the metadata version is 2.4 or greater, the source distribution MUST contain
any license files specified by the License-File field in the PKG-INFO
at their respective paths relative to the root directory of the sdist
(containing the pyproject.toml and the PKG-INFO metadata).
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 説明文書の中に、さらなる検証を行うためのヒント集 を含めることを検討するように推奨されています。