python-wheels 0.1.0__tar.gz

python_wheels-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: python -m pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Tag must match package version
+        run: |
+          v=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('src/pywheels/__init__.py').read_text()).group(1))")
+          test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != v$v"; exit 1; }
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/python-wheels/
+    permissions:
+      id-token: write # The only permission PyPI Trusted Publishing requires
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

python_wheels-0.1.0/.github/workflows/smoke-test-pywheels-install.yml

@@ -0,0 +1,90 @@
+name: smoke-test-pywheels-install
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - '.github/workflows/smoke-test-pywheels-install.yml'
+      - 'pywheels/**'
+      - 'src/pywheels/**'
+
+jobs:
+  install-on-win-arm64:
+    runs-on: windows-11-arm
+    env:
+      PYWHEELS_REPO: patrickryankenneth/python-wheels-builds
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ⚡ Restore Python toolcache: takes ~3 seconds instead of 3 minutes
+      - name: Cache Python toolcache (Windows ARM64)
+        uses: actions/cache@v4
+        with:
+          path: C:\hostedtoolcache\windows\Python
+          key: toolcache-python-3.11-win-arm64
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: System info
+        shell: pwsh
+        run: |
+          [System.Environment]::OSVersion
+          $env:PROCESSOR_ARCHITECTURE
+          python -c "import platform; print(platform.machine(), platform.architecture())"
+
+      - name: Install pywheels from source (with sigstore extra)
+        shell: pwsh
+        # The sigstore extra makes `doctor`/`verify_wheel`'s "auto" backend
+        # selection prefer sigstore over gh (see verify.py: sigstore_available()
+        # is checked first). sigstore verifies fully offline against the
+        # bundle file github_release.py already downloaded via plain
+        # urllib, so it never calls `gh attestation download` at all - it
+        # sidesteps whatever is failing there entirely, whatever the actual
+        # cause turns out to be (see verify.py's archive_check_error, which
+        # now surfaces that cause instead of swallowing it, for if/when the
+        # gh backend needs debugging directly).
+        run: pip install -e "."
+
+      - name: Check backend availability
+        shell: pwsh
+        run: pywheels doctor
+
+      - name: pywheels install (should fall through to our repo on this platform)
+        shell: pwsh
+        run: |
+          pywheels install dbt-oss==2.0.5 `
+            --tag dbt-oss-v2.0.5 `
+            --workflow build-dbt-oss-win-arm64.yml `
+            -v | Tee-Object -FilePath install-output.txt
+
+      - name: Assert the override actually detected the win-arm64 gap
+        shell: pwsh
+        run: |
+          if (Select-String -Path install-output.txt -Pattern "upstream has wheels" -Quiet) {
+            Write-Error "expected the upstream check to FAIL on win-arm64 (dbt-oss's manifest has no win_arm64 entry) - it reported success instead. Either the override broke, or upstream now ships a real win_arm64 wheel and this override can be retired."
+            exit 1
+          }
+          if (-not (Select-String -Path install-output.txt -Pattern "verified OK" -Quiet)) {
+            Write-Error "expected our repo's wheel to verify OK here - it didn't. See the full output above."
+            exit 1
+          }
+          Write-Host "confirmed: upstream check correctly failed on this platform, our wheel verified instead"
+
+      - name: Run the exact command pywheels recommended
+        shell: pwsh
+        run: |
+          $line = Select-String -Path install-output.txt -Pattern '^\s\s+pip install' | Select-Object -First 1
+          if (-not $line) { Write-Error "no 'pip install' line found in pywheels' output"; exit 1 }
+          $cmd = $line.Line.Trim()
+          Write-Host "running: $cmd"
+          Invoke-Expression $cmd
+
+      - name: Functional check - does the installed package actually run
+        shell: pwsh
+        run: |
+          python -c "import dbt; print('imported OK from', dbt.__file__)"
+          pip show dbt-oss

python_wheels-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# --- Python bytecode / cache ---
+__pycache__/
+*.py[cod]
+*$py.class
+
+# --- Build artifacts (setuptools and hatchling both use these) ---
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# --- pywheels' own local scratch space ---
+# .pywheels-cache/ is cli.py's --workdir default (where `pywheels verify`
+# downloads release assets to when not using --local-dir).
+# release-assets/ looks like the same kind of thing from manual testing -
+# if it's meant to be committed as test fixtures, remove this line and
+# `git add -f` it instead.
+.pywheels-cache/
+release-assets/
+
+# --- Virtual environments ---
+# Matches any dir ending in "env" - venv, .venv, env, my-project-env,
+# whatever you or anyone else names theirs - so this never needs a
+# personal/local env name added to it.
+*env/
+*ENV/
+
+# --- Editors / OS cruft ---
+.vscode/
+.idea/
+.DS_Store
+
+# --- Test/type-check caches, if you add pytest/mypy/ruff later ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

python_wheels-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-09-23
+
+Initial release.
+
+`pywheels` verifies that a wheel from [python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds)
+was actually built by that repo's own GitHub Actions workflow before you
+install it - not just downloaded from somewhere plausible. It checks two
+required attestations (SLSA build provenance, plus our own
+upstream-source attestation) against the exact signer identity, and, when
+a source archive is available, that the archive's digest matches what the
+attestation recorded.
+
+### Added
+
+- `pywheels verify` - verify a wheel's attestations directly, either
+  fetched from a GitHub release (`--tag`) or already sitting on disk
+  (`--local-dir`, e.g. output of `gh run download`).
+- `pywheels install` - the main workflow: check whether pip can already
+  resolve real wheels for a package on the current platform; if not,
+  fetch and verify our attested build instead; print the exact
+  `pip install` command that's safe to run, or fall back to an
+  unverified source build as a last resort. Never runs `pip install`
+  itself.
+- `pywheels doctor` - reports which verification backend(s) are usable
+  and how to fix the ones that aren't.
+- Two independent verification backends: `sigstore` (offline, needs the
+  optional `sigstore` extra) and the `gh` CLI (needs network, no pip
+  dependency). Falls back from the former to the latter automatically;
+  refuses to trust a wheel if neither is available.
+- Per-package build-detection overrides (`overrides.json`) for packages
+  whose real wheel availability isn't visible to plain `pip download`
+  probing - e.g. `dbt-oss`, whose PyPI sdist is a stub build backend that
+  fetches a real prebuilt wheel from GitHub, keyed by platform.
+- Initial attested build: `dbt-oss` for `win_arm64`, filling a real gap
+  upstream doesn't cover on that platform yet.
+
+[0.1.0]: https://github.com/patrickryankenneth/python-wheels/releases/tag/v0.1.0

python_wheels-0.1.0/LICENSE

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

python_wheels-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: python-wheels
+Version: 0.1.0
+Summary: Verify Sigstore-attested wheels from python-wheels-builds before installing
+Project-URL: Homepage, https://github.com/patrickryankenneth/python-wheels
+Project-URL: Builds, https://github.com/patrickryankenneth/python-wheels-builds
+Project-URL: Index, https://python-wheels.github.io
+Project-URL: Issues, https://github.com/patrickryankenneth/python-wheels/issues
+Project-URL: Changelog, https://github.com/patrickryankenneth/python-wheels/blob/main/CHANGELOG.md
+Author-email: Patrick Ryan <patrickryankenneth@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attestation,pip,provenance,sigstore,slsa,supply-chain,wheels
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.9
+Provides-Extra: sigstore
+Requires-Dist: sigstore<4.6,>=4.0; extra == 'sigstore'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# python-wheels
+
+**Status: working - v0.1.0.** The `python-wheels` CLI (command: `pywheels`,
+also installed as `python-wheels`) verifies and installs attested wheels
+today. First attested build shipped: `dbt-oss` for `win_arm64`.
+
+## The problem
+
+Some Python packages don't ship a wheel for your platform: an
+uncommon architecture, Alpine/musl instead of glibc, an OS upstream doesn't
+target, or just a combination nobody's gotten around to building for. Right
+now the options are "build it from source yourself, every time" or "hope
+someone in the community hosts one somewhere."
+
+It's also not always upstream being lazy. PyPI caps a project at 10GB of
+total storage, and wheels for every platform/arch/Python-version
+combination add up fast - that's part of why projects like PyTorch host
+some of their wheels off-PyPI and point people at an extra index instead.
+`python-wheels` is aimed at exactly that situation: popular packages that
+can't or don't publish a wheel for your platform, for any reason.
+
+## What it does
+
+```bash
+pip install python-wheels
+pywheels install dbt-oss==2.0.5 \
+  --repo patrickryankenneth/python-wheels-builds \
+  --tag dbt-oss-v2.0.5 \
+  --workflow build-dbt-oss-win-arm64.yml
+```
+
+1. **Checks upstream first.** If pip can already resolve real wheels for
+   the package - and its whole dependency closure, not just the top-level
+   package - on your platform, it says so and prints the plain
+   `pip install` command; this tool gets out of the way whenever upstream
+   already has you covered. A small per-package override list
+   (`overrides.json`) handles the rare case where a package's real wheel
+   availability is hidden from pip's normal resolution - e.g. `dbt-oss`,
+   whose PyPI sdist is a stub build backend that fetches a real prebuilt
+   wheel from GitHub, keyed by platform, with no source to fall back to.
+2. **Falls back, but verifies.** If there's no usable upstream wheel, it
+   fetches the matching release from
+   [python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds)
+   and checks, before recommending anything:
+   - its **build provenance attestation** (SLSA - built by the expected CI
+     workflow, from the expected repo and ref, unmodified since),
+   - its **upstream-source attestation** (built from the real, tagged
+     upstream release - not a fork or a patched copy),
+   - the **source archive's digest** against what that attestation
+     recorded, when a source archive is available.
+
+   Verification runs offline via [sigstore](https://pypi.org/project/sigstore/)
+   (`pip install python-wheels[sigstore]`) if it's installed, or falls back
+   to the `gh` CLI (no pip dependency, needs network) if it isn't. Run
+   `pywheels doctor` to see which backend is usable on your machine.
+3. **Fails loudly, not silently.** `pywheels install` never runs
+   `pip install` for you - it only ever prints the exact command that's
+   safe to run. If verification fails, or neither backend is available at
+   all, it says so plainly and falls back to `pip install
+   --no-binary=:all:` (unverified, from source) as the last resort - never
+   a silent, unattested install.
+
+`pywheels verify` runs the same verification directly against a wheel
+that's already on disk, or a specific release tag - useful for checking a
+build without going through the whole `install` flow.
+
+## Where the wheels actually come from
+
+This repo is only the installer and verifier. The wheels themselves are
+built and attested in
+[python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds),
+and also served as a plain [PEP 503](https://peps.python.org/pep-0503/)
+index at [python-wheels.github.io](https://python-wheels.github.io) for
+anyone who just wants `pip install --extra-index-url
+https://python-wheels.github.io/simple/ <package>` without the
+verification step. `pywheels` is the piece that ties the CLI, the
+release repo, and the attestation checks together so you don't have to run
+`gh attestation verify` by hand.
+
+## Longer-term direction
+
+The build side is currently one hand-tuned workflow for one package
+(`dbt-oss`/`dbt-core` on Windows ARM64). The goal is to turn that into a
+standardized, reproducible build recipe that can target other popular PyPI
+packages missing wheels for a given platform - starting with the platforms
+that come up most often (Alpine/musl, less-common architectures, newer
+Python versions upstream hasn't built for yet), rather than trying to
+cover everything at once.
+
+## Not yet decided
+
+- CLI surface beyond `install`/`verify`/`doctor` (list available
+  platforms? show why a package fell back? a way to request a new
+  package/platform combo?)
+- How package/platform requests get prioritized once this covers more than
+  one package
+- Whether to eventually provide a wrapper mode that invokes pip directly after verification, 
+  versus keeping the strict "print the safe command only" separation.
+
+Contributions and issues on any of the above are welcome - this project is
+still early, even with a first attested build shipped.

python_wheels-0.1.0/README.md

@@ -0,0 +1,101 @@
+# python-wheels
+
+**Status: working - v0.1.0.** The `python-wheels` CLI (command: `pywheels`,
+also installed as `python-wheels`) verifies and installs attested wheels
+today. First attested build shipped: `dbt-oss` for `win_arm64`.
+
+## The problem
+
+Some Python packages don't ship a wheel for your platform: an
+uncommon architecture, Alpine/musl instead of glibc, an OS upstream doesn't
+target, or just a combination nobody's gotten around to building for. Right
+now the options are "build it from source yourself, every time" or "hope
+someone in the community hosts one somewhere."
+
+It's also not always upstream being lazy. PyPI caps a project at 10GB of
+total storage, and wheels for every platform/arch/Python-version
+combination add up fast - that's part of why projects like PyTorch host
+some of their wheels off-PyPI and point people at an extra index instead.
+`python-wheels` is aimed at exactly that situation: popular packages that
+can't or don't publish a wheel for your platform, for any reason.
+
+## What it does
+
+```bash
+pip install python-wheels
+pywheels install dbt-oss==2.0.5 \
+  --repo patrickryankenneth/python-wheels-builds \
+  --tag dbt-oss-v2.0.5 \
+  --workflow build-dbt-oss-win-arm64.yml
+```
+
+1. **Checks upstream first.** If pip can already resolve real wheels for
+   the package - and its whole dependency closure, not just the top-level
+   package - on your platform, it says so and prints the plain
+   `pip install` command; this tool gets out of the way whenever upstream
+   already has you covered. A small per-package override list
+   (`overrides.json`) handles the rare case where a package's real wheel
+   availability is hidden from pip's normal resolution - e.g. `dbt-oss`,
+   whose PyPI sdist is a stub build backend that fetches a real prebuilt
+   wheel from GitHub, keyed by platform, with no source to fall back to.
+2. **Falls back, but verifies.** If there's no usable upstream wheel, it
+   fetches the matching release from
+   [python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds)
+   and checks, before recommending anything:
+   - its **build provenance attestation** (SLSA - built by the expected CI
+     workflow, from the expected repo and ref, unmodified since),
+   - its **upstream-source attestation** (built from the real, tagged
+     upstream release - not a fork or a patched copy),
+   - the **source archive's digest** against what that attestation
+     recorded, when a source archive is available.
+
+   Verification runs offline via [sigstore](https://pypi.org/project/sigstore/)
+   (`pip install python-wheels[sigstore]`) if it's installed, or falls back
+   to the `gh` CLI (no pip dependency, needs network) if it isn't. Run
+   `pywheels doctor` to see which backend is usable on your machine.
+3. **Fails loudly, not silently.** `pywheels install` never runs
+   `pip install` for you - it only ever prints the exact command that's
+   safe to run. If verification fails, or neither backend is available at
+   all, it says so plainly and falls back to `pip install
+   --no-binary=:all:` (unverified, from source) as the last resort - never
+   a silent, unattested install.
+
+`pywheels verify` runs the same verification directly against a wheel
+that's already on disk, or a specific release tag - useful for checking a
+build without going through the whole `install` flow.
+
+## Where the wheels actually come from
+
+This repo is only the installer and verifier. The wheels themselves are
+built and attested in
+[python-wheels-builds](https://github.com/patrickryankenneth/python-wheels-builds),
+and also served as a plain [PEP 503](https://peps.python.org/pep-0503/)
+index at [python-wheels.github.io](https://python-wheels.github.io) for
+anyone who just wants `pip install --extra-index-url
+https://python-wheels.github.io/simple/ <package>` without the
+verification step. `pywheels` is the piece that ties the CLI, the
+release repo, and the attestation checks together so you don't have to run
+`gh attestation verify` by hand.
+
+## Longer-term direction
+
+The build side is currently one hand-tuned workflow for one package
+(`dbt-oss`/`dbt-core` on Windows ARM64). The goal is to turn that into a
+standardized, reproducible build recipe that can target other popular PyPI
+packages missing wheels for a given platform - starting with the platforms
+that come up most often (Alpine/musl, less-common architectures, newer
+Python versions upstream hasn't built for yet), rather than trying to
+cover everything at once.
+
+## Not yet decided
+
+- CLI surface beyond `install`/`verify`/`doctor` (list available
+  platforms? show why a package fell back? a way to request a new
+  package/platform combo?)
+- How package/platform requests get prioritized once this covers more than
+  one package
+- Whether to eventually provide a wrapper mode that invokes pip directly after verification, 
+  versus keeping the strict "print the safe command only" separation.
+
+Contributions and issues on any of the above are welcome - this project is
+still early, even with a first attested build shipped.

python_wheels-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-wheels"
+dynamic = ["version"]
+description = "Verify Sigstore-attested wheels from python-wheels-builds before installing"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Patrick Ryan", email = "patrickryankenneth@gmail.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["wheels", "pip", "sigstore", "attestation", "supply-chain", "slsa", "provenance"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Security",
+  "Topic :: System :: Software Distribution",
+]
+# No required deps, and none planned - the whole design is "verify with
+# whatever's already there" (sigstore if installed, else the `gh` binary,
+# which isn't a pip dependency at all). Nothing here needs a transitive
+# dependency pinned either, for the same reason.
+dependencies = []
+
+# sigstore is optional: pywheels falls back to the `gh` CLI (a system
+# binary, not a pip dependency) if it's absent, and fails closed - refuses
+# to treat a wheel as trusted - only if NEITHER is available. See
+# pywheels/verify.py and `pywheels doctor`.
+#
+# Pinned to a range, not left open-ended: 4.0 <= version < 4.6 is the
+# range this scaffold was actually built and tested against (4.5.0, at
+# time of writing). Bump the upper bound deliberately after testing a
+# newer release, rather than always taking latest - a brand-new release
+# hasn't had time to be exercised by the broader ecosystem yet, which
+# matters more for a security-verification dependency than for most
+# others. We can pin our own dependency this way; we can't pin the `gh`
+# CLI or git the same way since they're not pip packages - the closest
+# equivalent there is installing them via your OS's package manager
+# (apt/brew/choco) rather than a bleeding-edge standalone installer, since
+# distro packaging tends to lag upstream by a bit, which is a feature here.
+[project.optional-dependencies]
+sigstore = ["sigstore>=4.0,<4.6"]
+test = ["pytest>=8"]
+
+[project.scripts]
+pywheels = "pywheels.cli:main"
+python-wheels = "pywheels.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/patrickryankenneth/python-wheels"
+Builds = "https://github.com/patrickryankenneth/python-wheels-builds"
+Index = "https://python-wheels.github.io"
+Issues = "https://github.com/patrickryankenneth/python-wheels/issues"
+Changelog = "https://github.com/patrickryankenneth/python-wheels/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/pywheels/__init__.py"
+
+# hatchling's default package discovery looks for a directory matching the
+# normalized project name (python-wheels -> python_wheels). Our importable
+# package is still named `pywheels/` on purpose (see the pyproject/import
+# naming discussion elsewhere), and it now lives under src/ - so it has to
+# be told explicitly where to find it, or the wheel build will fail to
+# locate any package at all. Giving "src/pywheels" (not just "pywheels")
+# is what tells hatchling to strip the src/ prefix - the wheel still ends
+# up with a top-level `pywheels/`, so nothing about the import path or the
+# [project.scripts] entry points below changes.
+[tool.hatch.build.targets.wheel]
+packages = ["src/pywheels"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

python_wheels-0.1.0/src/pywheels/__init__.py

@@ -0,0 +1,5 @@
+"""pywheels: verify Sigstore-attested wheels from python-wheels-builds
+before installing. See cli.py for the command-line interface and
+verify.py for the verification logic itself."""
+
+__version__ = "0.1.0"