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

lib_layered_config/examples/generate.py

@@ -0,0 +1,406 @@
+"""Example configuration asset generation helpers.
+
+Produce reproducible configuration scaffolding referenced in documentation and
+onboarding materials. This module belongs to the outer ring of the architecture
+and has no runtime coupling to the composition root.
+
+Contents:
+    - ``DEFAULT_HOST_PLACEHOLDER``: filename stub for host examples.
+    - ``ExampleSpec``: dataclass capturing a relative path and text content.
+    - ``generate_examples``: public orchestration expressed through helper
+      verbs.
+    - ``_build_specs``: yields platform-aware specifications.
+    - ``_write_spec`` / ``_should_write`` / ``_ensure_parent``: tiny filesystem
+      helpers that narrate how files are written.
+
+System Role:
+    Called by docs/scripts to create filesystem layouts demonstrating how layered
+    configuration works.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from .._platform import normalise_examples_platform
+
+DEFAULT_HOST_PLACEHOLDER = "your-hostname"
+"""Filename stub used for host-specific example files (documented in README)."""
+
+
+@dataclass(slots=True)
+class ExampleSpec:
+    """Describe a single example file to be written to disk.
+
+    Encapsulate metadata for templated files so generation logic stays simple
+    and testable.
+
+    Attributes:
+        relative_path: Path relative to the destination directory where the example will be
+            created.
+        content: File contents (UTF-8 text) including explanatory comments.
+    """
+
+    relative_path: Path
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExamplePlan:
+    """Plan describing how example files should be generated.
+
+    Attributes:
+        destination: Target directory where files will be written.
+        slug: Configuration slug used in templates.
+        vendor: Vendor name interpolated into paths/content.
+        app: Application name interpolated into paths/content.
+        force: Whether generation should overwrite existing files.
+        platform: Normalised platform key (``"posix"`` or ``"windows"``).
+    """
+
+    destination: Path
+    slug: str
+    vendor: str
+    app: str
+    force: bool
+    platform: str
+
+
+def generate_examples(
+    destination: str | Path,
+    *,
+    slug: str,
+    vendor: str,
+    app: str,
+    force: bool = False,
+    platform: str | None = None,
+) -> list[Path]:
+    """Write canonical example files for each configuration layer.
+
+    Creates directories and files under *destination* mirroring the recommended
+    filesystem layout. Returns paths of files written. Use *force=True* to
+    overwrite existing files; *platform* overrides OS detection ("posix"/"windows").
+    """
+    plan = _build_example_plan(
+        destination=destination,
+        slug=slug,
+        vendor=vendor,
+        app=app,
+        force=force,
+        platform=platform,
+    )
+    specs = _build_specs(plan.destination, slug=plan.slug, vendor=plan.vendor, app=plan.app, platform=plan.platform)
+    return _write_examples(plan.destination, specs, plan.force)
+
+
+def _build_example_plan(
+    *,
+    destination: str | Path,
+    slug: str,
+    vendor: str,
+    app: str,
+    force: bool,
+    platform: str | None,
+) -> ExamplePlan:
+    """Compose an example generation plan.
+
+    Args:
+        destination: Root destination directory (string or :class:`Path`).
+        slug: Identifiers embedded into generated content.
+        vendor: Identifiers embedded into generated content.
+        app: Identifiers embedded into generated content.
+        force: Whether existing files may be overwritten.
+        platform: Optional platform override supplied by the caller.
+
+    Returns:
+        ExamplePlan: Immutable plan consumed by downstream helpers.
+    """
+    dest = Path(destination)
+    return ExamplePlan(
+        destination=dest,
+        slug=slug,
+        vendor=vendor,
+        app=app,
+        force=force,
+        platform=_normalise_platform(platform),
+    )
+
+
+def _write_examples(destination: Path, specs: Iterator[ExampleSpec], force: bool) -> list[Path]:
+    """Write all ``specs`` under *destination* honouring the *force* flag.
+
+    Centralise the loop that applies ``force`` semantics and records written paths.
+
+    Args:
+        destination: Root directory that will receive the examples.
+        specs: Iterator of example specifications to materialise.
+        force: When ``True`` existing files are overwritten.
+
+    Returns:
+        list[Path]: Paths written during this invocation.
+
+    Side Effects:
+        Creates directories and writes files to disk.
+    """
+    written: list[Path] = []
+    for spec in specs:
+        path = destination / spec.relative_path
+        if not _should_write(path, force):
+            continue
+        _ensure_parent(path)
+        _write_spec(path, spec)
+        written.append(path)
+    return written
+
+
+def _write_spec(path: Path, spec: ExampleSpec) -> None:
+    """Persist ``spec`` content at *path* using UTF-8 encoding.
+
+    Keep the actual write primitive isolated for easy stubbing in tests.
+
+    Args:
+        path: Destination path for the example file.
+        spec: Example specification containing content to write.
+
+    Side Effects:
+        Writes UTF-8 text to *path*.
+    """
+    path.write_text(spec.content, encoding="utf-8")
+
+
+def _should_write(path: Path, force: bool) -> bool:
+    """Return ``True`` when *path* should be written respecting *force*.
+
+    Avoid clobbering existing content unless the caller explicitly requests it.
+
+    Args:
+        path: Destination path under consideration.
+        force: Whether overwriting is allowed.
+
+    Returns:
+        bool: ``True`` when writing should proceed.
+
+    Examples:
+        >>> from tempfile import NamedTemporaryFile
+        >>> tmp = NamedTemporaryFile(delete=True)
+        >>> _should_write(Path(tmp.name), force=False)
+        False
+        >>> _should_write(Path(tmp.name), force=True)
+        True
+        >>> tmp.close()
+    """
+    return force or not path.exists()
+
+
+def _ensure_parent(path: Path) -> None:
+    """Create parent directories for *path* when missing.
+
+    Ensure example generation works even on fresh directories.
+
+    Args:
+        path: Target file path whose parent directories should exist.
+
+    Side Effects:
+        Creates directories on disk.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _build_specs(destination: Path, *, slug: str, vendor: str, app: str, platform: str) -> Iterator[ExampleSpec]:
+    """Yield :class:`ExampleSpec` instances for each canonical layer.
+
+    Keep file templates in one place so they stay aligned with documentation.
+
+    Args:
+        destination: Destination root (currently unused; reserved for future dynamic templates).
+        slug: Metadata interpolated into template content.
+        vendor: Metadata interpolated into template content.
+        app: Metadata interpolated into template content.
+        platform: Normalised platform key (``"posix"`` or ``"windows"``).
+
+    Yields:
+        ExampleSpec: Specification describing one file to render.
+
+    Examples:
+        >>> specs = list(_build_specs(Path('.'), slug='demo', vendor='Acme', app='ConfigKit', platform='posix'))
+        >>> specs[0].relative_path.as_posix()
+        'xdg/demo/config.toml'
+    """
+    yield from _platform_specs(slug=slug, vendor=vendor, app=app, platform=platform)
+    yield _env_example(slug)
+
+
+def _platform_specs(*, slug: str, vendor: str, app: str, platform: str) -> Iterator[ExampleSpec]:
+    """Dispatch to platform-specific example specifications.
+
+    Args:
+        slug: Metadata interpolated into generated content.
+        vendor: Metadata interpolated into generated content.
+        app: Metadata interpolated into generated content.
+        platform: Normalised platform key (``"posix"`` or ``"windows"``).
+
+    Yields:
+        ExampleSpec: Specifications describing files to create.
+    """
+    if platform == "windows":
+        yield from _windows_specs(slug=slug, vendor=vendor, app=app)
+        return
+    yield from _posix_specs(slug=slug, vendor=vendor, app=app)
+
+
+def _windows_specs(*, slug: str, vendor: str, app: str) -> Iterator[ExampleSpec]:
+    """Yield Windows layout examples.
+
+    Args:
+        slug: Metadata interpolated into template content.
+        vendor: Metadata interpolated into template content.
+        app: Metadata interpolated into template content.
+
+    Yields:
+        ExampleSpec: Specification for each Windows example file.
+    """
+    root = Path("ProgramData") / vendor / app
+    yield ExampleSpec(root / "config.toml", _app_defaults_body(slug))
+    yield ExampleSpec(root / "hosts" / f"{DEFAULT_HOST_PLACEHOLDER}.toml", _host_override_body())
+    user_root = Path("AppData") / "Roaming" / vendor / app
+    yield ExampleSpec(user_root / "config.toml", _user_preferences_body(vendor, app))
+    yield ExampleSpec(user_root / "config.d" / "10-override.toml", _split_override_body())
+
+
+def _posix_specs(*, slug: str, vendor: str, app: str) -> Iterator[ExampleSpec]:
+    """Yield POSIX layout examples following XDG Base Directory specification.
+
+    Args:
+        slug: Metadata interpolated into template content.
+        vendor: Metadata interpolated into template content.
+        app: Metadata interpolated into template content.
+
+    Yields:
+        ExampleSpec: Specification for each POSIX example file.
+    """
+    # System-wide app configuration (XDG-compliant)
+    app_root = Path("xdg") / slug
+    yield ExampleSpec(app_root / "config.toml", _app_defaults_body(slug))
+    yield ExampleSpec(app_root / "hosts" / f"{DEFAULT_HOST_PLACEHOLDER}.toml", _host_override_body())
+    # User-level configuration
+    user_root = Path("home") / slug
+    yield ExampleSpec(user_root / "config.toml", _user_preferences_body(vendor, app))
+    yield ExampleSpec(user_root / "config.d" / "10-override.toml", _split_override_body())
+
+
+def _env_example(slug: str) -> ExampleSpec:
+    """Return the shared .env example specification.
+
+    Args:
+        slug: Configuration slug used when building environment variable names.
+
+    Returns:
+        ExampleSpec: Specification describing the `.env.example` file.
+    """
+    return ExampleSpec(Path(".env.example"), _env_secrets_body(slug))
+
+
+def _app_defaults_body(slug: str) -> str:
+    """Describe baseline application defaults.
+
+    Args:
+        slug: Configuration slug inserted into the template heading.
+
+    Returns:
+        str: TOML content explaining application-wide defaults.
+    """
+    return f"""# Application-wide defaults for {slug}
+[service]
+endpoint = "https://api.example.com"
+timeout = 10
+"""
+
+
+def _host_override_body() -> str:
+    """Describe host-level overrides.
+
+    Returns:
+        str: TOML content illustrating host-specific timeout overrides.
+    """
+    return """# Host overrides (replace filename with the machine hostname)
+[service]
+timeout = 15
+"""
+
+
+def _user_preferences_body(vendor: str, app: str) -> str:
+    """Describe user-level preferences.
+
+    Args:
+        vendor: Metadata interpolated into the template to keep prose friendly.
+        app: Metadata interpolated into the template to keep prose friendly.
+
+    Returns:
+        str: TOML content illustrating user-level overrides.
+    """
+    return f"""# User-specific preferences for {vendor} {app}
+[service]
+retry = 2
+"""
+
+
+def _split_override_body() -> str:
+    """Describe config.d overrides used for granular layering.
+
+    Returns:
+        str: TOML content emphasising lexicographic ordering of split overrides.
+    """
+    return """# Split overrides live in config.d/ and apply in lexical order
+[service]
+retry = 3
+"""
+
+
+def _env_secrets_body(slug: str) -> str:
+    """Describe .env secrets guidance.
+
+    Args:
+        slug: Configuration slug converted into an uppercase environment prefix.
+
+    Returns:
+        str: `.env` template content reminding users to provide secrets.
+    """
+    key = slug.replace("-", "_").upper()
+    return f"""# Copy to .env to provide secrets and local overrides
+{key}___SERVICE__PASSWORD=changeme
+"""
+
+
+def _default_platform() -> str:
+    """Return the default platform based on OS."""
+    return "windows" if os.name == "nt" else "posix"
+
+
+def _normalise_platform(value: str | None) -> str:
+    """Return a canonical platform key for example generation.
+
+    Args:
+        value: Optional platform alias supplied by the caller.
+
+    Returns:
+        str: Normalised platform key (``"posix"`` or ``"windows"``).
+
+    Raises:
+        ValueError: When *value* is invalid.
+
+    Examples:
+        >>> _normalise_platform('posix')
+        'posix'
+        >>> _normalise_platform(None) in {'posix', 'windows'}
+        True
+    """
+    if value is None:
+        return _default_platform()
+    try:
+        resolved = normalise_examples_platform(value)
+    except ValueError as exc:  # pragma: no cover - validated via CLI helpers
+        raise ValueError(str(exc)) from exc
+    return resolved or _default_platform()

lib_layered_config/observability.py

@@ -0,0 +1,209 @@
+"""Structured logging helpers distilled into tiny orchestration phrases.
+
+Keep every emission of logging data predictable, contextual, and ready for
+downstream aggregation pipelines without forcing applications to adopt a
+specific logging backend.
+
+Contents:
+    - ``TRACE_ID``: context variable storing the active trace identifier.
+    - ``get_logger``: returns the shared package logger (quiet by default).
+    - ``bind_trace_id``: binds or clears the active trace identifier.
+    - ``log_debug`` / ``log_info`` / ``log_warn`` / ``log_error``: emit structured
+      entries via a single private emitter.
+    - ``make_event``: convenience builder for structured event payloads.
+
+System Integration:
+    Used by adapters and the composition root to ensure all diagnostics carry
+    the same trace metadata. Keeps the domain layer free from logging concerns
+    while still offering consumers consistent observability hooks.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from contextvars import ContextVar
+from typing import Any, Final
+
+TRACE_ID: ContextVar[str | None] = ContextVar("lib_layered_config_trace_id", default=None)
+"""Current trace identifier propagated through logging helpers.
+
+Cross-cutting observability features (CLI, adapters) need a shared context without threading identifiers manually.
+
+Context variable storing a string identifier or ``None``.
+"""
+
+_LOGGER: Final[logging.Logger] = logging.getLogger("lib_layered_config")
+_LOGGER.addHandler(logging.NullHandler())
+
+
+def get_logger() -> logging.Logger:
+    """Expose the package logger so applications may attach handlers.
+
+    Leave the library silent by default while giving host applications full control over handler configuration.
+
+    Returns:
+        logging.Logger: Shared logger instance for ``lib_layered_config``.
+    """
+    return _LOGGER
+
+
+def bind_trace_id(trace_id: str | None) -> None:
+    """Bind or clear the active trace identifier.
+
+    Correlate configuration events with external trace spans.
+
+    Args:
+        trace_id: Identifier string or ``None`` to drop the binding.
+
+    Side Effects:
+        Mutates :data:`TRACE_ID`, affecting subsequent logging helpers.
+
+    Examples:
+        >>> bind_trace_id('abc123')
+        >>> TRACE_ID.get()
+        'abc123'
+        >>> bind_trace_id(None)
+        >>> TRACE_ID.get() is None
+        True
+    """
+    TRACE_ID.set(trace_id)
+
+
+def log_debug(message: str, **fields: Any) -> None:
+    """Emit a structured debug log entry that includes the trace context.
+
+    Provide consistent debug telemetry across adapters while threading trace metadata.
+
+    Args:
+        message: Event name rendered by the logger.
+        **fields: Structured context merged into the payload.
+
+    Side Effects:
+        Calls :func:`_emit`, which writes to the shared logger.
+    """
+    _emit(logging.DEBUG, message, fields)
+
+
+def log_info(message: str, **fields: Any) -> None:
+    """Emit a structured info log entry that includes the trace context.
+
+    Capture high-level lifecycle events (layer loaded, merge complete) with trace IDs attached.
+
+    Args:
+        message: Event name rendered by the logger.
+        **fields: Structured context merged into the payload.
+
+    Side Effects:
+        Calls :func:`_emit` with ``logging.INFO``.
+    """
+    _emit(logging.INFO, message, fields)
+
+
+def log_warn(message: str, **fields: Any) -> None:
+    """Emit a structured warning log entry that includes the trace context.
+
+    Surface potential configuration issues (e.g., type conflicts) that don't prevent
+    loading but may indicate user error.
+    """
+    _emit(logging.WARNING, message, fields)
+
+
+def log_error(message: str, **fields: Any) -> None:
+    """Emit a structured error log entry that includes the trace context.
+
+    Surface recoverable adapter failures (e.g., invalid files) with enough context for diagnosis.
+    """
+    _emit(logging.ERROR, message, fields)
+
+
+def make_event(
+    layer: str,
+    path: str | None,
+    payload: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a structured logging payload for configuration lifecycle events.
+
+    Keep event construction consistent so downstream log processors can rely on stable keys.
+
+    Args:
+        layer: Name of the configuration layer being observed.
+        path: Filesystem path associated with the event, if available.
+        payload: Optional mapping with extra diagnostic detail.
+
+    Returns:
+        dict[str, Any]: Data safe to unpack into :func:`log_debug`, :func:`log_info`, :func:`log_warn`, or :func:`log_error`.
+
+    Examples:
+        >>> make_event('env', None, {'keys': 3})
+        {'layer': 'env', 'path': None, 'keys': 3}
+    """
+    event = _base_event(layer, path)
+    return _merge_payload(event, payload)
+
+
+def _emit(level: int, message: str, fields: Mapping[str, Any]) -> None:
+    """Send a log entry through the shared logger with contextual metadata.
+
+    Centralise the call to ``logging.Logger.log`` so trace injection and field handling stay consistent.
+
+    Args:
+        level: Standard library logging level.
+        message: Event name rendered by the logger.
+        fields: Structured payload to merge with the trace identifier.
+
+    Side Effects:
+        Writes to the shared package logger.
+    """
+    _LOGGER.log(level, message, extra={"context": _with_trace(fields)})
+
+
+def _with_trace(fields: Mapping[str, Any]) -> dict[str, Any]:
+    """Attach the current trace identifier to the provided structured fields.
+
+    Guarantee that every log entry includes the active trace (when present).
+
+    Args:
+        fields: Mapping of additional structured context.
+
+    Returns:
+        dict[str, Any]: Copy of ``fields`` with ``trace_id`` added.
+    """
+    context = {"trace_id": TRACE_ID.get()}
+    context.update(fields)
+    return context
+
+
+def _base_event(layer: str, path: str | None) -> dict[str, Any]:
+    """Create the minimal event payload containing layer and path information.
+
+    Provide a consistent foundation for layer-related logging events.
+
+    Args:
+        layer: Layer name to annotate the event.
+        path: Optional filesystem path associated with the event.
+
+    Returns:
+        dict[str, Any]: Base payload ready for augmentation.
+    """
+    return {"layer": layer, "path": path}
+
+
+def _merge_payload(event: dict[str, Any], payload: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Merge optional diagnostic data into the event payload when provided.
+
+    Allow callers to enrich events without mutating the original dictionary outside this helper.
+
+    Args:
+        event: Base event payload.
+        payload: Optional mapping of diagnostic data.
+
+    Returns:
+        dict[str, Any]: Updated payload containing merged data.
+
+    Side Effects:
+        Mutates ``event`` when ``payload`` is provided.
+    """
+    if payload:
+        event |= dict(payload)
+    return event

lib_layered_config/testing.py

@@ -0,0 +1,46 @@
+"""Testing diagnostics that keep failure scenarios observable and predictable.
+
+Provide intentionally failing helpers that exercise error-handling paths in
+the CLI and integration suites without relying on brittle fixtures.
+
+Contents:
+    - ``FAILURE_MESSAGE``: stable message used when forcing a failure.
+    - ``i_should_fail``: raises ``RuntimeError`` so callers can assert on the
+      propagated error details.
+
+System Integration:
+    Resides in the testing support layer referenced by CLI end-to-end tests and
+    notebooks that demonstrate error propagation semantics.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+FAILURE_MESSAGE: Final[str] = "i should fail"
+"""Stable message emitted when :func:`i_should_fail` triggers a failure.
+
+Integration tests and tutorial notebooks assert on the wording to guarantee
+deterministic output during regression checks.
+
+What:
+    A short, lower-case sentence that stays compatible with published examples.
+"""
+
+
+def i_should_fail() -> None:
+    """Raise a deterministic :class:`RuntimeError` for failure-path testing.
+
+    Validates that higher-level orchestrators preserve stack traces and
+    messages when surfacing errors to end users.
+
+    Raises:
+        RuntimeError: Always raises with :data:`FAILURE_MESSAGE`.
+
+    Examples:
+        >>> i_should_fail()
+        Traceback (most recent call last):
+        ...
+        RuntimeError: i should fail
+    """
+    raise RuntimeError(FAILURE_MESSAGE)