consolekit.tracebacks

Functions for handling exceptions and their tracebacks.

New in version 1.0.0.

Classes:

TracebackHandler([exception])

Context manager to abort execution with a short error message on the following exception types:

Functions:

handle_tracebacks([show_traceback, cls])

Context manager to conditionally handle tracebacks, usually based on the value of a command line flag.

traceback_handler()

Context manager to abort execution with a short error message on the following exception types:

traceback_option([help_text])

Decorator to add the -T / --traceback option to a click command.

class TracebackHandler(exception=Abort())[source]

Bases: object

Context manager to abort execution with a short error message on the following exception types:

Other custom exception classes inheriting from Exception are also handled, but with a generic message.

The following exception classes are ignored:

How these exceptions are handled can be changed, and supported can be added for further exception classes by subclassing this class. Each method is named in the form handle_<exception>, where exception is the name of the exception class to handle.

New in version 1.0.0.

Parameters

exception (BaseException) – The exception to raise after handling the traceback. If not running within a click command or group you’ll likely want to set this to SystemExit(1). Default click.Abort().

Changed in version 1.4.0: Added the exception argument.

Methods:

__call__()

Use the TracebackHandler with a with block, and handle any exceptions raised within.

abort(msg)

Abort the current process by calling self.exception.

handle(e)

Handle the given exception.

Attributes:

exception

The exception to raise after handling the traceback.

__call__()[source]

Use the TracebackHandler with a with block, and handle any exceptions raised within.

abort(msg)[source]

Abort the current process by calling self.exception.

New in version 1.4.0.

Parameters

msg (Union[str, List[str]]) – The message to write to stderr before raising the exception. If a list of strings the strings are concatenated (i.e. ''.join(msg)).

Return type

NoReturn

exception

Type:    Exception

The exception to raise after handling the traceback.

New in version 1.4.0.

handle(e)[source]

Handle the given exception.

Parameters

e (BaseException)

Return type

bool

handle_tracebacks(show_traceback=False, cls=<class 'TracebackHandler'>)[source]

Context manager to conditionally handle tracebacks, usually based on the value of a command line flag.

New in version 0.8.0.

Parameters
Return type

AbstractContextManager[+T_co]

Changed in version 1.0.0: Added the cls parameter.

traceback_handler()[source]

Context manager to abort execution with a short error message on the following exception types:

Other custom exception classes inheriting from Exception are also handled, but with a generic message.

The following exception classes are ignored:

New in version 0.8.0.

traceback_option(help_text='Show the complete traceback on error.')[source]

Decorator to add the -T / --traceback option to a click command.

The value is exposed via the parameter show_traceback: bool.

New in version 1.0.0.

Parameters

help_text (str) – The help text for the option. Default 'Show the complete traceback on error.'.

Return type

Callable[[~_C], ~_C]