wheelgap 0.1.0__py3-none-any.whl

wheelgap/__init__.py

@@ -0,0 +1,3 @@
+"""wheelgap: find the dependencies that have no prebuilt wheel for your target platform."""
+
+__version__ = "0.1.0"

wheelgap/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

wheelgap/check.py

@@ -0,0 +1,134 @@
+"""Decide, per package and target, whether a prebuilt wheel exists."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from packaging.markers import InvalidMarker, Marker, UndefinedComparison, UndefinedEnvironmentName
+from packaging.tags import Tag
+from packaging.utils import InvalidWheelFilename, canonicalize_name, parse_wheel_filename
+
+from .sources import Edge, Package, Source
+from .targets import Target
+
+
+class Status(StrEnum):
+    WHEEL = "wheel"  # a compatible wheel exists
+    SOURCE = "source"  # no compatible wheel, but an sdist: installers will build it
+    MISSING = "missing"  # no compatible wheel and no sdist: install fails
+    UNKNOWN = "unknown"  # couldn't look the package up
+    NOT_NEEDED = "n/a"  # markers say this package isn't installed on the target
+
+
+SDIST_SUFFIXES = (".tar.gz", ".zip", ".tar.bz2", ".tgz", ".tar.xz")
+
+
+@dataclass
+class Row:
+    package: Package
+    results: dict[Target, Status] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return all(s in (Status.WHEEL, Status.NOT_NEEDED) for s in self.results.values())
+
+    @property
+    def needed(self) -> bool:
+        return any(s is not Status.NOT_NEEDED for s in self.results.values())
+
+
+def wheel_tags(files: list[str]) -> list[frozenset[Tag]]:
+    out = []
+    for f in files:
+        if not f.endswith(".whl"):
+            continue
+        try:
+            out.append(parse_wheel_filename(f)[3])
+        except InvalidWheelFilename:
+            continue
+    return out
+
+
+def has_sdist(files: list[str]) -> bool:
+    return any(f.endswith(SDIST_SUFFIXES) for f in files)
+
+
+def status_for(files: list[str] | None, target: Target, _wheels: list[frozenset[Tag]] | None = None) -> Status:
+    if files is None:
+        return Status.UNKNOWN
+    wheels = _wheels if _wheels is not None else wheel_tags(files)
+    if any(target.accepts(t) for t in wheels):
+        return Status.WHEEL
+    return Status.SOURCE if has_sdist(files) else Status.MISSING
+
+
+_marker_cache: dict[str, Marker | None] = {}
+
+
+def marker_holds(marker: str | None, target: Target) -> bool:
+    if not marker:
+        return True
+    if marker not in _marker_cache:
+        try:
+            _marker_cache[marker] = Marker(marker)
+        except InvalidMarker:
+            _marker_cache[marker] = None
+    m = _marker_cache[marker]
+    if m is None:
+        return True  # can't parse it: assume the package is needed rather than hide a gap
+    try:
+        return m.evaluate(target.marker_env)
+    except (UndefinedComparison, UndefinedEnvironmentName):
+        return True
+
+
+def reachable(source: Source, target: Target) -> set[int]:
+    """Indexes of packages installed on `target`, walking the lockfile graph from its roots."""
+    by_name: dict[str, list[int]] = {}
+    for i, p in enumerate(source.packages):
+        by_name.setdefault(p.key, []).append(i)
+
+    def follow(edge: Edge) -> list[int]:
+        name, version, marker = edge
+        if not marker_holds(marker, target):
+            return []
+        candidates = by_name.get(canonicalize_name(name), [])
+        if version is not None:
+            candidates = [i for i in candidates if source.packages[i].version == version] or candidates
+        return candidates
+
+    seen = set(source.roots)
+    stack = list(source.roots)
+    for edge in source.root_edges:
+        stack.extend(follow(edge))
+    while stack:
+        i = stack.pop()
+        seen.add(i)
+        for edge in (source.edges or {}).get(i, []):
+            for j in follow(edge):
+                if j not in seen:
+                    seen.add(j)
+                    stack.append(j)
+    return seen
+
+
+def applies(pkg: Package, target: Target) -> bool:
+    return pkg.markers is None or any(marker_holds(m, target) for m in pkg.markers)
+
+
+def check(sources: list[Source], targets: list[Target]) -> list[Row]:
+    rows = []
+    for source in sources:
+        installed = {t: reachable(source, t) for t in targets} if source.edges is not None else None
+        for i, pkg in enumerate(source.packages):
+            if pkg.skip:
+                continue
+            files = None if pkg.error else pkg.files
+            wheels = wheel_tags(files) if files is not None else []
+            row = Row(pkg)
+            for t in targets:
+                needed = i in installed[t] if installed is not None else applies(pkg, t)
+                row.results[t] = status_for(files, t, wheels) if needed else Status.NOT_NEEDED
+            rows.append(row)
+    return rows

wheelgap/cli.py

@@ -0,0 +1,248 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import sysconfig
+
+from . import __version__
+from .check import Row, Status, check
+from .pypi import fill_all
+from .sources import SourceError, load_inputs
+from .targets import DEFAULT_PLATFORMS, PLATFORMS, Target, TargetError, build_targets
+
+EXAMPLES = """\
+examples:
+  wheelgap                                 check the lockfile in the current directory
+  wheelgap uv.lock -t musl-aarch64         will my Alpine ARM image build from source?
+  wheelgap -p 3.14t -t all                 is my stack ready for free-threaded 3.14?
+  wheelgap psycopg2 uvloop -t win-amd64    check packages without a lockfile
+  wheelgap requirements.txt --json         machine-readable output for CI
+"""
+
+
+def running_python() -> str:
+    ft = "t" if sysconfig.get_config_var("Py_GIL_DISABLED") else ""
+    return f"{sys.version_info.major}.{sys.version_info.minor}{ft}"
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="wheelgap",
+        description="Find the dependencies that have no prebuilt wheel for your target platform, "
+        "so they'd be compiled from source (slow) or fail to install.",
+        epilog=EXAMPLES,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument(
+        "inputs",
+        nargs="*",
+        metavar="INPUT",
+        help="uv.lock, pylock.toml, poetry.lock, requirements.txt, a directory, or package specs (default: .)",
+    )
+    p.add_argument(
+        "-p",
+        "--python",
+        action="append",
+        default=[],
+        metavar="VER",
+        help=f"target Python, e.g. 3.13 or 3.14t (repeatable; default: {running_python()})",
+    )
+    p.add_argument(
+        "-t",
+        "--target",
+        action="append",
+        default=[],
+        metavar="PLATFORM",
+        help=f"target platform (repeatable, or 'all'; default: {','.join(DEFAULT_PLATFORMS)})",
+    )
+    p.add_argument("--glibc", default="2.36", metavar="X.Y", help="glibc version for linux-* targets (default: 2.36)")
+    p.add_argument("--musl", default="1.2", metavar="X.Y", help="musl version for musl-* targets (default: 1.2)")
+    p.add_argument("--macos", default="14.0", metavar="X.Y", help="minimum macOS for macos-* targets (default: 14.0)")
+    p.add_argument(
+        "--online", action="store_true", help="re-check lockfile packages against PyPI instead of trusting the lockfile"
+    )
+    p.add_argument("--all", action="store_true", help="show every package, not just the ones with gaps")
+    p.add_argument("--json", action="store_true", help="print JSON instead of a table")
+    p.add_argument("--exit-zero", action="store_true", help="exit 0 even when gaps are found")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("--list-targets", action="store_true", help="list platform names and exit")
+    p.add_argument("-V", "--version", action="version", version=f"wheelgap {__version__}")
+    return p.parse_args(argv)
+
+
+class Style:
+    def __init__(self, enabled: bool):
+        self.enabled = enabled
+
+    def __call__(self, text: str, code: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self.enabled else text
+
+    def green(self, t: str) -> str:
+        return self(t, "32")
+
+    def yellow(self, t: str) -> str:
+        return self(t, "33")
+
+    def red(self, t: str) -> str:
+        return self(t, "31")
+
+    def dim(self, t: str) -> str:
+        return self(t, "2")
+
+    def bold(self, t: str) -> str:
+        return self(t, "1")
+
+
+def use_color(mode: str) -> bool:
+    if mode != "auto":
+        return mode == "always"
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    return sys.stdout.isatty()
+
+
+CELL = {
+    Status.WHEEL: ("✓", "green"),
+    Status.SOURCE: ("● source", "yellow"),
+    Status.MISSING: ("✗ missing", "red"),
+    Status.UNKNOWN: ("? unknown", "dim"),
+    Status.NOT_NEEDED: ("–", "dim"),
+}
+
+
+def render_table(rows: list[Row], targets: list[Target], style: Style) -> list[str]:
+    multi_py = len({t.python for t in targets}) > 1
+    headers = ["package", "version"] + [t.label(multi_py) for t in targets]
+    body = []
+    for r in rows:
+        cells = [r.package.name, r.package.version or "?"]
+        cells += [CELL[r.results[t]][0] for t in targets]
+        body.append(cells)
+    widths = [max(len(h), *(len(c[i]) for c in body)) for i, h in enumerate(headers)]
+
+    def line(cells: list[str], colors: list[str] | None = None) -> str:
+        parts = []
+        for i, c in enumerate(cells):
+            padded = c.ljust(widths[i])
+            if colors and colors[i]:
+                padded = getattr(style, colors[i])(padded)
+            parts.append(padded)
+        return "  ".join(parts).rstrip()
+
+    out = [style.bold(line(headers))]
+    for r, cells in zip(rows, body, strict=True):
+        colors = ["", "dim"] + [CELL[r.results[t]][1] for t in targets]
+        out.append(line(cells, colors))
+    return out
+
+
+def report_json(rows: list[Row], targets: list[Target], sources: list[str], skipped: list) -> str:
+    multi_py = len({t.python for t in targets}) > 1
+    gaps = [r for r in rows if not r.ok]
+    return json.dumps(
+        {
+            "version": __version__,
+            "sources": sources,
+            "targets": [{"label": t.label(multi_py), "python": t.python, "platform": t.platform} for t in targets],
+            "packages": [
+                {
+                    "name": r.package.name,
+                    "version": r.package.version,
+                    "error": r.package.error,
+                    "results": {t.label(multi_py): r.results[t].value for t in targets},
+                }
+                for r in rows
+            ],
+            "skipped": [{"name": p.name, "reason": p.skip} for p in skipped],
+            "summary": {"packages": len(rows), "with_gaps": len(gaps)},
+        },
+        indent=2,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        # Don't crash printing ✓ to a non-UTF-8 pipe (e.g. Windows cp1252).
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure:
+            reconfigure(errors="replace")
+    args = parse_args(argv)
+    if args.list_targets:
+        for name, (family, arch) in PLATFORMS.items():
+            print(f"{name:<14} {family} {arch}")
+        return 0
+
+    try:
+        targets = build_targets(args.python or [running_python()], args.target, args.glibc, args.musl, args.macos)
+        sources = load_inputs(args.inputs or ["."])
+    except (TargetError, SourceError, OSError) as e:
+        print(f"wheelgap: error: {e}", file=sys.stderr)
+        return 2
+    except Exception as e:  # malformed TOML and friends
+        print(f"wheelgap: error: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+    packages = [p for s in sources for p in s.packages]
+    fill_all(packages, refresh=args.online)
+    skipped = [p for p in packages if p.skip]
+    rows = [r for r in check(sources, targets) if r.needed]
+    rows.sort(key=lambda r: r.package.key)
+    gaps = [r for r in rows if not r.ok]
+    source_labels = [s.label for s in sources]
+
+    if args.json:
+        print(report_json(rows, targets, source_labels, skipped))
+        return 0 if args.exit_zero or not gaps else 1
+
+    style = Style(use_color(args.color))
+    pys = ", ".join(dict.fromkeys(t.python for t in targets))
+    print(style.dim(f"wheelgap {__version__} · {' + '.join(source_labels)} · {len(rows)} packages · Python {pys}"))
+    print()
+
+    shown = rows if args.all else gaps
+    if shown:
+        for ln in render_table(shown, targets, style):
+            print(ln)
+        print()
+        hidden = len(rows) - len(shown)
+        if hidden:
+            noun = "package" if hidden == 1 else "packages"
+            print(style.dim(f"{hidden} {noun} with wheels for every target hidden (--all to show)"))
+
+    if skipped:
+        names = ", ".join(f"{p.name} ({p.skip})" for p in skipped)
+        print(style.dim(f"skipped {len(skipped)} non-index package{'s' * (len(skipped) != 1)}: {names}"))
+
+    errors = [r for r in rows if r.package.error]
+    for r in errors:
+        print(style.dim(f"could not check {r.package.name}: {r.package.error}"))
+
+    n_t = len(targets)
+    if not gaps:
+        what = "The 1 package has" if len(rows) == 1 else f"All {len(rows)} packages have"
+        print(style.green(f"✓ {what} a wheel for {'every one of ' if n_t > 1 else ''}{n_t} target{'s' * (n_t > 1)}."))
+        return 0
+
+    source = sum(any(s is Status.SOURCE for s in r.results.values()) for r in gaps)
+    missing = sum(any(s is Status.MISSING for s in r.results.values()) for r in gaps)
+    parts = []
+    if source:
+        parts.append(style.yellow(f"{source} will build from source"))
+    if missing:
+        parts.append(style.red(f"{missing} can't install at all"))
+    unknown = len(gaps) - source - missing
+    if unknown > 0:
+        parts.append(style.dim(f"{unknown} unknown"))
+    verb = "has" if len(gaps) == 1 else "have"
+    print(f"{style.bold(f'{len(gaps)} of {len(rows)} packages')} {verb} gaps: " + ", ".join(parts) + ".")
+    return 0 if args.exit_zero else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

wheelgap/pypi.py

@@ -0,0 +1,61 @@
+"""Fill in distribution filenames from the PyPI JSON API."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from urllib.parse import quote
+
+from . import __version__
+from .sources import Package
+
+DEFAULT_INDEX = "https://pypi.org/pypi"
+
+
+def index_url() -> str:
+    return os.environ.get("WHEELGAP_INDEX_URL", DEFAULT_INDEX).rstrip("/")
+
+
+def fetch_json(url: str, timeout: float = 20.0) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": f"wheelgap/{__version__}", "Accept": "application/json"})
+    last: Exception | None = None
+    for _ in range(3):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.load(resp)
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise
+            last = e
+        except (urllib.error.URLError, TimeoutError) as e:
+            last = e
+    raise last  # type: ignore[misc]
+
+
+def fill(pkg: Package) -> Package:
+    base = index_url()
+    name = quote(pkg.key)
+    url = f"{base}/{name}/{quote(pkg.version)}/json" if pkg.version else f"{base}/{name}/json"
+    try:
+        data = fetch_json(url)
+    except urllib.error.HTTPError as e:
+        pkg.error = "not on index" if e.code == 404 else f"HTTP {e.code}"
+        return pkg
+    except Exception as e:  # network trouble shouldn't kill the whole report
+        pkg.error = f"lookup failed ({type(e).__name__})"
+        return pkg
+    if not pkg.version:
+        pkg.version = data.get("info", {}).get("version")
+    pkg.files = [u["filename"] for u in data.get("urls", []) if not u.get("yanked")]
+    return pkg
+
+
+def fill_all(packages: list[Package], refresh: bool = False, workers: int = 16) -> None:
+    todo = [p for p in packages if not p.skip and (refresh or p.files is None)]
+    if not todo:
+        return
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        list(pool.map(fill, todo))

wheelgap/sources.py

@@ -0,0 +1,241 @@
+"""Read packages (and, where the lockfile records them, their distribution files) from inputs."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from urllib.parse import unquote, urlparse
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+LOCKFILES = ("uv.lock", "pylock.toml", "poetry.lock", "requirements.txt")
+
+
+class SourceError(ValueError):
+    pass
+
+
+@dataclass
+class Package:
+    name: str
+    version: str | None
+    # Distribution filenames. None means "unknown, ask the index".
+    files: list[str] | None = None
+    # Set for packages that don't come from an index (editable, git, path, ...).
+    skip: str | None = None
+    error: str | None = None
+    origin: str = ""
+    # Environment markers; the package is installed if any of them is true. None means always.
+    markers: list[str] | None = None
+
+    @property
+    def key(self) -> str:
+        return canonicalize_name(self.name)
+
+
+# A dependency edge in a lockfile graph: (name, version or None, marker or None)
+Edge = tuple[str, str | None, str | None]
+
+
+@dataclass
+class Source:
+    label: str
+    packages: list[Package] = field(default_factory=list)
+    # uv.lock only: which packages each package depends on, and where the walk starts.
+    # When set, a package applies to a target only if it's reachable along edges whose markers hold.
+    edges: dict[int, list[Edge]] | None = None
+    roots: list[int] = field(default_factory=list)
+    root_edges: list[Edge] = field(default_factory=list)
+
+
+def _filename(entry: dict) -> str | None:
+    for k in ("filename", "file", "name"):
+        if isinstance(entry.get(k), str) and entry[k].endswith((".whl", ".tar.gz", ".zip", ".tar.bz2", ".tgz")):
+            return entry[k]
+    url = entry.get("url")
+    if isinstance(url, str):
+        return unquote(Path(urlparse(url).path).name)
+    path = entry.get("path")
+    if isinstance(path, str):
+        return Path(path).name
+    return None
+
+
+def _uv_edges(p: dict) -> list[Edge]:
+    groups = [p.get("dependencies", [])]
+    for table in ("optional-dependencies", "dev-dependencies"):
+        groups.extend(p.get(table, {}).values())
+    return [(d["name"], d.get("version"), d.get("marker")) for g in groups for d in g]
+
+
+def parse_uv_lock(path: Path) -> Source:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    manifest = data.get("manifest", {})
+    members = {canonicalize_name(m) for m in manifest.get("members", [])}
+    source = Source(path.name, edges={})
+    for p in data.get("package", []):
+        src = p.get("source", {})
+        pkg = Package(p["name"], p.get("version"), origin=path.name)
+        kind = next((k for k in ("editable", "virtual", "git", "path", "directory", "url") if k in src), None)
+        if kind and "registry" not in src:
+            pkg.skip = kind
+        else:
+            files = [f for f in (_filename(w) for w in p.get("wheels", [])) if f]
+            if p.get("sdist"):
+                files.append(_filename(p["sdist"]) or f"{p['name']}-{p.get('version')}.tar.gz")
+            pkg.files = files
+        i = len(source.packages)
+        source.packages.append(pkg)
+        source.edges[i] = _uv_edges(p)
+        if kind in ("editable", "virtual", "directory") or pkg.key in members:
+            source.roots.append(i)
+    for group in manifest.get("dependency-groups", {}).values():
+        source.root_edges.extend((d["name"], None, d.get("marker")) for d in group)
+    source.root_edges.extend((d["name"], None, d.get("marker")) for d in manifest.get("requirements", []))
+    if not source.roots and not source.root_edges:
+        source.edges = None  # no idea where the graph starts; treat every package as needed
+    return source
+
+
+def parse_pylock(path: Path) -> Source:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    pkgs = []
+    for p in data.get("packages", []):
+        pkg = Package(p["name"], p.get("version"), origin=path.name)
+        if p.get("marker"):
+            pkg.markers = [p["marker"]]
+        if any(k in p for k in ("vcs", "directory", "archive")) and "wheels" not in p and "sdist" not in p:
+            pkg.skip = next(k for k in ("vcs", "directory", "archive") if k in p)
+        else:
+            files = [f for f in (_filename(w) for w in p.get("wheels", [])) if f]
+            if p.get("sdist"):
+                files.append(_filename(p["sdist"]) or f"{p['name']}-{p.get('version')}.tar.gz")
+            pkg.files = files
+        pkgs.append(pkg)
+    return Source(path.name, pkgs)
+
+
+def parse_poetry_lock(path: Path) -> Source:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    legacy_files = data.get("metadata", {}).get("files", {})
+    pkgs = []
+    for p in data.get("package", []):
+        pkg = Package(p["name"], p.get("version"), origin=path.name)
+        markers = p.get("markers")
+        if isinstance(markers, str):
+            pkg.markers = [markers]
+        elif isinstance(markers, dict):
+            pkg.markers = [m for m in markers.values() if isinstance(m, str)] or None
+        src_type = p.get("source", {}).get("type")
+        if src_type in ("git", "directory", "file", "url"):
+            pkg.skip = src_type
+        else:
+            entries = p.get("files")
+            if entries is None:
+                entries = legacy_files.get(p["name"], [])
+            pkg.files = [f for f in (_filename(e) for e in entries) if f]
+        pkgs.append(pkg)
+    return Source(path.name, pkgs)
+
+
+def _pinned_version(req: Requirement) -> str | None:
+    specs = list(req.specifier)
+    if len(specs) == 1 and specs[0].operator in ("==", "===") and "*" not in specs[0].version:
+        return specs[0].version
+    return None
+
+
+def requirement_to_package(text: str, origin: str) -> Package:
+    try:
+        req = Requirement(text)
+    except InvalidRequirement as e:
+        raise SourceError(f"{origin}: can't parse requirement {text!r}: {e}") from None
+    markers = [str(req.marker)] if req.marker else None
+    if req.url:
+        return Package(req.name, None, skip="url", origin=origin, markers=markers)
+    return Package(req.name, _pinned_version(req), origin=origin, markers=markers)
+
+
+def parse_requirements(path: Path, _seen: set[Path] | None = None) -> Source:
+    seen = _seen if _seen is not None else set()
+    path = path.resolve()
+    if path in seen:
+        return Source(path.name)
+    seen.add(path)
+    pkgs: list[Package] = []
+    lines = path.read_text(encoding="utf-8").replace("\\\n", " ").splitlines()
+    for raw in lines:
+        line = raw.split(" #", 1)[0].strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith(("-r ", "--requirement")):
+            ref = line.split(None, 1)[1].strip() if " " in line else line.split("=", 1)[1]
+            pkgs.extend(parse_requirements(path.parent / ref, seen).packages)
+            continue
+        if line.startswith("-e ") or line.startswith("--editable"):
+            name = line.split("#egg=", 1)[1] if "#egg=" in line else line.split(None, 1)[-1]
+            pkgs.append(Package(name, None, skip="editable", origin=path.name))
+            continue
+        if line.startswith("-"):
+            continue  # pip options: --index-url, -c, --hash continuation, ...
+        line = " ".join(t for t in line.split() if not t.startswith("--hash"))
+        if line.startswith((".", "/")):
+            pkgs.append(Package(line, None, skip="path", origin=path.name))
+            continue
+        if "://" in line and "@" not in line:
+            pkgs.append(Package(line, None, skip="url", origin=path.name))
+            continue
+        pkgs.append(requirement_to_package(line, path.name))
+    return Source(path.name, pkgs)
+
+
+PARSERS = {
+    "uv.lock": parse_uv_lock,
+    "pylock.toml": parse_pylock,
+    "poetry.lock": parse_poetry_lock,
+}
+
+
+def load_file(path: Path) -> Source:
+    name = path.name
+    if name in PARSERS:
+        return PARSERS[name](path)
+    if name.startswith("pylock.") and name.endswith(".toml"):
+        return parse_pylock(path)
+    if name.endswith(".lock") and "uv" in name:
+        return parse_uv_lock(path)
+    if name.endswith((".txt", ".in")):
+        return parse_requirements(path)
+    raise SourceError(f"don't know how to read {path} (expected uv.lock, pylock.toml, poetry.lock or requirements.txt)")
+
+
+def find_lockfile(directory: Path) -> Path:
+    for name in LOCKFILES:
+        candidate = directory / name
+        if candidate.is_file():
+            return candidate
+    raise SourceError(
+        f"no lockfile found in {directory} (looked for {', '.join(LOCKFILES)}). "
+        "Pass a file, or package names like `wheelgap numpy psycopg2`."
+    )
+
+
+def load_inputs(inputs: list[str]) -> list[Source]:
+    """Each input is a file, a directory (lockfile auto-detected) or a requirement like 'numpy==2.3.4'."""
+    sources: list[Source] = []
+    adhoc = Source("command line")
+    for item in inputs:
+        p = Path(item)
+        if p.is_dir():
+            sources.append(load_file(find_lockfile(p)))
+        elif p.is_file():
+            sources.append(load_file(p))
+        elif "/" in item or item.endswith((".lock", ".txt", ".toml")):
+            raise SourceError(f"{item}: no such file")
+        else:
+            adhoc.packages.append(requirement_to_package(item, "command line"))
+    if adhoc.packages:
+        sources.append(adhoc)
+    return sources

wheelgap/targets.py

@@ -0,0 +1,207 @@
+"""Install targets: a Python version on a platform, expanded to the wheel tags it accepts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from functools import cached_property
+
+from packaging import tags
+
+# Short platform name -> (family, arch)
+PLATFORMS: dict[str, tuple[str, str]] = {
+    "linux-x86_64": ("manylinux", "x86_64"),
+    "linux-aarch64": ("manylinux", "aarch64"),
+    "musl-x86_64": ("musllinux", "x86_64"),
+    "musl-aarch64": ("musllinux", "aarch64"),
+    "macos-arm64": ("macos", "arm64"),
+    "macos-x86_64": ("macos", "x86_64"),
+    "win-amd64": ("windows", "win_amd64"),
+    "win-arm64": ("windows", "win_arm64"),
+}
+
+ALIASES: dict[str, str] = {
+    "linux": "linux-x86_64",
+    "linux-amd64": "linux-x86_64",
+    "linux-arm64": "linux-aarch64",
+    "manylinux-x86_64": "linux-x86_64",
+    "manylinux-aarch64": "linux-aarch64",
+    "alpine": "musl-x86_64",
+    "musl": "musl-x86_64",
+    "musl-arm64": "musl-aarch64",
+    "musllinux-x86_64": "musl-x86_64",
+    "musllinux-aarch64": "musl-aarch64",
+    "alpine-arm64": "musl-aarch64",
+    "alpine-aarch64": "musl-aarch64",
+    "mac": "macos-arm64",
+    "macos": "macos-arm64",
+    "macos-aarch64": "macos-arm64",
+    "macos-intel": "macos-x86_64",
+    "windows": "win-amd64",
+    "win": "win-amd64",
+    "windows-amd64": "win-amd64",
+    "windows-x86_64": "win-amd64",
+    "win-x86_64": "win-amd64",
+    "windows-arm64": "win-arm64",
+}
+
+# family -> (sys_platform, platform_system, os_name); arch -> platform_machine
+_MARKER_OS = {
+    "manylinux": ("linux", "Linux", "posix"),
+    "musllinux": ("linux", "Linux", "posix"),
+    "macos": ("darwin", "Darwin", "posix"),
+    "windows": ("win32", "Windows", "nt"),
+}
+_MARKER_MACHINE = {"win_amd64": "AMD64", "win_arm64": "ARM64"}
+
+DEFAULT_PLATFORMS = ["linux-x86_64", "linux-aarch64", "macos-arm64", "win-amd64"]
+
+# Legacy manylinux aliases (PEP 513/571/599) and the glibc minor they map to.
+_LEGACY_MANYLINUX = {17: "manylinux2014", 12: "manylinux2010", 5: "manylinux1"}
+_LEGACY_ARCHES = {
+    "manylinux1": {"x86_64", "i686"},
+    "manylinux2010": {"x86_64", "i686"},
+    "manylinux2014": {"x86_64", "i686", "aarch64", "armv7l", "ppc64", "ppc64le", "s390x"},
+}
+
+_PY_RE = re.compile(r"^(?:cp|py)?(\d)\.?(\d{1,2})(t?)$")
+
+
+class TargetError(ValueError):
+    pass
+
+
+def _norm(name: str) -> str:
+    return name.strip().lower().replace("_", "-")
+
+
+_LOOKUP = {_norm(k): k for k in PLATFORMS} | {_norm(k): v for k, v in ALIASES.items()}
+
+
+def resolve_platform(name: str) -> str:
+    try:
+        return _LOOKUP[_norm(name)]
+    except KeyError:
+        known = ", ".join(PLATFORMS)
+        raise TargetError(f"unknown target {name!r} (known: {known})") from None
+
+
+def parse_python(spec: str) -> tuple[int, int, bool]:
+    """'3.14' -> (3, 14, False); '3.14t' / 'cp314t' -> (3, 14, True)."""
+    m = _PY_RE.match(spec.strip().lower())
+    if not m:
+        raise TargetError(f"can't parse Python version {spec!r} (try 3.13 or 3.14t)")
+    return int(m.group(1)), int(m.group(2)), bool(m.group(3))
+
+
+def parse_version_pair(spec: str, what: str) -> tuple[int, int]:
+    try:
+        major, minor = (int(p) for p in spec.split(".")[:2])
+    except ValueError:
+        raise TargetError(f"can't parse {what} version {spec!r} (expected e.g. 2.36)") from None
+    return major, minor
+
+
+def manylinux_platforms(arch: str, glibc: tuple[int, int]) -> list[str]:
+    major, minor = glibc
+    out = []
+    for m in range(minor, 4, -1):
+        out.append(f"manylinux_{major}_{m}_{arch}")
+        legacy = _LEGACY_MANYLINUX.get(m)
+        if major == 2 and legacy and arch in _LEGACY_ARCHES[legacy]:
+            out.append(f"{legacy}_{arch}")
+    return out
+
+
+def musllinux_platforms(arch: str, musl: tuple[int, int]) -> list[str]:
+    major, minor = musl
+    return [f"musllinux_{major}_{m}_{arch}" for m in range(minor, -1, -1)]
+
+
+@dataclass(frozen=True)
+class Target:
+    major: int
+    minor: int
+    freethreaded: bool
+    platform: str
+    glibc: tuple[int, int] = (2, 36)
+    musl: tuple[int, int] = (1, 2)
+    macos: tuple[int, int] = (14, 0)
+
+    @property
+    def python(self) -> str:
+        return f"{self.major}.{self.minor}{'t' if self.freethreaded else ''}"
+
+    def label(self, with_python: bool) -> str:
+        return f"{self.python} {self.platform}" if with_python else self.platform
+
+    def platform_tags(self) -> list[str]:
+        family, arch = PLATFORMS[self.platform]
+        if family == "manylinux":
+            return manylinux_platforms(arch, self.glibc)
+        if family == "musllinux":
+            return musllinux_platforms(arch, self.musl)
+        if family == "macos":
+            return list(tags.mac_platforms(self.macos, arch))
+        return [arch]
+
+    @cached_property
+    def marker_env(self) -> dict[str, str]:
+        """PEP 508 environment for evaluating markers like `sys_platform == 'win32'`."""
+        family, arch = PLATFORMS[self.platform]
+        sys_platform, system, os_name = _MARKER_OS[family]
+        version = f"{self.major}.{self.minor}"
+        return {
+            "implementation_name": "cpython",
+            "implementation_version": f"{version}.0",
+            "os_name": os_name,
+            "platform_machine": _MARKER_MACHINE.get(arch, arch),
+            "platform_python_implementation": "CPython",
+            "platform_release": "",
+            "platform_system": system,
+            "platform_version": "",
+            "python_full_version": f"{version}.0",
+            "python_version": version,
+            "sys_platform": sys_platform,
+            "extra": "",
+        }
+
+    @cached_property
+    def tags(self) -> frozenset[tags.Tag]:
+        version = (self.major, self.minor)
+        interp = f"cp{self.major}{self.minor}"
+        abi = interp + ("t" if self.freethreaded else "")
+        plats = self.platform_tags()
+        supported = set(tags.cpython_tags(version, [abi], plats))
+        supported.update(tags.compatible_tags(version, interp, plats))
+        return frozenset(supported)
+
+    def accepts(self, wheel_tags: frozenset[tags.Tag]) -> bool:
+        return not self.tags.isdisjoint(wheel_tags)
+
+
+def build_targets(
+    pythons: list[str],
+    platforms: list[str],
+    glibc: str = "2.36",
+    musl: str = "1.2",
+    macos: str = "14.0",
+) -> list[Target]:
+    plats: list[str] = []
+    for item in platforms:
+        for name in item.split(","):
+            if not name.strip():
+                continue
+            if name.strip().lower() == "all":
+                plats.extend(PLATFORMS)
+            else:
+                plats.append(resolve_platform(name))
+    plats = list(dict.fromkeys(plats)) or list(DEFAULT_PLATFORMS)
+
+    pys = list(dict.fromkeys(parse_python(p) for item in pythons for p in item.split(",") if p.strip()))
+    opts = dict(
+        glibc=parse_version_pair(glibc, "glibc"),
+        musl=parse_version_pair(musl, "musl"),
+        macos=parse_version_pair(macos, "macOS"),
+    )
+    return [Target(ma, mi, ft, plat, **opts) for (ma, mi, ft) in pys for plat in plats]

wheelgap-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: wheelgap
+Version: 0.1.0
+Summary: Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.
+Project-URL: Homepage, https://github.com/patrickballard/wheelgap
+Project-URL: Issues, https://github.com/patrickballard/wheelgap/issues
+Project-URL: Changelog, https://github.com/patrickballard/wheelgap/blob/main/CHANGELOG.md
+Author: Patrick Ballard
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alpine,arm64,docker,free-threading,lockfile,musllinux,packaging,pypi,uv,wheels
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.11
+Requires-Dist: packaging>=24.2
+Description-Content-Type: text/markdown
+
+# wheelgap
+
+[![CI](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml/badge.svg)](https://github.com/patrickballard/wheelgap/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+
+**Find the Python dependencies that have no prebuilt wheel for your target platform, before your Docker build does.**
+
+Point it at your lockfile and the platforms you ship to (ARM servers, Alpine images, Windows on ARM, free-threaded Python 3.14t). It tells you which packages pip or uv will have to compile from source, and which can't be installed at all.
+
+![wheelgap demo](docs/demo.gif)
+
+## Install and run (under 30 seconds)
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uvx --from git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Or with pipx:
+
+```bash
+pipx run --spec git+https://github.com/patrickballard/wheelgap wheelgap
+```
+
+Run either one in a project directory. It finds `uv.lock`, `pylock.toml`, `poetry.lock` or `requirements.txt` on its own.
+
+## Usage
+
+```bash
+# Will my Alpine ARM image compile anything?
+wheelgap -p 3.13 -t alpine-arm64
+
+# Is my stack ready for free-threaded Python 3.14?
+wheelgap -p 3.14t -t all
+
+# Several Pythons at once, Linux on both architectures
+wheelgap uv.lock -p 3.12,3.13,3.14 -t linux-x86_64,linux-aarch64
+
+# No lockfile? Check packages directly (latest version, or pin one)
+wheelgap psycopg2 uvloop numpy==2.3.4 -t windows,win-arm64
+
+# Machine-readable, for scripts and CI
+wheelgap --json > wheelgap.json
+```
+
+Each cell in the table is one of:
+
+| cell | meaning |
+| --- | --- |
+| `✓` | a compatible wheel exists, so the install is fast |
+| `● source` | no wheel, only an sdist, so it compiles at install time (needs a compiler, headers, time) |
+| `✗ missing` | no wheel and no sdist, so the install fails |
+| `–` | not installed on this target (environment markers exclude it) |
+
+Packages that are fine everywhere are hidden; `--all` shows them.
+
+**Exit codes:** `0` no gaps, `1` gaps found, `2` bad input. `--exit-zero` always exits `0`.
+
+### Targets
+
+| name | aliases | wheel tags it accepts |
+| --- | --- | --- |
+| `linux-x86_64` | `linux`, `linux-amd64` | `manylinux_2_*_x86_64` up to `--glibc` (default 2.36), legacy `manylinux2014`/`2010`/`1` |
+| `linux-aarch64` | `linux-arm64` | `manylinux_2_*_aarch64` |
+| `musl-x86_64` | `alpine`, `musl` | `musllinux_1_*_x86_64` up to `--musl` (default 1.2) |
+| `musl-aarch64` | `alpine-arm64` | `musllinux_1_*_aarch64` |
+| `macos-arm64` | `macos`, `mac` | `macosx_*_arm64` and `universal2` up to `--macos` (default 14.0) |
+| `macos-x86_64` | `macos-intel` | `macosx_*_x86_64` and `universal2` |
+| `win-amd64` | `windows`, `win` | `win_amd64` |
+| `win-arm64` | `windows-arm64` | `win_arm64` |
+
+`-t all` checks all eight. Python versions take a trailing `t` for free-threaded builds (`3.14t`), which correctly rejects `abi3` wheels. Without `-p`, wheelgap uses the Python it is running on.
+
+### In CI (GitHub Action)
+
+```yaml
+- uses: actions/checkout@v7
+- uses: patrickballard/wheelgap@v0.1.0
+  with:
+    args: uv.lock -p 3.13 -t linux-x86_64,linux-aarch64
+```
+
+The job fails when a dependency would build from source on a target you ship, for example when a dependency bump drops ARM wheels.
+
+## How it works
+
+- **Lockfiles are read offline.** `uv.lock`, `pylock.toml` and `poetry.lock` already record every file published for each pinned version. wheelgap parses the wheel filenames' tags with [`packaging`](https://packaging.pypa.io/) and checks them against the exact tag set each target accepts. That is the same logic pip and uv use to pick a wheel.
+- **`requirements.txt` and bare package names** are looked up on the PyPI JSON API. Feed it a fully pinned file (from `uv pip compile`, `pip-compile` or `uv export`): wheelgap checks the lines you give it and doesn't resolve dependencies.
+- **Environment markers are respected.** A `pywin32 ; sys_platform == 'win32'` dependency won't show up as a Linux gap. For `uv.lock` the dependency graph is walked per target, so transitive platform-specific packages are handled too.
+- `--online` re-checks lockfile packages against PyPI. Use it when a project has uploaded new wheels for an existing version since you locked, or if your `uv.lock` was generated with `environments` restrictions.
+
+## Why this exists
+
+Missing wheels show up late, in the most expensive place:
+
+- Your `python:3.13-alpine` image on an ARM runner takes 25 minutes because two transitive dependencies don't publish `musllinux_aarch64` wheels, and QEMU is compiling them.
+- A build fails with `error: Microsoft Visual C++ 14.0 or greater is required` on a teammate's Snapdragon laptop.
+- You try free-threaded Python 3.14t and half your stack quietly falls back to source builds, because `abi3` wheels don't apply there.
+
+Sites like [pyreadiness.org](https://pyreadiness.org) and [free-threaded wheels](https://hugovk.github.io/free-threaded-wheels/) track the top few hundred packages. wheelgap checks your packages, at your pinned versions, for your targets, in about a second, and it can run in CI.
+
+## Roadmap
+
+- [ ] Pyodide/WebAssembly, iOS and Android targets
+- [ ] Read targets from `[tool.wheelgap]` in `pyproject.toml`
+- [ ] Private indexes (`--index-url`, the simple API)
+- [ ] Infer the target from a `Dockerfile` (`FROM python:3.13-alpine`, `--platform=linux/arm64`)
+- [ ] "Closest version with a wheel" hints (e.g. upgrade `foo` 1.2 → 1.4 to get `musllinux` wheels)
+- [ ] Publish to PyPI so it's just `uvx wheelgap`
+
+Contributions welcome. Issues labelled [good first issue](https://github.com/patrickballard/wheelgap/labels/good%20first%20issue) are a good start, and [CONTRIBUTING.md](CONTRIBUTING.md) has the 3-command dev setup.
+
+## License
+
+[MIT](LICENSE)

wheelgap-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+wheelgap/__init__.py,sha256=aZ0JdyHx07vuIxKePYOpVEcMf9epq5kwg0U6Qdp8ixg,115
+wheelgap/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+wheelgap/check.py,sha256=Dj-CNHcvYm811mj-pA1pnVtGSzG2VLMIAVhmPlCmPnM,4539
+wheelgap/cli.py,sha256=Ma7-ByVpYLs88sIzM8Ab4827baQ_NIeTvYEnWvX085g,9393
+wheelgap/pypi.py,sha256=N-TKUHGF7J-qmNZ7IysziIshqyJ31inhN7bO080aBOk,2020
+wheelgap/sources.py,sha256=W4biwxH5lHcZhhwmqm5YjywMzqIcDfGEAEXTRmkNc7Y,9454
+wheelgap/targets.py,sha256=kttn0IqJO7md8hOb09hXFdTnDAF1u_oP6T5jIcb0Cj8,7020
+wheelgap-0.1.0.dist-info/METADATA,sha256=lChUowMbE1edQmFTSfD141uLWv4Fbug-ToHeHnLCuWs,7024
+wheelgap-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+wheelgap-0.1.0.dist-info/entry_points.txt,sha256=brFpw-P8-gNlf3-Jrlxc0VK8dazuAUPXaL2fWt6jLzk,47
+wheelgap-0.1.0.dist-info/licenses/LICENSE,sha256=LhIJM-PJ5BaE37PoE77nlizKBwzARAbBZw1lqpA7L3A,1072
+wheelgap-0.1.0.dist-info/RECORD,,

wheelgap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

wheelgap-0.1.0.dist-info/entry_points.txt

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

wheelgap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Ballard
+
+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.