Skip to content

Development Guides

This section provides comprehensive guides for using the tools and utilities included in this template. Whether you're managing dependencies, formatting code, or building production applications, these guides will help you work efficiently.

Overview

This template includes several modern Python development tools, each serving a specific purpose:

  • uv - Ultra-fast package management (10-100x faster than pip)
  • Ruff - Lightning-fast linting and formatting
  • Pyright - Advanced type checking
  • pytest - Comprehensive testing framework
  • nox - Task automation and workflow management
  • pre-commit - Automated code quality checks
  • Built-in utilities - Production-ready modules for logging, configuration, and monitoring

Task Automation with nox

nox is the primary way to run development tasks in this repository. It provides a consistent interface for common operations and handles dependency management automatically.

Available Sessions

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Format code with Ruff
uv run nox -s fmt

# Run linters (you can specify which ones)
uv run nox -s lint -- --pyright --ruff  # Both
uv run nox -s lint -- --pyright         # Pyright only
uv run nox -s lint -- --ruff            # Ruff only

# 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 -- --junitxml=results.xml

Why nox?

  • Consistent workflow - Same commands work for all developers
  • Isolated environments - Each session runs in isolation
  • Customizable - Easy to add new sessions for your needs
  • CI/CD friendly - Integrates seamlessly with GitHub Actions

Package Management

uv Guide

Learn how to manage Python packages with uv, the blazing-fast package manager:

  • Adding and removing dependencies
  • Managing development dependencies
  • Pinning Python versions
  • Understanding the lock file

Quick reference:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Add a package
uv add requests

# Add a dev dependency
uv add --dev pytest-mock

# Install all dependencies
uv sync

# Remove a package
uv remove requests

→ Read the full uv guide

Code Quality

Ruff Guide

Master Ruff, the all-in-one linter and formatter that replaces Black, isort, Flake8, and more:

  • Formatting code automatically
  • Running linting checks
  • Understanding Ruff rules
  • Customizing for your project

Quick reference:

1
2
3
4
5
6
7
8
# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Auto-fix issues
uv run ruff check . --fix

→ Read the full Ruff guide

Pyright Guide

Use Pyright for comprehensive type checking:

  • Running type checks
  • Understanding type errors
  • Configuring type checking strictness
  • Integrating with your editor

Quick reference:

1
2
3
4
5
# Run type checker
uv run pyright

# Check specific files
uv run pyright tools/logger/

→ Read the full Pyright guide

Testing

Testing Guide

Learn how to write and run tests with pytest:

  • Writing test cases
  • Running tests with coverage
  • Understanding coverage reports
  • Testing best practices

Quick reference:

1
2
3
4
5
6
7
8
# Run all tests
uv run pytest

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

# Run with coverage report
uv run pytest --cov=tools --cov-report=html

→ Read the full testing guide

Automation

Pre-commit Guide

Set up automated code quality checks that run before every commit:

  • Installing pre-commit hooks
  • Running hooks manually
  • Understanding hook failures
  • Customizing hooks

Quick reference:

1
2
3
4
5
6
7
8
# Install hooks
uv run pre-commit install

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

# Run specific hook
uv run pre-commit run ruff-format

→ Read the full pre-commit guide

Built-in Utilities

Tools Package

Explore the production-ready utility modules included in this template:

Logger

Flexible logging system with support for both local development and Google Cloud:

1
2
3
4
from tools.logger import Logger, LogType

logger = Logger(__name__, log_type=LogType.LOCAL)
logger.info("Application started")

Configuration

Environment-based configuration management:

1
2
3
4
from tools.config import Settings

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

Performance Tracer

Timer decorator and context manager for performance monitoring:

1
2
3
4
from tools.tracer import Timer

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

→ Explore all built-in utilities

Project Templates

Cookiecutter Guide

Learn how to use cookiecutter templates to bootstrap new projects:

  • Data Science projects
  • FastAPI applications
  • Django web apps
  • Flask microservices

Quick reference:

1
2
# Use a template
uv run cookiecutter https://github.com/fastapi/full-stack-fastapi-template

→ Read the full cookiecutter guide

Next Steps

  1. Start with basics: Read the uv guide to understand package management
  2. Ensure quality: Set up pre-commit hooks for automatic checks
  3. Explore utilities: Check out the built-in tools for common tasks
  4. See examples: Browse use cases for real-world applications

Need More Details?

For in-depth configuration information, see the Configuration Reference section.