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.
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.
- 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
🚀 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
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
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
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
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
See practical examples:
- Jupyter Notebooks - Data science and exploration
- FastAPI - Web API development
- OpenCV - Computer vision projects
.
├── 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
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.
- 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