python-project

# Python Project

## Use this workflow

Build and maintain Python 3.12+ projects with modern tooling and best practices. Follow the steps below for project setup, dependency management, quality tools, CLI patterns, and packaging workflows.

Key tools:
- **uv**: Fast Python package installer and environment manager
- **ruff**: Lightning-fast linter and formatter
- **pytest**: Testing framework with coverage support
- **ty**: Static type checker
- **typer**: Modern CLI framework
- **loguru**: Simplified logging

For Python coding conventions, see the `python-conventions` skill.

## Set up a new project

1. Initialize a project:

```bash
uv init my-project
cd my-project
```

2. Add runtime dependencies:

```bash
uv add loguru typer
```

3. Add development dependencies:

```bash
uv add --dev ruff pytest pytest-cov ty
```

4. Verify the setup:

```bash
uv run python -V
# Confirm the expected Python version
```

## Use a src/ layout

Use a `src/` layout for better import clarity and testing isolation:

```
my-project/
├── src/
│   └── my_project/
│       ├── __init__.py
│       ├── cli.py
│       └── core.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
└── README.md
```

Benefits of a `src/` layout:
- Prevent accidental imports from the project root
- Force installation for testing
- Keep source and tests separated

## Manage dependencies

Basic operations:
- Add runtime dependency: `uv add <package>`
- Add dev dependency: `uv add --dev <package>`
- Add to named group: `uv add --group <name> <package>`
- Run commands: `uv run <command>`
- Sync dependencies: `uv sync`

Key principles:
- Use `uv run <command>` instead of plain `python` or tool commands.
- Use `--dev` for tools that are not needed in production (ruff, pytest, ty).
- Pin versions in production and use ranges during development.

Read `references/uv-scripts.md` for inline metadata, `--no-project`, and `--with` flags.

## Run quality tools

Lint and format with ruff:
```bash
uv run ruff check         # C