docs(build): venvs, and why pipx install ./src/packages/api fails - #33
Merged
Merged
Conversation
Someone hit this for real: pipx reports "pip seemed to fail to build package: fastapi>=0.110", which is a guess from where pip's output stopped, while the actual error two lines down is that `helpmate<0.20,>=0.19.0` has "versions: none" -- it is built from this tree, not published to PyPI. pipx also gives every application its own isolated venv, so a helpmate installed elsewhere cannot satisfy it. The section names the red herring, explains the isolation, and gives the fix (`--preinstall "$PWD"`, repeatable for the dashboard), verified end to end: helpmate-api 0.19.0 with both console scripts. It also covers the plain venv route and points at the FetchContent hang that applies to the preinstall build too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DFQB6YogM3gaauunTfMuxW
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
1 participant
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.
Summary
A user trying
pipx install ./src/packages/apigot this and could not place it:FastAPI is a red herring: pipx guesses the culprit from where pip's output stopped. The real cause is that
helpmateis built from this tree and is not on PyPI, and pipx gives every application its own isolated venv, so ahelpmateinstalled globally or in the active venv cannot satisfy the dependency. BUILD.md mentioned neither venvs nor pipx.The new section under "Python package (pip)" covers the plain venv route, names the red herring, explains the isolation, and gives the fix (
--preinstall "$PWD", repeatable for the dashboard), with the note that the preinstall compiles the core again and re-runs FetchContent, so the documented hang applies there too.Test plan
PIPX_HOME:pipx install ./src/packages/api --preinstall <repo>installs helpmate-api 0.19.0 with workinghelpmate-serverandhelpmate-tables--preinstallsemantics confirmed against pipx 1.17.2: "Optional package to be installed into the Virtual Environment before installing the main package"make lintclean;tests/repounchanged (the four failures on this box are the pre-existing stale-wheel version checks, 0.17.0 installed vs 0.19.0 in the tree)🤖 Generated with Claude Code
https://claude.ai/code/session_01DFQB6YogM3gaauunTfMuxW