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

lib_layered_config/cli/__init__.py

@@ -0,0 +1,162 @@
+"""Package exposing the lib_layered_config command-line interface."""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable, Mapping, Optional, Sequence, cast
+
+from importlib import metadata as _metadata
+
+from pathlib import Path
+
+import lib_cli_exit_tools
+import rich_click as click
+
+from ..core import default_env_prefix as _default_env_prefix  # backward compatibility import
+from .common import (
+    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
+
+
+@click.group(
+    help="Immutable layered configuration reader",
+    context_settings=CLICK_CONTEXT_SETTINGS,
+    invoke_without_command=False,
+)
+@click.version_option(
+    version=version_string(),
+    prog_name="lib_layered_config",
+    message="lib_layered_config version %(version)s",
+)
+@click.option(
+    "--traceback/--no-traceback",
+    is_flag=True,
+    default=False,
+    help="Show full Python traceback on errors",
+)
+def cli(traceback: bool) -> None:
+    """Root command that remembers whether tracebacks should flow."""
+
+    toggle_traceback(traceback)
+
+
+def main(argv: Optional[Sequence[str]] = None, *, restore_traceback: bool = True) -> int:
+    """Entry point that restores traceback preferences on exit."""
+
+    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)
+    finally:
+        if restore_traceback:
+            lib_cli_exit_tools.config.traceback = previous_traceback
+            lib_cli_exit_tools.config.traceback_force_color = previous_force_color
+
+
+def _register_commands() -> None:
+    from . import deploy, fail, generate, info, read
+
+    for module in (read, deploy, generate, info, fail):
+        module.register(cli)
+
+
+_register_commands()
+
+metadata = _metadata
+_toggle_traceback = toggle_traceback
+_version_string = version_string
+
+
+def _normalise_platform(value: str | None) -> str | None:  # pyright: ignore[reportUnusedFunction]
+    return normalise_platform_option(value)
+
+
+def _normalise_examples_platform(value: str | None) -> str | None:  # pyright: ignore[reportUnusedFunction]
+    return normalise_examples_platform_option(value)
+
+
+def _json_paths(paths: Iterable[Path]) -> str:  # pyright: ignore[reportUnusedFunction]
+    return json_paths(paths)
+
+
+def _render_human(data: Mapping[str, object], provenance: Mapping[str, SourceInfoPayload]) -> str:  # pyright: ignore[reportUnusedFunction]
+    return render_human(data, provenance)
+
+
+def _format_scalar(value: object) -> str:  # pyright: ignore[reportUnusedFunction]
+    return format_scalar(value)
+
+
+def _normalise_prefer(values: Sequence[str]) -> tuple[str, ...] | None:  # pyright: ignore[reportUnusedFunction]
+    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
+
+    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)
+
+
+__all__ = [
+    "cli",
+    "main",
+    "_default_env_prefix",
+    "metadata",
+    "_toggle_traceback",
+    "_version_string",
+    "_describe_distribution",
+    "_load_distribution_metadata",
+    "_normalise_platform",
+    "_normalise_examples_platform",
+    "_json_paths",
+    "_render_human",
+    "_format_scalar",
+    "_normalise_prefer",
+    "cli_read_config",
+    "cli_read_config_json",
+]

lib_layered_config/cli/common.py

@@ -0,0 +1,232 @@
+"""Utilities shared by CLI command modules."""
+
+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
+
+import lib_cli_exit_tools
+import rich_click as click
+
+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
+from ..core import default_env_prefix as compute_default_env_prefix
+from .constants import DEFAULT_JSON_INDENT
+from ..core import read_config, read_config_json, read_config_raw
+
+
+@dataclass(frozen=True)
+class ReadQuery:
+    """Immutable bundle of parameters required to execute read commands."""
+
+    vendor: str
+    app: str
+    slug: str
+    prefer: tuple[str, ...] | None
+    start_dir: str | None
+    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:
+    """Return the installed distribution version or a fallback placeholder."""
+
+    try:
+        return metadata.version("lib_layered_config")
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+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}"
+
+
+def load_distribution_metadata() -> metadata.PackageMetadata | None:
+    """Return importlib metadata when the package is installed locally."""
+
+    try:
+        return metadata.metadata("lib_layered_config")
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def build_read_query(
+    vendor: str,
+    app: str,
+    slug: str,
+    prefer: Sequence[str],
+    start_dir: Optional[Path],
+    default_file: Optional[Path],
+) -> ReadQuery:
+    """Shape CLI parameters into a read query."""
+
+    return ReadQuery(
+        vendor=vendor,
+        app=app,
+        slug=slug,
+        prefer=normalise_prefer(prefer),
+        start_dir=stringify(start_dir),
+        default_file=stringify(default_file),
+    )
+
+
+def normalise_prefer(values: Sequence[str]) -> tuple[str, ...] | None:
+    """Lowercase supplied extensions and strip leading dots."""
+
+    if not values:
+        return None
+    return tuple(value.lower().lstrip(".") for value in values)
+
+
+def normalise_targets(values: Sequence[str]) -> tuple[str, ...]:
+    """Normalise deployment targets to lowercase for resolver routing."""
+
+    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."""
+
+    try:
+        return _normalise_resolver_platform(value)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--platform") from exc
+
+
+def normalise_examples_platform_option(value: Optional[str]) -> Optional[str]:
+    """Map example-generation platform aliases to canonical values."""
+
+    try:
+        return _normalise_examples_platform(value)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="--platform") from exc
+
+
+def stringify(path: Optional[Path]) -> Optional[str]:
+    """Return stringified path or ``None`` when *path* is ``None``."""
+
+    return None if path is None else str(path)
+
+
+def wants_json(output_format: str) -> bool:
+    """Return ``True`` when JSON output was requested."""
+
+    return output_format.strip().lower() == "json"
+
+
+def resolve_indent(enabled: bool) -> int | None:
+    """Return default JSON indentation when *enabled* is true."""
+
+    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."""
+
+    if include_provenance:
+        return read_config_json(
+            vendor=query.vendor,
+            app=query.app,
+            slug=query.slug,
+            prefer=query.prefer,
+            start_dir=query.start_dir,
+            default_file=query.default_file,
+            indent=indent,
+        )
+    config = read_config(
+        vendor=query.vendor,
+        app=query.app,
+        slug=query.slug,
+        prefer=query.prefer,
+        start_dir=query.start_dir,
+        default_file=query.default_file,
+    )
+    return config.to_json(indent=indent)
+
+
+def render_human(data: Mapping[str, object], provenance: Mapping[str, SourceInfoPayload]) -> str:
+    """Return a human-readable description of config values and provenance."""
+
+    entries = list(iter_leaf_items(data))
+    if not entries:
+        return "No configuration values were found."
+
+    lines: list[str] = []
+    for dotted, value in entries:
+        lines.append(f"{dotted}: {format_scalar(value)}")
+        info = provenance.get(dotted)
+        if info:
+            path = info["path"] or "(memory)"
+            lines.append(f"  provenance: layer={info['layer']}, path={path}")
+    return "\n".join(lines)
+
+
+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*."""
+
+    for key, value in mapping.items():
+        dotted = ".".join((*prefix, key))
+        if isinstance(value, Mapping):
+            nested = cast(Mapping[str, object], value)
+            yield from iter_leaf_items(nested, (*prefix, key))
+        else:
+            yield dotted, value
+
+
+def format_scalar(value: object) -> str:
+    """Return string representation used in human output for *value*."""
+
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value is None:
+        return "null"
+    return str(value)
+
+
+def json_paths(paths: Iterable[Path]) -> str:
+    """Return JSON array of stringified paths written by helper 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."""
+
+    data, meta = read_config_raw(
+        vendor=query.vendor,
+        app=query.app,
+        slug=query.slug,
+        prefer=query.prefer,
+        start_dir=query.start_dir,
+        default_file=query.default_file,
+    )
+    return render_human(data, meta)
+
+
+def default_env_prefix(slug: str) -> str:
+    """Expose the canonical environment prefix for CLI/commands."""
+
+    return compute_default_env_prefix(slug)

lib_layered_config/cli/constants.py

@@ -0,0 +1,12 @@
+"""Shared CLI constants used across command modules."""
+
+from __future__ import annotations
+
+from typing import Final
+
+CLICK_CONTEXT_SETTINGS: Final[dict[str, tuple[str, str]]] = {"help_option_names": ("-h", "--help")}
+TRACEBACK_SUMMARY: Final[int] = 500
+TRACEBACK_VERBOSE: Final[int] = 10_000
+TARGET_CHOICES: Final[tuple[str, ...]] = ("app", "host", "user")
+EXAMPLE_PLATFORM_CHOICES: Final[tuple[str, ...]] = ("posix", "windows")
+DEFAULT_JSON_INDENT: Final[int] = 2

lib_layered_config/cli/deploy.py

@@ -0,0 +1,70 @@
+"""CLI command for deploying configuration files into layer directories."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Sequence
+
+import rich_click as click
+
+from ..examples import deploy_config as deploy_config_impl
+from .common import json_paths, normalise_platform_option, normalise_targets
+from .constants import CLICK_CONTEXT_SETTINGS, TARGET_CHOICES
+
+
+@click.command("deploy", context_settings=CLICK_CONTEXT_SETTINGS)
+@click.option(
+    "--source",
+    type=click.Path(path_type=Path, exists=True, file_okay=True, dir_okay=False, readable=True),
+    required=True,
+    help="Path to the configuration file that should be copied",
+)
+@click.option("--vendor", required=True, help="Vendor namespace")
+@click.option("--app", required=True, help="Application name")
+@click.option("--slug", required=True, help="Slug identifying the configuration set")
+@click.option(
+    "--target",
+    "targets",
+    multiple=True,
+    required=True,
+    type=click.Choice(TARGET_CHOICES, case_sensitive=False),
+    help="Layer targets to deploy to (repeatable)",
+)
+@click.option(
+    "--platform",
+    default=None,
+    help="Override auto-detected platform (linux, darwin, windows)",
+)
+@click.option(
+    "--force/--no-force",
+    default=False,
+    show_default=True,
+    help="Overwrite existing files at the destination",
+)
+def deploy_command(
+    source: Path,
+    vendor: str,
+    app: str,
+    slug: str,
+    targets: Sequence[str],
+    platform: Optional[str],
+    force: bool,
+) -> None:
+    """Copy a source file into the requested layered directories."""
+
+    created = deploy_config_impl(
+        source,
+        vendor=vendor,
+        app=app,
+        slug=slug,
+        targets=normalise_targets(targets),
+        platform=normalise_platform_option(platform),
+        force=force,
+    )
+    click.echo(json_paths(created))
+
+
+def register(cli_group: click.Group) -> None:
+    """Register the deploy command with the root CLI group."""
+
+    cli_group.add_command(deploy_command)

lib_layered_config/cli/fail.py

@@ -0,0 +1,21 @@
+"""Debugging helpers exposed via the CLI."""
+
+from __future__ import annotations
+
+import rich_click as click
+
+from ..testing import i_should_fail
+from .constants import CLICK_CONTEXT_SETTINGS
+
+
+@click.command("fail", context_settings=CLICK_CONTEXT_SETTINGS)
+def fail_command() -> None:
+    """Intentionally raise a runtime error for test harnesses."""
+
+    i_should_fail()
+
+
+def register(cli_group: click.Group) -> None:
+    """Register the fail command with the root CLI group."""
+
+    cli_group.add_command(fail_command)

lib_layered_config/cli/generate.py

@@ -0,0 +1,60 @@
+"""CLI command for generating example configuration trees."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import rich_click as click
+
+from ..examples import generate_examples as generate_examples_impl
+from .common import json_paths, normalise_examples_platform_option
+from .constants import CLICK_CONTEXT_SETTINGS
+
+
+@click.command("generate-examples", context_settings=CLICK_CONTEXT_SETTINGS)
+@click.option(
+    "--destination",
+    type=click.Path(path_type=Path, file_okay=False, dir_okay=True, resolve_path=True),
+    required=True,
+    help="Directory that will receive the example tree",
+)
+@click.option("--slug", required=True, help="Slug identifying the configuration set")
+@click.option("--vendor", required=True, help="Vendor namespace")
+@click.option("--app", required=True, help="Application name")
+@click.option(
+    "--platform",
+    default=None,
+    help="Override platform layout (posix/windows)",
+)
+@click.option(
+    "--force/--no-force",
+    default=False,
+    show_default=True,
+    help="Overwrite existing example files",
+)
+def generate_examples_command(
+    destination: Path,
+    slug: str,
+    vendor: str,
+    app: str,
+    platform: Optional[str],
+    force: bool,
+) -> None:
+    """Create reference example trees for documentation or onboarding."""
+
+    created = generate_examples_impl(
+        destination,
+        slug=slug,
+        vendor=vendor,
+        app=app,
+        force=force,
+        platform=normalise_examples_platform_option(platform),
+    )
+    click.echo(json_paths(created))
+
+
+def register(cli_group: click.Group) -> None:
+    """Register the generate-examples command."""
+
+    cli_group.add_command(generate_examples_command)

lib_layered_config/cli/info.py

@@ -0,0 +1,31 @@
+"""Metadata-related CLI commands."""
+
+from __future__ import annotations
+
+import rich_click as click
+
+from .common import default_env_prefix, describe_distribution
+from .constants import CLICK_CONTEXT_SETTINGS
+
+
+@click.command("info", context_settings=CLICK_CONTEXT_SETTINGS)
+def info_command() -> None:
+    """Print package metadata in friendly lines."""
+
+    for line in describe_distribution():
+        click.echo(line)
+
+
+@click.command("env-prefix", context_settings=CLICK_CONTEXT_SETTINGS)
+@click.argument("slug")
+def env_prefix_command(slug: str) -> None:
+    """Echo the canonical environment variable prefix for a slug."""
+
+    click.echo(default_env_prefix(slug))
+
+
+def register(cli_group: click.Group) -> None:
+    """Register metadata commands with the root CLI group."""
+
+    cli_group.add_command(info_command)
+    cli_group.add_command(env_prefix_command)