Formato de distribuição fonte#

O formato padrão atual do formato de distribuição fonte é identificado pela presença de um arquivo pyproject.toml no arquivo de distribuição. O layout de tal distribuição foi originalmente especificado na PEP 517 e está formalmente documentado aqui.

Existe também o formato de distribuição fonte legado, implicitamente definido pelo comportamento do módulo distutils na biblioteca padrão, ao executar setup.py sdist. Este documento não tenta padronizar este formato, exceto para observar que se uma distribuição de fonte legada contém um arquivo PKG-INFO usando metadados versão 2.2 ou posterior, então ela DEVE seguir as regras aplicáveis às distribuições de fonte definidas nos metadados especificação.

Distribuições fonte também são conhecidas pela abreviação sdists.

Árvores fonte#

Uma árvore fonte é uma coleção de arquivos e diretórios – como um checkout local do sistema de controle de versão – que contém um arquivo pyproject.toml que pode ser usado para construir uma distribuição fonte a partir dos arquivos e diretórios contidos. PEP 517 e PEP 518 especificam o que é necessário para atender à definição do que pyproject.toml deve conter para que algo seja considerado uma árvore fonte.

Nome de arquivo da distribuição fonte#

O nome do arquivo de um sdist foi padronizado na PEP 625. O nome do arquivo deve estar no formato {name}-{version}.tar.gz, sendo {name} normalizado de acordo com as mesmas regras das distribuições binárias (veja Formato de distribuição binária) e {version} é a forma canonizada da versão do projeto (veja Especificadores de versão).

O nome e os componentes da versão do nome do arquivo DEVEM corresponder aos valores armazenados nos metadados contidos no arquivo.

Code that produces a source distribution file MUST give the file a name that matches this specification. This includes the build_sdist hook of a build backend.

Código que processa arquivos de distribuição fonte PODE reconhecer arquivos de distribuição fonte pelo sufixo .tar.gz e a presença de precisamente um hífen no nome do arquivo. O código que faz isso pode usar o nome e versão da distribuição a partir do nome do arquivo sem verificação adicional.

Formato de arquivo de distribuição fonte#

Uma distribuição fonte .tar.gz (sdist) contém um único diretório de nível superior chamado {name}-{version} (por exemplo, foo-1.0), contendo os arquivos fonte do pacote. O nome e a versão DEVEM corresponder aos metadados armazenados no arquivo. Este diretório também deve conter um pyproject.toml no formato definido em Declarando dependências do sistema de construção e um arquivo PKG-INFO contendo metadados no formato descrito na especificação Especificações de metadados principais. Os metadados DEVEM estar em conformidade com pelo menos a versão 2.2 da especificação de metadados.

Nenhum outro conteúdo de um sdist é necessário ou definido. Os sistemas de construção podem armazenar qualquer informação necessária no sdist para construir o projeto.

O tarball deve usar o formato tar pax POSIX.1-2001 moderno, que especifica nomes de arquivo baseados em UTF-8. Em particular, os arquivos de distribuição fonte devem ser legíveis usando o módulo tarfile de biblioteca padrão com o sinalizador aberto ‘r:gz’.

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 to their tool.

Histórico#

  • August 2023: Standardized the source distribution archive features (PEP 721)

  • September 2022: Standardized the filename of a source distribution (PEP 625)

  • July 2021: Defined what a source tree is

  • November 2020: PEP 643 converted to this specification

  • December 2000: Source distributions standardized in PEP 643