文章导读

解决Twine上传PyPI时reStructuredText描述渲染失败的问题

作者 2025年8月26日 14

python开发者在发布包到PyPI时，常使用twine工具。尽管本地build过程顺利，但在执行twine upload时却可能遭遇HTTPError: 400 Bad Request，并伴随“The description failed to render for ‘text/x-rst’”的错误信息。这通常表明包的long_description内容（通常是README.rst文件）在PyPI的RST解析器中存在渲染问题。

问题现象与诊断

当twine upload失败并返回httperror: 400 bad request时，错误信息会明确指出“the description failed to render for ‘text/x-rst’”。这提示我们问题出在long_description字段的内容上，即pypi无法正确解析其rst格式。

例如，在尝试上传包时，可能会看到以下输出：

H:gitgraphab4py>twine upload dist/* Uploading distributions to https://upload.pypi.org/legacy/ Uploading graphab4py-1.0.4-py3-none-any.whl 100% ---------------------------------------- 29.3/29.3 kB • 00:00 • 271.1 kB/s WARNING  Error during upload. Retry with the --verbose option for more details. ERROR    HTTPError: 400 Bad Request from https://upload.pypi.org/legacy/          The description failed to render for 'text/x-rst'. See https://pypi.org/help/#description-content-type for          more information.

使用twine upload dist/* –verbose命令可以获取更详细的错误响应，其中可能包含html格式的错误页面，进一步确认渲染失败的原因。

H:gitgraphab4py>twine upload dist/* --verbose INFO     Using configuration from C:Userspoppman.pypirc Uploading distributions to https://upload.pypi.org/legacy/ # ... (省略其他信息) ... INFO     Response from https://upload.pypi.org/legacy/:          400 The description failed to render for 'text/x-rst'. See https://pypi.org/help/#description-content-type for          more information. INFO     <html>           <head>            <title>400 The description failed to render for 'text/x-rst'. See          https://pypi.org/help/#description-content-type for more information.</title>           </head>           <body>            <h1>400 The description failed to render for 'text/x-rst'. See          https://pypi.org/help/#description-content-type for more information.</h1>            The server could not comply with the request since it is either malformed or otherwise incorrect.<br/><br/>          The description failed to render for &#x27;text/x-rst&#x27;. See          https://pypi.org/help/#description-content-type for more information.           </body>          </html> ERROR    HTTPError: 400 Bad Request from https://upload.pypi.org/legacy/          The description failed to render for 'text/x-rst'. See https://pypi.org/help/#description-content-type for          more information.

即使py -m build命令成功生成了.whl和.tar.gz文件，这并不意味着README.rst的内容完全符合PyPI的渲染标准。本地构建工具通常只检查基本的语法和文件包含，而不会执行PyPI服务器端的RST渲染验证。

一个更直接的本地诊断方法是运行twine check dist/*。这个命令会模拟PyPI的渲染检查，如果long_description存在问题，会输出类似的警告或错误，例如：

Checking distgraphab4py-1.0.4-py3-none-any.whl: FAILED ERROR    `long_description` has syntax errors in markup and would not be rendered on PyPI.          line 7: Warning: "raw" directive disabled. Checking distgraphab4py-1.0.4.tar.gz: FAILED ERROR    `long_description` has syntax errors in markup and would not be rendered on PyPI.          line 7: Warning: "raw" directive disabled.

这里的“Warning: “raw” directive disabled.”明确指出了问题所在。

根源剖析：PyPI对RST的严格要求

PyPI为了安全性和统一的页面渲染效果，对long_description中的reStructuredText语法有严格的解析规则。它使用docutils库进行解析，并禁用了一些可能导致安全风险或渲染不一致的指令。

本案例中的核心问题在于README.rst文件中使用了.. raw:: html指令。这个指令允许直接嵌入原始HTML代码，但在PyPI上是明确被禁用或限制的。PyPI出于安全考虑，会过滤掉或拒绝渲染这类内容，从而导致整个描述渲染失败。

原始的README.rst中可能包含如下导致问题的代码段：

.. raw:: html     <p align="center">      <img src="/docs/img/Ga4Py.png" alt="Graphab4py Logo" width="400">    </p>

其他可能导致渲染失败的RST问题还包括：不正确的缩进、未闭合的块、未定义的角色或指令、以及某些高级sphinx特有的指令等。例如，.. role:: bash(code)和.. role:: python(code)等自定义角色，虽然在Sphinx环境中有效，但在PyPI的默认RST渲染器中可能不被识别。

解决方案：优化README.rst内容

解决此问题的关键在于移除或替换README.rst中所有不兼容PyPI渲染规则的元素，特别是.. raw:: html指令，并使用标准的reStructuredText语法来替代。

移除或替换 .. raw:: html 指令： 这是解决此问题的关键一步。任何使用.. raw:: html来嵌入HTML代码的地方都应被移除，并尝试使用标准的reStructuredText语法来替代。

示例：替换HTML图片居中指令

将上述导致问题的HTML图片居中代码：
```
.. raw:: html     <p align="center">      <img src="/docs/img/Ga4Py.png" alt="Graphab4py Logo" width="400">    </p>
```
替换为标准的RST图片指令：
```
.. image:: ./docs/img/Ga4Py.png    :align: center    :alt: Logo    :width: 400px
```
注意事项： 尽管:align: center是RST的标准选项，但在PyPI的渲染环境中，它可能不总是能如预期般生效，或者其效果不如直接使用HTML那样灵活。开发者可能需要接受这种局限性，或者考虑将图片托管到外部，并使用PyPI支持的Markdown格式作为long_description_content_type来获得更灵活的渲染控制。
检查其他不兼容的RST语法： 除了.. raw:: html，还需检查是否存在其他Sphinx特有的或非标准的RST指令（如.. role:: bash(code)、.. role:: python(code)），这些在PyPI上可能不会被完全支持，但通常不会导致400错误，而是被忽略或渲染为普通文本。确保所有代码块都使用标准的.. code-block:: language格式，并且缩进正确。

验证与重新上传

本地验证： 在修改README.rst文件后，首先运行twine check dist/*来本地验证更改。如果不再出现关于long_description的错误或警告，例如“Warning: “raw” directive disabled.”，则说明修改有效。
重新构建： 然后，可以重新执行py -m build命令来生成新的分发文件（.whl和.tar.gz），确保最新的README.rst内容被打包进去。
上传至PyPI： 最后，使用twine upload dist/*命令将包上传至PyPI。此时，上传操作应能成功完成。

注意事项

github与PyPI渲染差异： GitHub在渲染README.rst时，其解析器可能比PyPI更宽容，或者支持一些PyPI不支持的RST扩展。因此，README.rst在GitHub上显示正常，不代表在PyPI上也能顺利渲染。
long_description_content_type： 如果RST格式始终难以满足需求，或者需要更丰富的排版功能，可以考虑将long_description_content_type设置为text/markdown，并在pyproject.toml或setup.py中指定README.md作为描述文件。
- 在pyproject.toml中：
```
[project] # ... readme = "README.md"
```
- 在setup.py中：
```
setup(     # ...     long_description=open("README.md", encoding="utf-8").read(),     long_description_content_type="text/markdown", )
```
图片路径： 确保.. image::指令中引用的图片路径是相对的，并且这些图片文件确实包含在最终的sdist或wheel包中。如果图片是项目内部的，通常建议将其放在包的docs或Static目录下，并在MANIFEST.in中正确声明以确保其被打包。对于外部图片，应使用完整的URL。

总结

成功将python包发布到PyPI不仅需要正确的构建过程，还需要确保long_description内容符合PyPI严格的渲染标准。当遇到400 Bad Request并提示RST渲染失败时，应重点检查README.rst文件中是否存在.. raw:: html等不兼容指令，并将其替换为标准的reStructuredText语法。通过本地twine check命令进行预验证，可以有效避免上传失败，确保包描述在PyPI上正确显示。

评论（已关闭）

评论已关闭

Hello! 欢迎来到悠悠畅享网！