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

lib_layered_config/__init__.py

@@ -0,0 +1,58 @@
+"""Public API surface for ``lib_layered_config``.
+
+Expose the curated, stable symbols that consumers need to interact with the
+library: reader functions, value object, error taxonomy, and observability
+helpers.
+
+Contents:
+    * :func:`lib_layered_config.core.read_config`
+    * :func:`lib_layered_config.core.read_config_raw`
+    * :func:`lib_layered_config.examples.deploy.deploy_config`
+    * :class:`lib_layered_config.domain.config.Config`
+    * Error hierarchy (:class:`ConfigError`, :class:`InvalidFormatError`, etc.)
+    * Diagnostics helpers (:func:`lib_layered_config.testing.i_should_fail`)
+    * Observability bindings (:func:`bind_trace_id`, :func:`get_logger`)
+
+System Role:
+    Acts as the frontline module imported by applications, keeping the public
+    surface area deliberate and well-documented (see
+    ``docs/systemdesign/module_reference.md``).
+"""
+
+from __future__ import annotations
+
+from .core import (
+    Config,
+    ConfigError,
+    InvalidFormatError,
+    LayerLoadError,
+    NotFoundError,
+    ValidationError,
+    default_env_prefix,
+    read_config,
+    read_config_json,
+    read_config_raw,
+)
+from .domain.identifiers import Layer
+from .examples import deploy_config, generate_examples
+from .observability import bind_trace_id, get_logger
+from .testing import i_should_fail
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "InvalidFormatError",
+    "ValidationError",
+    "NotFoundError",
+    "LayerLoadError",
+    "Layer",
+    "read_config",
+    "read_config_json",
+    "read_config_raw",
+    "deploy_config",
+    "generate_examples",
+    "default_env_prefix",
+    "i_should_fail",
+    "bind_trace_id",
+    "get_logger",
+]

lib_layered_config/__init__conf__.py

@@ -0,0 +1,74 @@
+"""Static package metadata surfaced to CLI commands and documentation.
+
+Purpose
+-------
+Expose the current project metadata as simple constants. These values are kept
+in sync with ``pyproject.toml`` by development automation (tests, push
+pipelines), so runtime code does not query packaging metadata.
+
+Contents
+--------
+* Module-level constants describing the published package.
+* :func:`print_info` rendering the constants for the CLI ``info`` command.
+
+System Role
+-----------
+Lives in the adapters/platform layer; CLI transports import these constants to
+present authoritative project information without invoking packaging APIs.
+"""
+
+from __future__ import annotations
+
+#: Distribution name declared in ``pyproject.toml``.
+name = "lib_layered_config"
+#: Human-readable summary shown in CLI help output.
+title = "Cross-platform layered configuration loader for Python"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "4.1.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/lib_layered_config"
+#: Author attribution surfaced in CLI output.
+author = "bitranox"
+#: Contact email surfaced in CLI output.
+author_email = "bitranox@gmail.com"
+#: Console-script name published by the package.
+shell_command = "lib-layered-config"
+
+#: Vendor identifier for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_VENDOR: str = "bitranox"
+#: Application display name for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_APP: str = "Lib Layered Config"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "lib-layered-config"
+
+
+def print_info() -> None:
+    """Print the summarised metadata block used by the CLI ``info`` command.
+
+    Why
+        Provides a single, auditable rendering function so documentation and
+        CLI output always match the system design reference.
+
+    Side Effects
+        Writes to ``stdout``.
+
+    Examples
+    --------
+    >>> print_info()  # doctest: +ELLIPSIS
+    Info for lib_layered_config:
+    ...
+    """
+
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    print("\n".join(lines))

lib_layered_config/__main__.py

@@ -0,0 +1,18 @@
+"""Let ``python -m lib_layered_config`` feel as gentle as ``cli.main``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .cli import main
+
+
+def run_module(arguments: Sequence[str] | None = None) -> int:
+    """Forward *arguments* to :func:`lib_layered_config.cli.main` and return the exit code."""
+    return main(arguments, restore_traceback=True)
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(run_module(sys.argv[1:]))

lib_layered_config/_layers.py

@@ -0,0 +1,310 @@
+"""Assemble configuration layers prior to merging.
+
+Provide a composition helper that coordinates filesystem discovery, dotenv
+loading, environment ingestion, and defaults injection before passing
+``LayerSnapshot`` instances to the merge policy.
+
+Contents:
+- ``collect_layers``: orchestrator returning a list of snapshots.
+- ``merge_or_empty``: convenience wrapper combining collect/merge behaviour.
+- Internal generators that yield defaults, filesystem, dotenv, and environment
+  snapshots in documented precedence order.
+
+System Role:
+Invoked exclusively by ``lib_layered_config.core``. Keeps orchestration logic
+separate from adapters while remaining independent of the domain layer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from pathlib import Path
+
+from .adapters.dotenv.default import DefaultDotEnvLoader
+from .adapters.env.default import DefaultEnvLoader, default_env_prefix
+from .adapters.file_loaders.structured import JSONFileLoader, TOMLFileLoader, YAMLFileLoader
+from .adapters.path_resolvers.default import DefaultPathResolver
+from .application.merge import LayerSnapshot, MergeResult, merge_layers
+from .domain.errors import InvalidFormatError, NotFoundError
+from .domain.identifiers import Layer
+from .observability import log_debug, log_info, make_event
+
+#: Mapping from file suffix to loader instance. The ordering preserves the
+#: precedence documented for structured configuration formats while keeping all
+#: logic in one place.
+_FILE_LOADERS = {
+    ".toml": TOMLFileLoader(),
+    ".json": JSONFileLoader(),
+    ".yaml": YAMLFileLoader(),
+    ".yml": YAMLFileLoader(),
+}
+
+__all__ = ["collect_layers", "merge_or_empty"]
+
+
+def collect_layers(
+    *,
+    resolver: DefaultPathResolver,
+    prefer: Sequence[str] | None,
+    default_file: str | None,
+    dotenv_loader: DefaultDotEnvLoader,
+    env_loader: DefaultEnvLoader,
+    slug: str,
+    start_dir: str | None,
+) -> list[LayerSnapshot]:
+    """Return layer snapshots in precedence order (defaults → app → host → user → dotenv → env).
+
+    Centralises discovery so callers stay focused on error handling.
+    Emits structured logging events when layers are discovered.
+    """
+    return list(
+        _snapshots_in_merge_sequence(
+            resolver=resolver,
+            prefer=prefer,
+            default_file=default_file,
+            dotenv_loader=dotenv_loader,
+            env_loader=env_loader,
+            slug=slug,
+            start_dir=start_dir,
+        )
+    )
+
+
+def _snapshots_in_merge_sequence(
+    *,
+    resolver: DefaultPathResolver,
+    prefer: Sequence[str] | None,
+    default_file: str | None,
+    dotenv_loader: DefaultDotEnvLoader,
+    env_loader: DefaultEnvLoader,
+    slug: str,
+    start_dir: str | None,
+) -> Iterator[LayerSnapshot]:
+    """Yield layer snapshots in the documented merge order.
+
+    Capture the precedence hierarchy (`defaults → app → host → user → dotenv → env`)
+    in one generator so callers cannot accidentally skip a layer.
+
+    Args:
+        resolver / prefer / default_file / dotenv_loader / env_loader / slug / start_dir:
+            Same meaning as :func:`collect_layers`.
+
+    Yields:
+        LayerSnapshot: Snapshot tuples ready for the merge policy.
+    """
+    yield from _default_snapshots(default_file)
+    yield from _filesystem_snapshots(resolver, prefer)
+    yield from _dotenv_snapshots(dotenv_loader, start_dir)
+    yield from _env_snapshots(env_loader, slug)
+
+
+def merge_or_empty(layers: list[LayerSnapshot]) -> MergeResult:
+    """Merge collected layers or return empty result when none exist.
+
+    Provides a guard so callers do not have to special-case empty layer collections.
+
+    Args:
+        layers: Layer snapshots in precedence order.
+
+    Returns:
+        MergeResult: Dataclass containing merged configuration data and provenance mappings.
+
+    Side Effects:
+        Emits ``configuration_empty`` or ``configuration_merged`` events depending on
+        the layer count.
+    """
+    if not layers:
+        _note_configuration_empty()
+        return MergeResult(data={}, provenance={})
+
+    result = merge_layers(layers)
+    _note_merge_complete(len(layers))
+    return result
+
+
+def _default_snapshots(default_file: str | None) -> Iterator[LayerSnapshot]:
+    """Yield a defaults snapshot when *default_file* is supplied.
+
+    Args:
+        default_file: Absolute path string to the optional defaults file.
+
+    Yields:
+        LayerSnapshot: Snapshot describing the defaults layer.
+
+    Side Effects:
+        Emits ``layer_loaded`` events when a defaults file is parsed.
+    """
+    if not default_file:
+        return
+
+    snapshot = _load_entry(Layer.DEFAULTS, default_file)
+    if snapshot is None:
+        return
+
+    _note_layer_loaded(snapshot.name, snapshot.origin, {"keys": len(snapshot.payload)})
+    yield snapshot
+
+
+def _filesystem_snapshots(resolver: DefaultPathResolver, prefer: Sequence[str] | None) -> Iterator[LayerSnapshot]:
+    """Yield filesystem-backed layer snapshots in precedence order.
+
+    Args:
+        resolver: Path resolver supplying candidate paths per layer.
+        prefer: Optional suffix ordering applied when multiple files exist.
+
+    Yields:
+        LayerSnapshot: Snapshots for ``app``/``host``/``user`` layers.
+    """
+    for layer, paths in (
+        (Layer.APP, resolver.app()),
+        (Layer.HOST, resolver.host()),
+        (Layer.USER, resolver.user()),
+    ):
+        snapshots = list(_snapshots_from_paths(layer, paths, prefer))
+        if snapshots:
+            _note_layer_loaded(layer, None, {"files": len(snapshots)})
+            yield from snapshots
+
+
+def _dotenv_snapshots(loader: DefaultDotEnvLoader, start_dir: str | None) -> Iterator[LayerSnapshot]:
+    """Yield a snapshot for dotenv-provided values when present.
+
+    Args:
+        loader: Dotenv loader that handles discovery and parsing.
+        start_dir: Optional starting directory for the upward search.
+
+    Yields:
+        LayerSnapshot: Snapshot representing the ``dotenv`` layer when a file exists.
+    """
+    data = loader.load(start_dir)
+    if not data:
+        return
+    _note_layer_loaded(Layer.DOTENV, loader.last_loaded_path, {"keys": len(data)})
+    yield LayerSnapshot(Layer.DOTENV, data, loader.last_loaded_path)
+
+
+def _env_snapshots(loader: DefaultEnvLoader, slug: str) -> Iterator[LayerSnapshot]:
+    """Yield a snapshot for environment-variable configuration.
+
+    Args:
+        loader: Environment loader converting prefixed variables into nested mappings.
+        slug: Slug identifying the configuration family.
+
+    Yields:
+        LayerSnapshot: Snapshot for the ``env`` layer when variables are present.
+    """
+    prefix = default_env_prefix(slug)
+    data = loader.load(prefix)
+    if not data:
+        return
+    _note_layer_loaded(Layer.ENV, None, {"keys": len(data)})
+    yield LayerSnapshot(Layer.ENV, data, None)
+
+
+def _snapshots_from_paths(layer: str, paths: Iterable[str], prefer: Sequence[str] | None) -> Iterator[LayerSnapshot]:
+    """Yield snapshots for every supported file inside *paths*.
+
+    Args:
+        layer: Logical layer name the files belong to.
+        paths: Iterable of candidate file paths.
+        prefer: Optional suffix ordering hint passed by the CLI/API.
+
+    Yields:
+        LayerSnapshot: Snapshot for each successfully loaded file.
+    """
+    for path in _paths_in_preferred_order(paths, prefer):
+        snapshot = _load_entry(layer, path)
+        if snapshot is not None:
+            yield snapshot
+
+
+def _load_entry(layer: str, path: str) -> LayerSnapshot | None:
+    """Load *path* using the configured file loaders and return a snapshot.
+
+    Args:
+        layer: Logical layer name associated with the file.
+        path: Absolute path to the candidate configuration file.
+
+    Returns:
+        LayerSnapshot | None: Snapshot when parsing succeeds and data is non-empty; otherwise ``None``.
+
+    Raises:
+        InvalidFormatError: When the loader encounters invalid content. The exception is logged
+            and re-raised so callers can surface context to users.
+    """
+    loader = _FILE_LOADERS.get(Path(path).suffix.lower())
+    if loader is None:
+        return None
+    try:
+        data = loader.load(path)
+    except NotFoundError:
+        return None
+    except InvalidFormatError as exc:  # pragma: no cover - validated by adapter tests
+        _note_layer_error(layer, path, exc)
+        raise
+    if not data:
+        return None
+    return LayerSnapshot(layer, data, path)
+
+
+def _paths_in_preferred_order(paths: Iterable[str], prefer: Sequence[str] | None) -> list[str]:
+    """Return candidate paths honouring the optional *prefer* order.
+
+    Args:
+        paths: Iterable of candidate file paths.
+        prefer: Optional sequence of preferred suffixes ordered by priority.
+
+    Returns:
+        list[str]: Candidate paths sorted according to preferred suffix ranking.
+
+    Examples:
+        >>> _paths_in_preferred_order(
+        ...     ['a.toml', 'b.yaml'],
+        ...     prefer=('yaml', 'toml'),
+        ... )
+        ['b.yaml', 'a.toml']
+    """
+    ordered = list(paths)
+    if not prefer:
+        return ordered
+    ranking = {suffix.lower().lstrip("."): index for index, suffix in enumerate(prefer)}
+    return sorted(ordered, key=lambda candidate: ranking.get(Path(candidate).suffix.lower().lstrip("."), len(ranking)))
+
+
+def _note_layer_loaded(layer: str, path: str | None, details: Mapping[str, object]) -> None:
+    """Emit a debug event capturing successful layer discovery.
+
+    Args:
+        layer: Logical layer name.
+        path: Optional path associated with the event.
+        details: Additional structured metadata (e.g., number of files or keys).
+
+    Side Effects:
+        Calls :func:`log_debug` with the structured event payload.
+    """
+    log_debug("layer_loaded", **make_event(layer, path, dict(details)))
+
+
+def _note_layer_error(layer: str, path: str, exc: Exception) -> None:
+    """Emit a debug event describing a recoverable layer error.
+
+    Args:
+        layer: Layer currently being processed.
+        path: File path that triggered the error.
+        exc: Exception raised by the loader.
+    """
+    log_debug("layer_error", **make_event(layer, path, {"error": str(exc)}))
+
+
+def _note_configuration_empty() -> None:
+    """Emit an info event signalling that no configuration was discovered."""
+    log_info("configuration_empty", layer="none", path=None)
+
+
+def _note_merge_complete(total_layers: int) -> None:
+    """Emit an info event summarising the merge outcome.
+
+    Args:
+        total_layers: Number of layers processed in the merge.
+    """
+    log_info("configuration_merged", layer="final", path=None, total_layers=total_layers)

lib_layered_config/_platform.py

@@ -0,0 +1,166 @@
+"""Shared helpers for normalising user-provided platform aliases.
+
+Bridge CLI/example inputs with resolver internals by translating human-friendly
+platform strings into the canonical identifiers expected across adapters and
+documentation.
+
+Contents:
+    - ``normalise_resolver_platform``: map CLI adapter aliases to ``sys.platform``
+      style identifiers.
+    - ``normalise_examples_platform``: map example-generation aliases to the two
+      supported documentation families.
+    - ``_sanitize`` plus canonical mapping constants that keep user inputs tidy and
+      predictable.
+
+System Role:
+    Reusable utilities consumed by CLI commands and example tooling to ensure
+    terminology matches ``docs/systemdesign/concept.md`` regardless of user input
+    quirks.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+#: Canonical resolver identifiers used when wiring the path resolver adapter.
+#: Values mirror ``sys.platform`` strings so downstream code can branch safely.
+_CANONICAL_RESOLVER: Final[dict[str, str]] = {
+    "linux": "linux",
+    "posix": "linux",
+    "darwin": "darwin",
+    "mac": "darwin",
+    "macos": "darwin",
+    "windows": "win32",
+    "win": "win32",
+    "win32": "win32",
+    "wine": "win32",
+}
+
+#: Canonical families used by documentation/example helpers. They collapse the
+#: wide variety of aliases into the two supported directory layouts.
+_CANONICAL_EXAMPLES: Final[dict[str, str]] = {
+    "posix": "posix",
+    "linux": "posix",
+    "darwin": "posix",
+    "mac": "posix",
+    "macos": "posix",
+    "windows": "windows",
+    "win": "windows",
+    "win32": "windows",
+    "wine": "windows",
+}
+
+
+def _sanitize(alias: str | None) -> str | None:
+    """Return a lower-cased alias stripped of whitespace when *alias* is truthy.
+
+    User input may include spacing or mixed casing; sanitising up front keeps the
+    canonical lookup tables compact and dependable.
+
+    Args:
+        alias: Optional raw alias provided by a user or CLI flag. ``None`` indicates no
+            override.
+
+    Returns:
+        Lower-case alias when *alias* contains characters, otherwise ``None`` when
+        no override is requested.
+
+    Raises:
+        ValueError: If *alias* contains only whitespace, because such inputs indicate a user
+            error that should surface immediately.
+
+    Examples:
+        >>> _sanitize('  MacOS  ')
+        'macos'
+        >>> _sanitize(None) is None
+        True
+        >>> _sanitize('   ')
+        Traceback (most recent call last):
+        ...
+        ValueError: Platform alias cannot be empty.
+    """
+    if alias is None:
+        return None
+    stripped = alias.strip().lower()
+    if not stripped:
+        raise ValueError("Platform alias cannot be empty.")
+    return stripped
+
+
+def normalise_resolver_platform(alias: str | None) -> str | None:
+    """Return canonical resolver platform identifiers for *alias*.
+
+    The path resolver adapter expects ``sys.platform`` style identifiers. This
+    helper converts human-friendly values (``"mac"``, ``"win"``) into the canonical
+    tokens documented in the system design.
+
+    Args:
+        alias: User-provided alias or ``None``. ``None`` preserves auto-detection.
+
+    Returns:
+        Canonical resolver identifier or ``None`` when auto-detection should be
+        used.
+
+    Raises:
+        ValueError: If *alias* is not recognised. The error message enumerates valid options
+            so CLI tooling can surface helpful guidance.
+
+    Examples:
+        >>> normalise_resolver_platform('mac')
+        'darwin'
+        >>> normalise_resolver_platform('win32')
+        'win32'
+        >>> normalise_resolver_platform(None) is None
+        True
+        >>> normalise_resolver_platform('beos')
+        Traceback (most recent call last):
+        ...
+        ValueError: Platform must be one of: darwin, linux, mac, macos, posix, win, win32, windows, wine.
+    """
+    sanitized = _sanitize(alias)
+    if sanitized is None:
+        return None
+    try:
+        return _CANONICAL_RESOLVER[sanitized]
+    except KeyError as exc:  # pragma: no cover - exercised via caller tests
+        allowed = ", ".join(sorted(_CANONICAL_RESOLVER))
+        raise ValueError(f"Platform must be one of: {allowed}.") from exc
+
+
+def normalise_examples_platform(alias: str | None) -> str | None:
+    """Return the example-generation platform family for *alias*.
+
+    Documentation and example helpers target two directory layouts (POSIX and
+    Windows). This function collapses a wide variety of synonyms into those
+    families for predictable template generation.
+
+    Args:
+        alias: User-provided alias or ``None`` to let the caller choose a default.
+
+    Returns:
+        Canonical example platform (``"posix"`` or ``"windows"``) or ``None`` when
+        the caller should rely on runtime defaults.
+
+    Raises:
+        ValueError: If *alias* is provided but not known.
+
+    Examples:
+        >>> normalise_examples_platform('darwin')
+        'posix'
+        >>> normalise_examples_platform('windows')
+        'windows'
+        >>> normalise_examples_platform(None) is None
+        True
+        >>> normalise_examples_platform('amiga')
+        Traceback (most recent call last):
+        ...
+        ValueError: Platform must be one of: darwin, linux, mac, macos, posix, win, win32, windows, wine.
+    """
+    sanitized = _sanitize(alias)
+    if sanitized is None:
+        return None
+    try:
+        return _CANONICAL_EXAMPLES[sanitized]
+    except KeyError as exc:  # pragma: no cover - exercised via caller tests
+        allowed = ", ".join(sorted(_CANONICAL_EXAMPLES))
+        raise ValueError(f"Platform must be one of: {allowed}.") from exc

lib_layered_config/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Adapter implementations for ``lib_layered_config``.
+
+Purpose
+-------
+Group concrete boundary code (filesystem, dotenv, environment, file parsers)
+that fulfils the application layer's ports.
+
+System Role
+-----------
+Modules inside this package implement contracts defined in
+:mod:`lib_layered_config.application.ports` and are wired together by the
+composition root.
+"""