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.

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 the name normalization specification and the version normalization specification), 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

The .dist-info directory’s name is formatted to unambiguously represent a distribution as a filesystem path. Tools presenting a distribution name to a user should avoid using the normalized name, and instead present the specified name (when needed prior to resolution to an installed package), or read the respective fields in Core Metadata, since values listed there are unescaped and accurately reflect the distribution. Libraries should provide API for such tools to consume, so tools can have access to the unnormalized name when displaying distribution information.

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 \).

The hash is either an empty string or the name of a hash algorithm from hashlib.algorithms_guaranteed, followed by the equals character = and the digest of the file’s contents, encoded with the urlsafe-base64-nopad encoding (base64.urlsafe_b64encode(digest) with trailing = removed).

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.)

Nota

It is strongly discouraged for an installed package to modify itself (e.g., store cache files under its namespace in site-packages). Changes inside site-packages should be left to specialized installer tools such as pip. If a package is nevertheless modified in this way, then the RECORD must be updated, otherwise uninstalling the package will leave unlisted files in place (possibly resulting in a zombie namespace package).

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 entry_points.txt#

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.

Prevenindo intencionalmente modificações nos pacotes instalados#

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 following 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

Histórico#

  • June 2009: The original version of this specification was approved through PEP 376. At the time, it was known as the Database of Installed Python Distributions.

  • March 2020: The specification of the direct_url.json file was approved through PEP 610. It is only mentioned on this page; see Gravando a Origem da URL Direta de distribuições instaladas for the full definition.

  • September 2020: Various amendments and clarifications were approved through PEP 627.