lib-cli-exit-tools 1.2.0__tar.gz → 1.3.0__tar.gz

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [1.3.0] - 2025-09-25
+
+- colored traceback
+
 ## [1.2.0] - 2025-09-25
 
 - use rich-click instead of click, minor fixes

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 1.2.0
+Version: 1.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

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/docs/system-design/reference.md

@@ -138,9 +138,9 @@ The package is the core runtime library for handling CLI exits within the broade
 **Location:** `lib_cli_exit_tools/lib_cli_exit_tools.py`
 
 #### Function: print_exception_message
-**Purpose:** Display the current exception message (and optional traceback) with output truncation safeguards.  
+**Purpose:** Display the current exception message (and optional rich-formatted traceback) with output truncation safeguards.  
 **Input:** `trace_back`, `length_limit`, optional `stream`.  
-**Output:** Writes formatted error details to the target stream; flushes stdout/stderr.  
+**Output:** Writes formatted error details to the target stream using a `rich` console and flushes stdout/stderr.  
 **Location:** `lib_cli_exit_tools/lib_cli_exit_tools.py`
 
 #### Function: _print_output

lib_cli_exit_tools-1.3.0/notebooks/Quickstart.ipynb

@@ -0,0 +1,209 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
+   "metadata": {},
+   "source": [
+    "# lib_cli_exit_tools Quickstart\n",
+    "\n",
+    "Use this notebook to install the package, explore the CLI, and observe how rich-formatted tracebacks behave when you enable debugging output.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "acae54e37e7d407bbb7b55eff062a284",
+   "metadata": {},
+   "source": [
+    "## 1) Install latest from GitHub (default)\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# update pip and setuptools\n",
+    "import sys\n",
+    "\n",
+    "!{sys.executable} -m pip install --upgrade pip\n",
+    "!{sys.executable} -m pip install --upgrade setuptools\n",
+    "\n",
+    "# install lib_cli_exit_tools from GitHub (default)\n",
+    "!{sys.executable} -m pip install --upgrade git+https://github.com/bitranox/lib_cli_exit_tools.git"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
+   "metadata": {},
+   "source": [
+    "## Or: Install from PyPI (alternative)\n",
+    "Uncomment and run the cell below if you prefer the PyPI release.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "72eea5119410473aa328ad9291626812",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# !{sys.executable} -m pip install --upgrade lib_cli_exit_tools\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8edb47106e1a46a883d545849b8ab81b",
+   "metadata": {},
+   "source": [
+    "## 2) CLI: version and help\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!lib_cli_exit_tools --version\n",
+    "!lib_cli_exit_tools --help\n",
+    "!lib_cli_exit_tools info"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
+   "metadata": {},
+   "source": [
+    "## 3) Demo command for failure handling\n",
+    "The helper below builds a tiny Click command that purposely raises an error so you can compare short messages with rich tracebacks.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7623eae2785240b9bd12b16a66d81610",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import click\n",
+    "from lib_cli_exit_tools.lib_cli_exit_tools import config, run_cli\n",
+    "\n",
+    "\n",
+    "@click.command()\n",
+    "def quickstart_fail() -> None:\n",
+    "    \"\"\"Raise a demo error to exercise lib_cli_exit_tools.\"\"\"\n",
+    "    raise RuntimeError(\"demo failure from Quickstart\")\n",
+    "\n",
+    "\n",
+    "def run_quickstart_demo(traceback_enabled: bool) -> int:\n",
+    "    \"\"\"Execute the demo command with the desired traceback mode.\n",
+    "\n",
+    "    The helper keeps tests deterministic by disabling signal handlers\n",
+    "    in notebook contexts and resets global flags after execution.\n",
+    "    \"\"\"\n",
+    "\n",
+    "    original_flag = config.traceback\n",
+    "    config.traceback = traceback_enabled\n",
+    "    try:\n",
+    "        return run_cli(quickstart_fail, argv=[], install_signals=False)\n",
+    "    finally:\n",
+    "        config.traceback = original_flag"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7cdc8c89c7104fffa095e18ddfef8986",
+   "metadata": {},
+   "source": [
+    "## 4) CLI failure with short message (default)\n",
+    "Tracebacks are suppressed by default; the CLI emits a concise summary and returns a deterministic exit code.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b118ea5561624da68c537baed56e602f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "exit_code = run_quickstart_demo(False)\n",
+    "print(f\"Exit code: {exit_code}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "938c804e27f84196a10c8828c723f798",
+   "metadata": {},
+   "source": [
+    "## 5) CLI failure with rich traceback\n",
+    "Enable tracebacks to surface a full Rich-formatted stack trace for debugging.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "504fb2a444614c0babb325280ed9130a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import lib_cli_exit_tools\n",
+    "\n",
+    "try:\n",
+    "    run_quickstart_demo(True)\n",
+    "except RuntimeError:\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "59bbdb311c014d738909a11f9e486628",
+   "metadata": {},
+   "source": [
+    "## 6) Library usage: exit codes and traceback formatting\n",
+    "Use the functional API to translate exceptions into exit codes and to opt in to rich tracebacks programmatically.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b43b363d81ae4b689946ece5c682cd59",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import lib_cli_exit_tools\n",
+    "\n",
+    "# Short message (default)\n",
+    "try:\n",
+    "    raise FileNotFoundError(\"missing.txt\")\n",
+    "except Exception as exc:\n",
+    "    exit_code = lib_cli_exit_tools.get_system_exit_code(exc)\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=False)\n",
+    "    print(f\"Exit code would be: {exit_code}\")\n",
+    "\n",
+    "# Rich traceback\n",
+    "try:\n",
+    "    raise ValueError(\"boom\")\n",
+    "except Exception:\n",
+    "    lib_cli_exit_tools.print_exception_message(trace_back=True)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/packaging/brew/Formula/lib-cli-exit-tools.rb

@@ -3,7 +3,7 @@ class LibCliExitTools < Formula
 
   desc "CLI exit handling helpers: clean signals, exit codes, and error printing"
   homepage "https://github.com/bitranox/lib_cli_exit_tools"
-  url "https://github.com/bitranox/lib_cli_exit_tools/archive/refs/tags/v1.2.0.tar.gz"
+  url "https://github.com/bitranox/lib_cli_exit_tools/archive/refs/tags/v1.3.0.tar.gz"
 k3cc316e7d0b09dd79e617cb3e91b14ee414b7e6695b108a326d9d3ccd08dd9"
   license "MIT"
 
@@ -17,7 +17,7 @@ k3cc316e7d0b09dd79e617cb3e91b14ee414b7e6695b108a326d9d3ccd08dd9"
 
   resource "rich-click" do
     url "https://files.pythonhosted.org/packages/29/c2/f08b5e7c1a33af8a115be640aa0796ba01c4732696da6d2254391376b314/rich_click-1.9.1.tar.gz"
-    sha256 "4f2620589d7287f86265432e6a909de4f281de909fe68d8c835fbba49265d268"
+ab87be0f5a4c171b43778922b5ed1f99611a0db5a4bf4d0f36770c18ef848d4"
   end
 
   def install

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/packaging/conda/recipe/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "lib_cli_exit_tools" %}
-{% set version = "1.2.0" %}
+{% set version = "1.3.0" %}
 
 package:
   name: {{ name|lower }}

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/packaging/nix/flake.nix

@@ -44,7 +44,7 @@
       {
         packages.default = pypkgs.buildPythonPackage {
           pname = "lib_cli_exit_tools";
-          version = "1.2.0";
+          version = "1.3.0";
           pyproject = true;
           src = ../..;
           nativeBuildInputs = [ hatchlingVendor ];

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "1.2.0"
+version = "1.3.0"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/src/lib_cli_exit_tools/lib_cli_exit_tools.py

@@ -25,12 +25,15 @@ import os
 import signal
 import subprocess
 import sys
-import traceback
 from dataclasses import dataclass
 from types import FrameType
 from typing import Any, Callable, List, Literal, Optional, Protocol, Sequence, TextIO
 
 import rich_click as click
+from rich_click import rich_click as rich_config
+from rich.console import Console
+from rich.text import Text
+from rich.traceback import Traceback
 
 __all__ = [
     "config",
@@ -559,6 +562,33 @@ def _sysexits_mapping(exc: BaseException) -> int:
     return 1
 
 
+def _build_console(stream: Optional[TextIO] = None) -> Console:
+    """Construct a Rich console that mirrors rich-click global settings.
+
+    Why:
+        Avoid duplicating console configuration whenever we need to emit
+        coloured output, ensuring help and error styling stay consistent.
+    Parameters:
+        stream: Optional target stream; defaults to :data:`sys.stderr`.
+    Returns:
+        Configured :class:`rich.console.Console` instance.
+    Side Effects:
+        None.
+    Examples:
+        >>> console = _build_console()
+        >>> isinstance(console, Console)
+        True
+    """
+
+    target_stream = stream or sys.stderr
+    return Console(
+        file=target_stream,
+        force_terminal=rich_config.FORCE_TERMINAL,
+        color_system=rich_config.COLOR_SYSTEM,
+        soft_wrap=True,
+    )
+
+
 def print_exception_message(
     trace_back: bool = config.traceback,
     length_limit: int = 500,
@@ -568,11 +598,12 @@ def print_exception_message(
 
     Why:
         Provide consistent, truncated error output when tracebacks are
-        suppressed. This keeps CLI UX tidy while still surfacing useful
-        information to the user.
+        suppressed while presenting syntax-highlighted tracebacks for
+        debugging when requested.
     Parameters:
-        trace_back: When ``True`` append the full traceback to the message.
-        length_limit: Maximum number of characters to emit.
+        trace_back: When ``True`` render a Rich traceback; otherwise emit a
+            single-line summary in red.
+        length_limit: Maximum number of characters to emit for summary output.
         stream: Target text stream; defaults to stderr.
     Returns:
         ``None``.
@@ -592,25 +623,36 @@ def print_exception_message(
 
     flush_streams()
 
-    if stream is None:
-        stream = sys.stderr
+    target_stream = stream or sys.stderr
 
     exc_info = sys.exc_info()[1]
     if exc_info is None:
         return
 
-    if trace_back:
-        exc_info_msg = "Traceback Information:\n" + traceback.format_exc()
-    else:
-        exc_info_msg = f"{type(exc_info).__name__}: {exc_info}"
+    _print_output(exc_info, "stdout", target_stream)
+    _print_output(exc_info, "stderr", target_stream)
 
-    if len(exc_info_msg) > length_limit:
-        exc_info_msg = f"{exc_info_msg[:length_limit]} ...[TRUNCATED at {length_limit} characters]"
+    console = _build_console(target_stream)
 
-    _print_output(exc_info, "stdout", stream)
-    _print_output(exc_info, "stderr", stream)
+    if trace_back:
+        tb_renderable = Traceback.from_exception(
+            type(exc_info),
+            exc_info,
+            exc_info.__traceback__,
+            show_locals=False,
+        )
+        console.print(tb_renderable)
+    else:
+        message = Text(
+            f"{type(exc_info).__name__}: {exc_info}",
+            style="bold red",
+        )
+        if len(message.plain) > length_limit:
+            truncated = f"{message.plain[:length_limit]} ... [TRUNCATED at {length_limit} characters]"
+            message = Text(truncated, style="bold red")
+        console.print(message)
 
-    print(exc_info_msg, file=stream)
+    console.file.flush()
     flush_streams()
 
 

{lib_cli_exit_tools-1.2.0 → lib_cli_exit_tools-1.3.0}/tests/test_lib_extra.py

@@ -52,7 +52,7 @@ def test_print_exception_message_traceback_and_truncate() -> None:
     except Exception:
         print_exception_message(True, length_limit=40, stream=buf)
     out = buf.getvalue()
-    assert "Traceback Information:" in out
+    assert "Traceback (most recent call last)" in out
 
     # Trigger truncation branch (traceback False) with tight limit
     buf = io.StringIO()

lib_cli_exit_tools-1.2.0/notebooks/Quickstart.ipynb

@@ -1,121 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "markdown",
-   "id": "intro",
-   "metadata": {},
-   "source": [
-    "# lib_cli_exit_tools Quickstart\n",
-    "\n",
-    "Install the package (from PyPI or GitHub), then try the CLI and API examples below."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "github-title",
-   "metadata": {},
-   "source": [
-    "## 1) Install latest from GitHub (default)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "github-install",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# update pip and setuptools\n",
-    "import sys\n",
-    "\n",
-    "!{sys.executable} -m pip install --upgrade pip\n",
-    "!{sys.executable} -m pip install --upgrade setuptools\n",
-    "\n",
-    "# install lib_cli_exit_tools from GitHub (default)\n",
-    "!{sys.executable} -m pip install --upgrade git+https://github.com/bitranox/lib_cli_exit_tools.git"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "pypi-title",
-   "metadata": {},
-   "source": [
-    "## Or: Install from PyPI (alternative)\n",
-    "Uncomment and run the cell below if you prefer the PyPI release."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "pypi-install",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# !{sys.executable} -m pip install --upgrade lib_cli_exit_tools\n"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "cli-title",
-   "metadata": {},
-   "source": [
-    "## 2) CLI: version and help"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cli-code",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "!lib_cli_exit_tools --version\n",
-    "!lib_cli_exit_tools --help\n",
-    "!lib_cli_exit_tools info"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "lib-title",
-   "metadata": {},
-   "source": [
-    "## 3) Library usage: map exceptions to exit codes"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "lib-code",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import lib_cli_exit_tools\n",
-    "\n",
-    "# show short messages\n",
-    "lib_cli_exit_tools.config.traceback = False\n",
-    "try:\n",
-    "    raise FileNotFoundError(\"missing.txt\")\n",
-    "except Exception as e:\n",
-    "    code = lib_cli_exit_tools.get_system_exit_code(e)  # 2 on POSIX\n",
-    "    lib_cli_exit_tools.print_exception_message()  # prints: FileNotFoundError: missing.txt\n",
-    "    # In a real CLI you might exit with the code.\n",
-    "    # raise SystemExit(code)\n",
-    "    # In this notebook we just display it to keep execution green.\n",
-    "    print(f\"Exit code would be: {code}\")"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "name": "python",
-   "version": "3"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}