Confocal

A multi-layer configuration management library built on pydantic with source tracking and profile support.

Features

• Hierarchical config file discovery (searches parent directories)
• Profile support for different environments
• Full source tracking to explain where each config value came from
• Built on pydantic for robust validation and type safety
• Rich terminal output for config inspection

Installation

pip install confocal

Quick Start

from confocal import BaseConfig
from pydantic import Field

class MyConfig(BaseConfig):
    database_url: str
    name: str = Field(default="Anonymous")
    debug: bool = False

# Load config from raiconfig.toml, environment variables, etc.
config = MyConfig.load()

# Show where config values came from
config.explain()

Config Sources (in order of precedence)

1. Initialization arguments
2. Environment variables
3. Active profile from config file
4. Config files (YAML or TOML)
5. Default values

Using Config Files

Confocal supports both TOML and YAML config files. Specify which format to use in your config class:

Using TOML (default)

class MyConfig(BaseConfig):
    model_config = SettingsConfigDict(
        toml_file="config.toml",
    )

Using YAML

class MyConfig(BaseConfig):
    model_config = SettingsConfigDict(
        yaml_file="config.yaml",
    )

Using Profiles

Profile support works with both TOML and YAML files.

TOML example (raiconfig.toml):

database_url = "postgresql://prod-db:5432"

[profile.dev]
database_url = "postgresql://localhost:5432"
debug = true

[profile.test]
database_url = "postgresql://test-db:5432"

YAML example (config.yaml):

database_url: "postgresql://prod-db:5432"

profile:
  dev:
    database_url: "postgresql://localhost:5432"
    debug: true
  test:
    database_url: "postgresql://test-db:5432"

Activate a profile:

export ACTIVE_PROFILE=dev

YAML Environment Variables

YAML configs support environment variable substitution:

database_url: "{{ env_var('DB_URL', 'postgresql://localhost:5432') }}"
api_key: "{{ env_var('API_KEY') }}"  # Required, will error if not set

The shell-style ${VAR} syntax is also supported (in YAML and TOML):

database_url: "${DB_URL:-postgresql://localhost:5432}"  # With default
api_key: "${API_KEY}"  # Required, will error if not set
literal: "$${NOT_SUBSTITUTED}"  # Escape: becomes the literal text ${NOT_SUBSTITUTED}

Lines starting with # are not substituted.

Advanced Usage

Show full config inheritance chain:

config.explain(verbose=True)

Manually find nearest config file in parent directories:

from confocal import find_upwards
config_path = find_upwards("config.toml")

License

MIT