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.

At time of writing, it is not formally specified how to merge the parts of this data structure into a single URL that can be passed to tools. A common representation is the pip URL format (VCS Support), other examples are provided in the Version specifier specification.

Especificação#

A estrutura de dados da URL direta DEVE ser um dicionário serializável para JSON de acordo com RFC 8259.

It MUST contain at least two fields. The first one is url, with type string. Its content must be a valid URL according to the WHATWG URL Standard.

Depending on what url refers to, the second field MUST be one of vcs_info (if url is a VCS reference), archive_info (if url is a source archive or a wheel), or dir_info (if url is a local directory). These info fields have a (possibly empty) subdictionary as value, with the possible keys defined below.

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

The user:password section of the URL MAY however be composed of environment variables, matching the following regular expression:

\$\{[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 (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.

  • A requested_revision key (type string) MAY be present naming a branch/tag/ref/commit/revision/etc (in a format compatible with the VCS). This field MUST match the revision requested by the user and MUST NOT exist when the user did not select a specific revision.

  • Uma chave commit_id (tipo string) 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 como commit_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.

    Any hash algorithm available via hashlib (specifically any that can be passed to hashlib.new() and do not require additional parameters) can be used as a key for the hashes dictionary. At least one secure algorithm from hashlib.algorithms_guaranteed SHOULD always be included. At time of writing, sha256 specifically is recommended.

  • Uma chave descontinuada hash (tipo string) 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ã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.

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

https://git-scm.com/

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

https://www.mercurial-scm.org/

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://www.breezy-vcs.org/

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

https://subversion.apache.org/

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.

JSON Schema#

The following JSON Schema can be used to validate the contents of direct_url.json:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "Direct URL Data",
  "description": "Data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and wheels.",
  "definitions": {
    "URL": {
      "type": "string",
      "format": "uri"
    },
    "DirInfo": {
      "type": "object",
      "properties": {
        "editable": {
          "type": ["boolean", "null"]
        }
      }
    },
    "VCSInfo": {
      "type": "object",
      "properties": {
        "vcs": {
          "type": "string",
          "enum": [
            "git",
            "hg",
            "bzr",
            "svn"
          ]
        },
        "requested_revision": {
          "type": "string"
        },
        "commit_id": {
          "type": "string"
        },
        "resolved_revision": {
          "type": "string"
        }
      },
      "required": [
        "vcs",
        "commit_id"
      ]
    },
    "ArchiveInfo": {
      "type": "object",
      "properties": {
        "hash": {
          "type": "string",
          "pattern": "^\\w+=[a-f0-9]+$",
          "deprecated": true
        },
        "hashes": {
          "type": "object",
          "patternProperties": {
            "^[a-f0-9]+$": {
              "type": "string"
            }
          }
        }
      }
    }
  },
  "allOf": [
    {
      "type": "object",
      "properties": {
        "url": {
          "$ref": "#/definitions/URL"
        }
      },
      "required": [
        "url"
      ]
    },
    {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "dir_info": {
              "$ref": "#/definitions/DirInfo"
            }
          },
          "required": [
            "dir_info"
          ]
        },
        {
          "type": "object",
          "properties": {
            "vcs_info": {
              "$ref": "#/definitions/VCSInfo"
            }
          },
          "required": [
            "vcs_info"
          ]
        },
        {
          "type": "object",
          "properties": {
            "archive_info": {
              "$ref": "#/definitions/ArchiveInfo"
            }
          },
          "required": [
            "archive_info"
          ]
        }
      ]
    }
  ]
}

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

Histórico#

  • March 2020: This specification was approved through PEP 610, defining the direct_url.json metadata file.

  • January 2023: Added the archive_info.hashes key (discussion).