lib-layered-config 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

lib_layered_config/__init__conf__.py

@@ -0,0 +1,67 @@
+"""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 = "1.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"
+
+
+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/adapters/file_loaders/structured.py

@@ -25,18 +25,17 @@ before passing the results to the merge policy.
 from __future__ import annotations
 
 import json
+from importlib import import_module
 from pathlib import Path
 from typing import Any, Mapping, NoReturn
+from types import ModuleType
 
 import tomllib
 
 from ...domain.errors import InvalidFormat, NotFound
 from ...observability import log_debug, log_error
 
-try:
-    import yaml  # type: ignore[import-not-found]
-except ModuleNotFoundError:  # pragma: no cover - optional dependency
-    yaml = None  # type: ignore[assignment]
+yaml: ModuleType | None = None
 
 
 FILE_LAYER = "file"
@@ -139,25 +138,73 @@ def _raise_invalid_format(path: str, format_name: str, exc: Exception) -> NoRetu
 
 
 def _ensure_yaml_available() -> None:
-    """Raise :class:`NotFound` when optional YAML support is missing.
+    """Announce clearly whether PyYAML can be reached.
 
     Why
     ----
-    Fail fast with a friendly message when YAML parsing is requested without the
-    optional dependency.
+    YAML support is optional; the loader must fail fast with guidance when the
+    dependency is absent so callers can install the expected extra.
 
     Returns
     -------
     None
 
+    Raises
+    ------
+    NotFound
+        When the PyYAML package cannot be imported.
+    """
+
+    _require_yaml_module()
+
+
+def _require_yaml_module() -> ModuleType:
+    """Fetch the PyYAML module or explain its absence.
+
+    Why
+    ----
+    Downstream helpers need the module object for access to both ``safe_load``
+    and the package-specific ``YAMLError`` type.
+
+    Returns
+    -------
+    ModuleType
+        The imported PyYAML module.
+
     Raises
     ------
     NotFound
         When PyYAML is not installed.
     """
 
-    if yaml is None:
+    module = _load_yaml_module()
+    if module is None:
         raise NotFound("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.
+
+    Why
+    ----
+    Avoid importing optional dependencies unless they are genuinely needed,
+    while still ensuring subsequent calls reuse the same module object.
+
+    Returns
+    -------
+    ModuleType | None
+        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:
@@ -390,7 +437,7 @@ class YAMLFileLoader(BaseFileLoader):
 
         Examples
         --------
-        >>> if yaml is not None:  # doctest: +SKIP
+        >>> 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')
@@ -400,11 +447,51 @@ class YAMLFileLoader(BaseFileLoader):
         """
 
         _ensure_yaml_available()
-        try:
-            payload: Any = yaml.safe_load(self._read(path))  # type: ignore[operator]
-        except yaml.YAMLError as exc:  # type: ignore[attr-defined]
-            _raise_invalid_format(path, "yaml", exc)
-        data: object = dict[str, object]() if payload is None else payload
-        result = self._ensure_mapping(data, path=path)
+        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 result
+        return mapping
+
+
+def _parse_yaml_bytes(payload: bytes, module: ModuleType, path: str) -> object:
+    """Turn YAML bytes into a Python shape that mirrors the file.
+
+    Why
+    ----
+    Normalise the PyYAML parsing contract so callers always receive a mapping,
+    raising a domain-specific error when the parser signals invalid syntax.
+
+    Parameters
+    ----------
+    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
+    -------
+    object
+        Parsed document; an empty dict when the YAML payload evaluates to ``None``.
+
+    Raises
+    ------
+    InvalidFormat
+        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/cli/__init__.py

@@ -2,31 +2,24 @@
 
 from __future__ import annotations
 
-from typing import Callable, Iterable, Mapping, Optional, Sequence, cast
-
-from importlib import metadata as _metadata
-
 from pathlib import Path
+from typing import Callable, Iterable, Mapping, Optional, Sequence, cast
 
-import lib_cli_exit_tools
 import rich_click as click
+from lib_cli_exit_tools import cli_session
 
-from ..core import default_env_prefix as _default_env_prefix  # backward compatibility import
+from ..application.ports import SourceInfoPayload
 from .common import (
+    describe_distribution,
     format_scalar,
     json_paths,
-    load_distribution_metadata,
     normalise_examples_platform_option,
     normalise_platform_option,
     normalise_prefer,
     render_human,
-    toggle_traceback,
     version_string,
 )
 from .constants import CLICK_CONTEXT_SETTINGS, TRACEBACK_SUMMARY, TRACEBACK_VERBOSE
-from ..application.ports import SourceInfoPayload
-
-
 from .read import read_command as cli_read_config, read_json_command as cli_read_config_json
 
 
@@ -46,33 +39,51 @@ from .read import read_command as cli_read_config, read_json_command as cli_read
     default=False,
     help="Show full Python traceback on errors",
 )
-def cli(traceback: bool) -> None:
-    """Root command that remembers whether tracebacks should flow."""
+@click.pass_context
+def cli(ctx: click.Context, traceback: bool) -> None:
+    """Root command storing the requested traceback preference."""
 
-    toggle_traceback(traceback)
+    ctx.ensure_object(dict)
+    ctx.obj["traceback"] = traceback
 
 
 def main(argv: Optional[Sequence[str]] = None, *, restore_traceback: bool = True) -> int:
-    """Entry point that restores traceback preferences on exit."""
+    """Entry point wiring the CLI through ``lib_cli_exit_tools.cli_session``."""
+
+    args_list = list(argv) if argv is not None else None
+    overrides = _session_overrides(args_list)
+
+    with cli_session(
+        summary_limit=TRACEBACK_SUMMARY,
+        verbose_limit=TRACEBACK_VERBOSE,
+        overrides=overrides or None,
+        restore=restore_traceback,
+    ) as run:
+        runner = cast("Callable[..., int]", run)
+        return runner(
+            cli,
+            argv=args_list,
+            prog_name="lib_layered_config",
+        )
+
+
+def _session_overrides(argv: Sequence[str] | None) -> dict[str, object]:
+    """Derive configuration overrides for ``cli_session`` based on CLI args."""
+
+    if not argv:
+        return {}
+
+    try:
+        ctx = cli.make_context("lib_layered_config", list(argv), resilient_parsing=True)
+    except click.ClickException:
+        return {}
 
-    previous_traceback = getattr(lib_cli_exit_tools.config, "traceback", False)
-    previous_force_color = getattr(lib_cli_exit_tools.config, "traceback_force_color", False)
     try:
-        try:
-            run_cli = cast(Callable[..., int], lib_cli_exit_tools.run_cli)  # pyright: ignore[reportUnknownMemberType]
-            return run_cli(cli, argv=list(argv) if argv is not None else None, prog_name="lib_layered_config")
-        except BaseException as exc:  # noqa: BLE001
-            print_exception = cast(Callable[..., None], lib_cli_exit_tools.print_exception_message)  # pyright: ignore[reportUnknownMemberType]
-            print_exception(
-                trace_back=lib_cli_exit_tools.config.traceback,
-                length_limit=TRACEBACK_VERBOSE if lib_cli_exit_tools.config.traceback else TRACEBACK_SUMMARY,
-            )
-            exit_code_fn = cast(Callable[[BaseException], int], lib_cli_exit_tools.get_system_exit_code)  # pyright: ignore[reportUnknownMemberType]
-            return exit_code_fn(exc)
+        enabled = bool(ctx.params.get("traceback", False))
     finally:
-        if restore_traceback:
-            lib_cli_exit_tools.config.traceback = previous_traceback
-            lib_cli_exit_tools.config.traceback_force_color = previous_force_color
+        ctx.close()
+
+    return {"traceback": enabled} if enabled else {}
 
 
 def _register_commands() -> None:
@@ -84,8 +95,6 @@ def _register_commands() -> None:
 
 _register_commands()
 
-metadata = _metadata
-_toggle_traceback = toggle_traceback
 _version_string = version_string
 
 
@@ -113,44 +122,17 @@ def _normalise_prefer(values: Sequence[str]) -> tuple[str, ...] | None:  # pyrig
     return normalise_prefer(values)
 
 
-def _load_distribution_metadata() -> _metadata.PackageMetadata | None:
-    """Wrapper that allows tests to monkeypatch metadata loading."""
-
-    return load_distribution_metadata()
-
-
 def _describe_distribution() -> tuple[str, ...]:
-    """Yield human-readable metadata lines about the installed distribution."""
-
-    meta = _load_distribution_metadata()
-    if meta is None:
-        return ("lib_layered_config (metadata unavailable)",)
-
-    lines = [f"Info for {meta.get('Name', 'lib_layered_config')}:"]
-    lines.append(f"  Version         : {meta.get('Version', version_string())}")
-    lines.append(f"  Requires-Python : {meta.get('Requires-Python', '>=3.13')}")
-    summary = meta.get("Summary")
-    if summary:
-        lines.append(f"  Summary         : {summary}")
-
-    def _no_urls(_: str) -> Iterable[str] | None:
-        return None
+    """Expose CLI metadata lines for backwards-compatible tests."""
 
-    get_all = cast(Callable[[str], Iterable[str] | None], getattr(meta, "get_all", _no_urls))
-    for entry in get_all("Project-URL") or []:
-        lines.append(f"  {entry}")
-    return tuple(lines)
+    return tuple(describe_distribution())
 
 
 __all__ = [
     "cli",
     "main",
-    "_default_env_prefix",
-    "metadata",
-    "_toggle_traceback",
     "_version_string",
     "_describe_distribution",
-    "_load_distribution_metadata",
     "_normalise_platform",
     "_normalise_examples_platform",
     "_json_paths",

lib_layered_config/cli/common.py

@@ -1,16 +1,37 @@
-"""Utilities shared by CLI command modules."""
+"""Utilities shared by CLI command modules.
+
+Purpose
+-------
+Tell the CLI story in small, declarative helpers so commands remain tiny. These
+functions construct read queries, choose output modes, format human summaries,
+and surface metadata drawn from ``__init__conf__``.
+
+Contents
+--------
+* :class:`ReadQuery` — frozen bundle capturing the parameters for configuration reads.
+* Metadata helpers (:func:`version_string`, :func:`describe_distribution`).
+* Query shaping (:func:`build_read_query`, :func:`normalise_prefer`, :func:`stringify`).
+* Output shaping (:func:`json_payload`, :func:`human_payload`, :func:`render_human`).
+* Human-friendly utilities (:func:`format_scalar`, :func:`json_paths`).
+
+System Role
+-----------
+Commands import these helpers to stay declarative. They rely on the application
+layer (`read_config*` functions) and on platform utilities for normalisation.
+Updates here must be mirrored in ``docs/systemdesign/module_reference.md`` to
+keep documentation and behaviour aligned.
+"""
 
 from __future__ import annotations
 
 import json
 from dataclasses import dataclass
-from importlib import metadata
 from pathlib import Path
-from typing import Iterable, Mapping, Optional, Sequence, cast
+from typing import Iterable, Mapping, Optional, Protocol, Sequence, cast
 
-import lib_cli_exit_tools
 import rich_click as click
 
+from .. import __init__conf__
 from .._platform import normalise_examples_platform as _normalise_examples_platform
 from .._platform import normalise_resolver_platform as _normalise_resolver_platform
 from ..application.ports import SourceInfoPayload
@@ -19,9 +40,47 @@ from .constants import DEFAULT_JSON_INDENT
 from ..core import read_config, read_config_json, read_config_raw
 
 
-@dataclass(frozen=True)
+class _PackageMetadata(Protocol):
+    name: str
+    title: str
+    version: str
+    homepage: str
+    author: str
+    author_email: str
+    shell_command: str
+
+    def info_lines(self) -> tuple[str, ...]: ...
+
+    def metadata_fields(self) -> tuple[tuple[str, str], ...]: ...
+
+
+package_metadata: _PackageMetadata = cast(_PackageMetadata, __init__conf__)
+
+
+@dataclass(frozen=True, slots=True)
 class ReadQuery:
-    """Immutable bundle of parameters required to execute read commands."""
+    """Immutable bundle of parameters required to execute read commands.
+
+    Why
+    ----
+    Capture CLI parameters in a frozen dataclass so functions can accept a
+    self-explanatory object rather than many loose arguments.
+
+    Attributes
+    ----------
+    vendor:
+        Vendor namespace requested by the user.
+    app:
+        Application identifier within the vendor namespace.
+    slug:
+        Configuration slug (environment/project).
+    prefer:
+        Ordered tuple of preferred file extensions, lowercased; ``None`` when the CLI falls back to defaults.
+    start_dir:
+        Starting directory as a string or ``None`` to use the current working directory.
+    default_file:
+        Optional baseline configuration file to load before layered overrides.
+    """
 
     vendor: str
     app: str
@@ -31,46 +90,41 @@ class ReadQuery:
     default_file: str | None
 
 
-def toggle_traceback(show: bool) -> None:
-    """Synchronise ``lib_cli_exit_tools`` traceback flags with *show*."""
-
-    lib_cli_exit_tools.config.traceback = show
-    lib_cli_exit_tools.config.traceback_force_color = show
+def version_string() -> str:
+    """Echo the project version declared in ``__init__conf__``.
 
+    Why
+    ----
+    The CLI `--version` option should reflect the single source of truth
+    maintained by release automation.
 
-def version_string() -> str:
-    """Return the installed distribution version or a fallback placeholder."""
+    Returns
+    -------
+    str
+        Semantic version string from the generated metadata module.
+    """
 
-    try:
-        return metadata.version("lib_layered_config")
-    except metadata.PackageNotFoundError:
-        return "0.0.0"
+    return package_metadata.version
 
 
 def describe_distribution() -> Iterable[str]:
-    """Yield human-readable metadata lines about the installed distribution."""
-
-    meta = load_distribution_metadata()
-    if meta is None:
-        yield "lib_layered_config (metadata unavailable)"
-        return
-    yield f"Info for {meta.get('Name', 'lib_layered_config')}:"
-    yield f"  Version         : {meta.get('Version', version_string())}"
-    yield f"  Requires-Python : {meta.get('Requires-Python', '>=3.13')}"
-    summary = meta.get("Summary")
-    if summary:
-        yield f"  Summary         : {summary}"
-    for entry in meta.get_all("Project-URL") or []:
-        yield f"  {entry}"
+    """Yield human-readable metadata lines sourced from ``__init__conf__``.
 
+    Why
+    ----
+    Support the `info` command with pre-formatted lines so the CLI stays thin.
 
-def load_distribution_metadata() -> metadata.PackageMetadata | None:
-    """Return importlib metadata when the package is installed locally."""
+    Returns
+    -------
+    Iterable[str]
+        Sequence of descriptive lines suitable for printing with ``click.echo``.
+    """
 
-    try:
-        return metadata.metadata("lib_layered_config")
-    except metadata.PackageNotFoundError:
-        return None
+    lines_provider = getattr(package_metadata, "info_lines", None)
+    if callable(lines_provider):
+        yield from cast(Iterable[str], lines_provider())
+        return
+    yield from _fallback_info_lines()
 
 
 def build_read_query(
@@ -81,7 +135,28 @@ def build_read_query(
     start_dir: Optional[Path],
     default_file: Optional[Path],
 ) -> ReadQuery:
-    """Shape CLI parameters into a read query."""
+    """Shape CLI parameters into a :class:`ReadQuery`.
+
+    Why
+    ----
+    Centralise normalisation so every command builds queries in the same way.
+
+    Parameters
+    ----------
+    vendor, app, slug:
+        Raw CLI strings describing the configuration slice to read.
+    prefer:
+        List of extensions supplied via ``--prefer`` (possibly empty).
+    start_dir:
+        Optional explicit starting directory.
+    default_file:
+        Optional explicit baseline file.
+
+    Returns
+    -------
+    ReadQuery
+        Frozen, normalised dataclass instance.
+    """
 
     return ReadQuery(
         vendor=vendor,
@@ -94,7 +169,13 @@ def build_read_query(
 
 
 def normalise_prefer(values: Sequence[str]) -> tuple[str, ...] | None:
-    """Lowercase supplied extensions and strip leading dots."""
+    """Normalise preferred extensions by lowercasing and trimming dots.
+
+    Returns
+    -------
+    tuple[str, ...] | None
+        Tuple of cleaned extensions, or ``None`` when no values were supplied.
+    """
 
     if not values:
         return None
@@ -102,13 +183,33 @@ def normalise_prefer(values: Sequence[str]) -> tuple[str, ...] | None:
 
 
 def normalise_targets(values: Sequence[str]) -> tuple[str, ...]:
-    """Normalise deployment targets to lowercase for resolver routing."""
+    """Normalise deployment targets to lowercase for resolver routing.
+
+    Why
+    ----
+    Deployment helpers expect stable lowercase slugs regardless of user input.
+
+    Returns
+    -------
+    tuple[str, ...]
+        Lowercased targets suitable for lookups.
+    """
 
     return tuple(value.lower() for value in values)
 
 
 def normalise_platform_option(value: Optional[str]) -> Optional[str]:
-    """Map user-friendly platform aliases to canonical resolver identifiers."""
+    """Map friendly platform aliases to canonical resolver identifiers.
+
+    Why
+    ----
+    Keep command options flexible without leaking resolver-specific tokens.
+
+    Raises
+    ------
+    click.BadParameter
+        When the alias is unrecognised.
+    """
 
     try:
         return _normalise_resolver_platform(value)
@@ -117,7 +218,18 @@ def normalise_platform_option(value: Optional[str]) -> Optional[str]:
 
 
 def normalise_examples_platform_option(value: Optional[str]) -> Optional[str]:
-    """Map example-generation platform aliases to canonical values."""
+    """Map example-generation platform aliases to canonical values.
+
+    Why
+    ----
+    Example templates use only ``posix`` or ``windows``; synonyms must collapse
+    to those keys.
+
+    Raises
+    ------
+    click.BadParameter
+        When the alias is unrecognised.
+    """
 
     try:
         return _normalise_examples_platform(value)
@@ -126,25 +238,60 @@ def normalise_examples_platform_option(value: Optional[str]) -> Optional[str]:
 
 
 def stringify(path: Optional[Path]) -> Optional[str]:
-    """Return stringified path or ``None`` when *path* is ``None``."""
+    """Return an absolute path string or ``None`` when the input is ``None``.
+
+    Why
+    ----
+    Downstream helpers prefer plain strings (for JSON serialization) while
+    preserving the absence of a path.
+    """
 
     return None if path is None else str(path)
 
 
 def wants_json(output_format: str) -> bool:
-    """Return ``True`` when JSON output was requested."""
+    """State plainly whether the caller requested JSON output.
+
+    Why
+    ----
+    Commands toggle between human and JSON representations; clarity matters.
+    """
 
     return output_format.strip().lower() == "json"
 
 
 def resolve_indent(enabled: bool) -> int | None:
-    """Return default JSON indentation when *enabled* is true."""
+    """Return the default JSON indentation when pretty-printing is enabled.
+
+    Why
+    ----
+    Provide a single source for the CLI's JSON formatting decision.
+    """
 
     return DEFAULT_JSON_INDENT if enabled else None
 
 
 def json_payload(query: ReadQuery, indent: int | None, include_provenance: bool) -> str:
-    """Build JSON payload for a query."""
+    """Build a JSON payload for the provided query.
+
+    Why
+    ----
+    Commands should share the same logic when emitting machine-readable output.
+
+    Parameters
+    ----------
+    query:
+        Normalised read parameters.
+    indent:
+        Indentation width or ``None`` for compact output.
+    include_provenance:
+        When ``True`` use :func:`read_config_json` to include source metadata.
+
+    Returns
+    -------
+    str
+        JSON document ready for ``click.echo``.
+    """
 
     if include_provenance:
         return read_config_json(
@@ -168,7 +315,20 @@ def json_payload(query: ReadQuery, indent: int | None, include_provenance: bool)
 
 
 def render_human(data: Mapping[str, object], provenance: Mapping[str, SourceInfoPayload]) -> str:
-    """Return a human-readable description of config values and provenance."""
+    """Render configuration values and provenance as friendly prose.
+
+    Parameters
+    ----------
+    data:
+        Nested mapping of configuration values.
+    provenance:
+        Mapping of dotted keys to source metadata.
+
+    Returns
+    -------
+    str
+        Multi-line description highlighting value and origin.
+    """
 
     entries = list(iter_leaf_items(data))
     if not entries:
@@ -185,7 +345,12 @@ def render_human(data: Mapping[str, object], provenance: Mapping[str, SourceInfo
 
 
 def iter_leaf_items(mapping: Mapping[str, object], prefix: tuple[str, ...] = ()) -> Iterable[tuple[str, object]]:
-    """Yield dotted paths and values for every leaf entry in *mapping*."""
+    """Yield dotted paths and values for every leaf node in *mapping*.
+
+    Why
+    ----
+    Flatten nested structures so human-readable output can focus on leaves.
+    """
 
     for key, value in mapping.items():
         dotted = ".".join((*prefix, key))
@@ -197,7 +362,13 @@ def iter_leaf_items(mapping: Mapping[str, object], prefix: tuple[str, ...] = ())
 
 
 def format_scalar(value: object) -> str:
-    """Return string representation used in human output for *value*."""
+    """Format a scalar value for human output.
+
+    Why
+    ----
+    Keep representation consistent across CLI messages (booleans lowercase,
+    ``None`` as ``null``).
+    """
 
     if isinstance(value, bool):
         return "true" if value else "false"
@@ -207,13 +378,23 @@ def format_scalar(value: object) -> str:
 
 
 def json_paths(paths: Iterable[Path]) -> str:
-    """Return JSON array of stringified paths written by helper commands."""
+    """Return a JSON array of stringified paths written by helper commands.
+
+    Why
+    ----
+    Provide machine-readable artifacts for deployment/generation commands.
+    """
 
     return json.dumps([str(path) for path in paths], indent=2)
 
 
 def human_payload(query: ReadQuery) -> str:
-    """Return prose describing config values and provenance."""
+    """Return prose describing config values and provenance.
+
+    Why
+    ----
+    Offer a human-first view that mirrors the JSON content yet remains readable.
+    """
 
     data, meta = read_config_raw(
         vendor=query.vendor,
@@ -227,6 +408,33 @@ def human_payload(query: ReadQuery) -> str:
 
 
 def default_env_prefix(slug: str) -> str:
-    """Expose the canonical environment prefix for CLI/commands."""
+    """Expose the canonical environment prefix for CLI/commands.
+
+    Why
+    ----
+    Sustain backward compatibility for callers that relied on the CLI proxy.
+    """
 
     return compute_default_env_prefix(slug)
+
+
+def _fallback_info_lines() -> tuple[str, ...]:
+    """Construct info lines from metadata constants when helpers are absent."""
+
+    fields_provider = getattr(package_metadata, "metadata_fields", None)
+    if callable(fields_provider):
+        fields = cast(tuple[tuple[str, str], ...], fields_provider())
+    else:
+        fields: tuple[tuple[str, str], ...] = (
+            ("name", package_metadata.name),
+            ("title", package_metadata.title),
+            ("version", package_metadata.version),
+            ("homepage", package_metadata.homepage),
+            ("author", package_metadata.author),
+            ("author_email", package_metadata.author_email),
+            ("shell_command", package_metadata.shell_command),
+        )
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {package_metadata.name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    return tuple(lines)

lib_layered_config/examples/generate.py

@@ -57,7 +57,7 @@ class ExampleSpec:
     content: str
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class ExamplePlan:
     """Plan describing how example files should be generated.
 

{lib_layered_config-1.0.0.dist-info → lib_layered_config-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_layered_config
-Version: 1.0.0
+Version: 1.1.0
 Summary: Cross-platform layered configuration loader for Python
 Project-URL: Homepage, https://github.com/bitranox/lib_layered_config
 Project-URL: Repository, https://github.com/bitranox/lib_layered_config.git
@@ -16,26 +16,26 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: lib-cli-exit-tools>=1.5.0
-Requires-Dist: rich-click>=1.9.2
+Requires-Dist: lib-cli-exit-tools>=2.1.0
+Requires-Dist: rich-click>=1.9.3
 Provides-Extra: dev
-Requires-Dist: bandit>=1.7.9; extra == 'dev'
-Requires-Dist: build>=1.3; extra == 'dev'
-Requires-Dist: codecov-cli>=0.6; extra == 'dev'
+Requires-Dist: bandit>=1.8.6; extra == 'dev'
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: codecov-cli>=11.2.3; extra == 'dev'
 Requires-Dist: coverage[toml]>=7.10.7; extra == 'dev'
 Requires-Dist: hypothesis>=6.140.3; extra == 'dev'
-Requires-Dist: import-linter>=2.0; extra == 'dev'
-Requires-Dist: pip-audit>=2.7; extra == 'dev'
-Requires-Dist: pyright>=1.1; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest-cov>=7.0; extra == 'dev'
-Requires-Dist: pytest>=8.4; extra == 'dev'
-Requires-Dist: pyyaml>=6.0; extra == 'dev'
-Requires-Dist: ruff>=0.13.3; extra == 'dev'
-Requires-Dist: textual>=6.1.0; extra == 'dev'
-Requires-Dist: twine>=6.2; extra == 'dev'
+Requires-Dist: import-linter>=2.5.2; extra == 'dev'
+Requires-Dist: pip-audit>=2.9.0; extra == 'dev'
+Requires-Dist: pyright>=1.1.406; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.4.2; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.14.0; extra == 'dev'
+Requires-Dist: textual>=6.3.0; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
 Provides-Extra: yaml
-Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Requires-Dist: pyyaml>=6.0.3; extra == 'yaml'
 Description-Content-Type: text/markdown
 
 # lib_layered_config
@@ -342,6 +342,10 @@ make build         # build wheel / sdist artifacts
 make run -- --help # run the CLI via the repo entrypoint
 ```
 
+The development extra now targets the latest stable releases of the toolchain
+(pytest 8.4.2, ruff 0.14.0, codecov-cli 11.2.3, etc.), so upgrading your local
+environment before running `make` is recommended.
+
 *Formatting gate:* Ruff formatting runs in check mode during `make test`. Run `ruff format .` (or `pre-commit run --all-files`) before pushing and consider `pre-commit install` to keep local edits aligned.
 
 *Coverage gate:* the maintained test suite must stay ≥90% (see `pyproject.toml`). Add targeted unit tests if you extend functionality.
@@ -357,7 +361,8 @@ The GitHub Actions workflow executes three jobs:
 
 - **Test matrix** (Linux/macOS/Windows, Python 3.13 + latest 3.x) running the same pipeline as `make test`.
 - **pipx / uv verification** to prove the built wheel installs cleanly with the common Python app launchers.
-- **Notebook smoke test** that executes `notebooks/Quickstart.ipynb` to keep the tutorial in sync.
+- **Notebook smoke test** that executes `notebooks/Quickstart.ipynb` to keep the tutorial in sync using the native nbformat workflow (no compatibility shims required).
+- CLI jobs run through `lib_cli_exit_tools.cli_session`, ensuring the `--traceback` flag behaves the same locally and in automation.
 
 Packaging-specific jobs (conda, Nix, Homebrew sync) were retired; the Python packaging metadata in `pyproject.toml` remains the single source of truth.
 

{lib_layered_config-1.0.0.dist-info → lib_layered_config-1.1.0.dist-info}/RECORD

@@ -1,4 +1,5 @@
 lib_layered_config/__init__.py,sha256=nJZkUMWFr_LhE71vquCUojqIy8miwo_T4WexbRRSA0o,1578
+lib_layered_config/__init__conf__.py,sha256=NEGCiwr_pri2exixloo6pWs893u_oTKyTXYIMvDvuKY,2154
 lib_layered_config/__main__.py,sha256=8zOwFdtTW_y8WBSefP1qYr99x3MWp6JOsTA1E0n-ceY,467
 lib_layered_config/_layers.py,sha256=21a_6pLIM2Hb-N54BAXVQxzbhmnNNXWNnJppKHl6ht4,13334
 lib_layered_config/_platform.py,sha256=eIvp_P8Cn-0meIzkxgZEQpKdgA9yU-fUYYKkp0Af1Qo,5819
@@ -12,14 +13,14 @@ lib_layered_config/adapters/dotenv/default.py,sha256=ghsgSgw99k14aQxPoXXsVk_oE_m
 lib_layered_config/adapters/env/__init__.py,sha256=EZY49s8TGhHvPWfEleRCIRc7W2eeAArpZPkaGTxUXX8,110
 lib_layered_config/adapters/env/default.py,sha256=r0SCfn24NxhVgmn5gFX07bPtTFTw-kk9AWtX0-b5rtI,13136
 lib_layered_config/adapters/file_loaders/__init__.py,sha256=V4KQJvY7xKJRMnY0cktkwj7SOILS6hO3eAfVBHP5B1k,45
-lib_layered_config/adapters/file_loaders/structured.py,sha256=sYe6QHZ3uoPUkVa86nz9-bRVdNUWTq5Bct2UsOkZt20,11198
+lib_layered_config/adapters/file_loaders/structured.py,sha256=eDq2o2_V2vObBq8X0hitjDrhCv8rXMMmyVcaLw998s0,13444
 lib_layered_config/adapters/path_resolvers/__init__.py,sha256=-SEC9-2kwEZcW4hOrVbdfpMqmPKQ9UlI_PgvxLZ9m8I,65
 lib_layered_config/adapters/path_resolvers/default.py,sha256=7JE6xHuiplwqXptsH30m_q5PmqRHZMi7YQ8nuQSU5mk,21358
 lib_layered_config/application/__init__.py,sha256=fGbDqRVtb6tIXhdjYwL22548P1opLgau8BkzmXs_KiA,276
 lib_layered_config/application/merge.py,sha256=ZpRRQoLhFBcmubCXeXpKbOCFse1w_2GljXuCnCR-VTQ,12536
 lib_layered_config/application/ports.py,sha256=8HyqTTVlFxZurhjR805tmEV1D3MdzZdTXbjfUTSuoac,3047
-lib_layered_config/cli/__init__.py,sha256=EEFQRfAcD-cYROns2GRg84MpjEl4X6snpUnIM3ByPKU,5433
-lib_layered_config/cli/common.py,sha256=swjIGqA52jFP15Kd4AzC5QtPj5kndxeTnK8-vsJqQuY,7120
+lib_layered_config/cli/__init__.py,sha256=Br31K5W-afy2e-1ZIcqyro-vrbbEc-WjY2SPDhLJUbc,4060
+lib_layered_config/cli/common.py,sha256=IUrYoT9Iyn46SDJymKrdrU2wkZVeZyF7JwnYE-zRrBM,12449
 lib_layered_config/cli/constants.py,sha256=15Cu0OfkP-iOmHTecKEDLK4YShYxgMeSWNKThAZV4DA,467
 lib_layered_config/cli/deploy.py,sha256=ZhxUbMx1rjWLwNTVDx8nfM63H7-6GFp60S6_zl2vGGg,2025
 lib_layered_config/cli/fail.py,sha256=PBuHrTvSdZ1mv-UGlZYbWUF24ii09IzQYnHqN1GR6JE,523
@@ -31,9 +32,9 @@ lib_layered_config/domain/config.py,sha256=j6L9Igxyxi9emW3wlqLDZWhdNhB0R-L06DuGs
 lib_layered_config/domain/errors.py,sha256=811KWV98R8eF142ReSYjKZ2LXCQdys75y3SpKwWAn3E,1929
 lib_layered_config/examples/__init__.py,sha256=1ShHdxvsxIxWzRAYfOxaIeL2m9Je32B2I9bX8MUwXHw,996
 lib_layered_config/examples/deploy.py,sha256=1aHXsIzw9L94dXgi8xr_rTshaDUpezKV_csU81nkx6w,11211
-lib_layered_config/examples/generate.py,sha256=B8RgooeA3nGGXF0Zk7zU1tcmv2dZLSBTJGIHsiLOexQ,13808
-lib_layered_config-1.0.0.dist-info/METADATA,sha256=HtWFNt0ndl2Qe91FmDp9m1XtX9gap_4W2zxJPuK2b2c,16330
-lib_layered_config-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-lib_layered_config-1.0.0.dist-info/entry_points.txt,sha256=peN9XKyKARqvDRE-DpK4eeZRc1JeiQqPpzx4BGv_EkE,116
-lib_layered_config-1.0.0.dist-info/licenses/LICENSE,sha256=6s9SL2InRrwynPjJYiER7ONHBshbGj_yC5EBzfo7l9I,1072
-lib_layered_config-1.0.0.dist-info/RECORD,,
+lib_layered_config/examples/generate.py,sha256=YCmUms5oqWze5lv1NRN7sjT0MVO7zr6-70a7yCWnX_E,13820
+lib_layered_config-1.1.0.dist-info/METADATA,sha256=48RYeqs_KwWgwQlvgdyBMel_PoroSV5CE_1_dcW10rE,16764
+lib_layered_config-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lib_layered_config-1.1.0.dist-info/entry_points.txt,sha256=peN9XKyKARqvDRE-DpK4eeZRc1JeiQqPpzx4BGv_EkE,116
+lib_layered_config-1.1.0.dist-info/licenses/LICENSE,sha256=6s9SL2InRrwynPjJYiER7ONHBshbGj_yC5EBzfo7l9I,1072
+lib_layered_config-1.1.0.dist-info/RECORD,,