simonw / simonw/til

CLI apps based on click-app won't work with "uv run" if name doesn't contain hyphens

Open
#97 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.