A production-ready Python development environment template using modern tools: uv for blazing-fast package management, Ruff for lightning-fast linting and formatting, ty for fast and reliable type checking, and VSCode Dev Containers for reproducible development environments.

📋 Table of Contents

• Python Development with uv and Ruff
  • 📋 Table of Contents
  • ✨ Features
  • 🚀 Quick Start
    • Using Dev Container (Recommended)
    • Using Docker Only
    • Local Setup (Without Docker)
  • 📚 Development Workflow
    • Installing Dependencies
    • Running Tasks
    • Pre-commit Hooks
    • Documentation
  • 🏗️ Project Structure
    • Built-in Utility Modules
      • Logger - Dual-mode logging system
      • Configuration - Environment-based settings
      • Timer - Performance monitoring
  • ⚙️ Configuration
    • Ruff Configuration
    • ty Configuration
    • Pytest Configuration
  • 🔄 CI/CD
  • 🎨 VSCode Configuration
  • 🍪 Cookiecutter Templates
  • 📖 Documentation
  • 🌿 Branches
  • 📄 License
  • 🙏 Acknowledgments

✨ Features

• 🚀 Ultra-fast package management with uv (10-100x faster than pip)
• ⚡ Lightning-fast linting & formatting with Ruff (replacing Black, isort, Flake8, and more)
• 🐳 Dev Container ready - Consistent development environment across all machines
• 🔍 Type checking with ty
• ✅ Pre-configured testing with pytest (75% coverage requirement)
• 🔄 Automated CI/CD with GitHub Actions
• 📦 Reusable utilities - Logger, configuration management, and performance tracing tools
• 🎯 Task automation with nox
• 🪝 Pre-commit hooks for automatic code quality checks

🚀 Quick Start

Using Dev Container (Recommended)

1. Prerequisites: Install Docker and VSCode with the Dev Containers extension

2. Open in container:

   git clone https://github.com/a5chin/python-uv.git
   cd python-uv
   code .

   When prompted, click "Reopen in Container"

3. Start developing:

   # Install dependencies
   uv sync
   
   # Run tests
   uv run nox -s test
   
   # Format and lint
   uv run nox -s fmt
   uv run nox -s lint -- --ruff --ty

Using Docker Only

# Build the image
docker build -t python-uv .

# Run container
docker run -it --rm -v $(pwd):/workspace python-uv

Local Setup (Without Docker)

Prerequisites: Python 3.11+ and uv

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/a5chin/python-uv.git
cd python-uv

# Install dependencies
uv sync

# Install pre-commit hooks (optional)
uv run pre-commit install

📚 Development Workflow

Installing Dependencies

# Install all dependencies (including dev dependencies)
uv sync

# Install without dev dependencies
uv sync --no-dev

# Add new dependencies
uv add requests pandas

# Add dev dependencies
uv add --dev pytest-mock

Running Tasks

This project uses nox for task automation. All common development tasks are available as nox sessions:

# Format code with Ruff
uv run nox -s fmt

# Run linters (Ruff + ty)
uv run nox -s lint -- --ruff --ty

# Run only ty
uv run nox -s lint -- --ty

# Run only Ruff linter
uv run nox -s lint -- --ruff

# Run tests with coverage (75% minimum required)
uv run nox -s test

# Run tests with JUnit XML output (for CI)
uv run nox -s test -- --cov_report xml --junitxml junit.xml

You can also run tools directly:

# Run pytest directly
uv run pytest

# Run specific test file
uv run pytest tests/tools/test__logger.py

# Format with Ruff
uv run ruff format .

# Lint with Ruff
uv run ruff check . --fix

# Type check with ty
uv run ty check

Pre-commit Hooks

Pre-commit hooks automatically run code quality checks before each commit:

# Install hooks
uv run pre-commit install

# Run manually on all files
uv run pre-commit run --all-files

Configured hooks:

• Ruff formatting and linting
• JSON, YAML, TOML validation
• Trailing whitespace removal
• End-of-file fixer
• Private key detection
• Dockerfile linting with hadolint

Documentation

Generate and serve documentation with MkDocs:

# Serve locally at http://127.0.0.1:8000
uv run mkdocs serve

# Build static site
uv run mkdocs build

# Deploy to GitHub Pages
uv run mkdocs gh-deploy

🏗️ 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)
│   └── tools/              # Unit tests for utility modules
├── docs/                   # MkDocs documentation
│   ├── getting-started/    # Setup guides
│   ├── guides/             # Tool usage guides
│   ├── configurations/     # Configuration references
│   └── usecases/           # Real-world examples
├── .devcontainer/          # Dev Container configuration
├── .github/                # GitHub Actions workflows, PR templates, and review checklists
├── CODE_OF_CONDUCT.md      # Community Code of Conduct
├── CONTRIBUTING.md         # Contribution guidelines
├── CLAUDE.md               # Claude Code development guidance
├── noxfile.py              # Task automation configuration (test, lint, fmt)
├── pyproject.toml          # Project metadata and dependencies (uv)
├── ruff.toml               # Ruff linter/formatter configuration
└── pytest.ini              # Pytest configuration (75% coverage requirement)

Built-in Utility Modules

The tools/ package provides production-ready utilities that can be used in your projects:

Logger - Dual-mode logging system

Environment-aware logging with support for local development and cloud environments:

from tools.logger import Logger, LogType

# Local development (colored console output)
logger = Logger(__name__, log_type=LogType.LOCAL)

# Google Cloud (structured JSON logging)
logger = Logger(__name__, log_type=LogType.GOOGLE_CLOUD, project="my-project")

logger.info("Application started")

Configuration - Environment-based settings

Type-safe configuration management using Pydantic:

from tools.config import Settings

settings = Settings()  # Loads from .env and .env.local
api_url = settings.api_prefix_v1
is_debug = settings.DEBUG

Timer - Performance monitoring

Automatic execution time logging for functions and code blocks:

from tools.tracer import Timer

# As context manager
with Timer("database_query"):
    result = db.query()  # Logs execution time automatically

# As decorator
@Timer("process_data")
def process_data(data):
    return transform(data)  # Logs execution time when function completes

⚙️ Configuration

Ruff Configuration

Ruff replaces multiple tools (Black, isort, Flake8, pydocstyle, pyupgrade, autoflake) with a single, fast tool.

Key settings in ruff.toml:

• Line length: 88 (Black-compatible)
• Target Python: 3.14
• Rules: ALL enabled by default with specific exclusions
• Test files: Exempt from INP001 (namespace packages) and S101 (assert usage)

See Ruff documentation for customization options.

ty Configuration

Static type checking for Python code.

Key settings in ty.toml:

• Include: tools/ and tests/ packages
• Exclude: Cache directories (__pycache__, .pytest_cache, .ruff_cache, .venv)

See ty documentation for advanced configuration.

Pytest Configuration

Testing framework with coverage enforcement.

Key settings in pytest.ini:

• Coverage requirement: 75% minimum (including branch coverage)
• Test file pattern: test__*.py (double underscore)
• Coverage reports: HTML and terminal
• Import mode: importlib

See pytest documentation for additional options.

🔄 CI/CD

Automated workflows ensure code quality and consistency. All workflows run on push and pull requests.

Available workflows in .github/workflows/:

🎨 VSCode Configuration

The Dev Container includes pre-configured extensions and settings for optimal Python development.

Python Development:

• Ruff - Fast linting and formatting
• ty - Static type checking
• Python - Core Python support
• autodocstring - Automatic docstring generation
• python-indent - Correct Python indentation

Code Quality:

• GitLens - Enhanced Git integration
• Error Lens - Inline error highlighting
• indent-rainbow - Visual indentation guide
• trailing-spaces - Highlight trailing whitespace

File Support:

• YAML, TOML, Markdown - Configuration file support
• Docker - Dockerfile and docker-compose support
• Material Icon Theme - File icons

Editor Settings:

• ✅ Format on save (Python, JSON, YAML, TOML, Dockerfile)
• ✅ Auto-trim trailing whitespace
• ✅ Auto-insert final newline
• ✅ Organize imports on save

Troubleshooting: If Ruff formatting doesn't work, reload the window: Cmd+Shift+P → "Developer: Reload Window"

🍪 Cookiecutter Templates

This repository can be used as a base template for various Python projects. Combine it with Cookiecutter to bootstrap project-specific setups:

# Install cookiecutter
uv add --dev cookiecutter

# Use a template
uv run cookiecutter <template-url>

Recommended templates:

• Data Science: cookiecutter-data-science - Standardized data science project structure
• FastAPI: full-stack-fastapi-template - Full-stack web applications
• Django: cookiecutter-django - Production-ready Django projects
• Flask: cookiecutter-flask - Flask web applications

📖 Documentation

Comprehensive documentation is available at https://a5chin.github.io/python-uv

Topics covered:

• 🚀 Getting Started - Docker, VSCode, Dev Containers setup
• ⚙️ Tool Configurations - uv, Ruff, ty, pre-commit
• 🧪 Testing Strategies - pytest, coverage, and best practices
• 🛠️ Utility Modules - Config, logger, and tracer guides
• 💡 Use Cases - Jupyter, FastAPI, OpenCV examples

🌿 Branches

This repository maintains multiple branches for different use cases:

• main - Current production-ready template (recommended)
• jupyter - Archived: Jupyter-specific configuration
• rye - Archived: Rye package manager version (replaced by uv)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This template is built on top of excellent open-source tools:

• uv by Astral - Ultra-fast Python package manager
• Ruff by Astral - Lightning-fast linter and formatter
• ty by Astral - Static type checker for Python
• nox - Flexible task automation for Python
• pytest - Testing framework for Python
• MkDocs - Documentation site generator

Special thanks to the open-source community for making these tools available!