lib-cli-exit-tools 2.2.4__py3-none-any.whl → 2.3.0__py3-none-any.whl

lib_cli_exit_tools/__init__.py

@@ -17,6 +17,7 @@ from . import lib_cli_exit_tools as _facade
 # 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.
+ExitCodeStyle = _facade.ExitCodeStyle
 CliSignalError = _facade.CliSignalError
 SigBreakInterrupt = _facade.SigBreakInterrupt
 SigIntInterrupt = _facade.SigIntInterrupt

lib_cli_exit_tools/__init__conf__.py

@@ -24,7 +24,7 @@ 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.4"
+version = "2.3.0"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/lib_cli_exit_tools"
 #: Author attribution surfaced in CLI output.

lib_cli_exit_tools/application/runner.py

@@ -20,7 +20,7 @@ from __future__ import annotations
 
 import sys
 from contextlib import contextmanager, nullcontext, suppress
-from typing import Callable, ContextManager, Iterable, Iterator, Literal, Mapping, Protocol, Sequence, TextIO, TypedDict, cast
+from typing import Callable, ContextManager, Iterable, Iterator, Literal, Protocol, Sequence, TextIO, TypedDict, cast
 
 import rich_click as click
 from rich_click import rich_click as rich_config
@@ -29,17 +29,12 @@ from rich.text import Text
 from rich.traceback import Traceback
 
 from ..adapters.signals import SignalSpec, default_signal_specs, install_signal_handlers
-from ..core.configuration import config, config_overrides
+from ..core.configuration import ExitCodeStyle, config, config_overrides
 from ..core.exit_codes import get_system_exit_code
 
 RichColorSystem = Literal["auto", "standard", "256", "truecolor", "windows"]
 ExitResolver = Callable[[BaseException], int | None]
 
-# Configuration field name constants to ensure type-safe access
-# These correspond to fields in _Config dataclass (core/configuration.py)
-_CONFIG_TRACEBACK = "traceback"
-_CONFIG_TRACEBACK_FORCE_COLOR = "traceback_force_color"
-
 
 class SessionOverrides(TypedDict, total=False):
     """Type-safe override mapping for cli_session configuration.
@@ -49,7 +44,7 @@ class SessionOverrides(TypedDict, total=False):
     """
 
     traceback: bool
-    exit_code_style: Literal["errno", "sysexits"]
+    exit_code_style: ExitCodeStyle
     broken_pipe_exit_code: int
     traceback_force_color: bool
 
@@ -464,7 +459,7 @@ def cli_session(
     *,
     summary_limit: int = 500,
     verbose_limit: int = 10_000,
-    overrides: Mapping[str, object] | None = None,
+    overrides: SessionOverrides | None = None,
     restore: bool = True,
 ) -> Iterator[
     Callable[
@@ -498,7 +493,7 @@ def cli_session(
     verbose_limit:
         Character budget used when tracebacks are enabled.
     overrides:
-        Optional mapping of configuration fields temporarily applied during
+        Optional :class:`SessionOverrides` mapping temporarily applied during
         the session. When ``traceback`` is supplied and
         ``traceback_force_color`` is omitted, colour output is forced to align
         with the verbose mode.
@@ -544,26 +539,29 @@ def cli_session(
         yield _run
 
 
-def _normalise_session_overrides(overrides: Mapping[str, object] | None) -> Mapping[str, object]:
+def _normalise_session_overrides(overrides: SessionOverrides | None) -> SessionOverrides:
     """Prepare configuration overrides, forcing colour when verbose tracebacks are enabled.
 
-    Returns a Mapping instead of dict to avoid unnecessary conversions.
-    Uses typed constants for field names to ensure type safety.
+    Why:
+        When traceback mode is enabled but force_color is not explicitly set,
+        automatically enable colour output to align with verbose mode.
+    Parameters:
+        overrides: Optional typed override mapping from the caller.
+    Returns:
+        Normalised override mapping with inferred defaults applied.
     """
     if not overrides:
-        return {}
+        return SessionOverrides()
 
-    # If traceback is enabled but force_color is not set, add it
-    if _CONFIG_TRACEBACK in overrides and _CONFIG_TRACEBACK_FORCE_COLOR not in overrides:
-        # Need to create a new dict to add the extra field
-        result: dict[str, object] = {**overrides}
-        result[_CONFIG_TRACEBACK_FORCE_COLOR] = bool(overrides[_CONFIG_TRACEBACK])
+    if "traceback" in overrides and "traceback_force_color" not in overrides:
+        result = SessionOverrides(**overrides)
+        result["traceback_force_color"] = bool(overrides["traceback"])
         return result
 
     return overrides
 
 
-def _session_config_manager(applied: Mapping[str, object], restore: bool) -> ContextManager[object]:
+def _session_config_manager(applied: SessionOverrides, restore: bool) -> ContextManager[object]:
     """Return the context manager used to apply session overrides."""
     if restore:
         return config_overrides(**applied)
@@ -573,17 +571,11 @@ def _session_config_manager(applied: Mapping[str, object], restore: bool) -> Con
 
 
 @contextmanager
-def _apply_overrides_without_restore(applied: Mapping[str, object]) -> Iterator[None]:
+def _apply_overrides_without_restore(applied: SessionOverrides) -> Iterator[None]:
     """Apply overrides without restoring prior state on exit.
 
-    Safety Note:
-        The setattr calls here are type-safe because all field names in ``applied``
-        have been validated by ``_reject_unknown_fields`` in configuration.py
-        (line 114) before reaching this function. The config_overrides context
-        manager ensures only valid _Config field names can be used.
-
     Parameters:
-        applied: Validated mapping of configuration field names to values.
+        applied: Typed override mapping of configuration field names to values.
     """
     for name, value in applied.items():
         setattr(config, name, value)

lib_cli_exit_tools/cli/__init__.py

@@ -0,0 +1,27 @@
+"""Click-based CLI adapter for lib_cli_exit_tools.
+
+Purpose:
+    Provide the end-user command-line surface while delegating error-handling
+    and exit-code logic to :mod:`lib_cli_exit_tools.lib_cli_exit_tools`.
+Contents:
+    * :func:`cli` group exposing shared options.
+    * :func:`cli_info` subcommand reporting distribution metadata.
+    * :func:`cli_fail` subcommand triggering a deterministic failure for testing error paths.
+    * :func:`main` entry point used by console scripts and ``python -m``.
+System Integration:
+    The CLI mutates :data:`lib_cli_exit_tools.config` based on the ``--traceback``
+    flag before handing execution off to :func:`lib_cli_exit_tools.run_cli`.
+"""
+
+from __future__ import annotations
+
+# --- Public surface re-exports (backward compatibility) ---
+from .commands import cli_fail as cli_fail
+from .commands import cli_info as cli_info
+from .group import CliContextState as CliContextState
+from .group import cli as cli
+from .group import main as main
+
+# --- Register subcommands with the root group ---
+cli.add_command(cli_info)
+cli.add_command(cli_fail)

lib_cli_exit_tools/cli/commands.py

@@ -0,0 +1,69 @@
+"""Click subcommands for the lib_cli_exit_tools CLI.
+
+Purpose:
+    Define individual CLI subcommands that expose library functionality to
+    end users (``info``, ``fail``).
+Contents:
+    * :data:`CLICK_CONTEXT_SETTINGS` shared context settings for all commands.
+    * :func:`cli_info` subcommand reporting distribution metadata.
+    * :func:`cli_fail` subcommand triggering a deterministic failure.
+System Integration:
+    Commands are registered with the root group in :mod:`lib_cli_exit_tools.cli`.
+"""
+
+from __future__ import annotations
+
+import rich_click as click
+
+from .. import __init__conf__
+from .. import lib_cli_exit_tools
+
+#: Help flag aliases applied to every Click command so documentation and CLI
+#: behaviour stay consistent (`-h` mirrors `--help`).
+#: Note: This uses dict literal syntax as required by Click framework API.
+CLICK_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.command("info", context_settings=CLICK_CONTEXT_SETTINGS)
+def cli_info() -> None:
+    """Display package metadata exported by :mod:`lib_cli_exit_tools.__init__conf__`.
+
+    Why:
+        Offer a zero-dependency way for users to confirm the installed version
+        and provenance of the CLI.
+    Side Effects:
+        Writes formatted metadata to stdout.
+    Examples:
+        >>> from click.testing import CliRunner
+        >>> from lib_cli_exit_tools.cli.group import cli
+        >>> runner = CliRunner()
+        >>> result = runner.invoke(cli, ["info"])
+        >>> "Info for" in result.output
+        True
+    """
+    __init__conf__.print_info()
+
+
+@click.command("fail", context_settings=CLICK_CONTEXT_SETTINGS)
+def cli_fail() -> None:
+    """Intentionally raise a failure to validate error handling.
+
+    Why:
+        Exercise the error-reporting path so engineers can confirm exit-code
+        translation and optional traceback behaviour without crafting custom
+        failing commands.
+    Side Effects:
+        Delegates to :func:`lib_cli_exit_tools.i_should_fail`, which raises
+        ``RuntimeError`` for the caller to handle.
+    Examples:
+        >>> from click.testing import CliRunner
+        >>> from lib_cli_exit_tools.cli.group import cli
+        >>> runner = CliRunner()
+        >>> result = runner.invoke(cli, ["fail"])
+        >>> result.exit_code != 0
+        True
+        >>> "i should fail" in str(result.exception)
+        True
+    """
+
+    lib_cli_exit_tools.i_should_fail()

lib_cli_exit_tools/cli/group.py

@@ -0,0 +1,123 @@
+"""Root Click group, context state, and CLI entry point.
+
+Purpose:
+    Define the top-level Click group with shared options (``--traceback``,
+    ``--version``) and the :func:`main` entry point used by console scripts.
+Contents:
+    * :class:`CliContextState` typed container for Click context state.
+    * :func:`cli` root Click group.
+    * :func:`main` entry point for console scripts and ``python -m``.
+System Integration:
+    The CLI mutates :data:`lib_cli_exit_tools.config` based on the ``--traceback``
+    flag before handing execution off to :func:`lib_cli_exit_tools.run_cli`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import rich_click as click
+
+from .. import __init__conf__
+from .. import lib_cli_exit_tools
+from .commands import CLICK_CONTEXT_SETTINGS
+from .styling import _temporary_rich_click_configuration  # pyright: ignore[reportPrivateUsage]
+
+
+@dataclass
+class CliContextState:
+    """Type-safe container for Click context object state.
+
+    Why:
+        Replaces untyped dict usage in ctx.obj to enforce type safety and
+        prevent string literal key access violations.
+
+    Attributes:
+        traceback: Whether to show full Python tracebacks on errors.
+    """
+
+    traceback: bool = False
+
+
+@click.group(help=__init__conf__.title, context_settings=CLICK_CONTEXT_SETTINGS)
+@click.version_option(
+    version=__init__conf__.version,
+    prog_name=__init__conf__.shell_command,
+    message=f"{__init__conf__.shell_command} version {__init__conf__.version}",
+)
+@click.option(
+    "--traceback/--no-traceback",
+    is_flag=True,
+    default=False,
+    help="Show full Python traceback on errors",
+)
+@click.pass_context
+def cli(ctx: click.Context, traceback: bool) -> None:
+    """Root Click group that primes shared configuration state.
+
+    Why:
+        Accept a single ``--traceback`` flag that determines whether downstream
+        helpers emit stack traces.
+    Parameters:
+        ctx: Click context object for the current invocation.
+        traceback: When ``True`` enables traceback output for subsequent commands.
+    Side Effects:
+        Mutates ``ctx.obj`` and :data:`lib_cli_exit_tools.config.traceback`.
+    Examples:
+        >>> from click.testing import CliRunner
+        >>> runner = CliRunner()
+        >>> result = runner.invoke(cli, ["--help"])
+        >>> result.exit_code == 0
+        True
+    """
+    _store_traceback_flag(ctx, traceback)
+    lib_cli_exit_tools.config.traceback = traceback
+
+
+def _store_traceback_flag(ctx: click.Context, traceback: bool) -> None:
+    """Store traceback flag in typed context state.
+
+    Parameters:
+        ctx: Click context object for the current invocation.
+        traceback: Whether to show full Python tracebacks on errors.
+
+    Side Effects:
+        Initializes ctx.obj as CliContextState if not already set and updates
+        the traceback field.
+    """
+    ctx.ensure_object(CliContextState)
+    # Type narrowing: ctx.obj is guaranteed to be CliContextState after ensure_object
+    state = ctx.obj
+    if isinstance(state, CliContextState):  # nosec B101 - type guard, not assertion
+        state.traceback = traceback
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI with :func:`lib_cli_exit_tools.run_cli` wiring.
+
+    Why:
+        Serve as the target for console scripts and ``python -m`` execution by
+        returning an integer exit code instead of exiting directly.
+    Parameters:
+        argv: Optional iterable of arguments passed to Click (without program name).
+    Returns:
+        Integer exit code from :func:`lib_cli_exit_tools.run_cli`.
+    Side Effects:
+        Delegates to Click and may write to stdout/stderr.
+    Examples:
+        >>> import contextlib, io
+        >>> buffer = io.StringIO()
+        >>> with contextlib.redirect_stdout(buffer):
+        ...     exit_code = main(["info"])
+        >>> exit_code
+        0
+        >>> "Info for" in buffer.getvalue()
+        True
+    """
+    with _temporary_rich_click_configuration():
+        return lib_cli_exit_tools.run_cli(
+            cli,
+            argv=list(argv) if argv is not None else None,
+            prog_name=__init__conf__.shell_command,
+        )

lib_cli_exit_tools/cli/styling.py

@@ -0,0 +1,111 @@
+"""Rich-click styling adapter for terminal capability detection.
+
+Purpose:
+    Detect terminal capabilities (TTY, encoding) and configure rich-click
+    global styling accordingly, falling back to ASCII-safe defaults when
+    the output stream cannot render Rich markup.
+Contents:
+    * :class:`RichClickSnapshot` typed snapshot of rich-click globals.
+    * Stream inspection helpers for TTY and encoding detection.
+    * :func:`_temporary_rich_click_configuration` context manager.
+System Integration:
+    Called by :func:`lib_cli_exit_tools.cli.group.main` before every CLI
+    invocation to ensure rich-click output matches terminal capabilities.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator, TypedDict
+
+import rich_click as click
+from rich_click import rich_click as rich_config
+
+
+class RichClickSnapshot(TypedDict):
+    """Type-safe snapshot of rich-click global styling configuration.
+
+    Attributes:
+        FORCE_TERMINAL: Whether to force terminal styling.
+        COLOR_SYSTEM: Color system to use (e.g., "auto", "256", "truecolor", None).
+        STYLE_OPTIONS_PANEL_BOX: Box style for options panel.
+        STYLE_COMMANDS_PANEL_BOX: Box style for commands panel.
+        STYLE_ERRORS_PANEL_BOX: Box style for errors panel.
+
+    Note:
+        Uses Any for field types to accommodate the dynamic nature of rich-click
+        configuration, which doesn't provide stable typing guarantees.
+    """
+
+    FORCE_TERMINAL: Any
+    COLOR_SYSTEM: Any
+    STYLE_OPTIONS_PANEL_BOX: Any
+    STYLE_COMMANDS_PANEL_BOX: Any
+    STYLE_ERRORS_PANEL_BOX: Any
+
+
+def _needs_plain_output(stream: object) -> bool:
+    """Tell whether ``stream`` will honour Rich styling."""
+
+    return (not _stream_is_tty(stream)) or (not _stream_supports_utf(stream))
+
+
+def _stream_is_tty(stream: object) -> bool:
+    """Return ``True`` when ``stream`` behaves like a TTY."""
+    checker = getattr(stream, "isatty", lambda: False)
+    try:
+        return bool(checker())
+    except Exception:  # pragma: no cover - defensive shield
+        return False
+
+
+def _stream_supports_utf(stream: object) -> bool:
+    """Tell whether ``stream`` reports a UTF-friendly encoding."""
+    encoding = (getattr(stream, "encoding", "") or "").lower()
+    return "utf" in encoding
+
+
+def _prefer_ascii_layout() -> None:
+    """Downgrade rich-click global styling to ASCII-friendly defaults."""
+    rich_config.FORCE_TERMINAL = False
+    rich_config.COLOR_SYSTEM = None
+    rich_config.STYLE_OPTIONS_PANEL_BOX = None
+    rich_config.STYLE_COMMANDS_PANEL_BOX = None
+    rich_config.STYLE_ERRORS_PANEL_BOX = None
+
+
+def _snapshot_rich_click_options() -> RichClickSnapshot:
+    """Capture rich-click global styling toggles for later restoration."""
+
+    return RichClickSnapshot(
+        FORCE_TERMINAL=getattr(rich_config, "FORCE_TERMINAL", None),
+        COLOR_SYSTEM=getattr(rich_config, "COLOR_SYSTEM", None),
+        STYLE_OPTIONS_PANEL_BOX=getattr(rich_config, "STYLE_OPTIONS_PANEL_BOX", None),
+        STYLE_COMMANDS_PANEL_BOX=getattr(rich_config, "STYLE_COMMANDS_PANEL_BOX", None),
+        STYLE_ERRORS_PANEL_BOX=getattr(rich_config, "STYLE_ERRORS_PANEL_BOX", None),
+    )
+
+
+def _restore_rich_click_options(snapshot: RichClickSnapshot) -> None:
+    """Restore rich-click globals to the captured snapshot."""
+
+    rich_config.FORCE_TERMINAL = snapshot["FORCE_TERMINAL"]
+    rich_config.COLOR_SYSTEM = snapshot["COLOR_SYSTEM"]
+    rich_config.STYLE_OPTIONS_PANEL_BOX = snapshot["STYLE_OPTIONS_PANEL_BOX"]
+    rich_config.STYLE_COMMANDS_PANEL_BOX = snapshot["STYLE_COMMANDS_PANEL_BOX"]
+    rich_config.STYLE_ERRORS_PANEL_BOX = snapshot["STYLE_ERRORS_PANEL_BOX"]
+
+
+@contextmanager
+def _temporary_rich_click_configuration() -> Iterator[None]:  # pyright: ignore[reportUnusedFunction]
+    """Apply plain-output safeguards and restore rich-click globals afterwards."""
+
+    snapshot = _snapshot_rich_click_options()
+    stdout_stream = click.get_text_stream("stdout")
+    stderr_stream = click.get_text_stream("stderr")
+    if _needs_plain_output(stdout_stream) and _needs_plain_output(stderr_stream):
+        _prefer_ascii_layout()
+    try:
+        yield
+    finally:
+        _restore_rich_click_options(snapshot)

lib_cli_exit_tools/core/configuration.py

@@ -23,9 +23,25 @@ from __future__ import annotations
 from collections.abc import Iterator, Mapping
 from contextlib import contextmanager
 from dataclasses import dataclass, fields
-from typing import Literal, TypedDict
+from enum import Enum
+from typing import TypedDict
 
-__all__ = ["_Config", "config", "config_overrides", "reset_config"]
+__all__ = ["ExitCodeStyle", "_Config", "config", "config_overrides", "reset_config"]
+
+
+class ExitCodeStyle(str, Enum):
+    """Exit-code mapping strategy selector.
+
+    Why:
+        Replace raw string literals with a closed set of values so comparisons
+        are type-safe and spelling mistakes are caught at import time.
+    Members:
+        ERRNO: Use POSIX/Windows errno-based exit codes (default).
+        SYSEXITS: Use BSD sysexits.h conventions for shell-centric workflows.
+    """
+
+    ERRNO = "errno"
+    SYSEXITS = "sysexits"
 
 
 class ConfigSnapshot(TypedDict):
@@ -43,7 +59,7 @@ class ConfigSnapshot(TypedDict):
     """
 
     traceback: bool
-    exit_code_style: Literal["errno", "sysexits"]
+    exit_code_style: ExitCodeStyle
     broken_pipe_exit_code: int
     traceback_force_color: bool
 
@@ -77,7 +93,7 @@ class _Config:
     """
 
     traceback: bool = False
-    exit_code_style: Literal["errno", "sysexits"] = "errno"
+    exit_code_style: ExitCodeStyle = ExitCodeStyle.ERRNO
     broken_pipe_exit_code: int = 141
     traceback_force_color: bool = False
 

lib_cli_exit_tools/core/exit_codes.py

@@ -19,7 +19,7 @@ import os
 import subprocess  # nosec B404 - imported for CalledProcessError type inspection
 from typing import Callable, Iterable, Mapping
 
-from .configuration import config
+from .configuration import ExitCodeStyle, config
 
 __all__ = ["get_system_exit_code"]
 
@@ -217,7 +217,7 @@ def _code_from_sysexits_mode(exc: BaseException) -> int | None:
     Side Effects:
         None.
     """
-    if config.exit_code_style != "sysexits":
+    if config.exit_code_style != ExitCodeStyle.SYSEXITS:
         return None
     return _sysexits_resolved_code(exc)
 

lib_cli_exit_tools/lib_cli_exit_tools.py

@@ -37,10 +37,11 @@ from .application.runner import (
     print_exception_message,
     run_cli,
 )
-from .core.configuration import config, config_overrides, reset_config
+from .core.configuration import ExitCodeStyle, config, config_overrides, reset_config
 from .core.exit_codes import get_system_exit_code
 
 __all__ = [
+    "ExitCodeStyle",
     "config",
     "get_system_exit_code",
     "print_exception_message",

{lib_cli_exit_tools-2.2.4.dist-info → lib_cli_exit_tools-2.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 2.2.4
+Version: 2.3.0
 Summary: CLI exit handling helpers: clean signals, exit codes, and error printing
 Project-URL: Homepage, https://github.com/bitranox/lib_cli_exit_tools
 Project-URL: Repository, https://github.com/bitranox/lib_cli_exit_tools.git
@@ -16,22 +16,22 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: rich-click>=1.9.6
+Requires-Dist: rich-click>=1.9.7
 Provides-Extra: dev
 Requires-Dist: bandit>=1.9.3; extra == 'dev'
 Requires-Dist: build>=1.4.0; extra == 'dev'
 Requires-Dist: codecov-cli>=11.2.6; extra == 'dev'
-Requires-Dist: coverage[toml]>=7.13.2; extra == 'dev'
-Requires-Dist: hypothesis>=6.151.2; extra == 'dev'
-Requires-Dist: import-linter>=2.9; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.13.4; extra == 'dev'
+Requires-Dist: hypothesis>=6.151.6; extra == 'dev'
+Requires-Dist: import-linter>=2.10; extra == 'dev'
 Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
 Requires-Dist: pyright[nodejs]>=1.1.408; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.2; extra == 'dev'
 Requires-Dist: rtoml>=0.13.0; extra == 'dev'
-Requires-Dist: ruff>=0.14.14; extra == 'dev'
-Requires-Dist: textual>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.1; extra == 'dev'
+Requires-Dist: textual>=7.5.0; extra == 'dev'
 Requires-Dist: twine>=6.2.0; extra == 'dev'
 Description-Content-Type: text/markdown
 

lib_cli_exit_tools-2.3.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+lib_cli_exit_tools/__init__.py,sha256=KzpZAMrc328V_nYm2GuTR0Sxyqh0XuKtlHP6dVCs2pc,1905
+lib_cli_exit_tools/__init__conf__.py,sha256=tYrmAVN5mo_12V1_m_un7FtroeeZY0M9zHrPFXvnOdU,2521
+lib_cli_exit_tools/__main__.py,sha256=wODJaNu_NyO7tknvlpPArq0MaDwDum8zqyb73-qshzo,257
+lib_cli_exit_tools/lib_cli_exit_tools.py,sha256=fCLgJypLi6VHjmnh0McUn3CbhBhdzGYdDGcwcLokL4o,2561
+lib_cli_exit_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lib_cli_exit_tools/adapters/__init__.py,sha256=Jj8FCGY1lAPAduYSW3wTDh8ojpr9BZms7wKEMPq8pWE,504
+lib_cli_exit_tools/adapters/signals.py,sha256=Q2D9Htv64nsT5n66cJFDDHRWVXJokaG77I-V8gTDMKg,5772
+lib_cli_exit_tools/application/__init__.py,sha256=Yikej3OOOaAjWOvFimg1jUYrCUGu5d3-RBiiai4tHDM,566
+lib_cli_exit_tools/application/runner.py,sha256=oTzARoieuN0JK7KRSzrMhKTFWF6GA8cxt1pK6YVjgVM,24413
+lib_cli_exit_tools/cli/__init__.py,sha256=IVyU1DEgn2xBYfp1BBpund9nucUEPyOu7yt8DShu470,1094
+lib_cli_exit_tools/cli/commands.py,sha256=WDF6hDsyczAb6cQp4fA6KMF1iqJQ1lzjv-RvIxq1itI,2418
+lib_cli_exit_tools/cli/group.py,sha256=UFKb8VCkkQEB4CwIDckItrPHTRxSCddyLXKKr-2xU-w,4224
+lib_cli_exit_tools/cli/styling.py,sha256=2W9-0Ig4X3RO8wVPukZEg2V_kBJfZKJANlawUOJAlhg,4236
+lib_cli_exit_tools/core/__init__.py,sha256=aR7OIBWOQ1PsA33blOTgLrq5ffKDCuaMVBS5mbrDAZ8,531
+lib_cli_exit_tools/core/configuration.py,sha256=ND0BBRBY7BkRbQWliWj-pp7pY1g8QULxgkeXfu2wfI8,6121
+lib_cli_exit_tools/core/exit_codes.py,sha256=ukinlUROFKb6KmF_-8luxE1C2VJc6UwxIMMr0eB9xFg,12349
+lib_cli_exit_tools-2.3.0.dist-info/METADATA,sha256=PQkASspOF7lCn8k3UG2y4lGdLJo_w-nHQWpoOirduC4,26234
+lib_cli_exit_tools-2.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+lib_cli_exit_tools-2.3.0.dist-info/entry_points.txt,sha256=8R-_3UT0KcQ7HQ7idDx6rlG77GhHb0E2N5QnN41dj-M,161
+lib_cli_exit_tools-2.3.0.dist-info/licenses/LICENSE,sha256=6s9SL2InRrwynPjJYiER7ONHBshbGj_yC5EBzfo7l9I,1072
+lib_cli_exit_tools-2.3.0.dist-info/RECORD,,

lib_cli_exit_tools/cli.py

@@ -1,261 +0,0 @@
-"""Click-based CLI adapter for lib_cli_exit_tools.
-
-Purpose:
-    Provide the end-user command-line surface while delegating error-handling
-    and exit-code logic to :mod:`lib_cli_exit_tools.lib_cli_exit_tools`.
-Contents:
-    * :func:`cli` group exposing shared options.
-    * :func:`cli_info` subcommand reporting distribution metadata.
-    * :func:`cli_fail` subcommand triggering a deterministic failure for testing error paths.
-    * :func:`main` entry point used by console scripts and ``python -m``.
-System Integration:
-    The CLI mutates :data:`lib_cli_exit_tools.config` based on the ``--traceback``
-    flag before handing execution off to :func:`lib_cli_exit_tools.run_cli`.
-"""
-
-from __future__ import annotations
-
-from contextlib import contextmanager
-from dataclasses import dataclass
-from typing import Any, Iterator, Sequence, TypedDict
-
-import rich_click as click
-from rich_click import rich_click as rich_config
-
-from . import __init__conf__
-from . import lib_cli_exit_tools
-
-#: Help flag aliases applied to every Click command so documentation and CLI
-#: behaviour stay consistent (`-h` mirrors `--help`).
-#: Note: This uses dict literal syntax as required by Click framework API.
-CLICK_CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
-
-
-class RichClickSnapshot(TypedDict):
-    """Type-safe snapshot of rich-click global styling configuration.
-
-    Attributes:
-        FORCE_TERMINAL: Whether to force terminal styling.
-        COLOR_SYSTEM: Color system to use (e.g., "auto", "256", "truecolor", None).
-        STYLE_OPTIONS_PANEL_BOX: Box style for options panel.
-        STYLE_COMMANDS_PANEL_BOX: Box style for commands panel.
-        STYLE_ERRORS_PANEL_BOX: Box style for errors panel.
-
-    Note:
-        Uses Any for field types to accommodate the dynamic nature of rich-click
-        configuration, which doesn't provide stable typing guarantees.
-    """
-
-    FORCE_TERMINAL: Any
-    COLOR_SYSTEM: Any
-    STYLE_OPTIONS_PANEL_BOX: Any
-    STYLE_COMMANDS_PANEL_BOX: Any
-    STYLE_ERRORS_PANEL_BOX: Any
-
-
-@dataclass
-class CliContextState:
-    """Type-safe container for Click context object state.
-
-    Why:
-        Replaces untyped dict usage in ctx.obj to enforce type safety and
-        prevent string literal key access violations.
-
-    Attributes:
-        traceback: Whether to show full Python tracebacks on errors.
-    """
-
-    traceback: bool = False
-
-
-def _needs_plain_output(stream: object) -> bool:
-    """Tell whether ``stream`` will honour Rich styling."""
-
-    return (not _stream_is_tty(stream)) or (not _stream_supports_utf(stream))
-
-
-def _stream_is_tty(stream: object) -> bool:
-    """Return ``True`` when ``stream`` behaves like a TTY."""
-    checker = getattr(stream, "isatty", lambda: False)
-    try:
-        return bool(checker())
-    except Exception:  # pragma: no cover - defensive shield
-        return False
-
-
-def _stream_supports_utf(stream: object) -> bool:
-    """Tell whether ``stream`` reports a UTF-friendly encoding."""
-    encoding = (getattr(stream, "encoding", "") or "").lower()
-    return "utf" in encoding
-
-
-def _prefer_ascii_layout() -> None:
-    """Downgrade rich-click global styling to ASCII-friendly defaults."""
-    rich_config.FORCE_TERMINAL = False
-    rich_config.COLOR_SYSTEM = None
-    rich_config.STYLE_OPTIONS_PANEL_BOX = None
-    rich_config.STYLE_COMMANDS_PANEL_BOX = None
-    rich_config.STYLE_ERRORS_PANEL_BOX = None
-
-
-def _snapshot_rich_click_options() -> RichClickSnapshot:
-    """Capture rich-click global styling toggles for later restoration."""
-
-    return RichClickSnapshot(
-        FORCE_TERMINAL=getattr(rich_config, "FORCE_TERMINAL", None),
-        COLOR_SYSTEM=getattr(rich_config, "COLOR_SYSTEM", None),
-        STYLE_OPTIONS_PANEL_BOX=getattr(rich_config, "STYLE_OPTIONS_PANEL_BOX", None),
-        STYLE_COMMANDS_PANEL_BOX=getattr(rich_config, "STYLE_COMMANDS_PANEL_BOX", None),
-        STYLE_ERRORS_PANEL_BOX=getattr(rich_config, "STYLE_ERRORS_PANEL_BOX", None),
-    )
-
-
-def _restore_rich_click_options(snapshot: RichClickSnapshot) -> None:
-    """Restore rich-click globals to the captured snapshot."""
-
-    rich_config.FORCE_TERMINAL = snapshot["FORCE_TERMINAL"]
-    rich_config.COLOR_SYSTEM = snapshot["COLOR_SYSTEM"]
-    rich_config.STYLE_OPTIONS_PANEL_BOX = snapshot["STYLE_OPTIONS_PANEL_BOX"]
-    rich_config.STYLE_COMMANDS_PANEL_BOX = snapshot["STYLE_COMMANDS_PANEL_BOX"]
-    rich_config.STYLE_ERRORS_PANEL_BOX = snapshot["STYLE_ERRORS_PANEL_BOX"]
-
-
-@contextmanager
-def _temporary_rich_click_configuration() -> Iterator[None]:
-    """Apply plain-output safeguards and restore rich-click globals afterwards."""
-
-    snapshot = _snapshot_rich_click_options()
-    stdout_stream = click.get_text_stream("stdout")
-    stderr_stream = click.get_text_stream("stderr")
-    if _needs_plain_output(stdout_stream) and _needs_plain_output(stderr_stream):
-        _prefer_ascii_layout()
-    try:
-        yield
-    finally:
-        _restore_rich_click_options(snapshot)
-
-
-@click.group(help=__init__conf__.title, context_settings=CLICK_CONTEXT_SETTINGS)
-@click.version_option(
-    version=__init__conf__.version,
-    prog_name=__init__conf__.shell_command,
-    message=f"{__init__conf__.shell_command} version {__init__conf__.version}",
-)
-@click.option(
-    "--traceback/--no-traceback",
-    is_flag=True,
-    default=False,
-    help="Show full Python traceback on errors",
-)
-@click.pass_context
-def cli(ctx: click.Context, traceback: bool) -> None:
-    """Root Click group that primes shared configuration state.
-
-    Why:
-        Accept a single ``--traceback`` flag that determines whether downstream
-        helpers emit stack traces.
-    Parameters:
-        ctx: Click context object for the current invocation.
-        traceback: When ``True`` enables traceback output for subsequent commands.
-    Side Effects:
-        Mutates ``ctx.obj`` and :data:`lib_cli_exit_tools.config.traceback`.
-    Examples:
-        >>> from click.testing import CliRunner
-        >>> runner = CliRunner()
-        >>> result = runner.invoke(cli, ["--help"])
-        >>> result.exit_code == 0
-        True
-    """
-    _store_traceback_flag(ctx, traceback)
-    lib_cli_exit_tools.config.traceback = traceback
-
-
-def _store_traceback_flag(ctx: click.Context, traceback: bool) -> None:
-    """Store traceback flag in typed context state.
-
-    Parameters:
-        ctx: Click context object for the current invocation.
-        traceback: Whether to show full Python tracebacks on errors.
-
-    Side Effects:
-        Initializes ctx.obj as CliContextState if not already set and updates
-        the traceback field.
-    """
-    ctx.ensure_object(CliContextState)
-    # Type narrowing: ctx.obj is guaranteed to be CliContextState after ensure_object
-    state = ctx.obj
-    if isinstance(state, CliContextState):  # nosec B101 - type guard, not assertion
-        state.traceback = traceback
-
-
-@cli.command("info", context_settings=CLICK_CONTEXT_SETTINGS)
-def cli_info() -> None:
-    """Display package metadata exported by :mod:`lib_cli_exit_tools.__init__conf__`.
-
-    Why:
-        Offer a zero-dependency way for users to confirm the installed version
-        and provenance of the CLI.
-    Side Effects:
-        Writes formatted metadata to stdout.
-    Examples:
-        >>> from click.testing import CliRunner
-        >>> runner = CliRunner()
-        >>> result = runner.invoke(cli, ["info"])
-        >>> "Info for" in result.output
-        True
-    """
-    __init__conf__.print_info()
-
-
-@cli.command("fail", context_settings=CLICK_CONTEXT_SETTINGS)
-def cli_fail() -> None:
-    """Intentionally raise a failure to validate error handling.
-
-    Why:
-        Exercise the error-reporting path so engineers can confirm exit-code
-        translation and optional traceback behaviour without crafting custom
-        failing commands.
-    Side Effects:
-        Delegates to :func:`lib_cli_exit_tools.i_should_fail`, which raises
-        ``RuntimeError`` for the caller to handle.
-    Examples:
-        >>> from click.testing import CliRunner
-        >>> runner = CliRunner()
-        >>> result = runner.invoke(cli, ["fail"])
-        >>> result.exit_code != 0
-        True
-        >>> "i should fail" in result.output or "i should fail" in result.stderr
-        True
-    """
-
-    lib_cli_exit_tools.i_should_fail()
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    """Run the CLI with :func:`lib_cli_exit_tools.run_cli` wiring.
-
-    Why:
-        Serve as the target for console scripts and ``python -m`` execution by
-        returning an integer exit code instead of exiting directly.
-    Parameters:
-        argv: Optional iterable of arguments passed to Click (without program name).
-    Returns:
-        Integer exit code from :func:`lib_cli_exit_tools.run_cli`.
-    Side Effects:
-        Delegates to Click and may write to stdout/stderr.
-    Examples:
-        >>> import contextlib, io
-        >>> buffer = io.StringIO()
-        >>> with contextlib.redirect_stdout(buffer):
-        ...     exit_code = main(["info"])
-        >>> exit_code
-        0
-        >>> "Info for" in buffer.getvalue()
-        True
-    """
-    with _temporary_rich_click_configuration():
-        return lib_cli_exit_tools.run_cli(
-            cli,
-            argv=list(argv) if argv is not None else None,
-            prog_name=__init__conf__.shell_command,
-        )

lib_cli_exit_tools-2.2.4.dist-info/RECORD

@@ -1,18 +0,0 @@
-lib_cli_exit_tools/__init__.py,sha256=Z-VXcrmjZCgJZ8NW0UCVIc0HBOsjQicCbzgHj7r22eA,1867
-lib_cli_exit_tools/__init__conf__.py,sha256=8b5wcSJwywaIvuqYoosuL3G0mpUqQ8kuVjpp67wdON4,2521
-lib_cli_exit_tools/__main__.py,sha256=wODJaNu_NyO7tknvlpPArq0MaDwDum8zqyb73-qshzo,257
-lib_cli_exit_tools/cli.py,sha256=k7LC08nVfse4i9RbsOGKTc9y-rrVbR1nOSKiwBvNxrE,9322
-lib_cli_exit_tools/lib_cli_exit_tools.py,sha256=-_kjKGiWyMQ715KxOqrS6uA57SXOgJmMeowU7AmtC8A,2525
-lib_cli_exit_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lib_cli_exit_tools/adapters/__init__.py,sha256=Jj8FCGY1lAPAduYSW3wTDh8ojpr9BZms7wKEMPq8pWE,504
-lib_cli_exit_tools/adapters/signals.py,sha256=Q2D9Htv64nsT5n66cJFDDHRWVXJokaG77I-V8gTDMKg,5772
-lib_cli_exit_tools/application/__init__.py,sha256=Yikej3OOOaAjWOvFimg1jUYrCUGu5d3-RBiiai4tHDM,566
-lib_cli_exit_tools/application/runner.py,sha256=AlCWX5o4VTRzsCom9EgnEK0iVCIZwyIdXtmqq5qegMM,24937
-lib_cli_exit_tools/core/__init__.py,sha256=aR7OIBWOQ1PsA33blOTgLrq5ffKDCuaMVBS5mbrDAZ8,531
-lib_cli_exit_tools/core/configuration.py,sha256=Ro6R2cmOIFhdOUogjK1VOxEJInx24Wgme0t-ucYJGEg,5658
-lib_cli_exit_tools/core/exit_codes.py,sha256=nqx-e6h-ji-FiECPnDV8b0yrjcLPJyU-3xf4zhfRCBE,12322
-lib_cli_exit_tools-2.2.4.dist-info/METADATA,sha256=RzJ0PBuOrRXwpWqnJkyjrd-mNlHxqi6jL2Nro9q2zoc,26234
-lib_cli_exit_tools-2.2.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-lib_cli_exit_tools-2.2.4.dist-info/entry_points.txt,sha256=8R-_3UT0KcQ7HQ7idDx6rlG77GhHb0E2N5QnN41dj-M,161
-lib_cli_exit_tools-2.2.4.dist-info/licenses/LICENSE,sha256=6s9SL2InRrwynPjJYiER7ONHBshbGj_yC5EBzfo7l9I,1072
-lib_cli_exit_tools-2.2.4.dist-info/RECORD,,