utilityhub_config

A deterministic, typed configuration loader for modern Python applications. Load settings from multiple sources with clear precedence, comprehensive metadata tracking, and detailed validation errors.

What It Does

utilityhub_config resolves application configuration from multiple sources in a strict, explicit precedence order. Instead of magic or implicit behavior, you get:

• ✅ Type-safe configuration - Full Pydantic v2+ validation
• ✅ Multi-source support - TOML, YAML, .env, environment variables, runtime overrides
• ✅ Utility functions - Get canonical config paths with get_config_path()
• ✅ Metadata tracking - Know exactly where each setting came from
• ✅ Deterministic resolution - Clear, predictable precedence order
• ✅ Rich error reporting - Validation failures include sources, files checked, and precedence info

Quick Start

uv add utilityhub_config

from pydantic import BaseModel
from utilityhub_config import load_settings

class Config(BaseModel):
    database_url: str = "sqlite:///default.db"
    debug: bool = False

# Load and validate configuration
settings, metadata = load_settings(Config)

# Type-safe access
print(settings.database_url)

# Track where it came from
print(f"Source: {metadata.get_source('database_url').source}")

Documentation

Getting Started

• Installation & Quick Start - Set up in 5 minutes

Understanding How It Works

• Precedence Order - How sources are prioritized
• Metadata Tracking - Understanding field origins

Usage Guides

• Basic Usage - First steps with load_settings
• Configuration Files - TOML, YAML, .env formats
• Config Paths - Get config paths with get_config_path (NEW!)
• Environment Variables - Using env vars
• Explicit Config Files - Load specific file paths (NEW!)
• Path Expansion - Expand ~ and $VAR in paths
• Runtime Overrides - Programmatic configuration
• Nested Models - Complex configurations
• Metadata Tracking - Practical metadata usage
• Error Handling - Handling validation errors

Examples & Help

• Examples - Common use cases
• Troubleshooting - Solutions to common problems

Key Concepts at a Glance

Precedence Order (lowest to highest):

Defaults < Global Config < Project Config < Dotenv < Environment Vars < Overrides

Metadata Tracking:

source = metadata.get_source("database_url")
print(source.source)        # Where it came from
print(source.source_path)   # File path or env var name
print(source.raw_value)     # Original value

Where to Go Next

👉 New here? Start with Getting Started

👉 Want to learn the design? Read Precedence Order

👉 Ready to code? Jump to Usage Guides

👉 Looking for examples? Check Examples

👉 Troubleshooting? See Troubleshooting