Estrutura de dados de URL direta¶
Este documento especifica uma estrutura de dados abstrata serializável em JSON que pode representar URLs para projetos python e artefatos de distribuição, como árvores de fonte VCS, árvores de fonte local, distribuições fonte e wheels.
A representação dos componentes desta estrutura de dados como uma URL RFC 1738 não é especificada formalmente no momento da escrita. Uma representação comum é o formato de URL pip. Outros exemplos são fornecidos em PEP 440.
Conteúdo
Especificação¶
A estrutura de dados da URL direta DEVE ser um dicionário serializável para JSON de acordo com RFC 8259.
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 pacote 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.
Quando persistido, url
DEVE ser podado a fim de retirar qualquer informação sensível de autenticação, 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
.
URLs de VCS¶
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).Uma chave
commit_id
(tipostring
) DEVE estar presente, contendo o número exato de commit/revisão que foi/será 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.
URLs de arquivos¶
Quando url
se refere a um arquivo fonte ou wheel, a chave archive_info
DEVE estar presente como um dicionário com as seguintes chaves:
Uma chave
hashes
DEVE estar presente como um dicionário mapeando um nome de hash para um resumo de arquivo codificado em hex.Vários hashes podem ser incluídos e cabe ao consumidor decidir o que fazer com vários hashes (pode validar todos eles ou um subconjunto deles, ou nada).
Esses nomes de hash DEVEM sempre ser normalizados para letras minúsculas.
Qualquer algoritmo de hash disponível via
hashlib
(especificamente qualquer um que possa ser passado parahashlib.new()
e não requeira parâmetros adicionais) pode ser usado como uma chave para o dicionário de hashes. Pelo menos um algoritmo seguro dehashlib.algorithms_guaranteed
DEVE sempre ser incluído. No momento da escrita,sha256
especificamente é recomendado.Uma chave descontinuada
hash
(tipostring
) PODE estar presente para fins de compatibilidade com versões anteriores, com valor<hash-algorithm>=<expected-hash>
.
Os produtores da estrutura de dados DEVEM emitir a chave hashes
se um ou vários hashes estiverem disponíveis. Os produtores DEVEM continuar a emitir a chave hash
em contextos onde o faziam antes, de modo a manter a compatibilidade com versões anteriores para clientes existentes.
Quando as chaves hash
e hashes
estão presentes, o hash representado na chave hash
DEVE também estar presente no dicionário hashes
, para que os consumidores possam considerar a chave hashes
apenas se estiver presente, e voltar para hash
caso contrário.
Diretórios locais¶
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/será 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.
Projetos em subdiretórios¶
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.
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
As ferramentas 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
https://bazaar.canonical.com (Não responde desde 5/2023)
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¶
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 em modo editável:
{
"url": "file:///home/user/project",
"dir_info": {
"editable": true
}
}