进阶 docs.pypi.org 2026-10-20 06:39:13 · 34 阅读

第26章 PyPI JSON API 详解

JSON API

提示 本页介绍的是 PyPI 特有的 JSON API。 如果你只需要 JSON 索引 API(例如获取某个包的所有发行文件或所有版本),可以使用 Index API。

路由 获取项目信息 路由:GET /pypi//json 返回某个项目最新版本的元数据(info)、该项目的所有版本列表以及项目 URL。版本信息包括版本名称、URL 以及 MD5、SHA256 和 BLAKE2b-256 哈希摘要,并以版本字符串作为键。返回的元数据来自上传时提供的值,不一定与上传文件的内容一致。每个版本只保留首次上传的数据,后续上传不会更新它。 每个文件对象还包含一个 core-metadata 键,描述随发行文件一同提供的 Core Metadata(参见 PEP 658 和 PEP 714)。当没有元数据文件时,其值为 false;有元数据文件时,则为哈希摘要对象(如 {"sha256": "..."})。这与 Index API 已暴露的 core-metadata 键保持一致,使镜像站无需额外请求即可发现并提供 Core Metadata。 在此端点上,vulnerabilities 数组列出了最新版本中所有已知漏洞(上面示例中没有)。如需精确控制该字段,请使用下文介绍的项目版本专用端点。

已弃用的键 以下键已被视为弃用:

releases:项目应尽量改用 Index API 获取这些信息。 downloads:此键始终为 -1,不应使用。 has_sig:此键始终为 false,不应使用。 bugtrack_url:此键始终为 null,不应使用。

将来这些键可能会从 API 响应中完全移除。

状态码:

200 OK - 无错误

请求示例: GET /pypi/sampleproject/json HTTP/1.1 Host: pypi.org Accept: application/json

JSON 响应示例 HTTP/1.1 200 OK Content-Type: application/json; charset="UTF-8"

{ "info": { "author": "", "author_email": "\"A. Random Developer\" ", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.9", "Topic :: Software Development :: Build Tools" ], "description": "...", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "dynamic": [ "requires_dist" ], "home_page": "", "keywords": "sample, setuptools, development", "license": "...", "license_expression": null, "license_files": null, "maintainer": "", "maintainer_email": "\"A. Great Maintainer\" ", "name": "sampleproject", "package_url": "https://pypi.org/project/sampleproject/", "platform": null, "project_url": "https://pypi.org/project/sampleproject/", "project_urls": { "Bug Reports": "https://github.com/pypa/sampleproject/issues", "Funding": "https://donate.pypi.org", "Homepage": "https://github.com/pypa/sampleproject", "Say Thanks!": "http://saythanks.io/to/example", "Source": "https://github.com/pypa/sampleproject/" }, "provides_extra": [ "dev", "test" ], "release_url": "https://pypi.org/project/sampleproject/4.0.0/", "requires_dist": [ "peppercorn", "check-manifest ; extra == 'dev'", "coverage ; extra == 'test'" ], "requires_python": ">=3.9", "summary": "A sample Python project", "version": "4.0.0", "yanked": false, "yanked_reason": null }, "last_serial": 25862117, "releases": { "1.0": [], "1.2.0": [ { "comment_text": "", "core-metadata": false, "digests": { "blake2b_256": "3052547eb3719d0e872bdd6fe3ab60cef92596f95262e925e1943f68f840df88", "md5": "bab8eb22e6710eddae3c6c7ac3453bd9", "sha256": "7a7a8b91086deccc54cac8d631e33f6a0e232ce5775c6be3dc44f86c2154019d" }, "downloads": -1, "filename": "sampleproject-1.2.0-py2.py3-none-any.whl", "has_sig": false, "md5_digest": "bab8eb22e6710eddae3c6c7ac3453bd9", "packagetype": "bdist_wheel", "python_version": "2.7", "requires_python": null, "size": 3795, "upload_time": "2015-06-14T14:38:05", "upload_time_iso_8601": "2015-06-14T14:38:05.875222Z", "url": "https://files.pythonhosted.org/packages/30/52/547eb3719d0e872bdd6fe3ab60cef92596f95262e925e1943f68f840df88/sampleproject-1.2.0-py2.py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "core-metadata": false, "digests": { "blake2b_256": "eb4579be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1", "md5": "d3bd605f932b3fb6e91f49be2d6f9479", "sha256": "3427a8a5dd0c1e176da48a44efb410875b3973bd9843403a0997e4187c408dc1" }, "downloads": -1, "filename": "sampleproject-1.2.0.tar.gz", "has_sig": false, "md5_digest": "d3bd605f932b3fb6e91f49be2d6f9479", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 3148, "upload_time": "2015-06-14T14:37:56", "upload_time_iso_8601": "2015-06-14T14:37:56.383366Z", "url": "https://files.pythonhosted.org/packages/eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/sampleproject-1.2.0.tar.gz", "yanked": false, "yanked_reason": null } ], "1.3.0": [ "..." ], "1.3.1": [ "..." ], "2.0.0": [ "..." ], "3.0.0": [ "..." ], "4.0.0": [ { "comment_text": "", "core-metadata": { "sha256": "a1d0c6e83f027327d8461063f4ac58a6e4a7a5d0a0e0d5b6c3b2e1f0a9b8c7d6" }, "digests": { "blake2b_256": "d773c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a", "md5": "d3857a217dacbca9e40a85f06f2b34f1", "sha256": "c23e447ea90d796d1e645c35c4b2de125040add12a845825546f91c93f391b6b" }, "downloads": -1, "filename": "sampleproject-4.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "d3857a217dacbca9e40a85f06f2b34f1", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.9", "size": 4661, "upload_time": "2024-11-06T22:37:09", "upload_time_iso_8601": "2024-11-06T22:37:09.220617Z", "url": "https://files.pythonhosted.org/packages/d7/73/c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a/sampleproject-4.0.0-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "core-metadata": { "sha256": "b2e1d7f94a138438e9572174a5bd69b7f5b8b6e1b1f1e6c7d4c3f2a1b0c9d8e7" }, "digests": { "blake2b_256": "488cc18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab", "md5": "9eab89661feaaf3b05b60fb1ed1f7171", "sha256": "0ace7980f82c5815ede4cd7bf9f6693684cec2ae47b9b7ade9add533b8627c6b" }, "downloads": -1, "filename": "sampleproject-4.0.0.tar.gz", "has_sig": false, "md5_digest": "9eab89661feaaf3b05b60fb1ed1f7171", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.9", "size": 5760, "upload_time": "2024-11-06T22:37:10", "upload_time_iso_8601": "2024-11-06T22:37:10.868088Z", "url": "https://files.pythonhosted.org/packages/48/8c/c18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab/sampleproject-4.0.0.tar.gz", "yanked": false, "yanked_reason": null } ] }, "urls": [ { "comment_text": "", "core-metadata": { "sha256": "a1d0c6e83f027327d8461063f4ac58a6e4a7a5d0a0e0d5b6c3b2e1f0a9b8c7d6" }, "digests": { "blake2b_256": "d773c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a", "md5": "d3857a217dacbca9e40a85f06f2b34f1", "sha256": "c23e447ea90d796d1e645c35c4b2de125040add12a845825546f91c93f391b6b" }, "downloads": -1, "filename": "sampleproject-4.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "d3857a217dacbca9e40a85f06f2b34f1", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.9", "size": 4661, "upload_time": "2024-11-06T22:37:09", "upload_time_iso_8601": "2024-11-06T22:37:09.220617Z", "url": "https://files.pythonhosted.org/packages/d7/73/c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a/sampleproject-4.0.0-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "core-metadata": { "sha256": "b2e1d7f94a138438e9572174a5bd69b7f5b8b6e1b1f1e6c7d4c3f2a1b0c9d8e7" }, "digests": { "blake2b_256": "488cc18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab", "md5": "9eab89661feaaf3b05b60fb1ed1f7171", "sha256": "0ace7980f82c5815ede4cd7bf9f6693684cec2ae47b9b7ade9add533b8627c6b" }, "downloads": -1, "filename": "sampleproject-4.0.0.tar.gz", "has_sig": false, "md5_digest": "9eab89661feaaf3b05b60fb1ed1f7171", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.9", "size": 5760, "upload_time": "2024-11-06T22:37:10", "upload_time_iso_8601": "2024-11-06T22:37:10.868088Z", "url": "https://files.pythonhosted.org/packages/48/8c/c18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab/sampleproject-4.0.0.tar.gz", "yanked": false, "yanked_reason": null } ], "vulnerabilities": [], "ownership": { "roles": [ {"role": "Owner", "user": "theacodes"}, {"role": "Maintainer", "user": "pypa-bot"} ], "organization": "pypa" } }

获取版本信息 路由:GET /pypi///json 返回某个项目特定版本的元数据,与 /pypi//json 相同,只是不包含 releases 键。

提示 此响应以前包含 releases 键,列出了该项目在 PyPI 上所有版本的所有文件 URL。出于稳定性考虑,该键已从版本专用页面中移除,现在此端点只返回与该版本相关的数据。 如需访问所有文件,建议使用 Index API,或者使用项目级的 JSON API(/pypi//json)。

已弃用的键 以下键已被视为弃用:

downloads:此键始终为 -1,不应使用。 has_sig:此键始终为 false,不应使用。 bugtrack_url:此键始终为 null,不应使用。

将来这些键可能会从 API 响应中完全移除。

状态码:

200 OK - 无错误

请求示例: GET /pypi/sampleproject/4.0.0/json HTTP/1.1 Host: pypi.org Accept: application/json

JSON 响应示例 HTTP/1.1 200 OK Content-Type: application/json; charset="UTF-8"

{ "info": { "author": "", "author_email": "\"A. Random Developer\" ", "bugtrack_url": null, "classifiers": [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.9", "Topic :: Software Development :: Build Tools" ], "description": "...", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "dynamic": [ "requires_dist" ], "home_page": "", "keywords": "sample, setuptools, development", "license": "... ", "license_expression": null, "license_files": null, "maintainer": "", "maintainer_email": "\"A. Great Maintainer\" ", "name": "sampleproject", "package_url": "https://pypi.org/project/sampleproject/", "platform": null, "project_url": "https://pypi.org/project/sampleproject/", "project_urls": { "Bug Reports": "https://github.com/pypa/sampleproject/issues", "Funding": "https://donate.pypi.org", "Homepage": "https://github.com/pypa/sampleproject", "Say Thanks!": "http://saythanks.io/to/example", "Source": "https://github.com/pypa/sampleproject/" }, "provides_extra": [ "dev", "test" ], "release_url": "https://pypi.org/project/sampleproject/4.0.0/", "requires_dist": [ "peppercorn", "check-manifest ; extra == 'dev'", "coverage ; extra == 'test'" ], "requires_python": ">=3.9", "summary": "A sample Python project", "version": "4.0.0", "yanked": false, "yanked_reason": null }, "last_serial": 25862117, "urls": [ { "comment_text": "", "core-metadata": { "sha256": "a1d0c6e83f027327d8461063f4ac58a6e4a7a5d0a0e0d5b6c3b2e1f0a9b8c7d6" }, "digests": { "blake2b_256": "d773c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a", "md5": "d3857a217dacbca9e40a85f06f2b34f1", "sha256": "c23e447ea90d796d1e645c35c4b2de125040add12a845825546f91c93f391b6b" }, "downloads": -1, "filename": "sampleproject-4.0.0-py3-none-any.whl", "has_sig": false, "md5_digest": "d3857a217dacbca9e40a85f06f2b34f1", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=3.9", "size": 4661, "upload_time": "2024-11-06T22:37:09", "upload_time_iso_8601": "2024-11-06T22:37:09.220617Z", "url": "https://files.pythonhosted.org/packages/d7/73/c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a/sampleproject-4.0.0-py3-none-any.whl", "yanked": false, "yanked_reason": null }, { "comment_text": "", "core-metadata": { "sha256": "b2e1d7f94a138438e9572174a5bd69b7f5b8b6e1b1f1e6c7d4c3f2a1b0c9d8e7" }, "digests": { "blake2b_256": "488cc18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab", "md5": "9eab89661feaaf3b05b60fb1ed1f7171", "sha256": "0ace7980f82c5815ede4cd7bf9f6693684cec2ae47b9b7ade9add533b8627c6b" }, "downloads": -1, "filename": "sampleproject-4.0.0.tar.gz", "has_sig": false, "md5_digest": "9eab89661feaaf3b05b60fb1ed1f7171", "packagetype": "sdist", "python_version": "source", "requires_python": ">=3.9", "size": 5760, "upload_time": "2024-11-06T22:37:10", "upload_time_iso_8601": "2024-11-06T22:37:10.868088Z", "url": "https://files.pythonhosted.org/packages/48/8c/c18d25735962870ccb6d1cd2ac7bde40008a332211055e260cb7ec4c6bab/sampleproject-4.0.0.tar.gz", "yanked": false, "yanked_reason": null } ], "vulnerabilities": [], "ownership": { "roles": [ {"role": "Owner", "user": "theacodes"}, {"role": "Maintainer", "user": "pypa-bot"} ], "organization": "pypa" } }

归属信息 ownership 键提供项目的角色和组织归属信息,包含两个字段:

roles:一组 {"role": "", "user": ""} 对象,表示项目的所有者和维护者。角色按 Owner 在前、Maintainer 在后排序,同一角色内按用户名字母顺序排列。项目没有分配任何角色时,此列表为空。 organization:拥有该项目的组织的 URL slug(如 "pypa"),项目不属于任何组织时为 null。

已知漏洞 在上面的示例中,请求的项目和版本组合没有已知漏洞。 下面是一个存在已知漏洞的项目的响应示例,为便于阅读省略了无关字段。 HTTP/1.1 200 OK Content-Type: application/json; charset="UTF-8"

{ "info": {}, "last_serial": 12089094, "releases": {}, "urls": [], "vulnerabilities": [ { "aliases": [ "CVE-2021-3281" ], "details": "In Django 2.2 before 2.2.18, 3.0 before 3.0.12, and 3.1 before 3.1.6, the django.utils.archive.extract method (used by \"startapp --template\" and \"startproject --template\") allows directory traversal via an archive with absolute paths or relative paths with dot segments.", "summary": "A shorter summary of the vulnerability", "fixed_in": [ "2.2.18", "3.0.12", "3.1.6" ], "id": "PYSEC-2021-9", "link": "https://osv.dev/vulnerability/PYSEC-2021-9", "source": "osv", "withdrawn": null }, ] }

withdrawn 字段尤其值得关注:当它不为 null 时,表示上游漏洞报告来源撤回该漏洞的 RFC 3339 时间戳。API 使用方可以借助该字段撤回后来被认定为无效的漏洞报告。例如,一个已撤回的漏洞可能如下所示: { "aliases": [ "CVE-2022-XXXXX" ], "details": "A long description.", "summary": "A shorter summary.", "fixed_in": [ "1.2.3" ], "id": "PYSEC-2022-XXX", "link": "https://osv.dev/vulnerability/PYSEC-2022-XXX", "source": "osv", "withdrawn": "2022-06-28T16:39:06Z" }

评论 (0)