Settings¶

def find_egregora_config(start_dir: Path, *, site: str | None = None) -> Path:
    """Search upward for .egregora.toml.

    Args:
        start_dir: Starting directory for upward search
        site: Optional site identifier (reserved for future use)

    Returns:
        Path to config file if found

    Raises:
        ConfigNotFoundError: If the config file cannot be found

    """
    current = start_dir.expanduser().resolve()
    for candidate in (current, *current.parents):
        toml_path = candidate / ".egregora.toml"
        if toml_path.exists():
            return toml_path

    raise ConfigNotFoundError(start_dir)

def load_egregora_config(site_root: Path | None = None, *, site: str | None = None) -> EgregoraConfig:
    """Load Egregora configuration from .egregora.toml.

    Configuration priority (highest to lowest):
    1. CLI (applied via from_cli_overrides later)
    2. Environment variables (EGREGORA_SECTION__KEY)
    3. Config file (.egregora.toml)
    4. Defaults

    Args:
        site_root: Root directory of the site. If None, uses current working directory.
        site: Optional site identifier to select from the sites mapping.

    Returns:
        Validated EgregoraConfig instance

    Raises:
        ConfigValidationError: If config file contains invalid data
        ConfigNotFoundError: If the config file cannot be found and a default one is not created.

    """
    if site_root is None:
        site_root = Path.cwd()

    try:
        config_path = find_egregora_config(site_root, site=site)
        logger.info("Loading config from %s", config_path)
    except ConfigNotFoundError:
        logger.info("No configuration found, creating default config at %s", site_root / ".egregora.toml")
        return create_default_config(site_root, site=site or DEFAULT_SITE_NAME)

    try:
        raw_config = config_path.read_text(encoding="utf-8")
        file_data = tomllib.loads(raw_config)

        # Create base config with defaults (environment overrides applied)
        base_config = EgregoraConfig()
        base_dict = base_config.model_dump(mode="json")

        # Merge file config into base, skipping keys that are set in env vars
        env_override_paths = _collect_env_override_paths()
        selected_site, site_data = _normalize_sites_config(file_data, site=site)

        env_override_paths_with_site = set(env_override_paths)
        for path in env_override_paths:
            if path and path[0] == "sites":
                env_override_paths_with_site.add(path)
            else:
                env_override_paths_with_site.add(("sites", selected_site, *path))

        wrapped_base = {"sites": {selected_site: base_dict}}
        wrapped_override = {"sites": {selected_site: site_data}}
        merged = _merge_config(wrapped_base, wrapped_override, env_override_paths_with_site)

        selected_config = merged["sites"][selected_site]
        return EgregoraConfig.model_validate(selected_config)

    except ValidationError as e:
        logger.exception("Configuration validation failed for %s:", config_path)
        for error in e.errors():
            loc = " -> ".join(str(location_part) for location_part in error["loc"])
            logger.exception("  %s: %s", loc, error["msg"])
        raise ConfigValidationError(e.errors()) from e
    except (OSError, ValueError) as e:
        logger.exception("Failed to read or parse config from %s", config_path)
        msg = f"Failed to process config file: {e}"
        raise ConfigError(msg) from e

def create_default_config(site_root: Path, *, site: str = DEFAULT_SITE_NAME) -> EgregoraConfig:
    """Create default .egregora.toml and return it.

    Args:
        site_root: Root directory of the site
        site: Site identifier to write under the sites mapping

    Returns:
        EgregoraConfig with all defaults

    """
    config = EgregoraConfig()  # All defaults from Pydantic
    save_egregora_config(config, site_root, site=site)
    logger.info("Created default config at %s/.egregora.toml", site_root)
    return config

def save_egregora_config(config: EgregoraConfig, site_root: Path, *, site: str = DEFAULT_SITE_NAME) -> Path:
    """Save EgregoraConfig to .egregora.toml in site_root.

    Args:
        config: EgregoraConfig instance to save
        site_root: Root directory of the site
        site: Site identifier to write under the sites mapping

    Returns:
        Path to the saved config file

    """
    config_path = site_root / ".egregora.toml"
    config_path.parent.mkdir(parents=True, exist_ok=True)

    # Export as dict under the selected site mapping
    data = {"sites": {site: config.model_dump(exclude_defaults=False, mode="json")}}

    # Remove None values as tomli_w doesn't support them
    def _clean_nones(d: dict[str, Any]) -> dict[str, Any]:
        cleaned = {}
        for k, v in d.items():
            if v is None:
                continue
            if isinstance(v, dict):
                v = _clean_nones(v)
            elif isinstance(v, list):
                v = [_clean_nones(item) if isinstance(item, dict) else item for item in v if item is not None]
            cleaned[k] = v
        return cleaned

    data = _clean_nones(data)

    # Write as TOML
    toml_str = tomli_w.dumps(data)

    config_path.write_text(toml_str, encoding="utf-8")
    logger.debug("Saved config to %s", config_path)

    return config_path

def parse_date_arg(date_str: str, _arg_name: str = "date") -> date:
    """Parse a date string in YYYY-MM-DD format.

    Args:
        date_str: Date string in YYYY-MM-DD format
        _arg_name: Name of the argument (for error messages)

    Returns:
        date object in UTC

    Raises:
        InvalidDateFormatError: If date_str is not in YYYY-MM-DD format

    """
    try:
        return datetime.strptime(date_str, "%Y-%m-%d").replace(tzinfo=UTC).date()
    except ValueError as e:
        raise InvalidDateFormatError(date_str) from e

def validate_timezone(timezone_str: str) -> ZoneInfo:
    """Validate timezone string and return ZoneInfo object.

    Args:
        timezone_str: Timezone identifier (e.g., 'America/New_York', 'UTC')

    Returns:
        ZoneInfo object for the specified timezone

    Raises:
        InvalidTimezoneError: If timezone_str is not a valid timezone identifier

    """
    try:
        return ZoneInfo(timezone_str)
    except Exception as e:
        raise InvalidTimezoneError(timezone_str, e) from e