lib-cli-exit-tools 2.2.0__tar.gz → 2.2.1__tar.gz

{lib_cli_exit_tools-2.2.0 → lib_cli_exit_tools-2.2.1}/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [2.2.1] - 2025-12-11
+
+### Added
+- "Why lib_cli_exit_tools?" section in README highlighting five key benefits: correct exit codes, portable signal handling, clean error output, pipeline-friendly behaviour, and zero boilerplate.
+- CLI Reference section in README with global options table and command descriptions.
+
+### Changed
+- Replaced all `--verbose` references in README examples with `--traceback` to match actual CLI option.
+- Updated `cli_session` documentation to include missing `restore` parameter.
+- Converted config field reference to table format with types and defaults.
+
+### Fixed
+- Added missing `traceback_force_color` configuration field to documentation.
+
 ## [2.2.0] - 2025-12-11
 
 ### Changed

{lib_cli_exit_tools-2.2.0 → lib_cli_exit_tools-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lib_cli_exit_tools
-Version: 2.2.0
+Version: 2.2.1
 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
@@ -23,7 +23,7 @@ Requires-Dist: build>=1.3.0; extra == 'dev'
 Requires-Dist: codecov-cli>=11.2.6; extra == 'dev'
 Requires-Dist: coverage[toml]>=7.13.0; extra == 'dev'
 Requires-Dist: hypothesis>=6.148.7; extra == 'dev'
-Requires-Dist: import-linter>=2.8; extra == 'dev'
+Requires-Dist: import-linter>=2.9; extra == 'dev'
 Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
 Requires-Dist: pyright>=1.1.407; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
@@ -55,6 +55,20 @@ Small helpers for robust CLI exit handling:
 - Consistent exception → exit code mapping
 - Concise error printing with optional traceback and subprocess stdout/stderr capture
 
+## Why lib_cli_exit_tools?
+
+Building CLI applications that behave correctly in shell pipelines, CI/CD systems, and across platforms is surprisingly tricky. This library solves five common pain points:
+
+1. **Correct Exit Codes** — Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` — matching shell conventions without manual bookkeeping.
+
+2. **Portable Signal Handling** — SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
+
+3. **Clean Error Output** — Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging — no code changes required.
+
+4. **Pipeline-Friendly** — `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
+
+5. **Zero Boilerplate** — Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
+
 ## Install
 
 Requires Python 3.10 or newer.
@@ -77,6 +91,35 @@ lib-cli-exit-tools fail  # intentionally trigger RuntimeError to test error path
 # Aliases are also generated: `cli-exit-tools`, `lib_cli_exit_tools`
 ```
 
+## CLI Reference
+
+The library installs three equivalent console scripts: `lib-cli-exit-tools` (primary), `cli-exit-tools`, and `lib_cli_exit_tools`. All invoke `lib_cli_exit_tools.cli:main`.
+
+### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--traceback` / `--no-traceback` | `False` | Show full Python traceback on errors |
+| `--version` | — | Show program version and exit |
+| `-h`, `--help` | — | Show help message and exit |
+
+### Commands
+
+#### `info`
+Display package metadata (name, version, homepage, author).
+
+```bash
+lib-cli-exit-tools info
+```
+
+#### `fail`
+Intentionally raise `RuntimeError('i should fail')` to validate error handling paths.
+
+```bash
+lib-cli-exit-tools fail
+lib-cli-exit-tools --traceback fail  # show full traceback
+```
+
 ### Examples
 
 The snippets below move from a minimal “hello world” through a production-ready
@@ -109,7 +152,7 @@ Run it with:
 python hello.py
 ```
 
-#### 2. Verbose-mode helper using `cli_session`
+#### 2. Traceback-mode helper using `cli_session`
 
 ```python
 from __future__ import annotations
@@ -120,22 +163,22 @@ from lib_cli_exit_tools import cli_session, run_cli
 
 
 @click.command()
-@click.option("--verbose", is_flag=True, help="Show full tracebacks on error")
-def cli(verbose: bool) -> int:
-    with cli_session(overrides={"traceback": verbose}) as execute:
+@click.option("--traceback", is_flag=True, help="Show full tracebacks on error")
+def cli(traceback: bool) -> int:
+    with cli_session(overrides={"traceback": traceback}) as execute:
         return execute(failable, argv=[])
 
 
 @click.command()
 def failable() -> None:
-    raise RuntimeError("toggle --verbose to see the full traceback")
+    raise RuntimeError("toggle --traceback to see the full traceback")
 
 
 if __name__ == "__main__":
     raise SystemExit(run_cli(cli))
 ```
 
-Invoking `python cli.py --verbose` enables coloured tracebacks just for that
+Invoking `python cli.py --traceback` enables coloured tracebacks just for that
 run and resets the configuration afterwards.
 
 #### 3. Full-featured multi-command CLI
@@ -154,21 +197,21 @@ from lib_cli_exit_tools import SignalSpec, cli_session, default_signal_specs
 @dataclass(slots=True)
 class Settings:
     pretty: bool
-    verbose: bool
+    traceback: bool
 
 
 @click.group()
 @click.option("--pretty/--no-pretty", default=True)
-@click.option("--verbose", is_flag=True)
+@click.option("--traceback", is_flag=True, help="Show full tracebacks on error")
 @click.pass_context
-def cli(ctx: click.Context, pretty: bool, verbose: bool) -> None:
-    ctx.obj = Settings(pretty=pretty, verbose=verbose)
+def cli(ctx: click.Context, pretty: bool, traceback: bool) -> None:
+    ctx.obj = Settings(pretty=pretty, traceback=traceback)
 
 
 @cli.command()
 @click.pass_obj
 def info(settings: Settings) -> None:
-    payload = {"verbose": settings.verbose, "pretty": settings.pretty}
+    payload = {"traceback": settings.traceback, "pretty": settings.pretty}
     click.echo(json.dumps(payload, indent=2 if settings.pretty else None))
 
 
@@ -308,9 +351,12 @@ config.broken_pipe_exit_code = 0     # treat BrokenPipeError as a benign truncat
 
 Field reference:
 
-- `traceback` (`bool`, default `False`): when `True`, `handle_cli_exception` renders a full Rich traceback to stderr and then returns a non-zero exit code. The original exception is not re-raised; callers should rely on the rendered output and returned status. The bundled CLI toggles this via `--traceback/--no-traceback`.
-- `exit_code_style` (`"errno"` or `"sysexits"`, default `"errno"`): controls the numeric mapping produced by `get_system_exit_code`. `errno` returns POSIX/Windows-style codes (e.g., `FileNotFoundError → 2`, `SIGINT → 130`); `sysexits` returns BSD-style semantic codes (`EX_NOINPUT`, `EX_USAGE`, etc.).
-- `broken_pipe_exit_code` (`int`, default `141`): overrides the exit status when a `BrokenPipeError` is raised (the default mirrors `128 + SIGPIPE`). Set this to `0` if you want truncation to be treated as success.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `traceback` | `bool` | `False` | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`. |
+| `exit_code_style` | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
+| `broken_pipe_exit_code` | `int` | `141` | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success. |
+| `traceback_force_color` | `bool` | `False` | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs. |
 
 Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
 
@@ -397,22 +443,25 @@ Parameters:
 - `exception_handler`: Callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
 - `signal_installer`: Callable mirroring ``install_signal_handlers`` for embedding scenarios.
 
-### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None)`
-Context manager that snapshots :mod:`lib_cli_exit_tools.config`, optionally
+### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None, restore=True)`
+Context manager that snapshots `lib_cli_exit_tools.config`, optionally
 applies temporary overrides, and yields a callable compatible with
-``run_cli``.
+`run_cli`.
 
 Parameters:
-- `summary_limit`: Character budget when tracebacks are disabled.
-- `verbose_limit`: Character budget when tracebacks are enabled.
-- `overrides`: Mapping of configuration field/value pairs applied during the session.
+- `summary_limit` (`int`, default `500`): Character budget when tracebacks are disabled.
+- `verbose_limit` (`int`, default `10_000`): Character budget when tracebacks are enabled.
+- `overrides` (`Mapping[str, object] | None`, default `None`): Mapping of configuration field/value pairs applied during the session. When `traceback` is supplied and `traceback_force_color` is omitted, colour output is automatically forced.
+- `restore` (`bool`, default `True`): When `True`, configuration state is restored after the session. Set to `False` to leave overrides in place once the context exits.
 
 Use it to restore configuration automatically—even when the wrapped command
 raises:
 
 ```python
+from lib_cli_exit_tools import cli_session
+
 with cli_session(overrides={"traceback": True}) as run:
-    exit_code = run(click_command, argv=args)
+    exit_code = run(my_click_command, argv=["--help"])
 ```
 
 ### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`

{lib_cli_exit_tools-2.2.0 → lib_cli_exit_tools-2.2.1}/README.md

@@ -18,6 +18,20 @@ Small helpers for robust CLI exit handling:
 - Consistent exception → exit code mapping
 - Concise error printing with optional traceback and subprocess stdout/stderr capture
 
+## Why lib_cli_exit_tools?
+
+Building CLI applications that behave correctly in shell pipelines, CI/CD systems, and across platforms is surprisingly tricky. This library solves five common pain points:
+
+1. **Correct Exit Codes** — Exceptions are automatically mapped to platform-appropriate exit codes (POSIX errno or BSD sysexits). `FileNotFoundError` returns `2`, `PermissionError` returns `13` on POSIX, and `KeyboardInterrupt` returns `130` — matching shell conventions without manual bookkeeping.
+
+2. **Portable Signal Handling** — SIGINT (Ctrl+C), SIGTERM, and Windows SIGBREAK are translated into structured Python exceptions with deterministic exit codes. Your CLI behaves consistently whether terminated by a user, a process manager, or a CI runner.
+
+3. **Clean Error Output** — Uncaught exceptions produce concise, coloured error messages by default. Toggle `--traceback` for full Rich-formatted stack traces during debugging — no code changes required.
+
+4. **Pipeline-Friendly** — `BrokenPipeError` is handled gracefully (exit 141 by default, matching `128 + SIGPIPE`), so piping output to `head` or other truncating tools doesn't produce noisy tracebacks.
+
+5. **Zero Boilerplate** — Wrap any Click command with `run_cli()` and get signal handling, exit-code translation, and stream flushing in one call. Configuration is centralised and test-friendly via context managers.
+
 ## Install
 
 Requires Python 3.10 or newer.
@@ -40,6 +54,35 @@ lib-cli-exit-tools fail  # intentionally trigger RuntimeError to test error path
 # Aliases are also generated: `cli-exit-tools`, `lib_cli_exit_tools`
 ```
 
+## CLI Reference
+
+The library installs three equivalent console scripts: `lib-cli-exit-tools` (primary), `cli-exit-tools`, and `lib_cli_exit_tools`. All invoke `lib_cli_exit_tools.cli:main`.
+
+### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--traceback` / `--no-traceback` | `False` | Show full Python traceback on errors |
+| `--version` | — | Show program version and exit |
+| `-h`, `--help` | — | Show help message and exit |
+
+### Commands
+
+#### `info`
+Display package metadata (name, version, homepage, author).
+
+```bash
+lib-cli-exit-tools info
+```
+
+#### `fail`
+Intentionally raise `RuntimeError('i should fail')` to validate error handling paths.
+
+```bash
+lib-cli-exit-tools fail
+lib-cli-exit-tools --traceback fail  # show full traceback
+```
+
 ### Examples
 
 The snippets below move from a minimal “hello world” through a production-ready
@@ -72,7 +115,7 @@ Run it with:
 python hello.py
 ```
 
-#### 2. Verbose-mode helper using `cli_session`
+#### 2. Traceback-mode helper using `cli_session`
 
 ```python
 from __future__ import annotations
@@ -83,22 +126,22 @@ from lib_cli_exit_tools import cli_session, run_cli
 
 
 @click.command()
-@click.option("--verbose", is_flag=True, help="Show full tracebacks on error")
-def cli(verbose: bool) -> int:
-    with cli_session(overrides={"traceback": verbose}) as execute:
+@click.option("--traceback", is_flag=True, help="Show full tracebacks on error")
+def cli(traceback: bool) -> int:
+    with cli_session(overrides={"traceback": traceback}) as execute:
         return execute(failable, argv=[])
 
 
 @click.command()
 def failable() -> None:
-    raise RuntimeError("toggle --verbose to see the full traceback")
+    raise RuntimeError("toggle --traceback to see the full traceback")
 
 
 if __name__ == "__main__":
     raise SystemExit(run_cli(cli))
 ```
 
-Invoking `python cli.py --verbose` enables coloured tracebacks just for that
+Invoking `python cli.py --traceback` enables coloured tracebacks just for that
 run and resets the configuration afterwards.
 
 #### 3. Full-featured multi-command CLI
@@ -117,21 +160,21 @@ from lib_cli_exit_tools import SignalSpec, cli_session, default_signal_specs
 @dataclass(slots=True)
 class Settings:
     pretty: bool
-    verbose: bool
+    traceback: bool
 
 
 @click.group()
 @click.option("--pretty/--no-pretty", default=True)
-@click.option("--verbose", is_flag=True)
+@click.option("--traceback", is_flag=True, help="Show full tracebacks on error")
 @click.pass_context
-def cli(ctx: click.Context, pretty: bool, verbose: bool) -> None:
-    ctx.obj = Settings(pretty=pretty, verbose=verbose)
+def cli(ctx: click.Context, pretty: bool, traceback: bool) -> None:
+    ctx.obj = Settings(pretty=pretty, traceback=traceback)
 
 
 @cli.command()
 @click.pass_obj
 def info(settings: Settings) -> None:
-    payload = {"verbose": settings.verbose, "pretty": settings.pretty}
+    payload = {"traceback": settings.traceback, "pretty": settings.pretty}
     click.echo(json.dumps(payload, indent=2 if settings.pretty else None))
 
 
@@ -271,9 +314,12 @@ config.broken_pipe_exit_code = 0     # treat BrokenPipeError as a benign truncat
 
 Field reference:
 
-- `traceback` (`bool`, default `False`): when `True`, `handle_cli_exception` renders a full Rich traceback to stderr and then returns a non-zero exit code. The original exception is not re-raised; callers should rely on the rendered output and returned status. The bundled CLI toggles this via `--traceback/--no-traceback`.
-- `exit_code_style` (`"errno"` or `"sysexits"`, default `"errno"`): controls the numeric mapping produced by `get_system_exit_code`. `errno` returns POSIX/Windows-style codes (e.g., `FileNotFoundError → 2`, `SIGINT → 130`); `sysexits` returns BSD-style semantic codes (`EX_NOINPUT`, `EX_USAGE`, etc.).
-- `broken_pipe_exit_code` (`int`, default `141`): overrides the exit status when a `BrokenPipeError` is raised (the default mirrors `128 + SIGPIPE`). Set this to `0` if you want truncation to be treated as success.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `traceback` | `bool` | `False` | When `True`, `handle_cli_exception` renders a full Rich traceback to stderr. The bundled CLI toggles this via `--traceback/--no-traceback`. |
+| `exit_code_style` | `"errno"` \| `"sysexits"` | `"errno"` | Controls exit code mapping. `errno` returns POSIX/Windows-style codes; `sysexits` returns BSD-style semantic codes (EX_USAGE, EX_NOINPUT, etc.). |
+| `broken_pipe_exit_code` | `int` | `141` | Exit status for `BrokenPipeError` (default mirrors `128 + SIGPIPE`). Set to `0` to treat truncation as success. |
+| `traceback_force_color` | `bool` | `False` | Force Rich to emit ANSI-coloured tracebacks even when stderr is not a TTY. Useful for CI logs. |
 
 Remember that `config` is module-level—if you call the library from multiple threads or embed it in another CLI, configure it once during bootstrap before handing control to user code. When you need temporary overrides (for tests or nested CLIs), wrap the change with the built-in context manager so state is restored automatically:
 
@@ -360,22 +406,25 @@ Parameters:
 - `exception_handler`: Callable receiving the raised exception and returning an exit code; defaults to ``handle_cli_exception``.
 - `signal_installer`: Callable mirroring ``install_signal_handlers`` for embedding scenarios.
 
-### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None)`
-Context manager that snapshots :mod:`lib_cli_exit_tools.config`, optionally
+### `cli_session(*, summary_limit=500, verbose_limit=10_000, overrides=None, restore=True)`
+Context manager that snapshots `lib_cli_exit_tools.config`, optionally
 applies temporary overrides, and yields a callable compatible with
-``run_cli``.
+`run_cli`.
 
 Parameters:
-- `summary_limit`: Character budget when tracebacks are disabled.
-- `verbose_limit`: Character budget when tracebacks are enabled.
-- `overrides`: Mapping of configuration field/value pairs applied during the session.
+- `summary_limit` (`int`, default `500`): Character budget when tracebacks are disabled.
+- `verbose_limit` (`int`, default `10_000`): Character budget when tracebacks are enabled.
+- `overrides` (`Mapping[str, object] | None`, default `None`): Mapping of configuration field/value pairs applied during the session. When `traceback` is supplied and `traceback_force_color` is omitted, colour output is automatically forced.
+- `restore` (`bool`, default `True`): When `True`, configuration state is restored after the session. Set to `False` to leave overrides in place once the context exits.
 
 Use it to restore configuration automatically—even when the wrapped command
 raises:
 
 ```python
+from lib_cli_exit_tools import cli_session
+
 with cli_session(overrides={"traceback": True}) as run:
-    exit_code = run(click_command, argv=args)
+    exit_code = run(my_click_command, argv=["--help"])
 ```
 
 ### `handle_cli_exception(exc, *, signal_specs=None, echo=None) -> int`

{lib_cli_exit_tools-2.2.0 → lib_cli_exit_tools-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lib_cli_exit_tools"
-version = "2.2.0"
+version = "2.2.1"
 description = "CLI exit handling helpers: clean signals, exit codes, and error printing"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,7 +28,7 @@ dev = [
   "codecov-cli>=11.2.6",
   "coverage[toml]>=7.13.0",
   "hypothesis>=6.148.7",
-  "import-linter>=2.8",
+  "import-linter>=2.9",
   "bandit>=1.9.2",
   "pip-audit>=2.10.0",
   "pyright>=1.1.407",

{lib_cli_exit_tools-2.2.0 → lib_cli_exit_tools-2.2.1}/src/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.0"
+version = "2.2.1"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/lib_cli_exit_tools"
 #: Author attribution surfaced in CLI output.