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

lib_cli_exit_tools/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from .lib_cli_exit_tools import (
+    config,
+    get_system_exit_code,
+    print_exception_message,
+    flush_streams,
+)
+
+__all__ = [
+    "config",
+    "get_system_exit_code",
+    "print_exception_message",
+    "flush_streams",
+]

lib_cli_exit_tools/__init__conf__.py

@@ -0,0 +1,108 @@
+"""Runtime metadata facade loaded from installed package metadata.
+
+Reads values from the installed distribution's metadata via `importlib.metadata`
+so that `pyproject.toml` remains the single source of truth.
+
+Falls back to defaults when not installed (e.g., running from a working tree
+without an editable install).
+"""
+
+from __future__ import annotations
+
+from importlib import metadata as _im
+from typing import Any, Protocol, runtime_checkable
+
+_DIST_NAME = "lib_cli_exit_tools"
+
+
+@runtime_checkable
+class _MetaMapping(Protocol):
+    """Minimal protocol for package metadata across Python versions.
+
+    On Python < 3.12, `importlib.metadata.metadata()` returns an
+    `email.message.Message` which supports `.get(key, default)`.
+    On Python >= 3.12, it returns `PackageMetadata`, which also supports `.get`.
+    We type to this protocol to keep Pyright happy on 3.10.
+    """
+
+    def get(self, __key: str, __default: object = ...) -> object: ...
+
+
+def _get_str(m: _MetaMapping, key: str, default: str = "") -> str:
+    """Return metadata value as string or a default if missing/not a string."""
+    v = m.get(key, default)
+    return v if isinstance(v, str) else default
+
+
+def _meta() -> Any | None:
+    try:
+        return _im.metadata(_DIST_NAME)
+    except _im.PackageNotFoundError:
+        return None
+
+
+def _version() -> str:
+    try:
+        return _im.version(_DIST_NAME)
+    except _im.PackageNotFoundError:
+        return "0.0.0.dev0"
+
+
+def _home_page(m: Any | None) -> str:
+    if not m:
+        return "https://github.com/bitranox/lib_cli_exit_tools"
+    # cast to protocol for typing purposes
+    mm: _MetaMapping = m  # type: ignore[assignment]
+    hp = _get_str(mm, "Home-page") or _get_str(mm, "Homepage")
+    return hp or "https://github.com/bitranox/lib_cli_exit_tools"
+
+
+def _author(m: Any | None) -> tuple[str, str]:
+    if not m:
+        return ("bitranox", "bitranox@gmail.com")
+    mm: _MetaMapping = m  # type: ignore[assignment]
+    return (_get_str(mm, "Author", ""), _get_str(mm, "Author-email", ""))
+
+
+def _summary(m: Any | None) -> str:
+    if not m:
+        return "Functions to exit a CLI application properly"
+    mm: _MetaMapping = m  # type: ignore[assignment]
+    return _get_str(mm, "Summary", "Functions to exit a CLI application properly")
+
+
+def _shell_command() -> str:
+    # Discover console script name mapping to our CLI main, fallback to dist name
+    eps = _im.entry_points(group="console_scripts")
+    target = "lib_cli_exit_tools.cli:main"
+    for ep in list(eps):
+        if ep.value == target:
+            return ep.name
+    return _DIST_NAME
+
+
+# Public values (resolve metadata once)
+_m = _meta()
+name = _DIST_NAME
+title = _summary(_m)
+version = _version()
+homepage = _home_page(_m)
+author, author_email = _author(_m)
+shell_command = _shell_command()
+
+
+def print_info() -> None:
+    """Print resolved metadata in a compact, aligned block."""
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(k) for k, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines += [f"    {k.ljust(pad)} = {v}" for k, v in fields]
+    print("\n".join(lines))

lib_cli_exit_tools/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lib_cli_exit_tools/cli.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import platform
+import signal
+from typing import Optional, List
+from types import FrameType
+
+import click
+
+from . import __init__conf__
+from . import lib_cli_exit_tools as tools
+
+is_windows = platform.system().lower() == "windows"
+is_posix = not is_windows
+
+
+class SigIntError(Exception):
+    """Raised on SIGINT (Ctrl+C)."""
+
+
+class SigTermError(Exception):
+    """Raised on SIGTERM (POSIX) or SIGBREAK (Windows)."""
+
+
+class SigBreakError(Exception):
+    """Raised on SIGBREAK (Windows Ctrl+Break)."""
+
+
+def _sigint_handler(signo: int, frame: FrameType | None) -> None:
+    raise SigIntError()
+
+
+def _sigterm_handler(signo: int, frame: FrameType | None) -> None:
+    raise SigTermError()
+
+
+def _install_signal_handlers() -> None:
+    """Install minimal, portable signal handlers.
+
+    * Always handle SIGINT.
+    * On POSIX, also handle SIGTERM.
+    * On Windows, handle SIGBREAK (Ctrl+Break) as a best-effort replacement for SIGTERM.
+    """
+    signal.signal(signal.SIGINT, _sigint_handler)
+    if is_posix:
+        signal.signal(signal.SIGTERM, _sigterm_handler)
+    else:
+        # SIGBREAK exists on Windows
+        try:
+
+            def _sigbreak_handler(signo: int, frame: FrameType | None) -> None:
+                raise SigBreakError()
+
+            signal.signal(signal.SIGBREAK, _sigbreak_handler)  # type: ignore[attr-defined]
+        except Exception:
+            pass
+
+
+CLICK_CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])  # noqa: C408
+
+
+@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 CLI group. Stores global opts in context & tools.config."""
+    ctx.ensure_object(dict)
+    ctx.obj["traceback"] = traceback
+    tools.config.traceback = traceback
+
+
+@cli.command("info", context_settings=CLICK_CONTEXT_SETTINGS)
+def cli_info() -> None:
+    """Print project information."""
+    __init__conf__.print_info()
+
+
+def _handle_exception(e: BaseException) -> int:
+    """Centralized exception → exit-code + printing.
+
+    Respects tools.config.traceback and uses tools.print_exception_message.
+    Returns an integer once (single return style).
+    """
+    result: int | None = None
+    if isinstance(e, (SigIntError, KeyboardInterrupt)):
+        click.echo("Aborted (SIGINT).", err=True)
+        result = 130  # 128 + SIGINT(2)
+    elif isinstance(e, SigTermError):
+        click.echo("Terminated (SIGTERM/SIGBREAK).", err=True)
+        result = 143  # 128 + SIGTERM(15)
+    elif isinstance(e, SigBreakError):  # precise mapping for Windows Ctrl+Break
+        click.echo("Terminated (SIGBREAK).", err=True)
+        result = 149  # 128 + SIGBREAK(21)
+    elif isinstance(e, BrokenPipeError):
+        # Broken pipe: stay quiet and exit with configured code
+        result = int(tools.config.broken_pipe_exit_code)
+    elif isinstance(e, click.ClickException):
+        e.show()
+        result = e.exit_code
+    elif isinstance(e, SystemExit):
+        try:
+            result = int(e.code or 0)
+        except Exception:
+            result = 1
+    else:
+        # Unexpected exception: print nicely or with traceback depending on config
+        if tools.config.traceback:
+            # Re-raise so Python prints full traceback (useful in CI/dev)
+            raise
+        tools.print_exception_message()
+        result = tools.get_system_exit_code(e)
+    return int(result)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Entrypoint returning an int exit code.
+
+    Use via `python -m lib_cli_exit_tools` or console script.
+    """
+    _install_signal_handlers()
+    try:
+        # Do not let Click exit the process; we want to convert to int code
+        cli.main(args=argv, standalone_mode=False, prog_name=__init__conf__.shell_command)
+        return 0
+    except BaseException as e:  # noqa: BLE001 - we want a single exit funnel
+        return _handle_exception(e)
+    finally:
+        tools.flush_streams()

lib_cli_exit_tools/lib_cli_exit_tools.py

@@ -0,0 +1,353 @@
+"""Core helpers for clean CLI exits and error printing.
+
+Exposed API:
+- config: runtime options (traceback toggle, exit code style, broken pipe behavior)
+- get_system_exit_code(exc): map exceptions → OS-appropriate exit codes
+- print_exception_message(...): print concise error, optional traceback, stdout/stderr if present
+- flush_streams(): flush stdout/stderr safely
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import traceback
+from dataclasses import dataclass
+from typing import Any, Literal, Optional, TextIO
+
+
+@dataclass(slots=True)
+class _Config:
+    """Runtime configuration for library behavior."""
+
+    traceback: bool = False
+    # errno → numeric OS codes (default) | sysexits (64–78 semantics)
+    exit_code_style: Literal["errno", "sysexits"] = "errno"
+    # Exit code to use for BrokenPipeError (common in pipelines). Typical choices:
+    # 141 (128+SIGPIPE), 0 (treat as benign truncation), or 32 (EPIPE).
+    broken_pipe_exit_code: int = 141
+
+
+config = _Config()
+
+
+def get_system_exit_code(exc: BaseException) -> int:
+    """
+    Return the exit code for linux or Windows os, based on the exception.
+    If, on windows, the winerror code is passed with the Exception, we return that winerror code.
+
+
+    Parameter
+    ---------
+    exc
+        the exception to analyze
+
+
+    Result
+    ------
+    exit_code
+        as integer
+
+
+    Examples
+    --------
+
+    >>> try:
+    ...     raise RuntimeError()
+    ... except RuntimeError as my_exc:
+    ...     get_system_exit_code(my_exc)
+    1
+    >>> try:
+    ...     raise RuntimeError()
+    ... except RuntimeError as my_exc:
+    ...     setattr(my_exc, 'winerror', 42)
+    ...     get_system_exit_code(my_exc)
+    42
+    >>> try:
+    ...     raise RuntimeError()
+    ... except RuntimeError as my_exc:
+    ...     setattr(my_exc, 'winerror', None)
+    ...     get_system_exit_code(my_exc)
+    1
+    >>> try:
+    ...     exit(99)
+    ... except SystemExit as my_exc:
+    ...     get_system_exit_code(my_exc)
+    99
+
+    """
+
+    # Prefer precise sources first: explicit returncodes, signals, winerror/errno
+    # subprocess returncode
+    if isinstance(exc, subprocess.CalledProcessError):
+        try:
+            return int(exc.returncode)
+        except Exception:
+            return 1
+
+    # KeyboardInterrupt should map to 130 regardless of platform
+    if isinstance(exc, KeyboardInterrupt):
+        return 130
+
+    # Windows-specific error code passthrough
+    if hasattr(exc, "winerror"):
+        try:
+            return int(getattr(exc, "winerror"))  # type: ignore[arg-type]
+        except (AttributeError, TypeError, ValueError):
+            pass
+
+    # Broken pipe (common when piping to head/less): don't be noisy
+    if isinstance(exc, BrokenPipeError):
+        return int(config.broken_pipe_exit_code)
+
+    # If an errno is present (OSError family), prefer it
+    if isinstance(exc, OSError) and getattr(exc, "errno", None) is not None:
+        try:
+            return int(exc.errno)  # type: ignore[arg-type]
+        except Exception:
+            pass
+
+    # Fallback mappings (ordered from specific to general)
+    # POSIX references: errno.h; Windows: common Win32/WSA equivalents when errno/winerror absent
+    posix_exceptions = {
+        FileNotFoundError: 2,  # ENOENT
+        PermissionError: 13,  # EACCES
+        FileExistsError: 17,  # EEXIST
+        IsADirectoryError: 21,  # EISDIR
+        NotADirectoryError: 20,  # ENOTDIR
+        TimeoutError: 110,  # ETIMEDOUT
+        TypeError: 22,  # EINVAL
+        ValueError: 22,  # EINVAL
+        RuntimeError: 1,
+    }
+    windows_exceptions = {
+        FileNotFoundError: 2,  # ERROR_FILE_NOT_FOUND
+        PermissionError: 5,  # ERROR_ACCESS_DENIED
+        FileExistsError: 80,  # ERROR_FILE_EXISTS
+        IsADirectoryError: 267,  # ERROR_DIRECTORY
+        NotADirectoryError: 267,  # ERROR_DIRECTORY
+        TimeoutError: 1460,  # ERROR_TIMEOUT
+        TypeError: 87,  # ERROR_INVALID_PARAMETER
+        ValueError: 87,  # map to invalid parameter
+        RuntimeError: 1,
+    }
+
+    # Handle SystemExit robustly
+    if isinstance(exc, SystemExit):
+        code = getattr(exc, "code", None)
+        if isinstance(code, int):
+            return code
+        if code is None:
+            return 0
+        try:
+            return int(str(code))
+        except Exception:
+            return 1
+
+    # At this point, if a sysexits mapping is requested, apply it
+    if config.exit_code_style == "sysexits":
+        return _sysexits_mapping(exc)
+
+    if os.name == "posix":
+        exceptions = posix_exceptions
+    else:
+        exceptions = windows_exceptions
+
+    # Handle all other Exceptions
+    for exception in exceptions:
+        if isinstance(exc, exception):
+            return exceptions[exception]
+
+    # this should never happen
+    return 1
+
+
+def _sysexits_mapping(exc: BaseException) -> int:
+    """Map common exceptions to sysexits(3) style codes.
+
+    EX_USAGE(64), EX_NOINPUT(66), EX_NOPERM(77), EX_IOERR(74)
+    Defaults to 1 if no good fit is found.
+    """
+    result: int
+    if isinstance(exc, SystemExit):
+        try:
+            result = int(exc.code)  # type: ignore[attr-defined]
+        except Exception:
+            result = 1
+    elif isinstance(exc, KeyboardInterrupt):
+        result = 130
+    elif isinstance(exc, subprocess.CalledProcessError):
+        try:
+            result = int(exc.returncode)
+        except Exception:
+            result = 1
+    elif isinstance(exc, BrokenPipeError):
+        # Broken pipe often considered benign; keep configured behavior
+        result = int(config.broken_pipe_exit_code)
+    elif isinstance(exc, (TypeError, ValueError)):
+        result = 64  # EX_USAGE
+    elif isinstance(exc, FileNotFoundError):
+        result = 66  # EX_NOINPUT
+    elif isinstance(exc, PermissionError):
+        result = 77  # EX_NOPERM
+    elif isinstance(exc, (OSError, IOError)):
+        result = 74  # EX_IOERR
+    else:
+        result = 1
+    return result
+
+
+def print_exception_message(trace_back: bool = config.traceback, length_limit: int = 500, stream: Optional[TextIO] = None) -> None:
+    """
+    Prints the Exception Message to stderr. If trace_back is True, it also prints the traceback information.
+    If the exception has stdout, stderr attributes (like subprocess.CalledProcessError), those will also be printed.
+
+    Parameters
+    ----------
+    trace_back : bool, optional
+        Whether to print traceback information. Default is False.
+    length_limit : int, optional
+        Maximum length of the exception message to be printed. Default is 500.
+    stream : Optional[TextIO], optional
+        The stream to print to. Default is sys.stderr.
+
+    Examples
+    --------
+
+    >>> # test with exc_info = None
+    >>> print_exception_message()
+
+    >>> # test with exc_info
+    >>> try:
+    ...     raise FileNotFoundError('unknown_command_test1')
+    ... except Exception:       # noqa
+    ...     print_exception_message(True, length_limit=15, stream=sys.stdout)
+    ...     print_exception_message(False, stream=sys.stdout)
+    ...     print_exception_message(True, stream=sys.stdout)
+    Traceback Info...
+
+    >>> # test with subprocess to get stdout, stderr
+    >>> import subprocess
+    >>> try:
+    ...     discard=subprocess.run('unknown_command_test2_this_should_fail', shell=True, check=True)
+    ... except subprocess.CalledProcessError:
+    ...     print_exception_message(False, stream=sys.stdout)
+    ...     print_exception_message(True, stream=sys.stdout)
+    ...     print_exception_message(True, stream=sys.stdout)
+    CalledProcessError...
+
+    """
+    flush_streams()
+
+    if stream is None:
+        stream = sys.stderr
+
+    exc_info = sys.exc_info()[1]  # Get the current exception
+    if exc_info is not None:
+        exc_info_type = type(exc_info).__name__
+        exc_info_msg = f"{exc_info_type}: {str(exc_info)}"
+
+        # Print traceback if trace_back is True
+        if trace_back:
+            exc_info_msg = f"Traceback Information:\n{traceback.format_exc()}"
+
+        # If message exceeds length limit, truncate it
+        if len(exc_info_msg) > length_limit:
+            exc_info_msg = f"{exc_info_msg[:length_limit]} ...[TRUNCATED at {length_limit} characters]"
+
+        # Print stdout/stderr if they exist in the exception
+        _print_output(exc_info, "stdout", stream)
+        _print_output(exc_info, "stderr", stream)
+
+        # Print the exception message
+        print(exc_info_msg, file=stream)
+        flush_streams()
+
+
+def _print_output(exc_info: Any, attr: str, stream: Optional[TextIO] = None) -> None:
+    """
+    Helper function to print an attribute (stdout, stderr) of the exc_info if it exists.
+
+    Parameters
+    ----------
+    exc_info : Any
+        The exception object that may contain stdout or stderr.
+    attr : str
+        The attribute name ('stdout' or 'stderr').
+    stream : Optional[TextIO]
+        The stream to print to. Default is sys.stderr.
+
+    >>> class ExcInfo(object):
+    ...    pass
+
+    >>> my_exc_info = ExcInfo()
+
+    >>> # test no stdout attribute
+    >>> _print_output(my_exc_info, 'stdout')
+
+    >>> # test stdout=None
+    >>> my_exc_info.stdout=None
+    >>> _print_output(my_exc_info, 'stdout')
+
+    >>> # test stdout
+    >>> my_exc_info.stdout=b'test'
+    >>> _print_output(my_exc_info, 'stdout', stream=sys.stdout)
+    STDOUT: test
+
+    >>> my_exc_info = ExcInfo()
+
+    >>> # test no stderr attribute
+    >>> _print_output(my_exc_info, 'stderr')
+
+    >>> # test stderr=None
+    >>> my_exc_info.stderr=None
+    >>> _print_output(my_exc_info, 'stderr')
+
+    >>> # test stderr
+    >>> my_exc_info.stderr=b'test'
+    >>> _print_output(my_exc_info, 'stderr', stream=sys.stdout)
+    STDERR: test
+
+    """
+    if stream is None:
+        stream = sys.stderr
+
+    if hasattr(exc_info, attr):
+        output = getattr(exc_info, attr)
+        if output is None:
+            return
+        text: Optional[str] = None
+        if isinstance(output, bytes):
+            try:
+                text = output.decode("utf-8", errors="replace")
+            except Exception:
+                text = None
+        elif isinstance(output, str):
+            text = output
+        if text is not None:
+            print(f"{attr.upper()}: {text}", file=stream)
+
+
+def flush_streams() -> None:
+    """
+    flush the streams - make sure the output is written early,
+    otherwise the output might be printed even after another CLI
+    command is launched
+
+
+    Examples
+    --------
+
+
+    >>> flush_streams()
+
+    """
+    try:
+        sys.stdout.flush()
+    except Exception:
+        pass
+    try:
+        sys.stderr.flush()
+    except Exception:
+        pass

lib_cli_exit_tools-1.0.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: lib_cli_exit_tools
+Version: 1.0.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
+Project-URL: Issues, https://github.com/bitranox/lib_cli_exit_tools/issues
+Author-email: bitranox <bitranox@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,click,errors,exit,signals
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: codecov>=2.1.13; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lib_cli_exit_tools
+
+<!-- Badges -->
+[![CI](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/codeql.yml/badge.svg)](https://github.com/bitranox/lib_cli_exit_tools/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Jupyter](https://img.shields.io/badge/Jupyter-Launch-orange?logo=jupyter)](https://mybinder.org/v2/gh/bitranox/lib_cli_exit_tools/HEAD?labpath=notebooks%2FQuickstart.ipynb)
+[![PyPI](https://img.shields.io/pypi/v/lib_cli_exit_tools.svg)](https://pypi.org/project/lib_cli_exit_tools/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/lib_cli_exit_tools.svg)](https://pypi.org/project/lib_cli_exit_tools/)
+[![Code Style: Ruff](https://img.shields.io/badge/Code%20Style-Ruff-46A3FF?logo=ruff&labelColor=000)](https://docs.astral.sh/ruff/)
+[![codecov](https://codecov.io/gh/bitranox/lib_cli_exit_tools/graph/badge.svg?token=z1D8JSjWEH)](https://codecov.io/gh/bitranox/lib_cli_exit_tools)
+[![Maintainability](https://qlty.sh/gh/bitranox/projects/lib_cli_exit_tools/maintainability.svg)](https://qlty.sh/gh/bitranox/projects/lib_cli_exit_tools)
+[![Known Vulnerabilities](https://snyk.io/test/github/bitranox/lib_cli_exit_tools/badge.svg)](https://snyk.io/test/github/bitranox/lib_cli_exit_tools)
+
+Small helpers for robust CLI exit handling:
+- Portable signal handling (SIGINT, SIGTERM/SIGBREAK)
+- Consistent exception → exit code mapping
+- Concise error printing with optional traceback and subprocess stdout/stderr capture
+
+## Install
+
+Pick one of the options below. All methods register the `lib_cli_exit_tools` and `cli-exit-tools` commands on your PATH.
+
+### 1) Standard virtualenv (pip)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
+pip install -e .[dev]       # dev install
+# or for runtime only:
+pip install .
+```
+
+### 2) Per-user (no venv)
+
+```bash
+pip install --user .
+```
+
+Note: respects PEP 668; avoid on system Python if “externally managed”. Ensure `~/.local/bin` (POSIX) is on PATH.
+
+### 3) pipx (isolated, recommended for end users)
+
+```bash
+pipx install .
+pipx upgrade lib_cli_exit_tools
+# From Git tag/commit:
+pipx install "git+https://github.com/bitranox/lib_cli_exit_tools@v0.1.0"
+```
+
+### 4) uv (fast installer/runner)
+
+```bash
+uv pip install -e .[dev]
+uv tool install .
+uvx lib_cli_exit_tools --help
+```
+
+### 5) From artifacts
+
+```bash
+python -m build
+pip install dist/lib_cli_exit_tools-*.whl
+pip install dist/lib_cli_exit_tools-*.tar.gz   # sdist
+```
+
+### 6) Poetry / PDM (project-managed envs)
+
+```bash
+# Poetry
+poetry add lib_cli_exit_tools     # as dependency
+poetry install                    # for local dev
+
+# PDM
+pdm add lib_cli_exit_tools
+pdm install
+```
+
+### 7) From Git via pip (CI-friendly)
+
+```bash
+pip install "git+https://github.com/bitranox/lib_cli_exit_tools@v0.1.0#egg=lib_cli_exit_tools"
+```
+
+### 8) Conda/mamba (optional)
+
+```bash
+mamba create -n cli-exit python=3.12 pip
+mamba activate cli-exit
+pip install .
+```
+
+### 9) System package managers (optional distribution)
+
+- Homebrew formula (macOS): `brew install lib_cli_exit_tools` (if published)
+- Nix: flake/package for reproducible installs
+- Deb/RPM via `fpm` for OS-native packages
+
+### Make Targets
+
+| Target            | Description                                                                                |
+|-------------------|--------------------------------------------------------------------------------------------|
+| `help`            | Show help                                                                                  |
+| `install`         | Install package editable                                                                   |
+| `dev`             | Install package with dev extras                                                            |
+| `test`            | Lint, type-check, run tests with coverage, upload to Codecov                               |
+| `run`             | Run module CLI (requires dev install or src on PYTHONPATH)                                 |
+| `version-current` | Print current version from pyproject.toml                                                  |
+| `bump`            | Bump version: VERSION=X.Y.Z or PART=major                                                  |minor|patch (default: patch); updates pyproject.toml and CHANGELOG.md |
+| `bump-patch`      | Bump patch version (X.Y.Z -> X.Y.(Z+1))                                                    |
+| `bump-minor`      | Bump minor version (X.Y.Z -> X.(Y+1).0)                                                    |
+| `bump-major`      | Bump major version ((X+1).0.0)                                                             |
+| `clean`           | Remove caches, build artifacts, and coverage                                               |
+| `push`            | Commit all changes once and push to GitHub (no CI monitoring)                              |
+| `build`           | Build wheel/sdist and attempt conda, brew, and nix builds (auto-installs tools if missing) |
+
+#### Target Details
+
+- `test`: single entry point for local CI — runs ruff lint + format check, pyright, pytest (including doctests) with coverage (enabled by default), and uploads coverage to Codecov if configured (reads `.env`).
+- Auto‑bootstrap: `make test` will try to install dev tools (`pip install -e .[dev]`) if `ruff`/`pyright`/`pytest` are missing. Set `SKIP_BOOTSTRAP=1` to skip this behavior.
+- `build`: convenient builder — creates Python wheel/sdist, then attempts Conda, Homebrew, and Nix builds. It auto‑installs missing tools (Miniforge, Homebrew, Nix) when needed.
+- `install`/`dev`/`user-install`: common install flows for editable or per‑user installs.
+- `version-current`: prints current version from `pyproject.toml`.
+- `bump`: updates `pyproject.toml` version and inserts a new section in `CHANGELOG.md`. Use `VERSION=X.Y.Z make bump` or `make bump-minor`/`bump-major`/`bump-patch`.
+- `pipx-*` and `uv-*`: isolated CLI installations for end users and fast developer tooling.
+- `which-cmd`/`verify-install`: quick diagnostics to ensure the command is on PATH.
+
+## Usage
+
+Console script:
+
+```bash
+# After install (pip/pipx/uv tool)
+lib_cli_exit_tools --help
+cli-exit-tools --help  # alias
+lib_cli_exit_tools info
+```
+
+Library:
+
+```python
+import lib_cli_exit_tools
+
+lib_cli_exit_tools.config.traceback = False  # show short messages
+try:
+    raise FileNotFoundError("missing.txt")
+except Exception as e:
+    code = lib_cli_exit_tools.get_system_exit_code(e)   # 2 on POSIX
+    lib_cli_exit_tools.print_exception_message()        # prints: FileNotFoundError: missing.txt
+    raise SystemExit(code)
+```
+
+Command names registered on install
+- lib_cli_exit_tools (default)
+- cli-exit-tools (alias)
+- python -m lib_cli_exit_tools (module entry)
+
+If you installed with --user or in a venv, make sure the corresponding bin directory is on PATH:
+- Linux/macOS venv: .venv/bin
+- Linux/macOS user: ~/.local/bin
+- Windows venv: .venv\Scripts
+- Windows user: %APPDATA%\Python\PythonXY\Scripts
+
+## Exit Codes
+
+- SIGINT → 130, SIGTERM → 143 (POSIX), SIGBREAK → 149 (Windows)
+- SystemExit(n) → n
+- Common exceptions map to POSIX/Windows codes (FileNotFoundError, PermissionError, ValueError, etc.)
+
+### Broken pipe behavior
+- Default: exit 141 quietly (128+SIGPIPE), no noisy error output.
+- Configure: `config.broken_pipe_exit_code = 0` to treat as benign truncation, or `32` (EPIPE).
+
+### Sysexits mode (optional)
+- Set `config.exit_code_style = "sysexits"` to map ValueError/TypeError → EX_USAGE(64),
+  FileNotFoundError → EX_NOINPUT(66), PermissionError → EX_NOPERM(77), generic OSError → EX_IOERR(74).
+
+## Development
+
+```bash
+make test                 # ruff + pyright + pytest + coverage (default ON)
+SKIP_BOOTSTRAP=1 make test  # skip auto-install of dev deps
+COVERAGE=off make test       # disable coverage locally
+COVERAGE=on make test        # force coverage and generate coverage.xml/codecov.xml
+```
+
+### Packaging sync (Conda/Brew/Nix)
+
+- `make test` and `make push` automatically align the packaging skeletons in `packaging/` with the current `pyproject.toml`:
+  - Conda: updates `{% set version = "X.Y.Z" %}` and both `python >=X.Y` constraints to match `requires-python`.
+  - Homebrew: updates the source URL tag to `vX.Y.Z` and sets `depends_on "python@X.Y"` to match `requires-python`.
+  - Nix: updates the package `version`, example `rev = "vX.Y.Z"`, and switches `pkgs.pythonXYZPackages` / `pkgs.pythonXYZ` to match the minimum Python version from `requires-python`.
+
+- To run just the sync without bumping versions: `python tools/bump_version.py --sync-packaging`.
+
+- On release tags (`v*.*.*`), CI validates that packaging files are consistent with `pyproject.toml` and will fail if they drift.
+
+## Versioning & Metadata
+
+- Single source of truth for package metadata is `pyproject.toml` (`[project]`).
+- The library reads its own installed metadata at runtime via `importlib.metadata` (see `src/lib_cli_exit_tools/__init__conf__.py`).
+- Do not duplicate the version in code; bump only `pyproject.toml` and update `CHANGELOG.md`.
+- Console script name is discovered from entry points; defaults to `lib_cli_exit_tools`.
+
+## Packaging Skeletons
+
+Starter files for package managers live under `packaging/`:
+
+- Conda: `packaging/conda/recipe/meta.yaml` (update version + sha256)
+- Homebrew: `packaging/brew/Formula/lib-cli-exit-tools.rb` (fill sha256 and vendored resources)
+- Nix: `packaging/nix/flake.nix` (use working tree or pin to GitHub rev with sha256)
+
+These are templates; fill placeholders (e.g., sha256) before publishing. Version and Python constraints are auto-synced from `pyproject.toml` by `make test`/`make push` and during version bumps.
+
+## CI & Publishing
+
+GitHub Actions workflows are included:
+
+- `.github/workflows/ci.yml` — lint/type/test, build wheel/sdist, verify pipx and uv installs, Nix and Conda builds (CI-only; no local install required).
+- `.github/workflows/release.yml` — on tags `v*.*.*`, builds artifacts and publishes to PyPI when `PYPI_API_TOKEN` secret is set.
+
+To publish a release:
+1. Bump `pyproject.toml` version and update `CHANGELOG.md`.
+2. Tag the commit (`git tag v0.1.1 && git push --tags`).
+3. Ensure `PYPI_API_TOKEN` secret is configured in the repo.
+4. Release workflow uploads wheel/sdist to PyPI.
+
+Conda/Homebrew/Nix: use files in `packaging/` to submit to their ecosystems. CI also attempts builds to validate recipes, but does not publish automatically.
+
+### Local Codecov uploads
+
+- `make test` (with coverage enabled) generates `coverage.xml` and `codecov.xml`, then attempts to upload via the Codecov CLI or the bash uploader.
+- For private repos, set `CODECOV_TOKEN` (see `.env.example`) or export it in your shell.
+- For public repos, a token is typically not required.
+
+## License
+
+MIT

lib_cli_exit_tools-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+lib_cli_exit_tools/__init__.py,sha256=bmWORhmUzMCxixZyY6kLItgZKNshEO7dW0lzcKdQv88,267
+lib_cli_exit_tools/__init__conf__.py,sha256=0yzJsfOvRnei1f8VuQXeAkQrNNm-OP-RW41jD_RE9oY,3311
+lib_cli_exit_tools/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+lib_cli_exit_tools/cli.py,sha256=E6oN628_Ej43vgTwjCsepUTyeER_6l21G2O6ve-rAiM,4322
+lib_cli_exit_tools/lib_cli_exit_tools.py,sha256=XAm3v4tGZViaF7uzG3rgVo_RnZn8JvkP8yZ18qJRRE4,10659
+lib_cli_exit_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lib_cli_exit_tools-1.0.0.dist-info/METADATA,sha256=GIp020qyvgnjvjTQZVtILVSlYe4dEWo_FxNT9O0ZC7I,12173
+lib_cli_exit_tools-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lib_cli_exit_tools-1.0.0.dist-info/entry_points.txt,sha256=8R-_3UT0KcQ7HQ7idDx6rlG77GhHb0E2N5QnN41dj-M,161
+lib_cli_exit_tools-1.0.0.dist-info/licenses/LICENSE,sha256=6s9SL2InRrwynPjJYiER7ONHBshbGj_yC5EBzfo7l9I,1072
+lib_cli_exit_tools-1.0.0.dist-info/RECORD,,

lib_cli_exit_tools-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lib_cli_exit_tools-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+cli-exit-tools = lib_cli_exit_tools.cli:main
+lib-cli-exit-tools = lib_cli_exit_tools.cli:main
+lib_cli_exit_tools = lib_cli_exit_tools.cli:main

lib_cli_exit_tools-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Robert Nowotny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+