docs: add wheel to the documented local build dependencies - #1228
Open
MohammedAlkindi wants to merge 1 commit into
Open
docs: add wheel to the documented local build dependencies#1228MohammedAlkindi wants to merge 1 commit into
MohammedAlkindi wants to merge 1 commit into
Conversation
scripts/build_wheel.py retags the built wheel platform-specific by running `python -m wheel tags` in the ambient interpreter. Without the wheel package that subprocess exits 1, and build_wheel.py downgrades the failure to a warning, so main() runs on and prints "Build complete!" with exit 0. The artifact left in dist/ is tagged py3-none-any with Root-Is-Purelib: true while containing the platform-specific bundled CLI, and twine check passes it. Both wheel-building CI jobs already install it (build-and-publish.yml line 30, build-wheel-check.yml line 44). The README is the only place that omits it, and build does not depend on wheel, so the documented `pip install build twine` never provides it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Following the "Building Wheels Locally" instructions on a clean checkout produces a wheel with the wrong tag, and the build reports success.
scripts/build_wheel.pyretags the wheel platform-specific by runningpython -m wheel tagsviasys.executable— the ambient interpreter. Without thewheelpackage that subprocess exits 1, andbuild_wheel.py:214-216downgrades the failure to a warning. No exception is raised, somain()runs on toprint("Build complete!")and exits 0.Before — README's exact install line and exact command, in a clean venv (Windows, Python 3.13):
The artifact left in
dist/isclaude_agent_sdk-0.2.143-py3-none-any.whl, whose metadata readsTag: py3-none-anyandRoot-Is-Purelib: truewhile the archive containsclaude_agent_sdk/_bundled/claude.exe.twine checkpasses it, so the documented flow's own safety net does not catch it either.After — same venv, same command,
pip install wheelthe only change:Tag: py3-none-win_amd64.Why the README is the right place
Both wheel-building CI jobs already install it —
build-and-publish.yml:30andbuild-wheel-check.yml:44both readpip install build twine wheel.README.md:312is the only place in the repo that states the list without it. (build-and-publish.yml:92is the sdist job, which correctly does not need it.)builddoes not depend onwheel— itsrequires_distispackaging,pyproject_hooks,coloramaon Windows — sopip install build twinenever provides it. I confirmed in fresh venvs on 3.13 and 3.14 thatpython -m wheel tagsis unavailable after the documented install.This appears to be a missed second copy rather than a decision: #283 added the same
pip install build twineline to bothpublish.ymland this README, and #345 fixed only the workflow the next day.Deliberately not included
[build-system] requires. I testedrequires = ["hatchling", "wheel"]and it does not fix this:wheelgets installed into hatchling's isolated PEP 517 environment, whileretag_wheelshells out to the outer interpreter, so the retag still fails and the artifact is stillpy3-none-any.build_wheel.pyfail loudly instead of warning. Probably worth doing, but it is a behaviour change to release machinery and a separate concern, so I left it out rather than bundle it. Happy to open it separately if you want it.Severity is bounded and I want to be straight about it: the publish job verifies all five expected platform wheels are present and exits 1 if any is missing, so a swallowed retag cannot reach PyPI — 0.2.143 shipped all five platform wheels. This affects the local/manual build path, which is exactly the path this README section documents.
AI assistance: I used Claude Code for this investigation. Verified myself on my own machine rather than taken on trust: the before/after builds above, run with the README's exact install line and exact command in a clean venv; the
WHEELmetadata and the presence ofclaude.exeinside the mistagged archive; thatbuilddoes not pullwheelon 3.13 or 3.14; that the[build-system] requiresalternative leaves the artifact unchanged; and thatREADME.md:312is the only occurrence of the list withoutwheel. I did not test macOS or Linux — the cross-platform evidence is this repo's own CI matrix, which already installswheel.