5.6 KiB

Raw Blame History

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

# 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

# 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:

# 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

# 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?

[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

# 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)

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)

uv sync
# Done! Everything locked and reproducible

Dependency Management

Adding Dependencies

# 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

# 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:

pip install uv
# or
curl -LsSf https://astral.sh/uv/install.sh | sh

"No module named 'xxx'"

Make sure you've run uv sync:

uv sync

Virtual Environment Not Found

Recreate it:

rm -rf .venv  # or rmdir /s .venv on Windows
uv sync

Import Errors

Use uv run to automatically activate the environment:

uv run python your_script.py

CI/CD Integration

GitHub Actions

- 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

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

Migration from requirements.txt

If you have an old requirements.txt:

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

# Or manually add each package
uv add openpyxl pandas xlrd

Best Practices

Always commit uv.lock - Ensures reproducible builds
Use uv run - Simplifies workflow, no activation needed
Keep pyproject.toml clean - Only list direct dependencies
Use version constraints - >=3.1.0 not ==3.1.0
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

Quick Reference Card

# 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

5.6 KiB Raw Blame History