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
).
This directory is named as {name}-{version}.dist-info
, with name
and
version
fields corresponding to Especificações de metadados principais. Both fields must be
normalized (see Package name normalization and
PEP 440 for the definition of normalization for
each field respectively), and replace dash (-
) characters with
underscore (_
) characters, so the .dist-info
directory always has
exactly one dash (-
) character in its stem, separating the name
and
version
fields.
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 projetoRECORD
: 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.