CLI apps based on click-app won't work with "uv run" if name doesn't contain hyphens
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 1.5k
- Forks
- 120
- PR merge metrics
- No merged PRs in 30d
Description
This isn't a bug per se, but it may be surprising and worth addressing soon to avoid inconsistency down the line.
Looking at:
https://github.com/simonw/til/blob/main/python/uv-cli-apps.md
If you follow this with "demo" instead of "demo-app" (or any other name without hyphens), then uv run demo will produce this error:
Traceback (most recent call last):
File "<frozen runpy>", line 198, in _run_module_as_main
File "<frozen runpy>", line 88, in _run_code
File "C:\Users\james\projects\demo\demo\__main__.py", line 1, in <module>
from .cli import cli
ImportError: attempted relative import with no known parent package
... assuming it is run at the top-level of the repo. The problem is that there's a demo subdirectory and uv resolves the ambiguity by attempting to run that subdirectory as a module from the parent directory, instead of running the demo executable. The preferred directory structure for uv (based on uv init --app --package) is to nest the demo package under an src directory. That fixes the issue.
If it's helpful, check out my fork of click-app which both fixes this issue and uses uv throughout the repo (e.g. for GitHub actions, based on uv's own docs), adhering more closely to uv init conventions in pyproject.toml (e.g. hatchling as a build backend).
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with python/uv-cli-apps.md and compare the documented demo-app layout with a demo layout that has no hyphens. Run uv run demo from the repository root to reproduce the ImportError, then verify that the documentation presents a consistent layout or clearly explains the required structure.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100