pip 安装报告（Installation Report）：解析 `pip install --report` 的 JSON 输出规范与源码实现

pip 安装报告Installation Report解析pip install --report的 JSON 输出规范与源码实现【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pip本篇技术指南围绕 pip 的安装报告Installation Report功能展开深入讲解pip install --report选项生成的 JSON 报告的字段规范、典型用法、源码实现与测试验证。读者读完本指南后将能够熟练生成、解析并利用安装报告将其用于需求锁定工具、CI 构建审计、可复现安装验证等场景同时理解该格式的设计边界它不是锁文件格式pip 也不接受其作为安装输入。功能概述与设计定位pip 的install命令提供了--report选项用于生成一份详细的 JSON 报告描述 pip 实际安装了什么或在与--dry-run组合时描述将会安装什么。该功能自 pip 22.2 起引入versionadded 22.2并在 pip 23.0 中将报告格式的version字段定为1正式宣布该格式稳定versionchanged 23.0。在 docs/html/reference/installation-report.md 中官方明确划定了该功能的使用边界使用前应当理解--report可用于实现需求锁定类工具但该格式本身不是锁文件格式目前没有计划让 pip 接受安装报告作为install、download或wheel命令的输入虽然--report选项与格式是 pip 的受支持功能但它不是PyPA 互操作标准其演进由 pip 自身的流程而非 PyPA 标准化流程管理。这意味着安装报告适合作为安装过程的机器可读记录消费而不是作为可以回灌给 pip 的规格文件。生成安装报告命令行用法--report选项在 install.py 中定义其dest为json_report_file参数为文件路径pip install --report file requirements关键细节当file使用-时报告写入stdout此时官方建议搭配--quiet使用避免 pip 的日志输出混入 JSON 输出源码 help 文本亦如此说明。与--dry-run组合时报告描述将会安装的内容可用于**解析resolve**需求而不实际安装。与--ignore-installed组合时pip 会忽略已安装的包完整解析依赖树。写文件时使用 UTF-8 编码、indent2缩进、ensure_asciiFalse保证 JSON 可读且保留非 ASCII 字符见 install.py。官方示例命令pip install \ --ignore-installed --dry-run --quiet \ --report - \ pydantic1.9 githttps://github.com/pypa/packagingmain该命令在终端直接输出 JSON 报告其中包含 pydantic 及其依赖、以及通过 VCS 直接引用的 packaging 的安装信息。报告顶层结构Report Specification报告是一个 JSON 对象包含以下四个顶层属性属性类型说明versionstring固定为1。仅当引入向后不兼容变更如移除必填字段、改变字段语义或数据类型时才会变更此类变更会走 pip 常规流程弃用周期或功能开关。工具必须检查该字段以确认自己支持的版本。pip_versionstring生成报告的 pip 版本号。installarray一组InstallationReportItem表示将要安装的分发包。environmentobject生成报告时的环境描述各字段为字符串类型对应 PEP 508 环境标记如implementation_name、python_version、sys_platform等。在源码层面顶层结构由 installation_report.py 的InstallationReport.to_dict()组装version硬编码为1pip_version取自pip.__version__environment来自packaging.markers.default_environment()。需要注意的是源码注释指出目前解析器使用默认环境来评估环境标记因此报告中记录的就是默认环境未来可能会考虑--python-version、--platform等选项见源码中的 TODO 及 issue 11198 引用。安装项结构InstallationReportIteminstall数组中的每一项描述一个将要安装的分发包字段如下属性类型说明metadataobject分发的元数据按 PEP 566 的 JSON 兼容元数据转换规则转为 JSON 对象。is_directbooleantrue表示需求以直接 URL 引用提供或约束为直接引用包括 editable 需求false表示以名称 版本说明符提供。is_yankedbooleantrue表示该需求在索引中被 yanked但 pip 仍按 PEP 592 选中了它。download_infoobject将要下载安装的工件信息使用 direct URL 数据结构PEP 610。当is_direct为true时该字段与direct_url.json元数据一致否则表示从索引或--find-links获取的工件 URL。requestedbooleantrue表示需求由用户显式提供命令行参数或 requirements 文件false表示作为其他需求的依赖被安装。requested_extrasarray用户请求的 extras 列表。仅当requested为true时出现。这些字段在 installation_report.py 的_install_req_to_dict()中逐项生成可一一对应download_info调用ireq.download_info.to_dict_compat()DirectUrl.to_dict_compat()会生成包含旧版hash键的兼容字典见 direct_url.pyis_direct取自ireq.is_directis_yanked取自ireq.link.is_yanked无 link 时为Falserequested取自ireq.user_suppliedmetadata取自ireq.get_dist().metadata_dict即 PEP 566 编码requested_extras仅在user_supplied且存在 extras 时输出且经排序sorted(ireq.extras)。download_info 的三种形态依据工件来源download_info呈现三种结构索引 /--find-links来源wheel 或 sdist包含url与archive_info.hashessha256 等。当从 wheel 缓存安装且缓存条目由未记录 origin URL 的旧版 pip 填充时sdist 的download_info.archive_info.hashes可能缺失文档专门给出此 note。VCS 直接引用包含url仓库地址与vcs_infovcs、requested_revision、解析出的commit_id。本地/editable 路径包含urlfile://路径与dir_info如editable: true。完整示例输出解读官方文档给出了上文命令的输出示例元数据为简洁已做删节完整结构如下{ version: 1, pip_version: 22.2, install: [ { download_info: { url: https://files.pythonhosted.org/packages/.../pydantic-1.9.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl, archive_info: { hashes: { sha256: 18f3e912f9ad1bdec27fb06b8198a2ccc32f201e24174cec1b3424dda605a310 } } }, is_direct: false, is_yanked: false, requested: true, metadata: { name: pydantic, version: 1.9.1, requires_dist: [ typing-extensions (3.7.4.3), dataclasses (0.6) ; python_version \3.7\, python-dotenv (0.10.4) ; extra dotenv, email-validator (1.0.3) ; extra email ], requires_python: 3.6.1, provides_extra: [ dotenv, email ] } }, { download_info: { url: https://github.com/pypa/packaging, vcs_info: { vcs: git, requested_revision: main, commit_id: 4f42225e91a0be634625c09e84dd29ea82b85e27 } }, is_direct: true, is_yanked: false, requested: true, metadata: { name: packaging, version: 21.4.dev0, requires_dist: [ pyparsing (!3.0.5,2.0.2) ], requires_python: 3.7 } }, { download_info: { url: https://files.pythonhosted.org/packages/.../pyparsing-3.0.9-py3-none-any.whl, archive_info: { hashes: { sha256: 5026bae9a10eeaefb61dab2f09052b9f4307d44aee4eda64b309723d8d206bbc } } }, is_direct: false, requested: false, metadata: { name: pyparsing, version: 3.0.9, requires_dist: [ railroad-diagrams ; extra \diagrams\, jinja2 ; extra \diagrams\ ], requires_python: 3.6.8 } }, { download_info: { url: https://files.pythonhosted.org/packages/.../typing_extensions-4.2.0-py3-none-any.whl, archive_info: { hashes: { sha256: 6657594ee297170d19f67d55c05852a874e7eb634f4f753dbd667855e07c1708 } } }, is_direct: false, requested: false, metadata: { name: typing_extensions, version: 4.2.0, requires_python: 3.7 } } ], environment: { implementation_name: cpython, implementation_version: 3.10.5, os_name: posix, platform_machine: x86_64, platform_release: 5.13-generic, platform_system: Linux, platform_version: ..., python_full_version: 3.10.5, platform_python_implementation: CPython, python_version: 3.10, sys_platform: linux } }示例要点pydantic用户显式请求requested: true和pyparsing、typing_extensions作为依赖安装requested: false且无requested_extras字段形成顶层需求 vs 传递依赖的对比packaging通过git直接 URL 提供因此is_direct: truedownload_info采用vcs_info结构并包含实际解析的commit_idenvironment的字段名与 PEP 508 环境标记一一对应。源码实现报告生成的调用链报告的生成发生在InstallCommand.run()中核心调用链如下resolver.resolve(reqs, ...)完成依赖解析得到requirement_set若设置了--report则用InstallationReport(requirement_set.requirements_to_install)构造报告对象见 install.pyrequirements_to_install返回所有需要安装的需求过滤掉约束项与已满足项见 req_set.py输出到 stdout-时调用print_json或写入文件json.dumpUTF-8、indent2、ensure_asciiFalse若同时启用了--dry-run随后还会以Would install ...的形式打印人类可读的安装清单见 install.py。值得注意的联动行为源码在 install.py 中显示当使用--dry-run --report组合时pip 会跳过PEP 668 外部管理环境EXTERNALLY-MANAGED检查——这是专门为只解析、不落地安装的便利场景做的豁免。测试验证报告字段在真实场景中的行为仓库的 tests/functional/test_install_report.py 覆盖了报告格式的多类场景可作为理解字段语义的权威佐证基础报告test_install_report_basic--dry-run --no-index --find-links安装simplewheel断言requested: true、is_direct: false、download_info.url为file://开头、archive_info.hash为sha256...格式依赖标记test_install_report_dep顶层需求require_simple的requested为true其依赖simple的requested为falseYank 语义test_yanked_version/test_skipped_yanked_version显式锁定到 yanked 版本simple3.0时is_yanked: true未锁定版本时 pip 自动避开 yanked 版本is_yanked: false——与 PEP 592 的行为一致索引 sdist extrastest_install_report_index从索引安装 sdist 时download_info.url指向files.pythonhosted.org的.tar.gz且requested_extras为[openid]多个 extras 会合并排序test_install_report_index_multiple_extras直接 URL 工件test_install_report_direct_archive直接指定本地 wheel 路径时is_direct: true且archive_info同时包含旧版hash与新版hashes两个键to_dict_compat的兼容行为VCS 与 wheel 缓存test_install_report_vcs_and_wheel_cachegit 引用的报告包含vcs_info.vcs、vcs_info.commit_id即便第二次命中 wheel 缓存stdout 出现Using cached报告仍保留原始 VCS URL 与 commit_ideditable 安装test_install_report_vcs_editableeditable 的 git 引用is_direct: truedownload_info.url为本地file://.../src/...路径且dir_info.editable为true本地路径 extrastest_install_report_local_path_with_extras本地目录项目pkga[test]的requested_extras为[test]依赖simple不包含requested_extras键输出到 stdouttest_install_report_to_stdout--report -与--quiet组合时stdout 可直接json.loads解析。典型使用场景与最佳实践结合官方定位与源码行为安装报告的典型用途包括需求锁定工具的数据源用--dry-run --ignore-installed --report解析依赖树从download_info中提取每个工件的 URL 与 sha256 哈希构建可复现的安装清单。注意报告格式本身不是锁文件格式锁定工具应将其转换为自己定义的锁格式。CI 构建审计在安装流水线中加入--report report.json将报告归档事后可精确回答这次构建装了什么、从哪下载、哈希是什么。可复现性验证比较两次构建的报告version、pip_version、各工件的download_info.url与哈希、environment快速定位环境漂移或依赖漂移。extras 追踪借助requested_extras记录顶层需求实际启用的可选依赖组。实操建议工具消费报告时务必先检查version字段当前为1以应对未来向后不兼容变更若将报告输出到 stdout请与--quiet组合使用并用--report -的约定便于管道化处理。【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考