lib-cli-exit-tools 2.2.1__py3-none-any.whl

lib_cli_exit_tools/__init__.py

@@ -0,0 +1,47 @@
+"""Public re-export surface for lib_cli_exit_tools helpers.
+
+Purpose:
+    Provide a stable import path for consumers (`from lib_cli_exit_tools import run_cli`).
+Contents:
+    Re-exports signal helpers, configuration, and CLI orchestration functions.
+System Integration:
+    Keeps the package interface aligned with the module reference documented in
+    ``docs/system-design/module_reference.md`` while hiding implementation modules.
+"""
+
+from __future__ import annotations
+
+from . import lib_cli_exit_tools as _facade
+
+# Re-export core helpers while keeping a single authoritative list of names in
+# the facade module. Attributes are assigned explicitly so static type checkers
+# understand the exports, while the debug assertion keeps this module aligned
+# with the facade surface.
+CliSignalError = _facade.CliSignalError
+SigBreakInterrupt = _facade.SigBreakInterrupt
+SigIntInterrupt = _facade.SigIntInterrupt
+SigTermInterrupt = _facade.SigTermInterrupt
+SignalSpec = _facade.SignalSpec
+config = _facade.config
+config_overrides = _facade.config_overrides
+default_signal_specs = _facade.default_signal_specs
+flush_streams = _facade.flush_streams
+get_system_exit_code = _facade.get_system_exit_code
+handle_cli_exception = _facade.handle_cli_exception
+i_should_fail = _facade.i_should_fail
+install_signal_handlers = _facade.install_signal_handlers
+print_exception_message = _facade.print_exception_message
+reset_config = _facade.reset_config
+run_cli = _facade.run_cli
+cli_session = _facade.cli_session
+
+__all__ = list(_facade.PUBLIC_API)  # pyright: ignore[reportUnsupportedDunderAll]
+
+if __debug__:
+    exported = {name for name in __all__ if name in globals()}
+    if len(exported) != len(__all__):
+        missing = sorted(set(__all__) - exported)
+        raise ImportError(f"lib_cli_exit_tools exports out of sync: missing {missing}")
+    del exported
+
+del _facade

lib_cli_exit_tools/__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_cli_exit_tools"
+#: Human-readable summary shown in CLI help output.
+title = "CLI exit handling helpers: clean signals, exit codes, and error printing"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "2.2.1"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/lib_cli_exit_tools"
+#: 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-cli-exit-tools"
+
+#: 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 Cli Exit Tools"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "lib-cli-exit-tools"
+
+
+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_cli_exit_tools:
+    ...
+    """
+
+    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_cli_exit_tools/__main__.py

@@ -0,0 +1,13 @@
+"""Let ``python -m lib_cli_exit_tools`` behave like the console script."""
+
+from . import cli
+
+
+def main() -> int:
+    """Forward module execution to the Click entry point."""
+
+    return cli.main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lib_cli_exit_tools/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""Adapter layer for lib_cli_exit_tools.
+
+Purpose:
+    Provide integration points with concrete frameworks (Click, Rich, signal
+    handlers) while delegating policy decisions to the core module.
+Contents:
+    Modules added here will contain Click helpers, signal installers, and other
+    I/O-centric code paths.
+System Integration:
+    Imported by the application layer to wire concrete behaviour without
+    violating dependency rules.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

lib_cli_exit_tools/adapters/signals.py

@@ -0,0 +1,178 @@
+"""Signal handling adapters for lib_cli_exit_tools.
+
+Purpose:
+    Translate operating-system signals into structured Python exceptions and
+    provide installation helpers that keep process-wide handlers reversible.
+Contents:
+    * :class:`CliSignalError` hierarchy capturing supported interrupts.
+    * :class:`SignalSpec` dataclass describing signal→exception mappings.
+    * :func:`default_signal_specs` building platform-aware defaults.
+    * :func:`install_signal_handlers` installing reversible handlers.
+System Integration:
+    The application runner leverages these helpers to provide consistent exit
+    codes across console entry points while allowing tests to inject fakes.
+"""
+
+from __future__ import annotations
+
+import signal
+from contextlib import ExitStack
+from dataclasses import dataclass
+from types import FrameType
+from typing import Callable, Iterable, Sequence
+
+__all__ = [
+    "CliSignalError",
+    "SigIntInterrupt",
+    "SigTermInterrupt",
+    "SigBreakInterrupt",
+    "SignalSpec",
+    "default_signal_specs",
+    "install_signal_handlers",
+]
+
+
+class CliSignalError(RuntimeError):
+    """Base class for translating OS signals into structured CLI errors.
+
+    Why:
+        Provide a dedicated hierarchy so exit handlers can recognise signal-driven
+        interruptions and map them to deterministic exit codes.
+    Usage:
+        Raised automatically by handlers created via :func:`install_signal_handlers`.
+    """
+
+
+class SigIntInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGINT`` (Ctrl+C)."""
+
+
+class SigTermInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGTERM`` (termination request)."""
+
+
+class SigBreakInterrupt(CliSignalError):
+    """Raised when the process receives ``SIGBREAK`` on Windows consoles."""
+
+
+@dataclass(slots=True)
+class SignalSpec:
+    """Describe how to translate a low-level signal into CLI-facing behaviour.
+
+    Fields:
+        signum: Numeric identifier registered with :mod:`signal`.
+        exception: Exception type raised by the generated handler.
+        message: User-facing text echoed to stderr when the signal fires.
+        exit_code: Numeric code returned to the operating system.
+    """
+
+    signum: int
+    exception: type[BaseException]
+    message: str
+    exit_code: int
+
+
+_Handler = Callable[[int, FrameType | None], None]
+
+
+def default_signal_specs(extra: Iterable[SignalSpec] | None = None) -> list[SignalSpec]:
+    """Build the default list of signal specifications for the host platform.
+
+    Why:
+        The application runner needs a predictable baseline of signals to
+        install without duplicating platform checks.
+    Parameters:
+        extra: Optional iterable of additional ``SignalSpec`` instances to
+            append for caller-specific behaviour.
+    Returns:
+        List of signal specifications tailored to the current interpreter.
+    """
+
+    specs: list[SignalSpec] = _standard_signal_specs()
+    if extra is not None:
+        specs.extend(extra)
+    return specs
+
+
+def _make_raise_handler(exc_type: type[BaseException]) -> _Handler:
+    """Wrap ``exc_type`` in a signal-compatible callable."""
+
+    def _handler(signo: int, frame: FrameType | None) -> None:  # pragma: no cover - just raises
+        raise exc_type()
+
+    return _handler
+
+
+def install_signal_handlers(specs: Sequence[SignalSpec] | None = None) -> Callable[[], None]:
+    """Install signal handlers that re-raise as structured exceptions."""
+
+    active_specs = _choose_specs(specs)
+    stack = _register_handlers(active_specs)
+    return stack.close
+
+
+def _choose_specs(specs: Sequence[SignalSpec] | None) -> list[SignalSpec]:
+    """Return a concrete list of signal specs, defaulting when ``None``."""
+    if specs is None:
+        return default_signal_specs()
+    return list(specs)
+
+
+def _register_handlers(specs: Sequence[SignalSpec]) -> ExitStack:
+    """Register handlers for each ``SignalSpec`` and capture previous handlers."""
+
+    stack = ExitStack()
+    for spec in specs:
+        handler = _make_raise_handler(spec.exception)
+        try:
+            previous = signal.getsignal(spec.signum)
+            signal.signal(spec.signum, handler)
+        except (AttributeError, OSError, RuntimeError):  # pragma: no cover - platform differences
+            continue
+        stack.callback(signal.signal, spec.signum, previous)
+    return stack
+
+
+def _standard_signal_specs() -> list[SignalSpec]:
+    """Return the base set of signal specifications for all platforms."""
+    specs: list[SignalSpec] = [_sigint_spec()]
+    specs.extend(_optional_specs())
+    return specs
+
+
+def _sigint_spec() -> SignalSpec:
+    """Return the ``SIGINT`` specification shared across all platforms."""
+    return SignalSpec(
+        signum=signal.SIGINT,
+        exception=SigIntInterrupt,
+        message="Aborted (SIGINT).",
+        exit_code=130,
+    )
+
+
+def _optional_specs() -> Iterable[SignalSpec]:
+    """Yield platform-conditional signal specifications."""
+    yield from _maybe_sigterm_spec()
+    yield from _maybe_sigbreak_spec()
+
+
+def _maybe_sigterm_spec() -> Iterable[SignalSpec]:
+    """Yield the ``SIGTERM`` specification when supported by the host."""
+    if hasattr(signal, "SIGTERM"):
+        yield SignalSpec(
+            signum=getattr(signal, "SIGTERM"),
+            exception=SigTermInterrupt,
+            message="Terminated (SIGTERM/SIGBREAK).",
+            exit_code=143,
+        )
+
+
+def _maybe_sigbreak_spec() -> Iterable[SignalSpec]:
+    """Yield the ``SIGBREAK`` specification when running on Windows."""
+    if hasattr(signal, "SIGBREAK"):
+        yield SignalSpec(
+            signum=getattr(signal, "SIGBREAK"),
+            exception=SigBreakInterrupt,
+            message="Terminated (SIGBREAK).",
+            exit_code=149,
+        )

lib_cli_exit_tools/application/__init__.py

@@ -0,0 +1,16 @@
+"""Application orchestration for lib_cli_exit_tools.
+
+Purpose:
+    Coordinate core exit-code logic with adapter implementations (Click,
+    signal handlers) while exposing a small surface for CLI entry points.
+Contents:
+    The `runner` module will host the refactored `run_cli` orchestration and any
+    supporting protocols.
+System Integration:
+    Imports only from `lib_cli_exit_tools.core` and adapter packages, keeping the
+    dependency direction consistent with Clean Architecture guidelines.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []