exception_handling.rst

Exception handling

Satella provides a rich functionality to register exception hooks.

Note

Satella does not install a custom faulthandler. Do it yourself.

Writing your own exception handlers

To write your own exception handlers, subclass the following class:

And then instantiate it and call install().

If you got a callable of signature [type, BaseException, types.TracebackType] (type, value, traceback) that returns True upon a request to swallow the exception, you can convert it to a Satella exception handler in two ways.

First:

a = FunctionExceptionHandler(exception_handle)
a.install()

Or

@exception_handler
def exception_handle(type, value, traceback) -> bool
    ...

exception_handle().install()

Pre-defined exception handlers

MemoryErrorExceptionHandler

This exception hook kills the entire process if a MemoryError is spotted, under the rule that it's better to fail early than admit undefined behaviour.

DumpToFileHandler

A handler that will dump each stack frame of the exception, along with it's variables, to a file (or stdout/stderr). Two file handles/names are admitted:

• human_readables - where human-readable form of the exception and it's values will be output
• trace_pickles - where pickled `Traceback`s from the exception will be put.

You can throw there either:

• a str - file of given name will be created and data will be output to it
• a file-like object supporting write() (and optionally flush()) - data will be output to it
• a None - output will be piped to /dev/null

Note that the arguments are lists, so you can specify multiple target sources.