Gravando a Origem da URL Direta de distribuições instaladas#

Este documento especifica um arquivo direct_url.json no diretório *.dist-info de uma distribuição instalada, para registrar a origem da URL direta da distribuição. A estrutura geral e uso de diretórios *.dist-info é descrita em Gravando projetos instalados.

Especificação#

O arquivo direct_url.json DEVE ser criado no diretório *.dist-info pelos instaladores ao instalar uma distribuição a partir de um requisito especificando 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).

Este arquivo JSON DEVE ser codificado em UTF-8, compatível com RFC 8259, serialização da Estrutura de dados de URL direta.

Nota

Quando a URL solicitada tem o esquema file:// e aponta para um diretório local que contém um checkout VCS, os instaladores NÃO DEVEM tentar inferir nenhuma informação VCS e, portanto, NÃO DEVEM emitir nenhuma informação relacionada ao VCS (como vcs_info) in direct_url.json.

Nota

Como regra geral, os instaladores devem, tanto quanto possível, preservar as informações fornecidas na URL solicitada ao gerar direct_url.json. Por exemplo, as variáveis de ambiente usuário:senha devem ser preservadas e required_revision deve refletir a revisão que foi fornecida na URL solicitada o mais fielmente possível. No entanto, essas informações são enriquecidas com dados mais precisos, como commit_id.

Exemplo de comandos pip e seus efeitos em direct_url.json#

Comandos que geram um direct_url.json:

  • pip install https://example.com/app-1.0.tgz

  • pip install https://example.com/app-1.0.whl

  • pip install "app @ git+https://example.com/repo/app.git#subdirectory=setup"

  • pip install ./app

  • pip install file:///home/user/app

  • pip install --editable "app @ git+https://example.com/repo/app.git#subdirectory=setup" (caso em que, url será o diretório local para o qual o repositório git foi clonado e dir_info estará presente com "editable": true e nenhum vcs_info será definido)

  • pip install -e ./app

Comandos que não geram um direct_url.json

  • pip install app

  • pip install app --no-index --find-links https://example.com/

Histórico#

  • Março de 2020: o arquivo de metadados direct_url.json foi originalmente especificado na PEP 610 e está formalmente documentado aqui.