lib-layered-config 4.1.0__py3-none-any.whl

lib_layered_config/adapters/file_loaders/structured.py

@@ -0,0 +1,376 @@
+"""Structured configuration file loaders.
+
+Convert on-disk artifacts into Python mappings that the merge layer understands.
+Adapters are small wrappers around ``tomllib``/``json``/``yaml.safe_load`` so
+error handling, observability, and immutability policies live in one place.
+
+Contents:
+    - ``BaseFileLoader``: shared primitives for reading files and asserting
+      mapping outputs.
+    - ``TOMLFileLoader`` / ``JSONFileLoader`` / ``YAMLFileLoader``: thin
+      adapters that delegate to parser-specific helpers.
+    - ``_log_file_read`` / ``_log_file_loaded`` / ``_log_file_invalid``:
+      structured logging helpers reused across loaders.
+    - ``_ensure_yaml_available``: guard ensuring YAML support is present before
+      attempting to parse.
+
+Invoked by :func:`lib_layered_config.core._load_files` to parse structured files
+before passing the results to the merge policy.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found,no-redef]
+from collections.abc import Mapping
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import Any, NoReturn
+
+from ...domain.errors import InvalidFormatError, NotFoundError
+from ...observability import log_debug, log_error
+
+yaml: ModuleType | None = None
+
+
+FILE_LAYER = "file"
+"""Layer label used in structured logging for file-oriented events.
+
+Tag observability events originating from file loaders with a consistent name.
+
+Constant referenced by logging helpers within this module.
+"""
+
+
+def _log_file_read(path: str, size: int) -> None:
+    """Record that *path* was read with *size* bytes.
+
+    Provide insight into which files were accessed and their size for
+    troubleshooting.
+
+    Args:
+        path: Absolute path read from disk.
+        size: Number of bytes read.
+    """
+    log_debug("config_file_read", layer=FILE_LAYER, path=path, size=size)
+
+
+def _log_file_loaded(path: str, format_name: str) -> None:
+    """Record a successful parse for *path* and *format_name*.
+
+    Trace successful parsing events and note which parser handled the file.
+
+    Args:
+        path: Absolute file path.
+        format_name: Parser identifier (e.g., ``"toml"``).
+    """
+    log_debug("config_file_loaded", layer=FILE_LAYER, path=path, format=format_name)
+
+
+def _log_file_invalid(path: str, format_name: str, exc: Exception) -> None:
+    """Capture parser failures for diagnostics.
+
+    Surface parse errors with enough context (path, format, message) for quick
+    troubleshooting.
+
+    Args:
+        path: File path that failed to parse.
+        format_name: Parser identifier.
+        exc: Exception raised by the parser.
+    """
+    log_error(
+        "config_file_invalid",
+        layer=FILE_LAYER,
+        path=path,
+        format=format_name,
+        error=str(exc),
+    )
+
+
+def _raise_invalid_format(path: str, format_name: str, exc: Exception) -> NoReturn:
+    """Log and raise :class:`InvalidFormatError` for parser errors.
+
+    Reuse logging side-effects while presenting callers with a uniform
+    exception type.
+
+    Args:
+        path: File path being parsed.
+        format_name: Parser identifier.
+        exc: Original exception raised by the parser.
+    """
+    _log_file_invalid(path, format_name, exc)
+    raise InvalidFormatError(f"Invalid {format_name.upper()} in {path}: {exc}") from exc
+
+
+def _ensure_yaml_available() -> None:
+    """Announce clearly whether PyYAML can be reached.
+
+    YAML support is optional; the loader must fail fast with guidance when the
+    dependency is absent so callers can install the expected extra.
+
+    Raises:
+        NotFoundError: When the PyYAML package cannot be imported.
+    """
+    _require_yaml_module()
+
+
+def _require_yaml_module() -> ModuleType:
+    """Fetch the PyYAML module or explain its absence.
+
+    Downstream helpers need the module object for access to both ``safe_load``
+    and the package-specific ``YAMLError`` type.
+
+    Returns:
+        The imported PyYAML module.
+
+    Raises:
+        NotFoundError: When PyYAML is not installed.
+    """
+    module = _load_yaml_module()
+    if module is None:
+        raise NotFoundError("PyYAML is required for YAML configuration support")
+    return module
+
+
+def _load_yaml_module() -> ModuleType | None:
+    """Import PyYAML on demand, caching the result for future readers.
+
+    Avoid importing optional dependencies unless they are genuinely needed,
+    while still ensuring subsequent calls reuse the same module object.
+
+    Returns:
+        The PyYAML module when available; otherwise ``None``.
+    """
+    global yaml
+    if yaml is not None:
+        return yaml
+    try:
+        yaml = import_module("yaml")
+    except ModuleNotFoundError:  # pragma: no cover - optional dependency
+        yaml = None
+    return yaml
+
+
+class BaseFileLoader:
+    """Common utilities shared by the structured file loaders.
+
+    Avoid duplicating file I/O, error handling, and mapping validation across
+    individual loaders.
+
+    Provides reusable helpers for reading files and asserting parser outputs.
+    """
+
+    def _read(self, path: str) -> bytes:
+        """Read *path* as bytes, raising :class:`NotFoundError` when the file is missing.
+
+        Centralise file existence checks and logging so all loaders behave
+        consistently.
+
+        Args:
+            path: Absolute file path expected to exist.
+
+        Returns:
+            Raw file contents.
+
+        Side Effects:
+            Emits ``config_file_read`` debug events.
+
+        Examples:
+            >>> from tempfile import NamedTemporaryFile
+            >>> tmp = NamedTemporaryFile(delete=False)
+            >>> _ = tmp.write(b"key = 'value'")
+            >>> tmp.close()
+            >>> BaseFileLoader()._read(tmp.name)[:3]
+            b'key'
+            >>> Path(tmp.name).unlink()
+        """
+        file_path = Path(path)
+        if not file_path.is_file():
+            raise NotFoundError(f"Configuration file not found: {path}")
+        payload = file_path.read_bytes()
+        _log_file_read(path, len(payload))
+        return payload
+
+    @staticmethod
+    def _ensure_mapping(data: object, *, path: str) -> Mapping[str, object]:
+        """Ensure *data* behaves like a mapping, otherwise raise ``InvalidFormatError``.
+
+        Merging logic expects mapping-like structures; other types indicate a
+        malformed configuration file.
+
+        Args:
+            data: Object produced by the parser.
+            path: Originating file path used for error messaging.
+
+        Returns:
+            The validated mapping.
+
+        Examples:
+            >>> BaseFileLoader._ensure_mapping({"key": 1}, path="demo")
+            {'key': 1}
+            >>> BaseFileLoader._ensure_mapping(42, path="demo")
+            Traceback (most recent call last):
+            ...
+            lib_layered_config.domain.errors.InvalidFormatError: File demo did not produce a mapping
+        """
+        if not isinstance(data, Mapping):
+            raise InvalidFormatError(f"File {path} did not produce a mapping")
+        return data  # type: ignore[return-value]
+
+
+class TOMLFileLoader(BaseFileLoader):
+    """Load TOML documents using the standard library parser."""
+
+    def load(self, path: str) -> Mapping[str, object]:
+        """Return mapping extracted from TOML file at *path*.
+
+        TOML is the primary structured format in the documentation; this loader
+        provides friendly error messages and structured logging.
+
+        Args:
+            path: Absolute path to a TOML document.
+
+        Returns:
+            Parsed configuration data.
+
+        Side Effects:
+            Emits ``config_file_loaded`` debug events.
+
+        Examples:
+            >>> from tempfile import NamedTemporaryFile
+            >>> tmp = NamedTemporaryFile('w', delete=False, encoding='utf-8')
+            >>> _ = tmp.write('key = "value"')
+            >>> tmp.close()
+            >>> TOMLFileLoader().load(tmp.name)["key"]
+            'value'
+            >>> Path(tmp.name).unlink()
+        """
+        try:
+            raw_bytes = self._read(path)
+            decoded = raw_bytes.decode("utf-8")
+            parsed = tomllib.loads(decoded)
+        except (UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:  # type: ignore[attr-defined]
+            _raise_invalid_format(path, "toml", exc)
+        result = self._ensure_mapping(parsed, path=path)
+        _log_file_loaded(path, "toml")
+        return result
+
+
+class JSONFileLoader(BaseFileLoader):
+    """Load JSON documents.
+
+    Provide a drop-in parser for JSON configuration files.
+
+    Uses :mod:`json` to parse files and delegates validation/logging to the base class.
+    """
+
+    def load(self, path: str) -> Mapping[str, object]:
+        """Return mapping extracted from JSON file at *path*.
+
+        Provide parity with TOML for teams that prefer JSON configuration.
+
+        Args:
+            path: Absolute path to a JSON document.
+
+        Returns:
+            Parsed configuration mapping.
+
+        Side Effects:
+            Emits ``config_file_loaded`` debug events.
+
+        Examples:
+            >>> from tempfile import NamedTemporaryFile
+            >>> tmp = NamedTemporaryFile('w', delete=False, encoding='utf-8')
+            >>> _ = tmp.write('{"enabled": true}')
+            >>> tmp.close()
+            >>> JSONFileLoader().load(tmp.name)["enabled"]
+            True
+            >>> Path(tmp.name).unlink()
+        """
+        try:
+            payload: Any = json.loads(self._read(path))
+        except json.JSONDecodeError as exc:
+            _raise_invalid_format(path, "json", exc)
+        result = self._ensure_mapping(payload, path=path)
+        _log_file_loaded(path, "json")
+        return result
+
+
+class YAMLFileLoader(BaseFileLoader):
+    """Load YAML documents when PyYAML is available.
+
+    Support teams that rely on YAML without imposing a mandatory dependency.
+
+    Guards on PyYAML availability before delegating to :func:`yaml.safe_load`.
+    """
+
+    def load(self, path: str) -> Mapping[str, object]:
+        """Return mapping extracted from YAML file at *path*.
+
+        Some teams rely on YAML for configuration; this loader keeps behaviour
+        consistent with TOML/JSON while remaining optional.
+
+        Args:
+            path: Absolute path to a YAML document.
+
+        Returns:
+            Parsed configuration mapping.
+
+        Raises:
+            NotFoundError: When PyYAML is not installed.
+
+        Side Effects:
+            Emits ``config_file_loaded`` debug events.
+
+        Examples:
+            >>> if _load_yaml_module() is not None:  # doctest: +SKIP
+            ...     from tempfile import NamedTemporaryFile
+            ...     tmp = NamedTemporaryFile('w', delete=False, encoding='utf-8')
+            ...     _ = tmp.write('key: 1')
+            ...     tmp.close()
+            ...     YAMLFileLoader().load(tmp.name)["key"]
+            ...     Path(tmp.name).unlink()
+        """
+        _ensure_yaml_available()
+        yaml_module = _require_yaml_module()
+        raw_bytes = self._read(path)
+        parsed = _parse_yaml_bytes(raw_bytes, yaml_module, path)
+        mapping = self._ensure_mapping(parsed, path=path)
+        _log_file_loaded(path, "yaml")
+        return mapping
+
+
+def _parse_yaml_bytes(payload: bytes, module: ModuleType, path: str) -> object:
+    """Turn YAML bytes into a Python shape that mirrors the file.
+
+    Normalise the PyYAML parsing contract so callers always receive a mapping,
+    raising a domain-specific error when the parser signals invalid syntax.
+
+    Args:
+        payload: Raw YAML document supplied as bytes.
+        module: PyYAML module providing ::func:`safe_load` and the ``YAMLError`` base class.
+        path: Source identifier used to enrich error messages.
+
+    Returns:
+        Parsed document; an empty dict when the YAML payload evaluates to ``None``.
+
+    Raises:
+        InvalidFormatError: When PyYAML raises ``YAMLError`` while parsing the payload.
+
+    Examples:
+        >>> from types import SimpleNamespace
+        >>> fake = SimpleNamespace(safe_load=lambda data: {"key": data.decode("utf-8")}, YAMLError=Exception)
+        >>> _parse_yaml_bytes(b"value", fake, "memory.yaml")  # doctest: +ELLIPSIS
+        {'key': 'value'}
+    """
+    try:
+        document = module.safe_load(payload)
+    except module.YAMLError as exc:  # type: ignore[attr-defined]
+        _raise_invalid_format(path, "yaml", exc)
+    return {} if document is None else document

lib_layered_config/adapters/path_resolvers/__init__.py

@@ -0,0 +1,28 @@
+"""Path resolver adapters for platform-specific search order.
+
+Contents
+--------
+- ``DefaultPathResolver``: main adapter using Strategy pattern
+- ``PlatformStrategy``, ``PlatformContext``: base classes for strategies
+- ``LinuxStrategy``, ``MacOSStrategy``, ``WindowsStrategy``: platform implementations
+- ``DotenvPathFinder``: utility for discovering ``.env`` files
+- ``collect_layer``: helper for enumerating config files in a directory
+"""
+
+from ._base import PlatformContext, PlatformStrategy, collect_layer
+from ._dotenv import DotenvPathFinder
+from ._linux import LinuxStrategy
+from ._macos import MacOSStrategy
+from ._windows import WindowsStrategy
+from .default import DefaultPathResolver
+
+__all__ = [
+    "DefaultPathResolver",
+    "PlatformContext",
+    "PlatformStrategy",
+    "LinuxStrategy",
+    "MacOSStrategy",
+    "WindowsStrategy",
+    "DotenvPathFinder",
+    "collect_layer",
+]

lib_layered_config/adapters/path_resolvers/_base.py

@@ -0,0 +1,166 @@
+"""Base classes and shared utilities for platform-specific path resolution.
+
+Define the contract for platform strategies and provide shared utilities
+used across all platform implementations.
+
+Contents:
+    - ``PlatformContext``: dataclass holding resolution context (vendor, app, etc.)
+    - ``PlatformStrategy``: abstract base for platform-specific resolvers
+    - ``_collect_layer``: shared helper for enumerating config files
+    - ``_ALLOWED_EXTENSIONS``: supported config file extensions
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+#: Supported structured configuration file extensions used when expanding
+#: ``config.d`` directories.
+_ALLOWED_EXTENSIONS = (".toml", ".yaml", ".yml", ".json")
+"""File suffixes considered when expanding ``config.d`` directories.
+
+Ensure platform-specific discovery yields consistent formats and avoids
+non-structured files.
+
+Tuple of lowercase extensions in precedence order.
+"""
+
+
+@dataclass(frozen=True)
+class PlatformContext:
+    """Immutable context required for path resolution.
+
+    Encapsulate all inputs needed by platform strategies to resolve paths,
+    enabling dependency injection and simplified testing.
+
+    Attributes:
+        vendor: Vendor name used in platform-specific directory structures.
+        app: Application name used in platform-specific directory structures.
+        slug: Short identifier used in Linux/XDG paths.
+        cwd: Current working directory for project-relative searches.
+        env: Environment variable mapping (for overrides and XDG lookups).
+        hostname: Hostname for host-specific configuration lookups.
+        profile: Optional profile name for environment-specific configurations.
+    """
+
+    vendor: str
+    app: str
+    slug: str
+    cwd: Path
+    env: dict[str, str]
+    hostname: str
+    profile: str | None = None
+
+
+class PlatformStrategy(abc.ABC):
+    """Abstract base class for platform-specific path resolution strategies.
+
+    Encapsulate platform-specific logic in dedicated classes, keeping each
+    implementation small and testable.
+
+    Subclasses:
+        - ``LinuxStrategy``: XDG and ``/etc`` based resolution
+        - ``MacOSStrategy``: Application Support based resolution
+        - ``WindowsStrategy``: ProgramData/AppData based resolution
+    """
+
+    def __init__(self, ctx: PlatformContext) -> None:
+        """Store the resolution context.
+
+        Args:
+            ctx: Immutable context containing vendor, app, slug, env, etc.
+        """
+        self.ctx = ctx
+
+    def _profile_segment(self) -> Path:
+        """Return the profile path segment or an empty path.
+
+        When a profile is configured, all paths should include a
+        ``profile/<name>/`` subdirectory. This helper centralises that logic.
+
+        Returns:
+            ``Path("profile/<name>")`` when profile is set, otherwise ``Path()``.
+        """
+        if self.ctx.profile:
+            return Path("profile") / self.ctx.profile
+        return Path()
+
+    @abc.abstractmethod
+    def app_paths(self) -> Iterable[str]:
+        """Yield application-default configuration paths.
+
+        Returns:
+            Paths for the app layer (lowest precedence system-wide defaults).
+        """
+
+    @abc.abstractmethod
+    def host_paths(self) -> Iterable[str]:
+        """Yield host-specific configuration paths.
+
+        Returns:
+            Paths for the host layer (machine-specific overrides).
+        """
+
+    @abc.abstractmethod
+    def user_paths(self) -> Iterable[str]:
+        """Yield user-specific configuration paths.
+
+        Returns:
+            Paths for the user layer (per-user preferences).
+        """
+
+    @abc.abstractmethod
+    def dotenv_path(self) -> Path | None:
+        """Return the platform-specific ``.env`` fallback path.
+
+        Returns:
+            Fallback ``.env`` location or ``None`` if unsupported.
+        """
+
+
+def collect_layer(base: Path) -> Iterable[str]:
+    """Yield canonical config files and ``config.d`` entries under *base*.
+
+    Normalise discovery across operating systems while respecting preferred
+    configuration formats.
+
+    Emits ``config.toml`` when present and lexicographically ordered entries
+    from ``config.d`` limited to supported extensions.
+
+    Args:
+        base: Base directory for a particular layer.
+
+    Returns:
+        Absolute file paths discovered under ``base``.
+
+    Examples:
+        >>> from tempfile import TemporaryDirectory
+        >>> from pathlib import Path
+        >>> import os
+        >>> tmp = TemporaryDirectory()
+        >>> root = Path(tmp.name)
+        >>> file_a = root / 'config.toml'
+        >>> file_b = root / 'config.d' / '10-extra.json'
+        >>> file_b.parent.mkdir(parents=True, exist_ok=True)
+        >>> _ = file_a.write_text(os.linesep.join(['[settings]', 'value=1']), encoding='utf-8')
+        >>> _ = file_b.write_text('{"value": 2}', encoding='utf-8')
+        >>> sorted(Path(p).name for p in collect_layer(root))
+        ['10-extra.json', 'config.toml']
+        >>> tmp.cleanup()
+    """
+    config_file = base / "config.toml"
+    if config_file.is_file():
+        yield str(config_file)
+    yield from _collect_config_d(base / "config.d")
+
+
+def _collect_config_d(config_dir: Path) -> Iterable[str]:
+    """Yield config files from a config.d directory."""
+    if not config_dir.is_dir():
+        return
+    for path in sorted(config_dir.iterdir()):
+        if path.is_file() and path.suffix.lower() in _ALLOWED_EXTENSIONS:
+            yield str(path)

lib_layered_config/adapters/path_resolvers/_dotenv.py

@@ -0,0 +1,74 @@
+"""Dotenv path discovery utilities.
+
+Provide reusable helpers for discovering ``.env`` files via upward
+directory traversal and platform-specific fallback locations.
+
+Contents:
+    - ``DotenvPathFinder``: encapsulates dotenv discovery logic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._base import PlatformStrategy
+
+
+class DotenvPathFinder:
+    """Discover ``.env`` files by walking upward and checking platform fallbacks.
+
+    ``.env`` files may live near the project root or in OS-specific config
+    directories. This class provides unified discovery respecting precedence rules.
+    """
+
+    def __init__(self, cwd: Path, strategy: PlatformStrategy | None) -> None:
+        """Store context for dotenv discovery.
+
+        Args:
+            cwd: Starting directory for upward traversal.
+            strategy: Platform strategy providing the fallback ``.env`` location.
+        """
+        self.cwd = cwd
+        self.strategy = strategy
+
+    def find_paths(self) -> Iterable[str]:
+        """Yield candidate ``.env`` paths in precedence order.
+
+        Projects often co-locate ``.env`` files near the repository root;
+        walking upward mirrors ``dotenv`` tooling semantics.
+
+        Returns:
+            Ordered ``.env`` path strings.
+        """
+        yield from self._project_paths()
+        extra = self._platform_path()
+        if extra and extra.is_file():
+            yield str(extra)
+
+    def _project_paths(self) -> Iterable[str]:
+        """Yield ``.env`` files discovered by walking upward from cwd.
+
+        Returns:
+            ``.env`` paths discovered while traversing parent directories.
+        """
+        seen: set[Path] = set()
+        for directory in [self.cwd, *self.cwd.parents]:
+            candidate = directory / ".env"
+            if candidate in seen:
+                continue
+            seen.add(candidate)
+            if candidate.is_file():
+                yield str(candidate)
+
+    def _platform_path(self) -> Path | None:
+        """Return the platform-specific ``.env`` fallback location.
+
+        Returns:
+            Platform fallback path or ``None`` if no strategy is set.
+        """
+        if self.strategy is None:
+            return None
+        return self.strategy.dotenv_path()