uv Package Manager Guide for Katana OpenAPI Client¶

This document provides common uv commands for working with the Katana OpenAPI Client project.

Task Runner (Poe)¶

This project uses poethepoet as a task runner, which works seamlessly with uv. All development commands are run through uv run poe:

# Show all available tasks
uv run poe help

# Quick development workflow
uv run poe check    # format-check + lint + test
uv run poe fix      # format + lint-fix
uv run poe ci       # Full CI pipeline

Why uv?¶

This project migrated from Poetry to uv for significant performance improvements:

10-100x faster dependency resolution
5x faster installation (~5-10s vs ~26s)
Modern tooling - Written in Rust by Astral (makers of Ruff)
Standards compliant - Uses PEP 621 format
Simpler - One tool replacing multiple (pip, pip-tools, virtualenv, etc.)

See ADR-009 for the full migration rationale.

Basic Commands¶

Project Management¶

# Check uv version
uv --version

# Show project info
uv tree

# List installed packages
uv pip list

# Show outdated packages
uv pip list --outdated

Environment Management¶

# Install all dependencies (including all extras)
uv sync --all-extras

# Install only production dependencies
uv sync

# Install specific extra groups
uv sync --extra dev
uv sync --extra docs

# Show environment info
uv venv

Workspace Management¶

This project uses uv workspace for monorepo management with multiple packages:

# Sync all workspace packages
uv sync --all-extras

# Check workspace structure
uv tree

# The workspace includes:
# - katana-openapi-client (main package, current directory)
# - katana-mcp-server (MCP server package, separate directory)

Note: The workspace is configured in the root pyproject.toml with:

[tool.uv.workspace]
members = [".", "katana_mcp_server"]

This allows both packages to share a unified lock file (uv.lock) and ensures version compatibility. See ADR-010 for the architectural rationale.

Package Management¶

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Remove a dependency
uv remove package-name

# Update all dependencies
uv lock --upgrade

# Update specific package
uv lock --upgrade-package package-name

Testing¶

Run Tests¶

# Run all tests
uv run poe test

# Run tests with coverage
uv run poe test-coverage

# Run specific test categories
uv run poe test-unit
uv run poe test-integration

# Run with specific pytest options
uv run pytest -x  # Stop on first failure
uv run pytest tests/test_katana_client.py  # Specific file
uv run pytest -v  # Verbose output

Code Quality¶

# Format code
uv run poe format          # Format all (Python + Markdown)
uv run poe format-python   # Python only
uv run poe format-check    # Check formatting

# Linting
uv run poe lint            # All linters
uv run poe lint-ruff       # Ruff linting
uv run poe typecheck       # Type checking (ty)
uv run poe lint-yaml       # YAML linting

OpenAPI Development¶

# Regenerate client from OpenAPI spec
uv run poe regenerate-client

# Validate OpenAPI specification
uv run poe validate-openapi

Test Categories¶

# Run only unit tests
uv run pytest -m unit

# Run only integration tests
uv run pytest -m integration

# Skip slow tests
uv run pytest -m "not slow"

Development¶

Running Python Code¶

# Run Python directly in the project environment
uv run python

# Run a specific script
uv run python your_script.py

# Run a module
uv run python -m module_name

# Quick import test
uv run python -c "from katana_public_api_client import KatanaClient; print('✅ Import successful')"

Interactive Development¶

# Open IPython shell (if installed)
uv run ipython

# Or standard Python REPL
uv run python

# Run a Jupyter notebook
uv run jupyter notebook

Building and Publishing¶

Build Package¶

# Build wheel and source distribution
uv build

# Check built packages
ls dist/

The build uses hatchling as the backend (configured in pyproject.toml).

Documentation¶

Build and Serve Docs¶

# Build documentation
uv run poe docs-build

# Serve documentation locally
uv run poe docs-serve

# Auto-rebuild on changes
uv run poe docs-autobuild

# Clean build artifacts
uv run poe docs-clean

Example Usage¶

Testing the Client¶

# Quick import test
uv run python -c "from katana_public_api_client import KatanaClient; print('✅ Import successful')"

# Run a specific test
uv run pytest tests/test_katana_client.py::TestKatanaClient::test_client_initialization -v

# Check test coverage for specific module
uv run pytest tests/ --cov=katana_public_api_client.katana_client --cov-report=term-missing

Development Workflow¶

# 1. Install dependencies
uv sync --all-extras

# 2. Make changes to code

# 3. Run tests
uv run poe test

# 4. Check formatting and linting
uv run poe check

# 5. Fix any issues
uv run poe fix

# 6. Check coverage
uv run poe test-coverage

Pre-commit Hooks¶

# Install pre-commit hooks
uv run poe pre-commit-install

# Run pre-commit on all files manually
uv run poe pre-commit-run

# Update pre-commit hook versions
uv run poe pre-commit-update

Troubleshooting¶

Common Issues¶

# Lock file issues - regenerate
uv lock

# Clear cache
rm -rf .venv
uv sync --all-extras

# Force reinstall all packages
uv sync --reinstall

# Verbose output for debugging
uv sync --verbose

Performance Tips¶

uv is already extremely fast, but you can optimize further:

# Use frozen mode (don't update lock file)
uv sync --frozen

# Use locked mode (assert lock file unchanged)
uv sync --locked

# Skip development dependencies for production
uv sync --no-dev

Command Comparison: Poetry → uv¶

Task	Poetry	uv
Install dependencies	`poetry install --extras "dev docs"`	`uv sync --all-extras`
Add package	`poetry add httpx`	`uv add httpx`
Add dev package	`poetry add --group dev pytest`	`uv add --dev pytest`
Remove package	`poetry remove httpx`	`uv remove httpx`
Update dependencies	`poetry update`	`uv lock --upgrade`
Run command	`poetry run python script.py`	`uv run python script.py`
Run poe task	`poetry run poe test`	`uv run poe test`
Build package	`poetry build`	`uv build`
Show packages	`poetry show`	`uv pip list`
Show dependency tree	`poetry show --tree`	`uv tree`
Environment info	`poetry env info`	`uv venv` (or `uv --version`)
Lock dependencies	`poetry lock`	`uv lock`
Clear cache	`poetry cache clear pypi --all`	`rm -rf ~/.cache/uv`

Advanced Usage¶

Running with Additional Dependencies¶

# Run with extra packages temporarily (without adding to project)
uv run --with requests python script.py

# Run with specific package version
uv run --with "httpx==0.24.0" python script.py

# Run in isolated environment
uv run --isolated python script.py

Working with Python Versions¶

# Use specific Python version
uv run --python 3.12 python script.py

# Install Python if needed (uv can manage Python installations)
uv python install 3.12
uv python install 3.13
uv python install 3.14

# List available Python versions
uv python list

Lock File Management¶

# Generate lock file
uv lock

# Update lock file with latest compatible versions
uv lock --upgrade

# Update specific package in lock file
uv lock --upgrade-package httpx

# Validate lock file is up to date
uv sync --locked  # Will fail if lock file doesn't match pyproject.toml

CI/CD Integration¶

This project uses uv in GitHub Actions for fast, reliable CI/CD:

- name: Install uv
  uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"
    python-version: "3.14"

- name: Install dependencies
  run: uv sync --all-extras

- name: Run tests
  run: uv run poe test-coverage

See .github/workflows/ci.yml for complete examples.