Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
779 lines (545 loc) · 15.8 KB

DEVELOPMENT.md

File metadata and controls

779 lines (545 loc) · 15.8 KB

Development Guide

This guide covers environment setup, development workflow, and tooling for contributing to flash-examples.

Table of Contents

Environment Setup

Prerequisites

  • Python 3.10+ (3.12 recommended)
  • One of: uv, pip, poetry, conda, or pipenv
  • Git

Quick Setup

The project Makefile auto-detects your package manager and sets up the environment:

git clone https://github.com/runpod/flash-examples.git
cd flash-examples
make setup

This works with any of these package managers:

uv (Recommended)

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

# Setup project
make setup

What it does:

  • Creates .venv if not exists
  • Syncs all dependency groups from uv.lock
  • Installs package in editable mode

pip + venv

# Setup project (creates venv automatically)
make setup

What it does:

  • Creates .venv using python -m venv
  • Installs from requirements.txt (or generates it)
  • Installs package in editable mode

poetry

# Install poetry
curl -sSL https://install.python-poetry.org | python3 -

# Setup project
make setup

What it does:

  • Uses poetry's virtual environment management
  • Installs dev dependencies
  • Installs package in editable mode

conda

# Setup project
make setup

What it does:

  • Creates conda environment at ./.venv
  • Installs dependencies via pip
  • Installs package in editable mode

pipenv

# Install pipenv
pip install pipenv

# Setup project
make setup

What it does:

  • Creates pipenv environment
  • Installs dev dependencies
  • Installs package in editable mode

Environment Manager Override

Force a specific package manager:

PKG_MANAGER=pip make setup
PKG_MANAGER=conda make setup

Verify Your Setup

Check that everything is configured correctly:

make verify-setup

Output:

═══════════════════════════════════════════════════════════════
  Flash Examples - Setup Verification
═══════════════════════════════════════════════════════════════

→ Checking Python version...
  ✓ Python 3.12.1 (>= 3.10 required)

→ Checking virtual environment...
  ✓ Virtual environment exists (.venv)

→ Checking Flash CLI...
  ✓ Flash CLI installed (flash, version 0.1.0)

→ Checking RUNPOD_API_KEY...
  ✓ RUNPOD_API_KEY set in environment

═══════════════════════════════════════════════════════════════
  Setup verification complete!
═══════════════════════════════════════════════════════════════

Check Environment Manager Status

make venv-info

Output:

Package Manager: uv
Python Runner: uv run
Virtual Environment: Active (.venv exists)
Python Version: Python 3.12.10

Running Flash with Different Package Managers

After make setup completes, you can run Flash in two ways:

Option A: Using Package Manager Prefix (recommended for uv/poetry/pipenv/conda)

Run commands with the package manager prefix without activation:

# With uv
uv run flash run

# With poetry
poetry run flash run

# With pipenv
pipenv run flash run

# With conda
conda run -p ./.venv flash run

Option B: Activate Virtual Environment (works with all managers)

Alternatively, activate the virtual environment first:

# Unix/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

# Then run normally
flash run

Once activated, you can run Flash and other commands directly without a prefix.

Makefile Commands

Help

make help

Shows all available commands with your detected environment manager.

Environment Management

Command Description
make setup Setup development environment (auto-detects package manager)
make verify-setup Verify environment is configured correctly
make venv-info Display environment manager and venv status
make clean-venv Remove .venv directory
make update-deps Update dependencies to latest versions

Dependency Files

Command Description
make requirements.txt Generate requirements.txt from pyproject.toml
make environment.yml Generate conda environment.yml
make sync-deps Generate all dependency files

When to use:

  • requirements.txt - For pip users, Docker builds, CI/CD
  • environment.yml - For conda users
  • After updating pyproject.toml dependencies

Code Quality

Command Description
make lint Check code with ruff
make lint-fix Auto-fix linting issues
make format Format code with ruff
make format-check Check formatting without changes
make typecheck Run mypy type checker

Quality Gates

Command Description Use Case
make quality-check Format check + lint Fast pre-commit check
make quality-check-strict Format + lint + typecheck Thorough validation
make ci-quality-github CI with GitHub Actions formatting GitHub Actions only

Cleanup

Command Description
make clean Remove build artifacts, __pycache__, .pyc files
make clean-venv Remove virtual environment

Flash CLI Usage

The Flash CLI provides commands for local development, building, and deployment.

Authentication

flash login                  # Authenticate with Runpod (opens browser)

Or set RUNPOD_API_KEY in your .env file.

Development Commands

# Run development server
flash run                    # Default: localhost:8888
flash run --port 9000        # Custom port
flash run --host 0.0.0.0     # Network accessible

# Build deployment package
flash build                  # Standard build
flash build --exclude torch  # Optimize size

Deployment Commands

# Environment management
flash env create dev
flash env create staging
flash env create production

# Deploy to environment
flash deploy --env dev
flash deploy --env production --exclude torch,torchvision

# Manage deployments
flash undeploy list          # Show all endpoints
flash undeploy <name>        # Remove specific endpoint

Complete Documentation

See comprehensive CLI documentation:

Development Workflow

1. Initial Setup

# Clone and setup
git clone https://github.com/runpod/flash-examples.git
cd flash-examples
make setup

# Verify setup
make venv-info

2. Create Feature Branch

git checkout -b feature/your-feature-name

3. Make Changes

Follow these principles:

  • Test-driven development (TDD)
  • Single responsibility per function
  • Type hints are mandatory
  • Early returns for guard clauses

4. Run Quality Checks

# Before committing
make quality-check

# For stricter validation
make quality-check-strict

5. Commit Changes

git add .
git commit -m "feat: your descriptive commit message"

Commit message format:

type(scope): subject

Longer description if needed
- Bullet points for multiple changes

Types: feat, fix, refactor, test, docs, perf, chore

6. Push and Create PR

git push origin feature/your-feature-name

Code Quality

Ruff (Linting & Formatting)

Check issues:

make lint

Auto-fix:

make lint-fix
make format

Configuration: pyproject.toml

Mypy (Type Checking)

Run type checker:

make typecheck

Type hints are mandatory:

# Good
def process_data(items: list[dict[str, Any]]) -> pd.DataFrame:
    """Process items and return DataFrame."""
    pass

# Bad
def process_data(items):
    """Process items and return DataFrame."""
    pass

Pre-commit Workflow

Before every commit:

make quality-check

If it fails:

  1. Fix issues manually or use make lint-fix + make format
  2. Re-run make quality-check
  3. Commit

Testing

Running Tests

# All tests
pytest

# Unit tests only
pytest tests/unit/

# Stop on first failure
pytest -xvs

# With coverage
pytest --cov=src --cov-report=html

Test Structure

Follow Arrange-Act-Assert pattern:

def test_user_creation():
    # Arrange
    user_data = {"email": "test@example.com", "name": "Test User"}

    # Act
    user = User.create(**user_data)

    # Assert
    assert user.email == user_data["email"]
    assert user.id is not None

Test Guidelines

  • Test behavior, not implementation
  • Use fixtures for reusable setup
  • Mock external services, not internal code
  • Test unhappy paths thoroughly

Common Tasks

Adding Dependencies

1. Edit pyproject.toml:

[project]
dependencies = [
    "runpod-flash",
    "new-package>=1.0.0",
]

2. Sync environment:

# With uv
uv sync

# With other managers
make setup

3. Generate dependency files:

make sync-deps

Updating Dependencies

make update-deps

Then review and test changes before committing.

Creating New Examples

1. Create directory and worker files:

mkdir 01_getting_started/05_new_example
cd 01_getting_started/05_new_example

2. Create files:

touch README.md gpu_worker.py pyproject.toml

Each worker file (named *_worker.py by convention) is self-contained with @Endpoint decorated functions. flash run discovers all .py files with @Endpoint functions automatically -- no main.py, no workers/ directories needed.

3. Declare dependencies:

Add a pyproject.toml with runpod-flash as the only local dependency. Runtime deps (torch, etc.) go in Endpoint(dependencies=[...]).

4. Verify discovery:

cd ../../  # Back to root
flash run  # Discovers all .py files with @Endpoint functions

Cleaning Up

Remove build artifacts:

make clean

Remove virtual environment:

make clean-venv

Fresh start:

make clean-venv
make setup

Unified App Architecture

The root directory provides a programmatic discovery system that automatically finds and loads all examples when you run flash run from the project root.

Discovery Process

  1. Scans all example category directories (01_getting_started/, 02_ml_inference/, etc.)
  2. Detects @remote decorated functions in .py files via AST parsing
  3. Dynamically generates routes with unique prefixes (e.g., /01_hello_world/gpu/)
  4. Generates metadata and documentation automatically

Benefits

  • Add new examples without modifying any central configuration
  • Consistent routing across all examples
  • Single entry point for exploring all functionality
  • Automatic discovery eliminates manual registration

Example Structure

Each example follows this flat-file pattern:

example_name/
├── README.md              # Documentation and deployment guide
├── gpu_worker.py          # @remote decorated functions (GPU)
├── cpu_worker.py          # @remote decorated functions (CPU, optional)
├── pyproject.toml         # Project dependencies
└── .gitignore             # Git ignore patterns

Example Dependency Syncing

The unified app requires all example dependencies to be installed in the root environment for discovery to work.

Automatic Dependency Syncing:

When adding a new example with additional dependencies:

  1. Define dependencies in your example's pyproject.toml
  2. Run make sync-example-deps to update the root dependencies
  3. Run uv sync --all-groups (or make setup) to install new packages
  4. Run make requirements.txt to regenerate the lockfile

The sync script automatically:

  • Scans all example directories for pyproject.toml files
  • Merges dependencies into the root configuration
  • Filters out transitive dependencies already provided by runpod-flash
  • Detects version conflicts and uses the most permissive constraint
  • Preserves essential root dependencies (numpy, torch, runpod-flash)

Example:

# After adding a new example with pillow and structlog dependencies
make sync-example-deps  # Syncs example deps to root pyproject.toml
uv sync --all-groups    # Installs new dependencies
make requirements.txt   # Regenerates lockfile

Troubleshooting

Package Manager Not Detected

Symptom:

make: *** No package manager found

Solution: Install one of: uv, pip, poetry, conda, or pipenv

# Easiest: pip (comes with Python)
python -m ensurepip

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

Virtual Environment Issues

Wrong Python version in venv:

make clean-venv
make setup

Dependencies out of sync:

# With uv
uv sync

# With pip
pip install -r requirements.txt

# Or recreate
make clean-venv
make setup

Quality Checks Failing

Formatting issues:

make format

Linting issues:

make lint-fix

Type errors:

Review mypy output and add type hints:

make typecheck

Makefile Commands Not Working

Check which environment manager is detected:

make venv-info

Force specific manager:

PKG_MANAGER=pip make setup

Run commands directly:

You can either use package manager prefixes or activate the environment first:

# Option 1: Use package manager prefix
uv run ruff check .          # With uv
poetry run ruff check .      # With poetry

# Option 2: Activate environment first (works with all managers)
source .venv/bin/activate   # Unix/macOS
.venv\Scripts\activate      # Windows
ruff check .

Import Errors

Package not installed in editable mode:

# With uv
uv pip install -e .

# With pip
pip install -e .

# Or use Makefile
make setup

Wrong virtual environment activated:

# Deactivate current
deactivate

# Use Makefile (auto-detects)
make lint

# Or activate correct venv
source .venv/bin/activate  # Unix
.venv\Scripts\activate     # Windows

CI/CD Integration

GitHub Actions

The project includes quality checks optimized for GitHub Actions:

- name: Run quality checks
  run: make ci-quality-github

This produces collapsible output groups in GitHub Actions logs.

Local CI Simulation

Test what CI will run:

make quality-check-strict

This runs the same checks as CI (format + lint + typecheck).

Editor Integration

VS Code

Install extensions:

  • Python (ms-python.python)
  • Ruff (charliermarsh.ruff)
  • Mypy Type Checker (ms-python.mypy-type-checker)

PyCharm

Enable external tools:

  • Settings → Tools → External Tools
  • Add Makefile commands

Vim/Neovim

Use ALE or null-ls with ruff and mypy configured.

Additional Resources

Getting Help