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. O layout deste arquivo foi originalmente especificado na PEP 610 e está formalmente documentado aqui.

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 um dicionário compatível com RFC 8259 e codificado em UTF-8.

Se presente, DEVE conter pelo menos dois campos. O primeiro é url, com tipo string. Dependendo de qual url se refere, o segundo campo DEVE ser um de vcs_info (se url é uma referência de VCS), archive_info (se url é um arquivo de código-fonte ou um wheel) ou dir_info (se url é um diretório local). Estes campos informacionais têm um subdicionário (possivelmente vazio) como valor, com as chaves possíveis definidas abaixo.

url DEVE ser podado a fim de retirar qualquer informação de autenticação sensível, por razões de segurança.

A seção usuário:senha da URL PODE, entretanto, ser composta de variáveis de ambiente, correspondendo à seguinte expressão regular:

\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?

Além disso, a seção usuário:senha da URL PODE ser uma string bem conhecida e não sensível à segurança. Um exemplo típico é git no caso de uma URL como ssh://git@gitlab.com/user/repo.

Quando a url faz referência a um repositório VCS, a chave vcs_info DEVE estar presente como um dicionário com as seguintes chaves:

  • Uma chave vcs (tipo string) DEVE estar presente, contendo o nome do VCS (ou seja, um de git, hg, bzr, svn). Outros VCS DEVERIAM ser registrados escrevendo uma PEP para alterar esta especificação. O valor url DEVE ser compatível com o VCS correspondente, para que um instalador possa entregá-lo sem transformação em um comando de checkout/download do VCS.

  • Uma chave required_revision (tipo string) PODE estar presente nomeando um branch/tag/ref/commit/revisão/etc (em um formato compatível com o VCS) para instalar.

  • Uma chave commit_id (tipo string) DEVE estar presente, contendo o número exato de commit/revisão que foi instalado. Se o VCS oferecer suporte a identificadores de revisão baseados em hash de commit, tal hash de commit DEVE ser usado como commit_id para referenciar a versão imutável do código-fonte que foi instalado.

Quando url se refere a um arquivo fonte ou wheel, a chave archive_info DEVE estar presente como um dicionário com a seguinte chave:

  • Uma chave hash (tipo string) DEVE estar presente, com o valor <algoritmo-hash>=<hash-esperada>. É RECOMENDADO que apenas hashes que são fornecidos incondicionalmente pela última versão do módulo hashlib da biblioteca padrão sejam usados para hashes de arquivo fonte. No momento da escrita, essa lista consistia em ‘md5’, ‘sha1’, ‘sha224’, ‘sha256’, ‘sha384’ e ‘sha512’.

Quando url se refere a um diretório local, a chave dir_info DEVE estar presente como um dicionário com a seguinte chave:

  • editable (tipo: boolean): true se a distribuição foi instalada em modo editável, false caso contrário. Se ausente, é usado o padrão false.

Quando url se refere a um diretório local, ele DEVE ter o esquema file e ser compatível com RFC 8089 Em particular, o componente do caminho deve ser absoluto. Links simbólicos DEVERIAM ser preservados ao tornar os caminhos relativos absolutos.

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.

Um campo subdirectory de nível superior PODE estar presente contendo um caminho de diretório, relativo à raiz do repositório VCS, arquivo fonte ou diretório local, para especificar onde pyproject.toml ou setup.py está localizado.

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.

VCS registrados

Esta seção lista os VCS registrados; expandidos, informações específicas do VCS sobre como usar vcs, required_revision e outros campos de vcs_info; e, em alguns casos, campos adicionais específicos de VCS. As ferramentas PODEM oferecer suporte a outros VCS, embora seja RECOMENDADO registrá-las escrevendo uma PEP para alterar esta especificação. O campo vcs DEVERIA ser o nome do comando (em letras minúsculas). Os campos adicionais que seriam necessários para oferecer suporte a esse VCS DEVERIAM ser prefixados com o nome do comando VCS.

Git

Site

Comando vcs

git

Campo vcs

git

Campo requested_revision

Um nome de tag, nome de branch, ref Git, hash de commit, hash de commit encurtado ou outra coisa relacionada a commit.

Campo commit_id

Um hash de confirmação (40 caracteres hexadecimais sha1).

Nota

Os instaladores podem usar os comandos git show-ref e git symbolic-ref para determinar se o required_revision corresponde a um ref Git. Por sua vez, um ref começando com refs/tags/ corresponde a uma tag, e um ref começando com refs/remotes/origin/ após a clonagem corresponde a um branch.

Mercurial

Site

Comando vcs

hg

Campo vcs

hg

Campo requested_revision

Um nome de tag, nome de branch, ID de changeset, ID de changeset abreviado.

Campo commit_id

Um ID de changeset (40 caracteres hexadecimais).

Bazaar

Site

Comando vcs

bzr

Campo vcs

bzr

Campo requested_revision

Um nome de tag, nome de branch, id de revisão.

Campo commit_id

Um id de revisão.

Subversion

Site

Comando vcs

svn

Campo vcs

svn

Campo requested_revision

requested_revision deve ser compatível com a opção --revision do svn checkout. No Subversion, branch ou tag é parte de url.

Campo commit_id

Visto que o Subversion não oferece suporte a identificadores globalmente únicos, este campo é o número da revisão do Subversion no repositório correspondente.

Exemplos

Exemplo de direct_url.json

Arquivo fonte:

{
    "url": "https://github.com/pypa/pip/archive/1.3.1.zip",
    "archive_info": {
        "hash": "sha256=2dc6b5a470a1bde68946f263f1af1515a2574a150a30d6ce02c6ff742fcc0db8"
    }
}

URL Git com tag e hash de commit:

{
    "url": "https://github.com/pypa/pip.git",
    "vcs_info": {
        "vcs": "git",
        "requested_revision": "1.3.1",
        "commit_id": "7921be1537eac1e97bc40179a57f0349c2aee67d"
    }
}

Diretório local:

{
    "url": "file:///home/user/project",
    "dir_info": {}
}

Diretório local instalado em modo editável:

{
    "url": "file:///home/user/project",
    "dir_info": {
        "editable": true
    }
}

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 "git+https://example.com/repo/app.git#egg=app&subdirectory=setup"

  • pip install ./app

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

  • pip install --editable "git+https://example.com/repo/app.git#egg=app&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/