Gravando projetos instalados

Este documento especifica um formato comum de gravação de informações sobre projetos Python instalados em um ambiente. Um formato de metadados comum permite que as ferramentas consultem, gerenciem ou desinstalem projetos, independentemente de como foram instalados.

Quase todas as informações são opcionais. Isso permite que ferramentas fora do ecossistema Python, como gerenciadores de pacotes Linux, se integrem com as ferramentas Python tanto quanto possível. Por exemplo, mesmo se um instalador não puder fornecer facilmente uma lista de arquivos instalados em um formato específico para as ferramentas Python, ele ainda deve registrar o nome e a versão do projeto instalado.

Histórico e fluxo de trabalho de mudança

Os metadados descritos aqui foram especificados primeiro na PEP 376, e posteriormente alterados na PEP 627. Era conhecido anteriormente como Banco de dados de distribuições Python instaladas. Outras alterações (exceto correções triviais de linguagem ou tipografia) devem ser feitas através do processo de PEP (veja PEP 1).

Embora este documento seja a especificação normativa, essas PEPs que introduzem alterações nele podem incluir informações adicionais, como justificativas e considerações de compatibilidade com versões anteriores.

O diretório .dist-info

Cada projeto instalado de uma distribuição deve, além dos arquivos, instalar um diretório “.dist-info” localizado junto com os módulos e pacotes importáveis (comumente, o diretório site-packages).

Este diretório é nomeado como {name}-{version}.dist-info, com os campos name e version correspondendo a Especificações de metadados principais. Ambos os campos devem ser normalizados (consulte a PEP 503 e a PEP 440 para a definição de normalização para cada campo respectivamente) e substitua os caracteres de traço (-) por caracteres de sublinhado (_), então o diretório .dist-info sempre tem exatamente um caractere de traço (-) em seu radical, separando os campos name e version.

Historicamente, as ferramentas falharam em substituir caracteres de ponto ou normalizar maiúsculas e minúsculas no campo name, ou não realizar a normalização no campo version. Ferramentas que consomem diretórios .dist-info devem esperar que esses campos sejam desnormalizados e tratá-los como equivalentes a suas contrapartes normalizadas. Novas ferramentas que escrevem diretórios .dist-info DEVEM normalizar ambos os campos name e version usando as regras descritas acima, e as ferramentas existentes são encorajadas a começar a normalizar esses campos.

Nota

O nome do diretório .dist-info é formatado para representar inequivocamente uma distribuição como um caminho do sistema de arquivos. As ferramentas que apresentam um nome de distribuição a um usuário devem evitar o uso do nome normalizado e, em vez disso, apresentar o nome especificado (quando necessário antes da resolução de um pacote instalado) ou ler os respectivos campos nos metadados principais, uma vez que os valores listados não têm escape e são precisos refletem a distribuição. As bibliotecas devem fornecer API para o consumo dessas ferramentas, de forma que as ferramentas possam ter acesso ao nome não normalizado ao exibir informações de distribuição.

Este diretório .dist-info pode conter esses arquivos, descritos em detalhes abaixo:

• METADATA: contém metadados do projeto

• RECORD: registra a lista de arquivos instalados.

• INSTALLER: registra o nome da ferramenta usada para instalar o projeto.

O arquivo METADATA é obrigatório. Todos os outros arquivos podem ser omitidos a critério da ferramenta de instalação. Arquivos adicionais específicos do instalador podem estar presentes.

Nota

A especificação Formato de distribuição binária descreve arquivos adicionais que podem aparecer no diretório .dist-info de um Wheel. Esses arquivos podem ser copiados para o diretório .dist-info de um projeto instalado.

As versões anteriores desta especificação também especificavam um arquivo REQUESTED. Este arquivo agora é considerado uma extensão específica da ferramenta, mas pode ser padronizado novamente no futuro. Consulte PEP 376 para seu significado original.

O arquivo METADATA

O arquivo METADATA contém metadados conforme descrito na especificação Especificações de metadados principais, versão 1.1 ou superior.

O arquivo METADATA é obrigatório. Se não puder ser criado ou se os metadados principais necessários não estiverem disponíveis, os instaladores devem relatar um erro e falhar ao instalar o projeto.

O arquivo RECORD

O arquivo RECORD contém a lista de arquivos instalados. É um arquivo CSV contendo um registro (linha) por arquivo instalado.

O dialeto CSV deve ser legível com o reader padrão do módulo csv do Python:

• delimitador de campo: , (vírgula),

• caractere de aspas: " (aspas duplas),

• terminador de linha: \r\n ou \n.

Cada registro é composto de três elementos: o caminho do arquivo, o hash do conteúdo e seu tamanho.

O caminho pode ser absoluto ou relativo ao diretório que contém o diretório .dist-info (comumente, o diretório site-packages). No Windows, os diretórios podem ser separados por barras ou barras invertidas (/ ou \).

O hash é uma string vazia ou o nome de um algoritmo hash de hashlib.algorithms_guaranteed, seguido pelo caractere igual = e o resumo do conteúdo do arquivo, codificado com a codificação urlsafe-base64-nopad (base64.urlsafe_b64encode(digest) com = ao final removido).

O tamanho é a string vazia ou o tamanho do arquivo em bytes, como um inteiro de base 10.

Para qualquer arquivo, um ou ambos os campos de hash e tamanho podem ser deixados em branco. Normalmente, entradas para arquivos .pyc e o próprio arquivo RECORD têm hash e tamanho vazios. Para os demais arquivos, não é recomendável deixar as informações de fora, pois impede a verificação da integridade do projeto instalado.

Se o arquivo RECORD estiver presente, ele deve listar todos os arquivos instalados do projeto, exceto os arquivos .pyc correspondentes aos arquivos .py listados em RECORD, que são opcionais. Notavelmente, o conteúdo do diretório .dist-info (incluindo o próprio arquivo RECORD) deve ser listado. Os diretórios não devem ser listados.

Para desinstalar completamente um pacote, uma ferramenta precisa remover todos os arquivos listados em RECORD, todos os arquivos .pyc (de todos os níveis de otimização) correspondentes aos arquivos .py removidos e quaisquer diretórios esvaziados pela desinstalação.

Aqui está um trecho de exemplo de um possível arquivo RECORD:

/usr/bin/black,sha256=iFlOnL32lIa-RKk-MDihcbJ37wxmRbE4xk6eVYVTTeU,220
../../../bin/blackd,sha256=lCadt4mcU-B67O1gkQVh7-vsKgLpx6ny1le34Jz6UVo,221
__pycache__/black.cpython-38.pyc,,
__pycache__/blackd.cpython-38.pyc,,
black-19.10b0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
black-19.10b0.dist-info/LICENSE,sha256=nAQo8MO0d5hQz1vZbhGqqK_HLUqG1KNiI9erouWNbgA,1080
black-19.10b0.dist-info/METADATA,sha256=UN40nGoVVTSpvLrTBwNsXgZdZIwoKFSrrDDHP6B7-A0,58841
black-19.10b0.dist-info/RECORD,,
black.py,sha256=45IF72OgNfF8WpeNHnxV2QGfbCLubV5Xjl55cI65kYs,140161
blackd.py,sha256=JCxaK4hLkMRwVfZMj8FRpRRYC0172-juKqbN22bISLE,6672
blib2to3/__init__.py,sha256=9_8wL9Scv8_Cs8HJyJHGvx1vwXErsuvlsAqNZLcJQR0,8
blib2to3/__pycache__/__init__.cpython-38.pyc,,
blib2to3/__pycache__/pygram.cpython-38.pyc,sha256=zpXgX4FHDuoeIQKO_v0sRsB-RzQFsuoKoBYvraAdoJw,1512
blib2to3/__pycache__/pytree.cpython-38.pyc,sha256=LYLplXtG578ZjaFeoVuoX8rmxHn-BMAamCOsJMU1b9I,24910
blib2to3/pygram.py,sha256=mXpQPqHcamFwch0RkyJsb92Wd0kUP3TW7d-u9dWhCGY,2085
blib2to3/pytree.py,sha256=RWj3IL4U-Ljhkn4laN0C3p7IRdfvT3aIRjTV-x9hK1c,28530

Se o arquivo RECORD estiver faltando, as ferramentas que dependem de .dist-info não devem tentar desinstalar ou atualizar o pacote. (Isso não se aplica a ferramentas que dependem de outras fontes de informação, como gerenciadores de pacotes do sistema em distros Linux.)

O arquivo INSTALLER

Se presente, INSTALLER é um arquivo de texto de uma linha que nomeia a ferramenta usada para instalar o projeto. Se o instalador for executável a partir da linha de comando, INSTALLER deve conter o nome do comando. Caso contrário, deve conter uma string ASCII imprimível.

O arquivo pode ser encerrado com zero ou mais caracteres de espaço em branco ASCII.

Aqui estão exemplos de dois possíveis arquivos INSTALLER:

pip

MegaCorp Cloud Install-O-Matic

Este valor deve ser usado apenas para fins informativos. Por exemplo, se uma ferramenta é solicitada a desinstalar um projeto, mas não encontra o arquivo RECORD, pode sugerir que a ferramenta nomeada em INSTALLER pode ser capaz de fazer a desinstalação.

O arquivo direct_url.json

Este arquivo DEVE ser criado por instaladores ao instalar uma distribuição a partir de um requisito que especifica uma referência de URL direta (incluindo uma URL de VCS).

Este arquivo NÃO DEVE ser criado ao instalar uma distribuição de outro tipo de requisito (ou seja, nome mais especificador de versão).

Sua especificação detalhada está em Gravando a Origem da URL Direta de distribuições instaladas.