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

lib_layered_config/adapters/_nested_keys.py

@@ -0,0 +1,126 @@
+"""Shared helpers for assigning nested keys using ``__`` delimiters.
+
+Both dotenv and environment adapters need identical logic for converting
+``SERVICE__TIMEOUT`` style keys into nested ``{"service": {"timeout": ...}}``
+structures. This module centralises that logic to eliminate duplication.
+
+Contents:
+    - ``assign_nested``: public function to assign a value at a nested key path.
+    - ``resolve_key``: case-insensitive key resolution.
+    - ``ensure_child_mapping``: ensure intermediate mappings exist.
+    - ``NESTED_KEY_DELIMITER``: constant for the ``__`` separator.
+
+Used by ``adapters.dotenv.default`` and ``adapters.env.default`` to share
+the nested key assignment algorithm.
+"""
+
+from __future__ import annotations
+
+from typing import Final, cast
+
+NESTED_KEY_DELIMITER: Final[str] = "__"
+"""Delimiter used to separate nested key segments in environment variables.
+
+Environment variables like ``SERVICE__TIMEOUT`` are split on this delimiter
+to create nested structures like ``{"service": {"timeout": ...}}``.
+"""
+
+
+def assign_nested(
+    target: dict[str, object],
+    key: str,
+    value: object,
+    *,
+    error_cls: type[Exception],
+) -> None:
+    """Assign ``value`` in ``target`` using case-insensitive ``__`` delimited syntax.
+
+    Args:
+        target: Mapping being mutated.
+        key: Key using ``__`` separators (e.g., ``SERVICE__TIMEOUT``).
+        value: Value to assign at the nested location.
+        error_cls: Exception type raised on scalar collisions.
+
+    Side Effects:
+        Mutates ``target`` in place.
+
+    Examples:
+        >>> data: dict[str, object] = {}
+        >>> assign_nested(data, 'SERVICE__TOKEN', 'secret', error_cls=ValueError)
+        >>> data
+        {'service': {'token': 'secret'}}
+    """
+    parts = key.split(NESTED_KEY_DELIMITER)
+    cursor = target
+    for part in parts[:-1]:
+        cursor = ensure_child_mapping(cursor, part, error_cls=error_cls)
+    final_key = resolve_key(cursor, parts[-1])
+    cursor[final_key] = value
+
+
+def resolve_key(mapping: dict[str, object], key: str) -> str:
+    """Return an existing key matching ``key`` case-insensitively, or a new lowercase key.
+
+    Preserve case stability while avoiding duplicates that differ only by case.
+
+    Args:
+        mapping: Mutable mapping being inspected.
+        key: Incoming key to resolve.
+
+    Returns:
+        Existing key name or newly normalised lowercase variant.
+
+    Examples:
+        >>> resolve_key({'timeout': 5}, 'TIMEOUT')
+        'timeout'
+        >>> resolve_key({}, 'Endpoint')
+        'endpoint'
+    """
+    lower = key.lower()
+    for existing in mapping:
+        if existing.lower() == lower:
+            return existing
+    return lower
+
+
+def ensure_child_mapping(
+    mapping: dict[str, object],
+    key: str,
+    *,
+    error_cls: type[Exception],
+) -> dict[str, object]:
+    """Ensure ``mapping[key]`` is a ``dict``, creating or validating as necessary.
+
+    Prevent accidental overwrites of scalar values when nested keys are introduced.
+
+    Args:
+        mapping: Mutable mapping being mutated.
+        key: Candidate key to ensure.
+        error_cls: Exception type raised when a scalar collision occurs.
+
+    Returns:
+        Child mapping stored at the resolved key.
+
+    Side Effects:
+        Mutates ``mapping`` by inserting a new child mapping when missing.
+
+    Examples:
+        >>> target: dict[str, object] = {}
+        >>> child = ensure_child_mapping(target, 'SERVICE', error_cls=ValueError)
+        >>> child == {}
+        True
+        >>> target
+        {'service': {}}
+    """
+    resolved = resolve_key(mapping, key)
+    if resolved not in mapping:
+        mapping[resolved] = dict[str, object]()
+    child = mapping[resolved]
+    if not isinstance(child, dict):
+        raise error_cls(f"Cannot override scalar with mapping for key {key}")
+    typed_child = cast(dict[str, object], child)
+    mapping[resolved] = typed_child
+    return typed_child
+
+
+__all__ = ["assign_nested", "resolve_key", "ensure_child_mapping"]

lib_layered_config/adapters/dotenv/__init__.py

@@ -0,0 +1 @@
+"""Dotenv adapter implementations."""

lib_layered_config/adapters/dotenv/default.py

@@ -0,0 +1,143 @@
+"""`.env` adapter.
+
+Implement the :class:`lib_layered_config.application.ports.DotEnvLoader`
+protocol by scanning for `.env` files using the search discipline captured in
+``docs/systemdesign/module_reference.md``.
+
+Contents:
+    - ``DefaultDotEnvLoader``: public loader that composes the helpers.
+    - ``_iter_candidates`` / ``_build_search_list``: gather candidate paths.
+    - ``_parse_dotenv``: strict parser converting dotenv files into nested dicts.
+    - ``_log_dotenv_*``: logging helpers that narrate discovery and parsing outcomes.
+    - Constants for parsing quote characters and delimiters.
+
+Feeds `.env` key/value pairs into the merge pipeline using the same nesting
+semantics as the environment adapter.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from typing import Final
+
+from ...domain.errors import InvalidFormatError
+from ...observability import log_debug, log_error
+from .._nested_keys import assign_nested
+
+# Constants for dotenv parsing
+_QUOTE_CHARS: Final[frozenset[str]] = frozenset({'"', "'"})
+_COMMENT_CHAR: Final[str] = "#"
+_INLINE_COMMENT_DELIMITER: Final[str] = " #"
+_KEY_VALUE_DELIMITER: Final[str] = "="
+
+DOTENV_LAYER = "dotenv"
+"""Layer name for structured logging calls."""
+
+
+def _log_dotenv_loaded(path: Path, keys: Mapping[str, object]) -> None:
+    """Log which dotenv file was loaded and its key names."""
+    log_debug("dotenv_loaded", layer=DOTENV_LAYER, path=str(path), keys=sorted(keys.keys()))
+
+
+def _log_dotenv_missing() -> None:
+    """Log that no dotenv file was found in the search path."""
+    log_debug("dotenv_not_found", layer=DOTENV_LAYER, path=None)
+
+
+def _log_dotenv_error(path: Path, line_number: int) -> None:
+    """Log a malformed line error with file path and line number."""
+    log_error("dotenv_invalid_line", layer=DOTENV_LAYER, path=str(path), line=line_number)
+
+
+class DefaultDotEnvLoader:
+    """Load a dotenv file into a nested configuration dictionary.
+
+    Searches candidate paths, parses the first existing file, and tracks
+    the loaded path for provenance.
+    """
+
+    def __init__(self, *, extras: Iterable[str] | None = None) -> None:
+        """Initialise with optional extra search paths from the path resolver."""
+        self._extras = [Path(p) for p in extras or []]
+        self.last_loaded_path: str | None = None
+
+    def load(self, start_dir: str | None = None) -> Mapping[str, object]:
+        """Return the first parsed dotenv file discovered in the search order.
+
+        Searches from *start_dir* upward plus any extras, parses the first
+        existing file into a nested mapping, and sets :attr:`last_loaded_path`.
+        """
+        candidates = _build_search_list(start_dir, self._extras)
+        self.last_loaded_path = None
+        for candidate in candidates:
+            if not candidate.is_file():
+                continue
+            self.last_loaded_path = str(candidate)
+            data = _parse_dotenv(candidate)
+            _log_dotenv_loaded(candidate, data)
+            return data
+        _log_dotenv_missing()
+        return {}
+
+
+def _build_search_list(start_dir: str | None, extras: Iterable[Path]) -> list[Path]:
+    """Combine upward-search candidates with platform-specific extras."""
+    return [*list(_iter_candidates(start_dir)), *extras]
+
+
+def _iter_candidates(start_dir: str | None) -> Iterable[Path]:
+    """Yield `.env` paths from start_dir upward to filesystem root."""
+    base = Path(start_dir) if start_dir else Path.cwd()
+    for directory in [base, *base.parents]:
+        yield directory / ".env"
+
+
+def _parse_dotenv(path: Path) -> Mapping[str, object]:
+    """Parse dotenv file into nested dict. Raises InvalidFormatError on malformed lines."""
+    result: dict[str, object] = {}
+    with path.open("r", encoding="utf-8") as handle:
+        for line_number, raw_line in enumerate(handle, start=1):
+            _process_line(result, raw_line, line_number, path)
+    return result
+
+
+def _is_ignorable(line: str) -> bool:
+    """Return True if line is empty or a comment."""
+    return not line or line.startswith(_COMMENT_CHAR)
+
+
+def _process_line(
+    result: dict[str, object],
+    raw_line: str,
+    line_number: int,
+    path: Path,
+) -> None:
+    """Process a single dotenv line, updating result in place."""
+    line = raw_line.strip()
+    if _is_ignorable(line):
+        return
+    if _KEY_VALUE_DELIMITER not in line:
+        _log_dotenv_error(path, line_number)
+        raise InvalidFormatError(f"Malformed line {line_number} in {path}")
+    key, value = line.split(_KEY_VALUE_DELIMITER, 1)
+    assign_nested(result, key.strip(), _strip_quotes(value.strip()), error_cls=InvalidFormatError)
+
+
+def _is_quoted(value: str) -> bool:
+    """Check if value is wrapped in matching quotes."""
+    return len(value) >= 2 and value[0] == value[-1] and value[0] in _QUOTE_CHARS
+
+
+def _strip_inline_comment(value: str) -> str:
+    """Remove trailing inline comment from value."""
+    return value.split(_INLINE_COMMENT_DELIMITER, 1)[0].strip() if _INLINE_COMMENT_DELIMITER in value else value
+
+
+def _strip_quotes(value: str) -> str:
+    """Remove surrounding quotes and trailing inline comments from value."""
+    if _is_quoted(value):
+        return value[1:-1]
+    if value.startswith(_COMMENT_CHAR):
+        return ""
+    return _strip_inline_comment(value)

lib_layered_config/adapters/env/__init__.py

@@ -0,0 +1,5 @@
+"""Environment variable adapters for ``lib_layered_config``."""
+
+from . import default
+
+__all__ = ["default"]

lib_layered_config/adapters/env/default.py

@@ -0,0 +1,288 @@
+"""Environment variable adapter.
+
+Translate process environment variables into nested configuration dictionaries.
+It implements the port described in ``docs/systemdesign/module_reference.md``
+and forms the final precedence layer in ``lib_layered_config``.
+
+Contents:
+    - ``default_env_prefix``: canonical prefix builder for a slug.
+    - ``DefaultEnvLoader``: orchestrates filtering, coercion, and nesting.
+    - ``_coerce`` plus tiny predicate helpers that translate strings into
+      Python primitives.
+    - ``_normalize_prefix`` / ``_iter_namespace_entries`` / ``_collect_keys``:
+      small verbs that keep the loader body declarative.
+    - Constants for boolean and null literal detection.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Iterator
+from typing import Final
+
+from ...observability import log_debug
+from .._nested_keys import assign_nested
+
+# Constants for environment variable value coercion
+_BOOL_TRUE: Final[str] = "true"
+_BOOL_FALSE: Final[str] = "false"
+_BOOL_LITERALS: Final[frozenset[str]] = frozenset({_BOOL_TRUE, _BOOL_FALSE})
+_NULL_LITERALS: Final[frozenset[str]] = frozenset({"null", "none"})
+
+
+def default_env_prefix(slug: str) -> str:
+    """Return the canonical environment prefix for *slug*.
+
+    Namespacing prevents unrelated environment variables from leaking into the
+    configuration payload. The triple underscore (``___``) separator clearly
+    distinguishes the application prefix from section/key separators which use
+    double underscores (``__``).
+
+    Args:
+        slug: Package/application slug (typically ``kebab-case``).
+
+    Returns:
+        Upper-case prefix with dashes converted to underscores, ending with
+        triple underscore separator.
+
+    Examples:
+        >>> default_env_prefix('lib-layered-config')
+        'LIB_LAYERED_CONFIG___'
+    """
+    return slug.replace("-", "_").upper() + "___"
+
+
+class DefaultEnvLoader:
+    """Load environment variables that belong to the configuration namespace.
+
+    Implements the :class:`lib_layered_config.application.ports.EnvLoader` port,
+    translating process environment variables into merge-ready payloads.
+
+    Filters environment entries by prefix, nests values using ``__`` separators,
+    performs primitive coercion, and emits observability events.
+    """
+
+    def __init__(self, *, environ: dict[str, str] | None = None) -> None:
+        """Initialise the loader with a specific ``environ`` mapping for testability.
+
+        Allow tests and callers to supply deterministic environments.
+
+        Args:
+            environ: Mapping to read from. Defaults to :data:`os.environ`.
+        """
+        self._environ = os.environ if environ is None else environ
+
+    def load(self, prefix: str) -> dict[str, object]:
+        """Return a nested mapping containing variables with the supplied *prefix*.
+
+        Environment variables should integrate with the merge pipeline using the
+        same nesting semantics as `.env` files.
+
+        Normalises the prefix, filters matching entries, coerces values, nests
+        keys via :func:`assign_nested`, and logs the summarised result.
+
+        Args:
+            prefix: Prefix filter (upper-case). The loader appends ``___`` if missing.
+
+        Returns:
+            Nested mapping suitable for the merge algorithm. Keys are stored in
+            lowercase to align with file-based layers.
+
+        Side Effects:
+            Emits ``env_variables_loaded`` debug events with summarised keys.
+
+        Examples:
+            >>> env = {
+            ...     'DEMO___SERVICE__ENABLED': 'true',
+            ...     'DEMO___SERVICE__RETRIES': '3',
+            ... }
+            >>> loader = DefaultEnvLoader(environ=env)
+            >>> payload = loader.load('DEMO')
+            >>> payload['service']['retries']
+            3
+            >>> payload['service']['enabled']
+            True
+        """
+        normalized_prefix = _normalize_prefix(prefix)
+        collected: dict[str, object] = {}
+        for raw_key, value in _iter_namespace_entries(self._environ.items(), normalized_prefix):
+            assign_nested(collected, raw_key, _coerce(value), error_cls=ValueError)
+        log_debug("env_variables_loaded", layer="env", path=None, keys=_collect_keys(collected))
+        return collected
+
+
+def _normalize_prefix(prefix: str) -> str:
+    """Ensure the prefix ends with triple underscore when non-empty.
+
+    Aligns environment variable filtering semantics regardless of user input.
+    The triple underscore (``___``) separator clearly distinguishes the
+    application prefix from section/key separators (``__``).
+
+    Args:
+        prefix: Raw prefix string (upper-case expected but not enforced).
+
+    Returns:
+        Prefix guaranteed to end with ``___`` when non-empty.
+
+    Examples:
+        >>> _normalize_prefix('DEMO')
+        'DEMO___'
+        >>> _normalize_prefix('DEMO___')
+        'DEMO___'
+        >>> _normalize_prefix('')
+        ''
+    """
+    if prefix and not prefix.endswith("___"):
+        return f"{prefix}___"
+    return prefix
+
+
+def _iter_namespace_entries(
+    items: Iterable[tuple[str, str]],
+    prefix: str,
+) -> Iterator[tuple[str, str]]:
+    """Yield ``(stripped_key, value)`` pairs that match *prefix*.
+
+    Encapsulate prefix filtering so caller code stays declarative.
+
+    Args:
+        items: Iterable of environment items to examine.
+        prefix: Normalised prefix (including trailing triple underscore) to filter on.
+
+    Returns:
+        Pairs whose keys share the prefix with the prefix removed.
+
+    Examples:
+        >>> list(_iter_namespace_entries([('DEMO___FLAG', '1'), ('OTHER', '0')], 'DEMO___'))
+        [('FLAG', '1')]
+        >>> list(_iter_namespace_entries([('DEMO', '1')], 'DEMO___'))
+        []
+    """
+    for key, value in items:
+        if prefix and not key.startswith(prefix):
+            continue
+        stripped = key[len(prefix) :] if prefix else key
+        if not stripped:
+            continue
+        yield stripped, value
+
+
+def _collect_keys(mapping: dict[str, object]) -> list[str]:
+    """Return sorted top-level keys for logging.
+
+    Provide compact telemetry context without dumping entire payloads.
+
+    Args:
+        mapping: Nested mapping produced by environment parsing.
+
+    Returns:
+        Sorted list of top-level keys.
+
+    Examples:
+        >>> _collect_keys({'service': {}, 'logging': {}})
+        ['logging', 'service']
+    """
+    return sorted(mapping.keys())
+
+
+def _coerce(value: str) -> object:
+    """Coerce textual environment values to Python primitives where possible.
+
+    Convert human-friendly strings (``true``, ``5``, ``3.14``) into their Python
+    equivalents before merging.
+
+    Applies boolean, null, integer, and float heuristics in sequence, returning
+    the original string when none match.
+
+    Returns:
+        Parsed primitive or original string when coercion is not possible.
+
+    Examples:
+        >>> _coerce('true'), _coerce('10'), _coerce('3.5'), _coerce('hello'), _coerce('null')
+        (True, 10, 3.5, 'hello', None)
+    """
+    lowered = value.lower()
+    if _looks_like_bool(lowered):
+        return lowered == _BOOL_TRUE
+    if _looks_like_null(lowered):
+        return None
+    if _looks_like_int(value):
+        return int(value)
+    return _maybe_float(value)
+
+
+def _looks_like_bool(value: str) -> bool:
+    """Return ``True`` when *value* spells a boolean literal.
+
+    Support `_coerce` in recognising booleans without repeated literal sets.
+
+    Args:
+        value: Lower-cased string to inspect.
+
+    Returns:
+        ``True`` when the value is ``"true"`` or ``"false"``.
+
+    Examples:
+        >>> _looks_like_bool('true'), _looks_like_bool('false'), _looks_like_bool('maybe')
+        (True, True, False)
+    """
+    return value in _BOOL_LITERALS
+
+
+def _looks_like_null(value: str) -> bool:
+    """Return ``True`` when *value* represents a null literal.
+
+    Allow `_coerce` to map textual null representations to ``None``.
+
+    Args:
+        value: Lower-cased string to inspect.
+
+    Returns:
+        ``True`` when the value is ``"null"`` or ``"none"``.
+
+    Examples:
+        >>> _looks_like_null('null'), _looks_like_null('none'), _looks_like_null('nil')
+        (True, True, False)
+    """
+    return value in _NULL_LITERALS
+
+
+def _looks_like_int(value: str) -> bool:
+    """Return ``True`` when *value* can be parsed as an integer.
+
+    Let `_coerce` distinguish integers before attempting float conversion.
+
+    Args:
+        value: String to inspect (not yet normalised).
+
+    Returns:
+        ``True`` when the value represents a base-10 integer literal.
+
+    Examples:
+        >>> _looks_like_int('42'), _looks_like_int('-7'), _looks_like_int('3.14')
+        (True, True, False)
+    """
+    if value.startswith("-"):
+        return value[1:].isdigit()
+    return value.isdigit()
+
+
+def _maybe_float(value: str) -> object:
+    """Return a float when *value* looks numeric; otherwise return the original string.
+
+    Provide a final numeric coercion step after integer detection fails.
+
+    Args:
+        value: String candidate for float conversion.
+
+    Returns:
+        Float value or the original string when conversion fails.
+
+    Examples:
+        >>> _maybe_float('2.5'), _maybe_float('not-a-number')
+        (2.5, 'not-a-number')
+    """
+    try:
+        return float(value)
+    except ValueError:
+        return value

lib_layered_config/adapters/file_loaders/__init__.py

@@ -0,0 +1 @@
+"""Structured configuration file loaders."""