Add Source distribution archive features (PEP 721)

Author: encukou

source/specifications/source-distribution-format.rst

@@ -67,3 +67,73 @@ whatever information they need in the sdist to build the project.
 The tarball should use the modern POSIX.1-2001 pax tar format, which specifies
 UTF-8 based file names. In particular, source distribution files must be readable
 using the standard library tarfile module with the open flag 'r:gz'.
+
+
+.. _sdist-archive-features:
+
+Source distribution archive features
+====================================
+
+Because extracting tar files as-is is dangerous, and the results are
+platform-specific, archive features of source distributions are limited.
+
+Unpacking with the data filter
+------------------------------
+
+When extracting a source distribution, tools MUST either use
+``tarfile.data_filter`` (e.g. ``TarFile.extractall(..., filter='data')``), OR
+follow the *Unpacking without the data filter* section below.
+
+As an exception, on Python interpreters without ``hasattr(tarfile, 'data_filter')``
+(:pep:`706`), tools that normally use that filter (directly on indirectly)
+MAY warn the user and ignore this specification.
+The trade-off between usability (e.g. fully trusting the archive) and
+security (e.g. refusing to unpack) is left up to the tool in this case.
+
+
+Unpacking without the data filter
+---------------------------------
+
+Tools that do not use the ``data`` filter directly (e.g. for backwards
+compatibility, allowing additional features, or not using Python) MUST follow
+this section.
+(At the time of this writing, the ``data`` filter also follows this section,
+but it may get out of sync in the future.)
+
+The following files are invalid in an ``sdist`` archive.
+Upon encountering such an entry, tools SHOULD notify the user,
+MUST NOT unpack the entry, and MAY abort with a failure:
+
+- Files that would be placed outside the destination directory.
+- Links (symbolic or hard) pointing outside the destination directory.
+- Device files (including pipes).
+
+The following are also invalid. Tools MAY treat them as above,
+but are NOT REQUIRED to do so:
+
+- Files with a ``..`` component in the filename or link target.
+- Links pointing to a file that is not part of the archive.
+
+Tools MAY unpack links (symbolic or hard) as regular files,
+using content from the archive.
+
+When extracting ``sdist`` archives:
+
+- Leading slashes in file names MUST be dropped.
+  (This is nowadays standard behaviour for ``tar`` unpacking.)
+- For each ``mode`` (Unix permission) bit, tools MUST either:
+
+  - use the platform's default for a new file/directory (respectively),
+  - set the bit according to the archive, or
+  - use the bit from ``rw-r--r--`` (``0o644``) for non-executable files or
+    ``rwxr-xr-x`` (``0o755``) for executable files and directories.
+
+- High ``mode`` bits (setuid, setgid, sticky) MUST be cleared.
+- It is RECOMMENDED to preserve the user *executable* bit.
+
+
+Further hints
+-------------
+
+Tool authors are encouraged to consider how *hints for further
+verification* in ``tarfile`` documentation apply for their tool.