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
SQL linting - sqruff for SQL code quality
GitHub Actions linting - actionlint for workflow file quality
Type safety - ty 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 ty
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
ty Guide - Type checking
Testing Guide - Running tests with pytest
Pre-commit Guide - Automated quality checks
Built-in Utilities - Logger, Config, Timer

Contributing

How changes are written, checked, and released:

Code Standards - Coding rules, tests, and documentation rules
Branch Strategy & Release Flow - GitHub Flow, Draft Release, Develop / Production
CI/CD Workflows - What each GitHub Actions workflow does

Configuration Reference

Deep dive into tool configurations:

uv Configuration - Package manager settings
Ruff Configuration - Linter and formatter rules
ty Configuration - Type checker settings
sqruff Configuration - SQL linter and formatter rules
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 (Settings, FastAPI config)
│   ├── logger/             # Logging utilities (Local & Google Cloud formatters)
│   └── tracer/             # Performance tracing (Timer decorator/context manager)
├── tests/                  # Test suite (mirrors tools/ structure)
├── docs/                   # This documentation (MkDocs)
├── .devcontainer/          # Dev Container configuration
├── .github/                # GitHub Actions workflows, PR template, repository settings
├── CLAUDE.md               # Guidance for Claude Code
├── CODE_OF_CONDUCT.md      # Community Code of Conduct
├── CONTRIBUTING.md         # Contribution guidelines
├── Dockerfile              # App image
├── mkdocs.yml              # Documentation site configuration
├── noxfile.py              # Task automation (fmt, lint, test)
├── pyproject.toml          # Project metadata and dependencies (uv)
├── pytest.ini              # pytest configuration (75% coverage requirement)
├── ruff.toml               # Ruff configuration
├── ty.toml                 # ty configuration
└── .sqruff                 # sqruff configuration

Common Commands

Install dependencies with uv sync, then use the nox sessions in Task Automation with nox to format, lint, and test. Serve this documentation locally with uv run mkdocs serve.

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