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.
O código que produz um arquivo de distribuição de origem DEVE dar ao arquivo um nome que corresponda a essa especificação. Isso inclui o gancho build_sdist de um backend de construção.
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’.