Gravando a Origem da URL Direta de distribuições instaladas¶
This document specifies a direct_url.json
file in the
*.dist-info
directory of an installed distribution, to record the
Direct URL Origin of the distribution.
Conteúdo
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
(tipostring
) DEVE estar presente, contendo o nome do VCS (ou seja, um degit
,hg
,bzr
,svn
). Outros VCS DEVERIAM ser registrados escrevendo uma PEP para alterar esta especificação. O valorurl
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
(tipostring
) 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
(tipostring
) 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 comocommit_id
para referenciar a versão imutável do código-fonte que foi instalado.
When url
refers to a source archive or a wheel, the archive_info
key
MUST be present as a dictionary with the following keys:
A
hashes
key SHOULD be present as a dictionary mapping a hash name to a hex encoded digest of the file.Multiple hashes can be included, and it is up to the consumer to decide what to do with multiple hashes (it may validate all of them or a subset of them, or nothing at all).
These hash names SHOULD always be normalized to be lowercase.
Any hash algorithm available via
hashlib
(specifically any that can be passed tohashlib.new()
and do not require additional parameters) can be used as a key for the hashes dictionary. At least one secure algorithm fromhashlib.algorithms_guaranteed
SHOULD always be included. At time of writing,sha256
specifically is recommended.A deprecated
hash
key (typestring
) MAY be present for backwards compatibility purposes, with value<hash-algorithm>=<expected-hash>
.
Producers of the data structure SHOULD emit the hashes
key whether one or multiple
hashes are available. Producers SHOULD continue to emit the hash
key in contexts
where they did so before, so as to keep backwards compatibility for existing clients.
When both the hash
and hashes
keys are present, the hash represented in the
hash
key MUST also be present in the hashes
dictionary, so consumers can
consider the hashes
key only if it is present, and fall back to hash
otherwise.
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ãofalse
.
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
dosvn checkout
. No Subversion, branch ou tag é parte deurl
.
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": {
"hashes": {
"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 edir_info
estará presente com"editable": true
e nenhumvcs_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/
History¶
March 2020: the
direct_url.json
metadata file was originally specified in PEP 610 and is formally documented here.January 2023: Added the
archive_info.hashes
key (discussion).