Add Source distribution archive features (PEP 721)

manolotron · Aug 3, 2023 · 137713c · 137713c
1 parent c022989
commit 137713c
Showing 1 changed file with 70 additions and 0 deletions.
diff --git a/source/specifications/source-distribution-format.rst b/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.