# Development Guide

## Prerequisites

- Python 3.14 or higher
- `uv` (recommended) or `pip`

## Installation

1. Install dependencies:
   ```bash
   uv pip install -r requirements.txt
   # OR
   pip install -r requirements.txt
   ```

## Running Tests

We use `pytest` for testing.

### Using `uv` (Recommended)

To run tests with all dependencies automatically handled:

```bash
uv run --with-requirements requirements.txt pytest
```

## Project Structure

- `main.py`: Main application script.
- `tests/`: Directory containing test files.
- `requirements.txt`: Python package dependencies.

## Tooling

This project uses modern Python tooling for code quality:

- **Ruff**: For linting and code formatting.
- **Ty**: For static type checking.

These tools are configured in `pyproject.toml`.

### Running Ruff

To check for linting errors:

```bash
uv tool run ruff check .
```

To fix fixable linting errors automatically:

```bash
uv tool run ruff check --fix .
```

To format the code:

```bash
uv tool run ruff format .
```

### Running Ty (Type Checking)

To run type checks:

```bash
uv tool run ty check
```

### Pre-commit

To run pre-commit hook:

```bash
uv tool run pre-commit run --all-files
```   


## Release to PyPI

To publish a new version of the package to PyPI, follow these steps:

1.  **Build the package**:
    This will create a `dist/` directory with the distribution files.
    ```bash
    uv tool run --from build pyproject-build
    ```

2.  **Upload to PyPI**:
    Use `twine` to upload the distribution files. 
    
    If your `.pypirc` is already configured with your API key:
    ```bash
    uv tool run twine upload --repository testpypi dist/*
    ```

    Or, to explicitly use your `PYPI_API_KEY` environment variable:
    ```bash
    uv tool run twine upload -u __token__ -p $env:PYPI_API_KEY dist/*
    ```
