# =============================================
# UV CHEATSHEET (Python Package & Env Management)
# =============================================
# Astral's ultra-fast alternative to pip/venv.
# Install: curl -LsSf https://astral.sh/uv/install.sh | sh
# Docs: https://github.com/astral-sh/uv

# ---------------------------------------------------------------------
# 1. VIRTUAL ENVIRONMENTS
# ---------------------------------------------------------------------

# Create a new virtual environment (replace .venv with your path)
uv venv .venv              # Faster alternative to `python -m venv .venv`

# Activate the environment (manual step)
source .venv/bin/activate  # Linux/macOS
.\.venv\Scripts\activate   # Windows (PowerShell)

# ---------------------------------------------------------------------
# 2. PACKAGE INSTALLATION & MANAGEMENT
# ---------------------------------------------------------------------

# Install packages (like `pip install`)
uv pip install numpy pandas

# Install with version constraints
uv pip install "flask>=2.0,<3.0"

# Install from requirements.txt (much faster than pip)
uv pip sync requirements.txt

# Install editable (development mode)
uv pip install -e .

# Uninstall packages
uv pip uninstall numpy

# ---------------------------------------------------------------------
# 3. DEPENDENCY RESOLUTION & LOCKING
# ---------------------------------------------------------------------

# Generate a locked requirements.txt (like `pip-tools`)
uv pip compile requirements.in -o requirements.txt

# Upgrade all dependencies
uv pip compile requirements.in --upgrade -o requirements.txt

# Check for outdated packages
uv pip list --outdated

# ---------------------------------------------------------------------
# 4. ENVIRONMENT & CACHE MANAGEMENT
# ---------------------------------------------------------------------

# List installed packages
uv pip list

# Show package metadata
uv pip show flask

# Clear UV's cache (useful for troubleshooting)
uv cache clean

# ---------------------------------------------------------------------
# 5. INTEGRATION WITH OTHER TOOLS
# ---------------------------------------------------------------------

# Use with direnv (auto-activate .venv on directory entry)
# In .envrc: `source .venv/bin/activate`
# Run: `direnv allow`

# Use in CI/CD (example GitHub Actions step)
# - run: uv pip install -r requirements.txt

# =============================================
# TIPS:
# - Use `uv pip` instead of `pip` for 10-100x faster installs.
# - Combine with `direnv` for auto-activation.
# - `uv pip sync` is atomic (safer than pip for deployments).
# =============================================