PEP 847：简单仓库API的问题详情
内容提要
本PEP提议为Python简单仓库API的错误响应制定统一格式，采用RFC 9457“HTTP API问题详情”标准。目前该API仅定义成功响应，错误响应无标准，安装器只能显示HTTP状态码，缺乏上下文。新方案要求索引以Problem Details对象返回错误，并附Content-Type头，客户端据此渲染更丰富的错误信息，且向后兼容，风险极低。
延伸解读
错误响应标准化的背景与动机
简单仓库API目前只定义了成功响应的格式，错误响应没有统一标准，导致安装器只能显示HTTP状态码和原因短语。而HTTP/2移除了原因短语，使得错误信息更加模糊。PyPI和第三方索引都受此影响，用户无法获得足够的上下文来理解错误原因或采取行动。因此，需要一种标准机制来传递错误详情。
RFC 9457作为解决方案的优势
PEP提议采用RFC 9457（HTTP API问题详情）作为错误响应的基线格式。该标准允许服务器返回结构化的Problem Details对象，包含type、status、title、detail等可选字段，客户端可以据此渲染更丰富的错误信息。选择RFC 9457还考虑了未来扩展性，因为Python打包生态可能继续标准化其他接口，而RFC 9457足够通用。
向后兼容性与低风险
由于Python打包生态从未规定错误响应格式，安装器客户端对任意响应都有弹性。PEP审查了pip、Poetry和uv等流行安装器，发现它们目前不解析错误响应体，因此旧版本客户端会优雅降级，不会因新格式而崩溃。标准化错误格式的向后兼容风险极低，用户只会看到更友好的错误消息。
实施要点与客户端处理
索引在返回错误响应时，应格式化为Problem Details对象，并发送Content-Type: application/problem+json头。客户端收到错误响应后，应检查Content-Type，若匹配则解析Problem Details，并逐步提取title、detail等字段来丰富错误信息；若解析失败或字段缺失，则回退到通用HTTP错误处理。这种渐进增强方式确保了兼容性和灵活性。
Q&A
PEP 847 提议为 Python 简单仓库 API 的错误响应制定什么标准？
PEP 847 提议采用 RFC 9457（HTTP API 问题详情）作为简单仓库 API 错误响应的统一基线格式，要求索引以 Problem Details 对象返回错误，并附带 Content-Type: application/problem+json 头。
为什么简单仓库 API 需要标准化的错误响应格式？
目前简单仓库 API 只定义了成功响应的表示（HTML 和 JSON），错误响应没有标准格式。安装器只能显示 HTTP 状态码和原因短语，而原因短语可能被代理截断或重写，HTTP/2 甚至移除了原因短语，导致用户只能看到如 401 这样的状态码，缺乏上下文。标准化错误格式能让安装器渲染更丰富、更有用的错误信息。
PEP 847 中，包索引在返回错误响应时应该怎么做？
包索引 SHOULD 将错误响应格式化为 RFC 9457 Problem Details 对象，并且 MUST 额外发送 Content-Type: application/problem+json 响应头。Problem Details 对象包含 type、status、title、detail、instance 等可选字段。
客户端收到简单仓库 API 的错误响应后应该如何处理？
客户端 SHOULD 检查 Content-Type 是否为 application/problem+json，如果是则解析 Problem Details 对象，并据此渲染更丰富的错误信息。如果解析失败或响应不是 Problem Details，客户端 MAY 回退到原有的通用 HTTP 错误处理逻辑。
采用 RFC 9457 作为错误格式的向后兼容性风险如何？
PEP 847 认为向后兼容风险非常低。因为 Python 打包生态从未为简单仓库 API 指定过特定的错误响应格式，安装器客户端对任意响应都具有弹性。对 pip、Poetry 和 uv 的审查表明，旧版本都能优雅降级或增强处理 Problem Details 响应，不会尝试解析或解释错误响应体。
PEP 847 为什么不选择保留现状或自定义错误格式？
保留现状被认为不合适，因为它不能帮助索引和客户端做出用户友好的错误消息决策，并且随着 HTTP/2 及以后版本的普及，错误报告的缺口会进一步扩大。自定义错误格式虽然可以提供特定错误码，但被认为不合适，因为 RFC 9457 已经足够通用且面向未来，且已有其他打包相关的 PEP 提议使用 RFC 9457。
