Skip to content

Automatic Config File Search#

By default, all file-based sources automatically search for config files in standard system locations. This feature is enabled by default and works across all platforms.

Search Order#

When you specify a config file, dature searches in the following order:

  1. Specified path - The path you provide (relative to current working directory or absolute)
  2. User config directories (platform-specific):
  3. Linux: ~/.config/
  4. macOS: ~/Library/Application Support/, ~/.config/
  5. Windows: %APPDATA%/
  6. System config directories (Linux/macOS only):
  7. /etc/
  8. /etc/xdg/

Examples#

By default, file-based sources search standard config locations. This example writes app.yaml into a directory, where the search occurs, and points the platform config env var there so the loader finds it through system search.

import os
import sys
import tempfile
from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int


with tempfile.TemporaryDirectory() as tmp:
    config_dir = Path(tmp)
    (config_dir / "app.yaml").write_text(
        (SHARED_DIR / "common_app.yaml").read_text(),
    )

    os.environ["APPDATA" if sys.platform == "win32" else "XDG_CONFIG_HOME"] = (
        str(config_dir)
    )

    config = dature.load(
        dature.Yaml12Source(file="app.yaml"),
        schema=Config,
    )

    assert config.host == "localhost"
    assert config.port == 8080

import tempfile
from dataclasses import dataclass

import dature


@dataclass
class Config:
    host: str
    port: int


with tempfile.TemporaryDirectory() as tmpdir:
    custom_dir = Path(tmpdir)

    config_file = custom_dir / "app.yaml"
    config_file.write_text((SHARED_DIR / "common_app.yaml").read_text())

    config = dature.load(
        dature.Yaml12Source(
            file="app.yaml",
            system_config_dirs=(custom_dir,),
        ),
        schema=Config,
    )

    assert config.host == "localhost"
    assert config.port == 8080

import tempfile
from dataclasses import dataclass

import dature


@dataclass
class Config:
    debug: bool = True
    name: str = "default"


with tempfile.TemporaryDirectory() as tmpdir:
    tmpdir_path = Path(tmpdir)
    config_file = tmpdir_path / "config.yaml"
    config_file.write_text((SHARED_DIR / "common_app.yaml").read_text())

    dature.configure(
        loading={
            "search_system_paths": False,
            "system_config_dirs": (tmpdir_path,),
        },
    )

    dature.load(
        dature.Yaml12Source(file="config.yaml"),
        schema=Config,
    )  # Failed

Disable search only for one source while the global setting remains unchanged. Even though system_config_dirs contains the directory with the file, it won't be searched — search_system_paths=False overrides it locally. 

import tempfile
from dataclasses import dataclass

import dature


@dataclass
class Config:
    name: str
    value: int


with tempfile.TemporaryDirectory() as tmpdir:
    tmpdir_path = Path(tmpdir)
    config_file = tmpdir_path / "local.yaml"
    config_file.write_text((SHARED_DIR / "common_app.yaml").read_text())

    dature.load(
        dature.Yaml12Source(
            file="local.yaml",
            system_config_dirs=(tmpdir_path,),
            search_system_paths=False,
        ),
        schema=Config,
    )

Configuration#

For global and per-source configuration options, see Configure.

Environment Variables#

The following environment variables affect search paths:

  • XDG_CONFIG_HOME - Overrides ~/.config/ on Linux/macOS
  • XDG_CONFIG_DIRS - Overrides /etc/xdg/ on Linux
  • APPDATA - Used for Windows user config directory