DEV Community

hao li
hao li

Posted on

readmeta v0.2: --fix rewrites your broken PyPI README links at build time

#python #pypi #packaging #opensource

readmeta v0.1 checked whether
your README will actually render on PyPI — by inspecting the built
artifact's long_description, not your repo's README.md. Relative images,
relative links, raw SVGs, and dead in-page anchors that look fine on GitHub
silently 404 on PyPI, and twine check never flags them.

v0.2 closes the loop: --fix rewrites the broken references for you — at
build time, not in your source files.

pip install readmeta

python -m build
readmeta check dist/* --fix --repo octo/demo
twine upload dist/*.fixed.*
Enter fullscreen mode Exit fullscreen mode

Why build-time instead of editing the README? Two reasons:

  1. The artifact is derived output — hand-editing dist/*.whl isn't a repeatable pipeline step.
  2. Baking absolute URLs into the source README is wrong for GitHub: a tag-pinned raw.githubusercontent.com URL 404s until the tag exists (chicken-and-egg), and a branch-pinned URL drifts. Keep relative paths in the source; let the pipeline rewrite them for PyPI.

What --fix does:

  • Rewrites every relative image / link / raw-SVG finding to an absolute URL. Images go to raw.githubusercontent.com/<repo>/<ref>/<path>; other relative links to github.com/<repo>/blob/<ref>/<path> (--ref pins the ref, default main).
  • Or resolve everything against your own CDN with --base-url https://cdn.example.com/static/.
  • Emits *.fixed.whl / *.fixed.tar.gz next to the inputs (or into --out-dir). Your inputs — and your source files — are never touched.
  • Never rewrites inside fenced code blocks, inline code, or <pre>/<code>: documentation about a bad pattern stays as-is.
  • Can't rewrite broken #anchor links (there's no sensible absolute form), so those are reported as remaining issues for you to fix by hand.

Example:

$ readmeta check dist/* --fix --repo octo/demo
...
--fix: rewrote 3 reference(s) -> dist/fakepkg-0.1.0-py3-none-any.fixed.whl

  [relative-image] dist/fakepkg-0.1.0-py3-none-any.whl:12
      docs/shot.png
      -> https://raw.githubusercontent.com/octo/demo/main/docs/shot.png

--fix: 1 issue(s) could not be rewritten (manual fix needed):

  [broken-anchor] dist/fakepkg-0.1.0-py3-none-any.fixed.whl:20
      #instalation
      -> No heading with a matching id was found; the link goes nowhere on PyPI.
Enter fullscreen mode Exit fullscreen mode

With --fix, the exit code is 0 when everything was clean or fully
rewritten, 1 when unrewritable issues (anchors) remain, 2 on error —
CI-friendly.

Amusing detail: readmeta dogfoods itself. The v0.2 README shipped a
[LICENSE](LICENSE) relative link; readmeta's own check flagged it during the
release build, and the release README now links the absolute GitHub URL.

Install: pip install readmeta ·
PyPI: https://pypi.org/project/readmeta/0.2.0/ ·
GitHub: https://github.com/hahahahahahahahah6/readmeta

Stdlib only, Python 3.9+, MIT.

Top comments (0)