# uv and pyproject.toml

This project uses `pyproject.toml` with the `uv` package manager instead of `setup.py` + `requirements.txt`.

## Legacy Files

These files are kept for backward compatibility with tools that still use them. For example, these are required to publish package versions via the `publish-pypi-package-v2` pipeline.

- `MANIFEST.in` - Hatchling handles package data automatically
- `requirements-dev.txt` - Replaced by the `dev` dependency group in `pyproject.toml`
- `requirements.txt` - Replaced by `dependencies` in `pyproject.toml`
- `setup.cfg` - Pytest config moved to `pyproject.toml`
- `setup.py` - Replaced by `pyproject.toml`

## Installation & Usage

### Installing uv

```bash
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv
```

### Setting Up the Project

```bash
# Install dependencies and create virtual environment
uv sync
```

### Development Workflows

> **Note**: If you modify dependencies (add, remove, update), always run `make requirements` to regenerate requirement files. This is required for backward compatibility.

#### Installing Dependencies

```bash
# Install production dependencies
make env

# Install with dev dependencies
make dev_env

# Install with integration test dependencies
make env_integration
```

#### Adding New Dependencies
```bash
# Add a production dependency
uv add pytest~=1.2.3

# Add a dev dependency
uv add --dev pytest~=1.2.3

# Add to a specific group
uv add --group integration pytest~=1.2.3

# Always regenerate requirements files for backward compatibility
make requirements
```

#### Upgrading Dependencies
```bash
# Upgrade a specific package to the latest compatible version
uv lock --upgrade-package flask

# Or upgrade all packages to their latest compatible versions
uv lock --upgrade

# After upgrading, sync your environment
uv sync

# Always regenerate requirements files for backward compatibility
make requirements
```

> **Note**: `uv lock --upgrade` respects version constraints in `pyproject.toml`. To upgrade to versions outside those constraints, modify the version specification in `pyproject.toml` first (e.g., change `flask>=2.3.3` to `flask>=3.0.0`), then try again.

#### Removing Dependencies
```bash
# Remove a dependency
uv remove flask

# Remove a dev dependency
uv remove --dev pytest

# Remove a specific group dependency
uv remove --group integration pytest

# Always regenerate requirements files for backward compatibility
make requirements
```

#### Building the Package
```bash
# Build wheel and sdist. Outputs to dist/
uv build
```

## Benefits of uv

1. **Speed**: 10-100x faster than pip
2. **Deterministic**: `uv.lock` ensures reproducible installs
3. **Modern**: Uses pyproject.toml standard (PEP 621)
4. **Simple**: One command to install everything (`uv sync`)
5. **Virtual env management**: Automatic .venv creation and management

## Dependency Groups

The project has three dependency groups:

- **Production** (`dependencies`): Runtime dependencies
- **Development** (`dev`): Tools for development (ruff, pytest, etc.)
- **Integration** (`integration`): Dependencies for integration tests

## Troubleshooting

### Issue: uv not found
**Solution**: Install uv following the instructions above

### Issue: Dependencies not installing
**Solution**: Try removing the lock file and re-syncing:
```bash
rm uv.lock
uv sync
```

## Questions?

Contact the Abacus team or refer to:
- [uv documentation](https://docs.astral.sh/uv/)
- [PEP 621 - Storing project metadata in pyproject.toml](https://peps.python.org/pep-0621/)