✨ 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

**Co