report_skill_expm/UV_SETUP_GUIDE.md

# Quick Start Guide for UV-based Setup

## Why UV + pyproject.toml?

✅ **Reliable**: All dependencies locked to specific versions  
✅ **Fast**: UV is significantly faster than pip  
✅ **Reproducible**: Same environment across all machines  
✅ **Simple**: One command to set up everything  
✅ **Modern**: Using Python packaging best practices  

## Installation

### First Time Setup

```bash
# Install uv (if not already installed)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

# Or with pip
pip install uv
```

### Project Setup

```bash
# Clone or navigate to the repository
cd report_skill_expm

# Create virtual environment and install all dependencies
uv sync

# That's it! All dependencies are now installed and locked
```

## Usage

### Option 1: Using `uv run` (Recommended)

No need to activate the virtual environment - uv handles it automatically:

```bash
# Run the example
uv run python example.py

# Run the report generator directly
uv run python skills/week_report_gen/generate_report.py

# Import and use in Python
uv run python -c "from skills.week_report_gen.generate_report import generate_weekly_report; print('Ready!')"
```

### Option 2: Traditional Virtual Environment

```bash
# Activate the virtual environment
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

# Now you can run Python normally
python example.py
python skills/week_report_gen/generate_report.py
```

## What's in pyproject.toml?

```toml
[project]
name = "report-skill-expm"
version = "1.0.0"
requires-python = ">=3.9"

dependencies = [
    "openpyxl>=3.1.0",   # Excel file handling
    "pandas>=2.0.0",     # Data processing
    "xlrd>=2.0.0",       # Reading .xls files
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",     # Testing framework
    "black>=23.0.0",     # Code formatter
    "flake8>=6.0.0",     # Linter
]
```

## Common Commands

```bash
# Install/update dependencies
uv sync

# Install with dev dependencies
uv sync --extra dev

# Add a new dependency
uv add package-name

# Remove a dependency
uv remove package-name

# Update all dependencies
uv sync --upgrade

# Show installed packages
uv pip list

# Run any Python script
uv run python your_script.py

# Run a specific module
uv run python -m skills.week_report_gen.generate_report

# Start Python REPL with dependencies available
uv run python
```

## Benefits Over Manual pip Installation

### Before (Manual)
```bash
python -m venv .venv
.venv\Scripts\activate
pip install openpyxl pandas xlrd
# Need to remember all packages and versions
# No lock file - different versions on different machines
```

### After (UV + pyproject.toml)
```bash
uv sync
# Done! Everything locked and reproducible
```

## Dependency Management

### Adding Dependencies

```bash
# Add a runtime dependency
uv add requests

# Add a development dependency
uv add --dev pytest-cov

# Add with version constraint
uv add "pandas>=2.0,<3.0"
```

### Updating Dependencies

```bash
# Update all dependencies
uv sync --upgrade

# Update specific package
uv add --upgrade pandas
```

### Lock File

The `uv.lock` file (auto-generated) ensures:
- ✅ Exact versions are used across all environments
- ✅ Transitive dependencies are locked
- ✅ No "works on my machine" issues
- ✅ Fast, deterministic installs

**Commit `uv.lock` to version control!**

## Troubleshooting

### "uv: command not found"

Install uv first:
```bash
pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### "No module named 'xxx'"

Make sure you've run `uv sync`:
```bash
uv sync
```

### Virtual Environment Not Found

Recreate it:
```bash
rm -rf .venv  # or rmdir /s .venv on Windows
uv sync
```

### Import Errors

Use `uv run` to automatically activate the environment:
```bash
uv run python your_script.py
```

## CI/CD Integration

### GitHub Actions

```yaml
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install uv
  run: pip install uv

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest
```

### GitLab CI

```yaml
test:
  script:
    - pip install uv
    - uv sync
    - uv run pytest
```

## Migration from requirements.txt

If you have an old `requirements.txt`:

```bash
# Import from requirements.txt
uv add $(cat requirements.txt)

# Or manually add each package
uv add openpyxl pandas xlrd
```

## Best Practices

1. **Always commit `uv.lock`** - Ensures reproducible builds
2. **Use `uv run`** - Simplifies workflow, no activation needed
3. **Keep pyproject.toml clean** - Only list direct dependencies
4. **Use version constraints** - `>=3.1.0` not `==3.1.0`
5. **Separate dev dependencies** - Use `[project.optional-dependencies]`

## Comparison: pip vs uv

| Feature | pip | uv |
|---------|-----|-----|
| Speed | 🐌 Slow | 🚀 Fast (10-100x) |
| Lock file | requirements.txt (manual) | uv.lock (automatic) |
| Resolver | Sometimes inconsistent | Always consistent |
| Parallel installs | No | Yes |
| Built-in venv | Need separate commands | Integrated |

## Resources

- [UV Documentation](https://github.com/astral-sh/uv)
- [Python Packaging Guide](https://packaging.python.org/)
- [pyproject.toml Specification](https://peps.python.org/pep-0621/)

---

**Quick Reference Card**

```bash
# Setup
uv sync              # Install everything

# Run
uv run python app.py # Execute with dependencies

# Manage
uv add pkg           # Add dependency
uv remove pkg        # Remove dependency
uv sync --upgrade    # Update all

# Dev
uv sync --extra dev  # Install dev dependencies
uv run pytest        # Run tests
uv run black .       # Format code
```