Welcome to python-uv

A production-ready Python development environment template featuring uv for blazing-fast package management, Ruff for lightning-fast linting and formatting, and VSCode Dev Containers for reproducible development environments.

Overview

This repository provides a complete, batteries-included development environment for modern Python projects. Whether you're building web applications, data science pipelines, or microservices, this template gives you a solid foundation with best practices built-in.

What's Included

Ultra-fast package management - uv is 10-100x faster than pip
Lightning-fast code quality - Ruff replaces Black, isort, Flake8, and more
Type safety - Pyright for comprehensive type checking
Automated testing - pytest with 75% coverage requirement
Task automation - nox for streamlined development workflows
Pre-commit hooks - Automatic code quality checks before every commit
CI/CD ready - GitHub Actions workflows included
Production utilities - Logger, configuration management, and performance tracing

Key Features

🚀 Performance First

uv resolves dependencies and installs packages 10-100x faster than traditional tools
Ruff lints and formats Python code orders of magnitude faster than legacy tools
Optimized Docker images for fast container builds

🔧 Developer Experience

Dev Container configuration for consistent environments across teams
Pre-configured VSCode settings and extensions
Automated code formatting on save
Comprehensive pre-commit hooks

📦 Production Ready

Reusable utility modules for common tasks
Structured logging with local and Google Cloud support
Environment-based configuration management
Performance monitoring with Timer decorator

✅ Quality Assurance

Automated testing with pytest
Code coverage tracking (75% minimum)
Type checking with Pyright
Continuous integration workflows

Getting Started

New to this template? Start here:

Installation Prerequisites - Set up Docker, VSCode, and Dev Containers
Docker Setup - Install Docker Desktop
VSCode Setup - Configure your editor
Dev Container - Launch the development environment

Development Guides

Learn how to use the tools and utilities:

uv Guide - Package management commands
Ruff Guide - Linting and formatting
Pyright Guide - Type checking
Testing Guide - Running tests with pytest
Pre-commit Guide - Automated quality checks
Built-in Utilities - Logger, Config, Timer

Configuration Reference

Deep dive into tool configurations:

uv Configuration - Package manager settings
Ruff Configuration - Linter and formatter rules
Pyright Configuration - Type checker settings
pytest Configuration - Testing framework setup
Pre-commit Configuration - Hook definitions

Use Cases

See practical examples:

Jupyter Notebooks - Data science and exploration
FastAPI - Web API development
OpenCV - Computer vision projects

Project Structure

.
├── tools/                    # Reusable utility modules
│   ├── config/              # Configuration management
│   ├── logger/              # Logging utilities
│   └── tracer/              # Performance monitoring
├── tests/                   # Test suite
├── docs/                    # This documentation
├── .devcontainer/           # Dev Container configuration
├── .github/                 # GitHub Actions workflows
├── noxfile.py              # Task automation
├── pyproject.toml          # Project metadata
├── ruff.toml               # Ruff configuration
├── pyrightconfig.json      # Type checking config
└── pytest.ini              # Testing configuration

Common Commands

# Install dependencies
uv sync

# Format code
uv run nox -s fmt

# Run linters
uv run nox -s lint -- --pyright --ruff

# Run tests
uv run nox -s test

# Serve documentation
uv run mkdocs serve

# Add dependencies
uv add requests pandas

Next Steps

Set up your environment: Follow the Getting Started guide
Explore the utilities: Check out the built-in tools
Customize for your project: Review the configuration guides
See it in action: Browse the use cases