Skip to content

docs: add wheel to the documented local build dependencies - #1228

Open
MohammedAlkindi wants to merge 1 commit into
anthropics:mainfrom
MohammedAlkindi:docs/readme-wheel-build-dep
Open

docs: add wheel to the documented local build dependencies#1228
MohammedAlkindi wants to merge 1 commit into
anthropics:mainfrom
MohammedAlkindi:docs/readme-wheel-build-dep

Conversation

@MohammedAlkindi

Copy link
Copy Markdown

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.py retags the wheel platform-specific by running python -m wheel tags via sys.executable — the ambient interpreter. Without the wheel package that subprocess exits 1, and build_wheel.py:214-216 downgrades the failure to a warning. No exception is raised, so main() runs on to print("Build complete!") and exits 0.

Before — README's exact install line and exact command, in a clean venv (Windows, Python 3.13):

$ pip install build twine
$ python scripts/build_wheel.py
Old: claude_agent_sdk-0.2.143-py3-none-any.whl
Warning: Failed to retag wheel: ...\venv\Scripts\python.exe: No module named wheel
Checking dist\claude_agent_sdk-0.2.143-py3-none-any.whl: PASSED
Package check passed
Build complete!
$ echo $?
0

The artifact left in dist/ is claude_agent_sdk-0.2.143-py3-none-any.whl, whose metadata reads Tag: py3-none-any and Root-Is-Purelib: true while the archive contains claude_agent_sdk/_bundled/claude.exe. twine check passes it, so the documented flow's own safety net does not catch it either.

After — same venv, same command, pip install wheel the only change:

Old: claude_agent_sdk-0.2.143-py3-none-any.whl
New: claude_agent_sdk-0.2.143-py3-none-win_amd64.whl
Wheel retagged successfully
Build complete!

Tag: py3-none-win_amd64.

Why the README is the right place

Both wheel-building CI jobs already install it — build-and-publish.yml:30 and build-wheel-check.yml:44 both read pip install build twine wheel. README.md:312 is the only place in the repo that states the list without it. (build-and-publish.yml:92 is the sdist job, which correctly does not need it.)

build does not depend on wheel — its requires_dist is packaging, pyproject_hooks, colorama on Windows — so pip install build twine never provides it. I confirmed in fresh venvs on 3.13 and 3.14 that python -m wheel tags is unavailable after the documented install.

This appears to be a missed second copy rather than a decision: #283 added the same pip install build twine line to both publish.yml and this README, and #345 fixed only the workflow the next day.

Deliberately not included

  • [build-system] requires. I tested requires = ["hatchling", "wheel"] and it does not fix this: wheel gets installed into hatchling's isolated PEP 517 environment, while retag_wheel shells out to the outer interpreter, so the retag still fails and the artifact is still py3-none-any.
  • Making build_wheel.py fail 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 WHEEL metadata and the presence of claude.exe inside the mistagged archive; that build does not pull wheel on 3.13 or 3.14; that the [build-system] requires alternative leaves the artifact unchanged; and that README.md:312 is the only occurrence of the list without wheel. I did not test macOS or Linux — the cross-platform evidence is this repo's own CI matrix, which already installs wheel.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant