Source code for ctdcast.config.loader

"""Config loading utilities for ctdcast reports."""

from __future__ import annotations

import copy
import warnings
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any

import yaml


[docs] class ConfigError(ValueError): """A YAML file ctdcast reads could not be used as written; the message says where and why."""
class _StrictLoader(yaml.SafeLoader): """A safe YAML loader that refuses a key repeated in one mapping. Plain YAML keeps the last of two equal keys and drops the first without a word, so a second ``steps:`` under ``data_processing:``, or two steps written as one list item, would silently lose everything under the first. """ def construct_mapping( self, node: yaml.MappingNode, deep: bool = False ) -> dict: # PyYAML's signature seen: dict[Any, int] = {} for key_node, _value in node.value: key = self.construct_object(key_node, deep=deep) line = key_node.start_mark.line + 1 if key in seen: raise _DuplicateKey(key, seen[key], line) seen[key] = line return super().construct_mapping(node, deep=deep) class _DuplicateKey(yaml.YAMLError): def __init__(self, key: Any, first: int, second: int) -> None: # noqa: ANN401 # any YAML key super().__init__(f"{key!r} at lines {first} and {second}") self.key, self.first, self.second = key, first, second #: Names of processing steps, for the hint when one is repeated inside a list item. _STEP_NAMES = { "wildedit", "alignctd", "celltm", "window_filter", "filter", "loopedit", "split", "binavg", }
[docs] def load_yaml(path: Path | str) -> Any: # noqa: ANN401 # whatever the file holds """Read a YAML file, refusing a key repeated in one mapping. Parameters ---------- path : path-like The file. Returns ------- object The parsed content (``None`` for an empty file). Raises ------ ConfigError When the file cannot be parsed, or a key appears twice in the same block; the message names the file, the key and the lines, and what to change. FileNotFoundError When the file does not exist. """ p = Path(path) text = p.read_text(encoding="utf-8") try: return yaml.load(text, Loader=_StrictLoader) # a SafeLoader subclass except _DuplicateKey as exc: if exc.key in _STEP_NAMES: hint = ( f"If these are two {exc.key} steps, start each with '- ' on its own line so " "they are separate items in the steps list; written as one item, only the " "second would run." ) else: hint = ( "YAML would keep only the second and silently drop everything under the " f"first; merge the two {exc.key!r} blocks into one, or delete one." ) msg = ( f"{p}: {exc.key!r} appears twice in the same block, at lines {exc.first} and " f"{exc.second}. {hint}" ) raise ConfigError(msg) from None except yaml.YAMLError as exc: mark = getattr(exc, "problem_mark", None) where = f" at line {mark.line + 1}, column {mark.column + 1}" if mark else "" problem = getattr(exc, "problem", None) or str(exc) msg = f"{p}: not valid YAML{where}: {problem}" raise ConfigError(msg) from None
[docs] def load_config(path: Path | str) -> dict[str, Any]: """Read a cruise ``config.yaml``: a mapping, with no key repeated in one block. Parameters ---------- path : path-like The config file. Returns ------- dict The parsed config; empty for an empty file. Raises ------ ConfigError As :func:`load_yaml`, or when the file is not a mapping of blocks. FileNotFoundError When the file does not exist. """ data = load_yaml(path) if data is None: return {} if not isinstance(data, dict): msg = ( f"{path}: expected blocks such as data:, output:, data_processing: at the top " f"level, got a {type(data).__name__}" ) raise ConfigError(msg) return data
[docs] def warn_section_yaml_deprecated() -> None: """Warn that ``section_yaml`` is deprecated in favour of ``groupings_yaml``. The single notice for the config-key spelling and the ``report()`` / ``init`` parameter spelling, so every entry point that still honours ``section_yaml`` emits the same ``DeprecationWarning`` naming the replacement and the removal version (0.5.0). """ warnings.warn( "`section_yaml` is deprecated and will be removed in 0.5.0; use `groupings_yaml` " "(the file holds both sections: and timeseries:).", DeprecationWarning, stacklevel=3, )
[docs] def groupings_path(data: dict[str, Any] | None) -> Path | None: """Return the groupings YAML named by a config ``data:`` block. The file defines two kinds of cast group -- ``sections:`` (transects plotted against distance) and ``timeseries:`` (repeat stations plotted against time) -- so ``groupings_yaml`` is the key, and ``ctd_groupings.yaml`` the conventional filename. ``section_yaml`` named only half of what the file does; it stays accepted, with a ``DeprecationWarning``, until 0.5.0. Parameters ---------- data : dict or None The config's ``data:`` mapping. Returns ------- Path or None The path, or ``None`` when neither key is set. """ d = data or {} value = d.get("groupings_yaml") if value is None and d.get("section_yaml"): warn_section_yaml_deprecated() value = d.get("section_yaml") return Path(str(value)) if value else None
[docs] @dataclass class SectionsConfig: """Parsed contents of a ``ctd_sections.yaml`` file. Loaded once at the ``report()`` entry point and passed to page builders, replacing four independent ``yaml.safe_load`` calls scattered across the reports package. """ sections: dict[str, dict[str, Any]] = field(default_factory=dict) timeseries: dict[str, dict[str, Any]] = field(default_factory=dict) # Values are not all strings: ``contributors`` is a list of mappings and # ``creator``/``embargo`` are mappings. See ctdcast.config.people. cruise_info: dict[str, Any] = field(default_factory=dict)
[docs] @classmethod def from_yaml(cls, path: Path | str) -> SectionsConfig: """Load a ``SectionsConfig`` from a ``ctd_sections.yaml`` file. Returns an empty ``SectionsConfig`` if the file does not exist. """ p = Path(path) if not p.exists(): return cls() data: dict[str, Any] = load_yaml(p) or {} return cls( sections=data.get("sections") or {}, timeseries=data.get("timeseries") or {}, cruise_info=data.get("cruise_info") or {}, )
[docs] def load_display_config(cruise_cfg: dict[str, Any]) -> dict[str, dict]: """Return VARIABLES with cruise-level overrides applied. Package defaults come from :data:`ctdcast.config.parameters.VARIABLES`. Per-cruise overrides are read from ``cruise_cfg["display"]["variables"]`` (the ``display:`` block in the cruise ``config.yaml``). Later keys win. Returns a new dict; nothing global is mutated, so the result can be recorded in the output file's attributes for provenance. Example cruise config override:: display: variables: temperature_1: vmin: 4 vmax: 25 """ from ctdcast.config.parameters import VARIABLES merged: dict[str, dict] = copy.deepcopy(VARIABLES) overrides = (cruise_cfg.get("display") or {}).get("variables") or {} for name, over in overrides.items(): merged.setdefault(name, {}).update(over) return merged