Skip to content

refactor: remove poetry traces and add uv tool run fallback for cookiecutter #808

@hartym

Description

@hartym

Summary

TLDR - Remove remaining Poetry references from CLI commands and add uv tool run as a fallback for running cookiecutter when it's not installed as a Python package. This completes the UV migration for user-facing tooling.

Context

The harp create project command uses cookiecutter to generate new projects. Currently:

  • The error message references poetry install -E dev (line 18 in harp/commandline/create.py)
  • The docs development command uses poetry run sphinx-autobuild (line 94 in harp/commandline/utils/manager.py)

The cookiecutter templates themselves have already been migrated to UV (using hatchling, UV-based Makefiles).

Files to modify

  • harp/commandline/create.py - cookiecutter invocation and error message
  • harp/commandline/utils/manager.py - docs command

Implementation

Cookiecutter invocation strategy

Use subprocess consistently in both cases for simpler, more predictable behavior:

  1. Check if cookiecutter is available as an installed package → run via subprocess.run(["cookiecutter", ...])
  2. If not found, check if uv is available → run via subprocess.run(["uv", "tool", "run", "cookiecutter", ...])
  3. If neither is available, show error with UV-based installation instructions
# Pseudocode flow:
if shutil.which("cookiecutter"):
    subprocess.run(["cookiecutter", template_path], check=True)
elif shutil.which("uv"):
    subprocess.run(["uv", "tool", "run", "cookiecutter", template_path], check=True)
else:
    raise UsageError("Install cookiecutter with `uv add harp-proxy --extra dev` or ensure `uv` is available to run it via `uv tool run`.")

This approach:

  • Removes the need to import cookiecutter as a Python module
  • Makes both code paths behave identically (subprocess)
  • Simplifies error handling

Error message update

Change error message from:

"You need to install cookiecutter to use this command (or use the dev extra, for example using pip install harp-proxy[dev] or poetry install -E dev)."

To:

"Install cookiecutter with uv add harp-proxy --extra dev or ensure uv is available to run it via uv tool run."

Docs command update

Change harp/commandline/utils/manager.py:94 from:

"poetry run sphinx-autobuild . _build/html"

To:

"uv run sphinx-autobuild . _build/html"

Testing Scenarios

  1. Happy Path (cookiecutter installed): cookiecutter binary available → runs via subprocess
  2. Happy Path (uv fallback): cookiecutter not found, uv available → runs uv tool run cookiecutter
  3. Error Case: Neither cookiecutter nor uv available → shows UV-only error message

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions