Skip to content

Configure#

Global configure()#

Customize defaults for the entire application — programmatically or via environment variables:

"""Global dature.configure() — customize masking, errors, loading."""

from dataclasses import dataclass
from pathlib import Path

import dature

SHARED_DIR = Path(__file__).parents[2] / "shared"


@dataclass
class Config:
    host: str
    port: int
    debug: bool = False


# 1. Default config — debug is off, no report
config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is None

# 2. Enable debug globally via dature.configure()
dature.configure(loading={"debug": True})

config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is not None

# 3. Reset to defaults — debug is off again
dature.configure(loading={})

config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is None

"""Global dature.configure() via environment variables — DATURE_ prefix."""

import os
from dataclasses import dataclass
from pathlib import Path

import dature

SHARED_DIR = Path(__file__).parents[2] / "shared"

# Set env vars before first load — dature reads DATURE_* on first use
os.environ["DATURE_LOADING__DEBUG"] = "true"


@dataclass
class Config:
    host: str
    port: int
    debug: bool = False


# 1. DATURE_LOADING__DEBUG=true — debug is on, report attached
config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is not None

# 2. Override env with dature.configure() — debug is off
dature.configure(loading={"debug": False})

config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is None

# 3. Reset to env defaults — debug is on again
dature.configure(loading={"debug": True})

config = dature.load(
    dature.Yaml12Source(file=SHARED_DIR / "common_app.yaml"),
    schema=Config,
)
report = dature.get_load_report(config)
assert report is not None

host: localhost
port: 8080
debug: false

MaskingConfig#

@dataclass(frozen=True, slots=True)
class MaskingConfig:
    mask: str = "<REDACTED>"
    visible_prefix: int = 0
    visible_suffix: int = 0
    min_heuristic_length: int = 8
    heuristic_threshold: float = 0.5
    secret_field_names: tuple[str, ...] = (
        "password",
        "passwd",
        "secret",
        "token",
        "api_key",
        "apikey",
        "api_secret",
        "access_key",
        "private_key",
        "auth",
        "credential",
    )
    mask_secrets: bool = True

ErrorDisplayConfig#

@dataclass(frozen=True, slots=True)
class ErrorDisplayConfig:
    max_visible_lines: int = 3
    max_line_length: int = 80

LoadingConfig#

@dataclass(frozen=True, slots=True)
class LoadingConfig:
    cache: bool | timedelta = True
    debug: bool = False
    nested_resolve_strategy: NestedResolveStrategy = "flat"
    expand_env_vars: ExpandEnvVarsMode = "default"
    search_system_paths: bool = True
    system_config_dirs: SystemConfigDirsArg = field(default_factory=_default_system_config_dirs)
    encoding: str | None = None

type_loaders#

Register global custom type loaders that apply to all dature.load() calls. See Custom Types & Loaders.

Environment Variables#

dature auto-loads its own config from DATURE_* environment variables on first use. Nested fields use __ as delimiter:

Variable Config Field Description
DATURE_MASKING__MASK MaskingConfig mask Replacement string for masked values
DATURE_MASKING__VISIBLE_PREFIX MaskingConfig visible_prefix Number of characters left visible at the start
DATURE_MASKING__VISIBLE_SUFFIX MaskingConfig visible_suffix Number of characters left visible at the end
DATURE_MASKING__MIN_HEURISTIC_LENGTH MaskingConfig min_heuristic_length Minimum field value length for auto-detection of secrets by field name
DATURE_MASKING__HEURISTIC_THRESHOLD MaskingConfig heuristic_threshold Uncommon bigram ratio threshold for heuristic secret detection (0.0–1.0)
DATURE_MASKING__MASK_SECRETS MaskingConfig mask_secrets Enable or disable secret masking globally
DATURE_ERROR_DISPLAY__MAX_VISIBLE_LINES ErrorDisplayConfig max_visible_lines Max lines shown in error messages for source file previews
DATURE_ERROR_DISPLAY__MAX_LINE_LENGTH ErrorDisplayConfig max_line_length Max character width per line in error messages
DATURE_LOADING__CACHE LoadingConfig cache Enable caching. true/false or a timedelta string (e.g. 0:00:30, 30 seconds) for TTL. See Caching
DATURE_LOADING__DEBUG LoadingConfig debug Attach LoadReport to every loaded instance
DATURE_LOADING__NESTED_RESOLVE_STRATEGY LoadingConfig nested_resolve_strategy Default priority for JSON vs flat keys: flat (default) or json. See Nested Resolve
DATURE_LOADING__EXPAND_ENV_VARS LoadingConfig expand_env_vars Default env var expansion mode: default, disabled, empty, or strict. See Env Expansion
DATURE_LOADING__SEARCH_SYSTEM_PATHS LoadingConfig search_system_paths Enable automatic config file search in standard system locations (~/.config/, /etc/, %APPDATA%/). See Config Search
DATURE_LOADING__SYSTEM_CONFIG_DIRS LoadingConfig system_config_dirs Custom colon-separated list of directories for config file search (overrides auto-detection)