PyPI silently rejects RST raw directives in package descriptions for security. Convert to Markdown or remove raw directives before publishing.
During a framework release, PyPI deployment failed with a cryptic metadata rejection error. Investigation revealed that PyPI disables .. raw:: RST directives in package descriptions for security reasons, even when the raw content is just HTML badges. This isn't well-documented and the error message doesn't clearly indicate the root cause.
The failure occurred after a successful local build and git tag creation, creating a complex recovery scenario where the release tag existed but PyPI deployment never completed. The solution required converting the entire README from reStructuredText to Markdown and updating pyproject.toml to reference README.md instead of README.rst.
This security restriction catches developers off-guard because RST raw directives are commonly used for embedded HTML badges in READMEs, and the restriction isn't prominently documented in PyPI's packaging guides.