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

The metadata described here was first specified in PEP 376, and later amended in PEP 627 (and other PEPs). It was formerly known as Database of Installed Python Distributions. As with other PyPA specifications, editorial amendments with no functional impact may be made through the GitHub pull request workflow. Proposals for functional changes that would require amendments to package building and/or installation tools must be made through the PEP process (see PEP 1).

While this document is the normative specification, the PEPs that introduce changes to it may include additional information such as rationales and backwards compatibility considerations.

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 Normalização de nome de pacote 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.

This .dist-info directory may contain the following files, described in detail below:

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

If the RECORD file is missing, tools that rely on .dist-info must not attempt to uninstall or upgrade the package. (This restriction does not apply to tools that rely on other sources of information, such as system package managers in Linux distros.)

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.

The entry_points.txt file

This file MAY be created by installers to indicate when packages contain components intended for discovery and use by other code, including console scripts and other applications that the installer has made available for execution.

Its detailed specification is at Especificação de pontos de entrada.

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.

Intentionally preventing changes to installed packages

In some cases (such as when needing to manage external dependencies in addition to Python ecosystem dependencies), it is desirable for a tool that installs packages into a Python environment to ensure that other tools are not used to uninstall or otherwise modify that installed package, as doing so may cause compatibility problems with the wider environment.

To achieve this, affected tools should take the folllowing steps:

  • Rename or remove the RECORD file to prevent changes via other tools (e.g. appending a suffix to create a non-standard RECORD.tool file if the tool itself needs the information, or omitting the file entirely if the package contents are tracked and managed via other means)

  • Write an INSTALLER file indicating the name of the tool that should be used to manage the package (this allows RECORD-aware tools to provide better error notices when asked to modify affected packages)

Python runtime providers may also prevent inadvertent modification of platform provided packages by modifying the default Python package installation scheme to use a location other than that used by platform provided packages (while also ensuring both locations appear on the default Python import path).

In some circumstances, it may be desirable to block even installation of additional packages via Python-specific tools. For these cases refer to Ambiente gerenciado externamente