直接 URL 数据结构¶

Direct URL Data Structure

中文

本文档指定了一种可 JSON 序列化的抽象数据结构，用于表示指向 Python 项目和分发工件的 URL，例如 VCS 源树、本地源树、源分发和轮子文件。

在撰写时，尚未正式指定如何将该数据结构的各部分合并为一个可以传递给工具的单一 URL。一种常见的表示方式是 pip URL 格式（ VCS 支持），其他示例见版本说明符规范。

英文

This document specifies a JSON-serializable abstract data structure that can represent URLs to python projects and distribution artifacts such as VCS source trees, local source trees, source distributions and 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.

JSON 架构¶

JSON Schema

中文

以下 JSON Schema 可用于验证 direct_url.json 的内容：

英文

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

示例¶

Examples

中文

源档案:

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

带有标签和提交哈希的 Git URL:

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

本地目录:

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

可编辑模式下的本地目录:

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

英文

Source archive:

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

Git URL with tag and commit-hash:

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

Local directory:

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

Local directory in editable mode:

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

历史¶

History

中文

2020年3月：该规范通过 PEP 610 获得批准，定义了 direct_url.json 元数据文件。
2023年1月：添加了 archive_info.hashes 键（讨论）。

英文

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).

直接 URL 数据结构¶

规范¶

安全注意事项¶

VCS URL¶

存档 URL¶

本地目录¶

子目录中的项目¶

已注册的 VCS¶

Git¶

Mercurial¶

Bazaar¶

Subversion¶

JSON 架构¶

示例¶

历史¶