config

TOML configuration loading. See the Configuration guide for the file's contents and lookup order.

config

Configuration file loading for gridcalc.

Lookup order (first found wins, CWD overrides user config): 1. ./gridcalc.toml 2. $XDG_CONFIG_HOME/gridcalc/gridcalc.toml (default: ~/.config/gridcalc/gridcalc.toml)

Config dataclass

Config(
    editor: str = "",
    sandbox: bool = True,
    width: int = 0,
    format: str = "",
    libs: list[str] = list(),
    allowed_modules: list[str] = list(),
    keys: dict[str, dict[str, list[ParsedKey]]] = dict(),
    config_path: str = "",
    warnings: list[str] = list(),
)

load_config

load_config(path: Path | str | None = None) -> Config

Load configuration from a TOML file.

If path is None, uses the standard lookup order. On a parse error or missing file, returns a default Config (with the parse error reported via cfg.warnings and printed to stderr by the caller, if desired).

Source code in src/gridcalc/config.py

def load_config(path: Path | str | None = None) -> Config:
    """Load configuration from a TOML file.

    If path is None, uses the standard lookup order. On a parse error or
    missing file, returns a default Config (with the parse error reported
    via ``cfg.warnings`` and printed to stderr by the caller, if desired).
    """
    if path is None:
        resolved = find_config()
    else:
        resolved = Path(path) if not isinstance(path, Path) else path
        if not resolved.is_file():
            return Config()

    if resolved is None:
        return Config()

    try:
        with open(resolved, "rb") as f:
            data = tomllib.load(f)
    except OSError as exc:
        cfg = Config()
        cfg.config_path = str(resolved)
        cfg.warnings.append(f"could not read {resolved}: {exc}")
        return cfg
    except tomllib.TOMLDecodeError as exc:
        cfg = Config()
        cfg.config_path = str(resolved)
        cfg.warnings.append(f"TOML parse error in {resolved}: {exc}")
        return cfg

    cfg = _parse_config(data)
    cfg.config_path = str(resolved)
    return cfg

find_config

find_config() -> Path | None

Find the first gridcalc.toml in the lookup order.

Source code in src/gridcalc/config.py

def find_config() -> Path | None:
    """Find the first gridcalc.toml in the lookup order."""
    cwd_config = Path.cwd() / CONFIG_FILENAME
    if cwd_config.is_file():
        return cwd_config

    user_config = user_config_dir() / CONFIG_FILENAME
    if user_config.is_file():
        return user_config

    return None

user_config_dir

user_config_dir() -> Path

Return the user-level config directory (XDG_CONFIG_HOME/gridcalc).

Source code in src/gridcalc/config.py

def user_config_dir() -> Path:
    """Return the user-level config directory (XDG_CONFIG_HOME/gridcalc)."""
    xdg = os.environ.get("XDG_CONFIG_HOME")
    if xdg:
        return Path(xdg) / "gridcalc"
    return Path.home() / ".config" / "gridcalc"

emit_warnings

emit_warnings(cfg: Config) -> None

Print any config warnings to stderr. Call once after load_config.

Source code in src/gridcalc/config.py

def emit_warnings(cfg: Config) -> None:
    """Print any config warnings to stderr. Call once after load_config."""
    for w in cfg.warnings:
        print(f"gridcalc: config warning: {w}", file=sys.stderr)