Skip to content

fix: the banner could not render on PyPI, for two separate reasons - #52

Merged
harshuljain13 merged 1 commit into
mainfrom
fix/pypi-banner
Oct 5, 2026
Merged

harshuljain13 merged 1 commit into
mainfrom
fix/pypi-banner

Conversation

@harshuljain13

Copy link
Copy Markdown
Owner

Both invisible locally and on GitHub, where the README renders fine.

Cause
1 src was assets/banner.svg — a relative path. PyPI renders a long_description with no repository context, so it resolves to nothing
2 PyPI proxies images through camo, which does not serve SVG. So even an absolute URL ending .svg is a broken image

Fixed to an absolute raw.githubusercontent.com URL pointing at a PNG rendered from the SVG, which stays the source.

Tested, so it cannot regress

for src in re.findall(r'<img[^>]*src="([^"]+)"', readme):
    assert src.startswith("http"), "relative src will not resolve on PyPI"
    assert not src.endswith(".svg"), "PyPI's image proxy does not serve SVG"

Plus a check that the file actually exists at the path the URL claims — a 404 from raw.githubusercontent looks exactly like a broken renderer.

I verified the fix through readme_renderer, which is the library PyPI itself uses: one image survives, no .svg references remain.

The banner was also stale

Its tagline read "benchmark-driven admission control layer for LLM inference" — what the project was before it became a standard for policies. Now matches the package summary.

Why 0.0.2

A published long_description cannot be edited. PyPI renders it from the uploaded distribution's metadata, so fixing the page requires a release. Tag v0.0.2 after merge.

179 passed, lint clean, both artifacts pass twine check --strict.

Both were invisible locally and on GitHub, where the README renders fine.

  The src was `assets/banner.svg`, a RELATIVE path. PyPI renders a long_description
  with no repository context, so it resolves to nothing.

  PyPI proxies images through camo, which does not serve SVG. So even an absolute
  URL ending in .svg is a broken image.

Now an absolute raw.githubusercontent URL pointing at a PNG rendered from the SVG,
which stays the source. tests/test_layering.py asserts both conditions for every
image in the README, plus that the file actually exists at the path the URL claims
— a 404 from raw.githubusercontent looks exactly like a broken renderer.

The banner's own tagline was stale too: "benchmark-driven admission control layer
for LLM inference", which is what the project was before it became a standard for
policies. It now matches the package summary.

Version 0.0.2, because a published long_description cannot be edited — PyPI
renders it from the uploaded distribution's metadata, so fixing the page requires
a release.

179 passed, lint clean, both artifacts pass twine check --strict.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@harshuljain13
harshuljain13 requested a review from tsah20 October 5, 2026 12:09
@harshuljain13 harshuljain13 self-assigned this Oct 5, 2026
@harshuljain13 harshuljain13 added the documentation Improvements or additions to documentation label Oct 5, 2026
@harshuljain13 harshuljain13 added this to the 0.1.0 milestone Oct 5, 2026
@harshuljain13
harshuljain13 merged commit 99c7dc5 into main Oct 5, 2026
4 checks passed
@harshuljain13
harshuljain13 deleted the fix/pypi-banner branch October 5, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant