Northern-Thailand-Ping-River-Monitor/MIGRATION_TO_UV.md

# Migration to uv

This document describes the migration from traditional Python package management (pip + requirements.txt) to [uv](https://docs.astral.sh/uv/), a fast Python package installer and resolver.

## What Changed

### Files Added
- `pyproject.toml` - Modern Python project configuration combining dependencies and metadata
- `.python-version` - Specifies Python version for uv
- `scripts/setup_uv.sh` - Unix setup script for uv environment
- `scripts/setup_uv.bat` - Windows setup script for uv environment
- This migration guide

### Files Modified
- `Makefile` - Updated all commands to use `uv run` instead of direct Python execution

### Files That Can Be Removed (Optional)
- `requirements.txt` - Dependencies now in pyproject.toml
- `requirements-dev.txt` - Dev dependencies now in pyproject.toml
- `setup.py` - Configuration now in pyproject.toml

## Installation

### Install uv

**Unix/macOS:**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### Setup Project

**Unix/macOS:**
```bash
# Run the setup script
chmod +x scripts/setup_uv.sh
./scripts/setup_uv.sh

# Or manually:
uv sync
uv run pre-commit install
```

**Windows:**
```batch
REM Run the setup script
scripts\setup_uv.bat

REM Or manually:
uv sync
uv run pre-commit install
```

## New Workflow

### Common Commands

| Old Command | New Command | Description |
|-------------|-------------|-------------|
| `pip install -r requirements.txt` | `uv sync --no-dev` | Install production dependencies |
| `pip install -r requirements-dev.txt` | `uv sync` | Install all dependencies (including dev) |
| `python run.py` | `uv run python run.py` | Run the application |
| `pytest` | `uv run pytest` | Run tests |
| `black src/` | `uv run black src/` | Format code |

### Using the Makefile

The Makefile has been updated to use uv, so all existing commands work the same:

```bash
make install-dev    # Install dev dependencies with uv
make test          # Run tests with uv
make run-api       # Start API server with uv
make lint          # Lint code with uv
make format        # Format code with uv
```

### Adding Dependencies

**Production dependency:**
```bash
uv add requests
```

**Development dependency:**
```bash
uv add --dev pytest
```

**Specific version:**
```bash
uv add "fastapi==0.104.1"
```

### Managing Python Versions

uv can automatically manage Python versions:

```bash
# Install and use Python 3.11
uv python install 3.11
uv sync

# Use specific Python version
uv sync --python 3.11
```

## Benefits of uv

1. **Speed** - 10-100x faster than pip
2. **Reliability** - Better dependency resolution
3. **Simplicity** - Single tool for packages and Python versions
4. **Reproducibility** - Lock file ensures consistent environments
5. **Modern** - Built-in support for pyproject.toml

## Troubleshooting

### Command not found
Make sure uv is in your PATH after installation. Restart your terminal or run:
```bash
source ~/.bashrc  # or ~/.zshrc
```

### Lock file conflicts
If you encounter lock file issues:
```bash
rm uv.lock
uv sync
```

### Python version issues
Ensure the Python version in `.python-version` is available:
```bash
uv python list
uv python install 3.11  # if needed
```

## Rollback (if needed)

If you need to rollback to the old system:

1. Use the original requirements files:
   ```bash
   pip install -r requirements.txt
   pip install -r requirements-dev.txt
   ```

2. Revert the Makefile changes to use `python` instead of `uv run python`

3. Remove uv-specific files:
   ```bash
   rm pyproject.toml .python-version uv.lock
   rm -rf .venv  # if created by uv
   ```

## Additional Resources

- [uv Documentation](https://docs.astral.sh/uv/)
- [Migration Guide](https://docs.astral.sh/uv/guides/projects/)
- [pyproject.toml Reference](https://packaging.python.org/en/latest/specifications/pyproject-toml/)