Tool Usage Learnings

This file is intended to be used by an LLM such as Claude.

UV Package Manager

Use uv run to run Python tools without activating virtual environments
For formatting: uv run ruff format .
For type checking: uv run pyright
For upgrading packages:
- uv add --dev package --upgrade-package package to upgrade a specific package
- Don't use @latest syntax - it doesn't work
- Be careful with uv pip install as it may downgrade packages

Git and GitHub CLI

When using gh CLI for PRs, always quote title and body:

gh pr create --title "\"my title\"" --body "\"my body\""

For git commits, use double quotes and escape inner quotes:
```
git commit -am "\"fix: my commit message\""
```

Python Tools

Ruff

Handles both formatting and linting
For formatting: uv run ruff format .
For checking: uv run ruff check .
For auto-fixing: uv run ruff check . --fix
Common issues:
- Line length (default 88 chars)
- Import sorting (I001 errors)
- Unused imports
When line length errors occur:
- For strings, use parentheses and line continuation
- For function calls, use multiple lines with proper indentation
- For imports, split into multiple lines

Pyright

Type checker
Run with: uv run pyright
Version warnings can be ignored if type checking passes
Common issues:
- Optional types need explicit None checks
- String operations need type narrowing

Pre-commit Hooks

Configuration in .pre-commit-config.yaml
Runs automatically on git commit
Includes:
- Prettier for YAML/JSON formatting
- Ruff for Python formatting and linting
When updating ruff version:
- Check available versions on PyPI
- Update rev in config to match available version
- Add and commit config changes before other changes

Best Practices

Always check git status and diff before committing
Run formatters before type checkers
When fixing CI:
- Start with formatting issues
- Then fix type errors
- Then address any remaining linting issues
For type errors:
- Get full context around error lines
- Consider optional types
- Add type narrowing checks when needed