readmeta 0.1.0__py3-none-any.whl

readmeta/__init__.py

@@ -0,0 +1,3 @@
+"""readmeta: check that your README will actually render on PyPI."""
+
+__version__ = "0.1.0"

readmeta/check.py

@@ -0,0 +1,288 @@
+"""Core checks for readmeta.
+
+Key insight: PyPI renders the *built artifact's* long_description (the body of
+``METADATA`` in a wheel / ``PKG-INFO`` in an sdist), not the repository's
+``README.md``. Relative images, relative links, in-page anchors and raw SVG
+references that work on GitHub silently 404 on PyPI, and ``twine check``
+does not catch them.
+"""
+
+from __future__ import annotations
+
+import re
+import tarfile
+import zipfile
+from dataclasses import dataclass
+from email import message_from_string
+from html.parser import HTMLParser
+
+
+# ---------------------------------------------------------------------------
+# Findings
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Finding:
+    kind: str      # relative-image | relative-link | broken-anchor | relative-svg
+    target: str    # the offending URL / anchor
+    context: str = ""  # e.g. "dist/foo-1.0.whl:12"
+    hint: str = ""
+
+
+HINTS = {
+    "relative-image": (
+        "PyPI renders the description standalone; relative image paths 404. "
+        "Use an absolute https:// URL (e.g. raw.githubusercontent.com)."
+    ),
+    "relative-link": (
+        "Relative links resolve against pypi.org and break. "
+        "Use an absolute https:// URL."
+    ),
+    "broken-anchor": (
+        "No heading with a matching id was found; the link goes nowhere on PyPI."
+    ),
+    "relative-svg": (
+        "Relative .svg references 404 on PyPI (PyPI does not serve repo files); "
+        "twine check does not flag these. Use an absolute https:// URL."
+    ),
+}
+
+
+def _is_external(url: str) -> bool:
+    u = url.strip().lower()
+    return u.startswith(("http://", "https://", "//", "data:", "mailto:"))
+
+
+def _github_slug(text: str) -> str:
+    """Approximate GitHub/PyPI heading-id slugification."""
+    text = text.strip().lower()
+    text = re.sub(r"[^\w\s-]", "", text)
+    return re.sub(r"\s+", "-", text).strip("-")
+
+
+# ---------------------------------------------------------------------------
+# HTML mode (for text/html long descriptions)
+# ---------------------------------------------------------------------------
+
+class _ReadmeHTMLParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.ids: set[str] = set()
+        self.anchors: list[tuple[str, int]] = []   # (target, line)
+        self.images: list[tuple[str, int]] = []    # (src, line)
+        self.links: list[tuple[str, int]] = []     # (href, line)
+        self._heading_text: str | None = None
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        a = dict(attrs)
+        line = self.getpos()[0]
+        ident = a.get("id")
+        if ident:
+            self.ids.add(ident)
+        if tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
+            self._heading_text = ""
+        elif tag == "img":
+            self.images.append((a.get("src") or "", line))
+        elif tag == "a":
+            href = a.get("href") or ""
+            self.links.append((href, line))
+            if href.startswith("#") and len(href) > 1:
+                self.anchors.append((href[1:], line))
+
+    def handle_data(self, data: str) -> None:
+        if self._heading_text is not None:
+            self._heading_text += data
+
+    def handle_endtag(self, tag: str) -> None:
+        if self._heading_text is not None and tag in (
+            "h1", "h2", "h3", "h4", "h5", "h6",
+        ):
+            slug = _github_slug(self._heading_text)
+            if slug:
+                self.ids.add(slug)
+            self._heading_text = None
+
+
+def check_html(html: str, source: str = "<html>") -> list[Finding]:
+    """Check an HTML long description. Returns findings sorted by line."""
+    # Mask <pre>/<code> blocks: documentation *about* bad patterns must not flag.
+    html = _mask_spans(r"<pre\b.*?</pre>", html, re.S | re.I)
+    html = _mask_spans(r"<code\b.*?</code>", html, re.S | re.I)
+    parser = _ReadmeHTMLParser()
+    parser.feed(html)
+    out: list[Finding] = []
+
+    def ctx(line: int) -> str:
+        return f"{source}:{line}"
+
+    for src, line in parser.images:
+        s = src.strip()
+        if not s or _is_external(s):
+            continue
+        kind = "relative-svg" if s.lower().split("?")[0].split("#")[0].endswith(".svg") else "relative-image"
+        out.append(Finding(kind, s, ctx(line), HINTS[kind]))
+
+    for href, line in parser.links:
+        h = href.strip()
+        if not h or h.startswith("#") or _is_external(h):
+            continue
+        kind = "relative-svg" if h.lower().split("?")[0].split("#")[0].endswith(".svg") else "relative-link"
+        out.append(Finding(kind, h, ctx(line), HINTS[kind]))
+
+    for target, line in parser.anchors:
+        if target not in parser.ids:
+            out.append(Finding("broken-anchor", "#" + target, ctx(line), HINTS["broken-anchor"]))
+
+    out.sort(key=lambda f: f.context)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Text mode (Markdown / RST raw source, as stored in METADATA / PKG-INFO)
+# ---------------------------------------------------------------------------
+
+_MD_INLINE = re.compile(r"(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+_MD_REFDEF = re.compile(r"^\s*\[[^\]]+\]:\s*(\S+)", re.M)
+_MD_HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*#*\s*$", re.M)
+_HTML_IMG_SRC = re.compile(r"<img\b[^>]*?\bsrc=[\"']([^\"']+)[\"']", re.I)
+_RST_IMAGE = re.compile(r"^\s*\.\.\s+(?:image|figure)::\s*(\S+)", re.M)
+
+
+def _mask_spans(pattern: str, text: str, flags: int = 0) -> str:
+    """Replace matches with spaces (newlines preserved) so line numbers survive."""
+
+    def _mask(m: re.Match) -> str:
+        return "".join("\n" if ch == "\n" else " " for ch in m.group(0))
+
+    return re.sub(pattern, _mask, text, flags=flags)
+
+
+def _strip_code(text: str) -> str:
+    """Mask fenced code blocks and inline code spans: documentation *about*
+    bad patterns (like this docstring) must not be flagged."""
+    text = _mask_spans(r"```.*?```", text, re.S)
+    return _mask_spans(r"`[^`\n]+`", text)
+
+
+def _line_of(text: str, pos: int) -> int:
+    return text.count("\n", 0, pos) + 1
+
+
+def check_text(text: str, source: str = "<text>") -> list[Finding]:
+    """Regex-based check for raw Markdown / RST long descriptions."""
+    text = _strip_code(text)
+    out: list[Finding] = []
+
+    def ctx(pos: int) -> str:
+        return f"{source}:{_line_of(text, pos)}"
+
+    def add_url(url: str, pos: int, is_image: bool) -> None:
+        u = url.strip()
+        if not u or _is_external(u):
+            return
+        if u.startswith("#"):
+            return  # handled by the anchor pass below
+        stem = u.lower().split("?")[0].split("#")[0]
+        kind = "relative-svg" if stem.endswith(".svg") else ("relative-image" if is_image else "relative-link")
+        out.append(Finding(kind, u, ctx(pos), HINTS[kind]))
+
+    # Inline Markdown images / links: ![alt](url), [text](url)
+    for m in _MD_INLINE.finditer(text):
+        add_url(m.group(2), m.start(), is_image=bool(m.group(1)))
+
+    # Reference-style definitions: [ref]: url
+    for m in _MD_REFDEF.finditer(text):
+        add_url(m.group(1), m.start(), is_image=False)
+
+    # Raw <img> tags embedded in Markdown
+    for m in _HTML_IMG_SRC.finditer(text):
+        add_url(m.group(1), m.start(), is_image=True)
+
+    # RST image / figure directives
+    for m in _RST_IMAGE.finditer(text):
+        add_url(m.group(1), m.start(), is_image=True)
+
+    # In-page anchors (Markdown): [text](#anchor) vs ## Headings
+    known = {_github_slug(m.group(1)) for m in _MD_HEADING.finditer(text)}
+    for m in _MD_INLINE.finditer(text):
+        url = m.group(2).strip()
+        if url.startswith("#") and len(url) > 1:
+            target = url[1:]
+            if target not in known:
+                out.append(Finding("broken-anchor", url, ctx(m.start()), HINTS["broken-anchor"]))
+
+    out.sort(key=lambda f: f.context)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Artifact / PyPI input
+# ---------------------------------------------------------------------------
+
+def read_artifact(path: str) -> tuple[str, str, str, str]:
+    """Return (name, version, content_type, long_description) for a wheel/sdist."""
+    if path.endswith(".whl"):
+        with zipfile.ZipFile(path) as z:
+            names = [n for n in z.namelist() if n.endswith(".dist-info/METADATA")]
+            if not names:
+                raise ValueError(f"no .dist-info/METADATA found in {path}")
+            raw = z.read(names[0]).decode("utf-8", "replace")
+    elif path.endswith((".tar.gz", ".tgz")):
+        with tarfile.open(path, "r:gz") as t:
+            members = [m for m in t.getmembers() if m.name.endswith("PKG-INFO")]
+            if not members:
+                raise ValueError(f"no PKG-INFO found in {path}")
+            f = t.extractfile(members[0])
+            assert f is not None
+            raw = f.read().decode("utf-8", "replace")
+    else:
+        raise ValueError(f"unsupported artifact (want .whl or .tar.gz): {path}")
+
+    msg = message_from_string(raw)
+    ctype = (msg.get("Description-Content-Type") or "text/plain").split(";")[0].strip().lower()
+    desc = msg.get_payload()
+    if not isinstance(desc, str):
+        desc = ""
+    return (
+        msg.get("Name") or "?",
+        msg.get("Version") or "?",
+        ctype,
+        desc,
+    )
+
+
+def fetch_pypi(name: str, timeout: float = 20.0) -> tuple[str, str, str, str]:
+    """Return (name, version, content_type, description) from the PyPI JSON API.
+
+    Note: the public JSON API exposes the raw ``description``, not rendered
+    HTML, so text-mode scanning applies unless a ``description_html`` field
+    is ever present.
+    """
+    import json
+    import urllib.request
+
+    url = f"https://pypi.org/pypi/{name}/json"
+    req = urllib.request.Request(url, headers={"User-Agent": "readmeta/0.1.0"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        data = json.load(resp)
+    info = data.get("info", {})
+    if "description_html" in info and info["description_html"]:
+        return (
+            info.get("name") or name,
+            info.get("version") or "?",
+            "text/html",
+            info["description_html"],
+        )
+    ctype = (info.get("description_content_type") or "text/plain").split(";")[0].strip().lower()
+    return (
+        info.get("name") or name,
+        info.get("version") or "?",
+        ctype,
+        info.get("description") or "",
+    )
+
+
+def check_description(content_type: str, description: str, source: str) -> list[Finding]:
+    if "html" in content_type:
+        return check_html(description, source)
+    return check_text(description, source)

readmeta/cli.py

@@ -0,0 +1,73 @@
+"""Command-line interface for readmeta."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import urllib.error
+
+from . import __version__
+from .check import check_description, fetch_pypi, read_artifact
+
+
+def _report(name: str, version: str, content_type: str, source: str, description: str) -> int:
+    findings = check_description(content_type, description, source)
+    print(f"{name} {version}  [{content_type}]  <- {source}")
+    if not findings:
+        print("OK: no PyPI rendering issues found.")
+        return 0
+    print(f"Found {len(findings)} issue(s):\n")
+    for f in findings:
+        print(f"  [{f.kind}] {f.context}\n      {f.target}\n      -> {f.hint}\n")
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="readmeta",
+        description=(
+            "Check whether a package's README will render correctly on PyPI. "
+            "Inspects the built artifact's long_description (what PyPI actually "
+            "renders), not the repo's README.md."
+        ),
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    chk = sub.add_parser("check", help="check artifacts or a PyPI project for rendering issues")
+    chk.add_argument("paths", nargs="*", help="wheel (.whl) and/or sdist (.tar.gz) files")
+    chk.add_argument("--pypi", metavar="NAME", help="check the description hosted on PyPI instead of local files")
+
+    args = ap.parse_args(argv)
+
+    if args.command == "check":
+        if args.pypi:
+            try:
+                name, version, ctype, desc = fetch_pypi(args.pypi)
+            except urllib.error.HTTPError as e:
+                print(f"error: PyPI request failed ({e.code} {e.reason})", file=sys.stderr)
+                return 2
+            except OSError as e:
+                print(f"error: could not reach PyPI: {e}", file=sys.stderr)
+                return 2
+            return _report(name, version, ctype, f"pypi:{args.pypi}", desc)
+
+        if not args.paths:
+            ap.error("check needs at least one artifact path or --pypi NAME")
+        worst = 0
+        for path in args.paths:
+            try:
+                name, version, ctype, desc = read_artifact(path)
+            except (OSError, ValueError) as e:
+                print(f"error: {e}", file=sys.stderr)
+                worst = max(worst, 2)
+                continue
+            rc = _report(name, version, ctype, path, desc)
+            worst = max(worst, rc)
+        return worst
+
+    return 2  # pragma: no cover
+
+
+if __name__ == "__main__":
+    sys.exit(main())

readmeta-0.1.0.dist-info/METADATA

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: readmeta
+Version: 0.1.0
+Summary: Check that your README will actually render on PyPI — inspects the built artifact, not the repo
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/readmeta
+Keywords: pypi,readme,packaging,ci,twine
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# readmeta
+
+Check that your README will actually render on PyPI — by inspecting the **built artifact**, not the repo.
+
+## The problem
+
+PyPI renders the `long_description` from your built artifact (the body of `METADATA` in a wheel / `PKG-INFO` in an sdist). It does **not** render your repo's `README.md`. Things that look perfect on GitHub silently break on PyPI:
+
+- **Relative images** (`![shot](docs/shot.png)`) → 404, PyPI has no `docs/` folder
+- **Relative links** (`[usage](docs/usage.md)`) → resolve against `pypi.org`, broken
+- **Raw SVG references** (`assets/logo.svg`) → 404; PyPI doesn't serve repo files
+- **In-page anchors** (`[setup](#instalation)`) → go nowhere when the heading id doesn't exist
+
+`twine check` validates that the description *renders* — it does not check that any link or image actually *resolves*.
+
+Real cases this catches:
+
+- `armsmith` v1.2.1 shipped a relative SVG badge that 404'd on its PyPI page while rendering fine on GitHub.
+- `aicertify` maintains a separate `README-pypi.md` with rewritten absolute URLs, precisely because the GitHub README breaks on PyPI.
+- An audit of the `modern-python` GitHub org found 23 of 25 packages shipping relative asset references that can't resolve on PyPI.
+
+## Install
+
+```bash
+pip install readmeta
+```
+
+Requires Python 3.9+. No dependencies — stdlib only.
+
+## Usage
+
+Check your built artifacts (build first, then check what PyPI will actually see):
+
+```bash
+python -m build
+readmeta check dist/*
+```
+
+Or check what's currently hosted on PyPI:
+
+```bash
+readmeta check --pypi requests
+```
+
+Example output:
+
+```
+fakepkg 0.1.0  [text/markdown]  <- dist/fakepkg-0.1.0-py3-none-any.whl
+Found 2 issue(s):
+
+  [relative-image] dist/fakepkg-0.1.0-py3-none-any.whl:12
+      docs/shot.png
+      -> PyPI renders the description standalone; relative image paths 404. Use an absolute https:// URL (e.g. raw.githubusercontent.com).
+
+  [broken-anchor] dist/fakepkg-0.1.0-py3-none-any.whl:20
+      #instalation
+      -> No heading with a matching id was found; the link goes nowhere on PyPI.
+```
+
+Exit codes are CI-friendly: `0` = clean, `1` = issues found, `2` = error (unreadable artifact, PyPI unreachable, bad usage).
+
+## CI example
+
+```yaml
+- name: Build
+  run: python -m build
+
+- name: Check PyPI rendering
+  run: |
+    pip install readmeta
+    readmeta check dist/*
+```
+
+## How it works
+
+1. Reads `long_description` from `.whl` (`zipfile` → `.dist-info/METADATA`) or `.tar.gz` (`tarfile` → `PKG-INFO`), plus the `Description-Content-Type` header.
+2. For `text/html`, parses with `html.parser` and validates every `img[src]`, `a[href]`, and `#anchor` against collected element ids (explicit ids plus GitHub-style heading slugs).
+3. For Markdown/RST (what artifacts actually carry — the raw source, not rendered HTML), scans with regexes: inline and reference-style images/links, embedded `<img>` tags, RST `image::`/`figure::` directives, and `#anchor` links against `# Heading` slugs.
+4. `--pypi` mode fetches `https://pypi.org/pypi/<name>/json` and checks the hosted description.
+
+## Limitations (v0.1)
+
+- **Check only** — no `--fix`. A build-time rewrite mode (convert relative refs to absolute URLs at build time) is planned.
+- Anchor validation for RST is limited (Markdown headings and HTML ids are covered; RST `.. _target:` definitions are not yet resolved).
+- Code spans and fenced code blocks are ignored (documenting a bad pattern doesn't flag it); indented code blocks are still scanned.
+- Heading-slug generation approximates GitHub/PyPI's algorithm; exotic headings could produce false positives — explicit `id` attributes always win.
+- `--pypi` uses the raw `description` from the JSON API (the API doesn't expose rendered HTML); findings are identical to checking a fresh local build.

readmeta-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+readmeta/__init__.py,sha256=m79wxCNuNjTk0iJ5IIwxdCHRa-Sfi0-89aB6YW7TrCM,92
+readmeta/check.py,sha256=EHHacQ6vAu3WJDo6oSoi6JviHR6ltJbKZ7IAFjWrvg0,10723
+readmeta/cli.py,sha256=mhPyrGwtBg8kq8X7smi4h7j8OYLGcDy5it7SIekRHfs,2657
+readmeta-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+readmeta-0.1.0.dist-info/METADATA,sha256=8O7qmEkXj4gFMFYuXc7He127APE6L5ILQP8C89qaBt0,4196
+readmeta-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+readmeta-0.1.0.dist-info/entry_points.txt,sha256=rwamKpg_5cn4RnhaMAMZ8tijuikXf36Bc6LKY-YzWsg,47
+readmeta-0.1.0.dist-info/top_level.txt,sha256=KVbdaBc_bSBeVCWPG2d4VgAkDH--2z5wBJMmWcib6Os,9
+readmeta-0.1.0.dist-info/RECORD,,

readmeta-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

readmeta-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+readmeta = readmeta.cli:main

readmeta-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

readmeta-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+readmeta