Install & Compatibility
Where this runs
tested against v1.2.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.034s · 32.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.028s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cli_exit_tools
✓ from cli_exit_tools import cli_exit_tools
✗ from cli_exit_tools import print_exception_message
The core utilities like `print_exception_message` and `get_exit_code_from_exception` are part of the `cli_exit_tools` module within the `cli_exit_tools` package.
This quickstart demonstrates how to use `cli_exit_tools` to gracefully handle an exception within a simulated CLI task. It shows how to print a detailed exception message, including traceback, to `stderr` and obtain a proper exit code from the exception, which can then be used with `sys.exit()`.
import sys
from cli_exit_tools import cli_exit_tools
def run_cli_task():
"""Simulates a task in a CLI application that might raise an error."""
try:
# Simulate an operation that causes an error, e.g., division by zero
# Or an invalid type conversion
value = int("not_a_number")
print(f"Processed value: {value}")
return 0 # Success exit code
except Exception as e:
print(f"An unexpected error occurred: {e}", file=sys.stderr)
# Use cli_exit_tools to print detailed exception message and get an appropriate exit code
cli_exit_tools.print_exception_message(trace_back=True, stream=sys.stderr)
return cli_exit_tools.get_exit_code_from_exception(e)
if __name__ == "__main__":
# In a real CLI application, you would typically call sys.exit(exit_code)
exit_code = run_cli_task()
print(f"\nApplication finished with exit code: {exit_code}", file=sys.stderr)
# sys.exit(exit_code)
cli-exit-tools --version
Debug
Known issues
gotchaDefault traceback behavior might be unexpected. The `print_exception_message` function's `trace_back` parameter defaults to a value (often from an internal `config` object) that can be influenced by CLI options. Developers should explicitly set `trace_back=True` if they consistently want full tracebacks, or ensure their CLI configuration correctly controls this behavior, otherwise, tracebacks might be suppressed by default.fixExplicitly pass `trace_back=True` to `cli_exit_tools.print_exception_message()` if full tracebacks are desired regardless of external configuration.
affects: All versions
gotchaIncorrect import path for core utilities. Users commonly attempt to import functions like `print_exception_message` directly from the top-level `cli_exit_tools` package. However, these utilities are located within the `cli_exit_tools` module itself, requiring `from cli_exit_tools import cli_exit_tools` to access them.fixAlways import the module as `from cli_exit_tools import cli_exit_tools` and then call functions like `cli_exit_tools.print_exception_message()`.
affects: All versions
breakingChanges to exit code semantics or output structure can break consuming scripts. As with any CLI utility, future versions changing the default exit codes returned by `get_exit_code_from_exception` or modifying the format of messages printed by `print_exception_message` (e.g., switching from plain text to JSON, or reordering output) could break automated scripts or parsers relying on consistent output.fixPin your `cli-exit-tools` version in `requirements.txt` or similar, and carefully review release notes and changelogs for any changes to exit codes or output formats when upgrading. Implement robust parsing that is resilient to minor output variations.
affects: Any future major or minor version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cli_exit_tools'
The 'cli-exit-tools' package has not been installed in the current Python environment.
fixInstall the package using pip: `pip install cli-exit-tools`
ImportError: cannot import name 'print_exception_message' from 'cli_exit_tools' (or similar for other functions)
The core utilities like `print_exception_message` are located within a submodule also named `cli_exit_tools`, not directly at the top-level package import path.
fixImport the `cli_exit_tools` module from the `cli_exit_tools` package, then access its functions: `from cli_exit_tools import cli_exit_tools; cli_exit_tools.print_exception_message(...)`
cli-exit-tools print_exception_message no traceback
The `trace_back` parameter of `print_exception_message` defaults to a value from an internal configuration, which might be `False` by default or influenced by CLI options, thereby suppressing the traceback.
fixExplicitly set `trace_back=True` when calling `print_exception_message` to ensure full traceback information is printed: `cli_exit_tools.print_exception_message(trace_back=True, stream=sys.stderr)`
Upgrade
Version history
1.2.7latest on PyPI · released Oct 2, 2024
Audit
Dependencies
clickrequiredUsed for command-line interface foundations.
lib-detect-testenvrequiredUsed for detecting and configuring behavior in test environments.