satella.exception_handling package

Submodules

satella.exception_handling.dump_to_file module

class satella.exception_handling.dump_to_file.AsStream(o, human_readable)

Bases: object

A stream to dump to

Parameters:
  • o (Union[str, IO, None, Logger, Tuple[Logger, int]]) – stream, or a file name to use, or None to use /dev/null

  • human_readable (bool) – whether the output should be human-readable or a pickle (False for pickle)

file
human_readable
level
logger
mode
o
class satella.exception_handling.dump_to_file.DumpToFileHandler(human_readables, trace_pickles=None)

Bases: BaseExceptionHandler

Write the stack trace to a stream-file.

Note that your file-like objects you throw into that must support only .write() and optionally .flush()

Parameters:
  • human_readables (Iterable[Union[str, TextIO, Logger, Tuple[Logger, int]]]) – iterable of either a file-like objects, or paths where human-readable files will be output. Also a logger can be put here, or a tuple of logger, logging level. Default logging level will be ERROR.

  • trace_pickles (Iterable[Union[str, BinaryIO]]) – iterable of either a file-like objects, or paths where pickles with stack status will be output

Raises:

TypeError – invalid stream

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority – Priority to use for this handler

  • human_readables (Iterable[Union[str, TextIO, Logger, Tuple[Logger, int]]]) –

  • trace_pickles (Iterable[Union[str, BinaryIO]]) –

handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Return type:

bool

hr: List[AsStream]
tb: List[AsStream]
class satella.exception_handling.dump_to_file.StreamType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: IntEnum

MODE_DEVNULL = 2
MODE_FILE = 0
MODE_LOGGER = 3
MODE_STREAM = 1

satella.exception_handling.exception_handlers module

class satella.exception_handling.exception_handlers.BaseExceptionHandler(priority=0)

Bases: object

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:

priority – Priority to use for this handler

abstract handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Parameters:
  • type_ (Callable[[type, BaseException, TracebackType], None]) –

  • traceback (TracebackType) –

Return type:

Optional[bool]

install()

Register this handler to run upon exceptions

Return type:

BaseExceptionHandler

priority
uninstall()

Unregister this handler to run on exceptions

class satella.exception_handling.exception_handlers.FunctionExceptionHandler(fun, priority=0)

Bases: BaseExceptionHandler

A exception handler to make callables of given signature into Satella’s exception handlers.

Your exception handler must return a bool, whether to intercept the exception and not propagate it.

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority (int) – Priority to use for this handler

  • fun (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

fun
handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

satella.exception_handling.exception_handlers.exception_handler(priority=0)

Convert a callable to an FunctionExceptionHandler. Usage

>>> @exception_handler(priority=-10)
>>> def handle_exc(type_, val, traceback):
>>>     ...

You can use also:

>>> @exception_handler
>>> def handle_exc(type_, val, traceback):
>>>     ...

The default priority is 0. But this way of calling it is not recommended, and will result in a UserWarning.

Returns:

ExceptionHandler instance

Parameters:

priority (int) –

satella.exception_handling.global_eh module

class satella.exception_handling.global_eh.GlobalExcepthook

Bases: object

Global event interceptor.

Always installed

add_hook(new_hook)

Register a hook to fire in case of an exception.

Parameters:

new_hook (Union[Callable, BaseExceptionHandler]) – callable(type, value, traceback) or instance of BaseExceptionHandler to use

Return type:

BaseExceptionHandler

ignore_failed_hooks: bool
installed_hooks: List[BaseExceptionHandler]
old_excepthook
remove_hook(hook)

Unregister a hook

Parameters:

hook (BaseExceptionHandler) – hook to remove

Raises:

ValueError – if hook not in list

satella.exception_handling.memerrhandler module

class satella.exception_handling.memerrhandler.MemoryErrorExceptionHandler(custom_hook=<function MemoryErrorExceptionHandler.<lambda>>, kill_pg=False)

Bases: BaseExceptionHandler

A handler that terminates the entire process (or process group) is a MemoryError is seen.

custom_hook is an exception callable to implement you own behavior. If it returns True, then MemoryErrorExceptionHandler won’t kill anyone. You can also provide a CallableGroup with gather=True - if any of callables returns True, the process won’t be killed.

Parameters:
  • kill_pg (bool) – whether to kill entire process group, if applicable

  • custom_hook (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority – Priority to use for this handler

  • custom_hook (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

  • kill_pg (bool) –

custom_hook: Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]
handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Return type:

Optional[bool]

install()

Register this handler to run upon exceptions

installed: bool
kill_pg: bool
priority

Module contents

class satella.exception_handling.AsStream(o, human_readable)

Bases: object

A stream to dump to

Parameters:
  • o (Union[str, IO, None, Logger, Tuple[Logger, int]]) – stream, or a file name to use, or None to use /dev/null

  • human_readable (bool) – whether the output should be human-readable or a pickle (False for pickle)

file
human_readable
level
logger
mode
o
class satella.exception_handling.BaseExceptionHandler(priority=0)

Bases: object

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:

priority – Priority to use for this handler

abstract handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Parameters:
  • type_ (Callable[[type, BaseException, TracebackType], None]) –

  • traceback (TracebackType) –

Return type:

Optional[bool]

install()

Register this handler to run upon exceptions

Return type:

BaseExceptionHandler

priority
uninstall()

Unregister this handler to run on exceptions

class satella.exception_handling.DumpToFileHandler(human_readables, trace_pickles=None)

Bases: BaseExceptionHandler

Write the stack trace to a stream-file.

Note that your file-like objects you throw into that must support only .write() and optionally .flush()

Parameters:
  • human_readables (Iterable[Union[str, TextIO, Logger, Tuple[Logger, int]]]) – iterable of either a file-like objects, or paths where human-readable files will be output. Also a logger can be put here, or a tuple of logger, logging level. Default logging level will be ERROR.

  • trace_pickles (Iterable[Union[str, BinaryIO]]) – iterable of either a file-like objects, or paths where pickles with stack status will be output

Raises:

TypeError – invalid stream

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority – Priority to use for this handler

  • human_readables (Iterable[Union[str, TextIO, Logger, Tuple[Logger, int]]]) –

  • trace_pickles (Iterable[Union[str, BinaryIO]]) –

handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Return type:

bool

hr: List[AsStream]
tb: List[AsStream]
class satella.exception_handling.FunctionExceptionHandler(fun, priority=0)

Bases: BaseExceptionHandler

A exception handler to make callables of given signature into Satella’s exception handlers.

Your exception handler must return a bool, whether to intercept the exception and not propagate it.

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority (int) – Priority to use for this handler

  • fun (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

fun
handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

class satella.exception_handling.GlobalExcepthook

Bases: object

Global event interceptor.

Always installed

add_hook(new_hook)

Register a hook to fire in case of an exception.

Parameters:

new_hook (Union[Callable, BaseExceptionHandler]) – callable(type, value, traceback) or instance of BaseExceptionHandler to use

Return type:

BaseExceptionHandler

ignore_failed_hooks: bool
installed_hooks: List[BaseExceptionHandler]
old_excepthook
remove_hook(hook)

Unregister a hook

Parameters:

hook (BaseExceptionHandler) – hook to remove

Raises:

ValueError – if hook not in list

class satella.exception_handling.MemoryErrorExceptionHandler(custom_hook=<function MemoryErrorExceptionHandler.<lambda>>, kill_pg=False)

Bases: BaseExceptionHandler

A handler that terminates the entire process (or process group) is a MemoryError is seen.

custom_hook is an exception callable to implement you own behavior. If it returns True, then MemoryErrorExceptionHandler won’t kill anyone. You can also provide a CallableGroup with gather=True - if any of callables returns True, the process won’t be killed.

Parameters:
  • kill_pg (bool) – whether to kill entire process group, if applicable

  • custom_hook (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

Instantiate an exception handler with provided priority. Handlers with smaller priorities run sooner.

Parameters:
  • priority – Priority to use for this handler

  • custom_hook (Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]) –

  • kill_pg (bool) –

custom_hook: Callable[[type, BaseException, TracebackType], Union[Sequence[bool], bool]]
handle_exception(type_, value, traceback)

Return True to intercept the exception, so that it won’t be propagated to other handlers.

Return type:

Optional[bool]

install()

Register this handler to run upon exceptions

installed: bool
kill_pg: bool
priority
satella.exception_handling.exception_handler(priority=0)

Convert a callable to an FunctionExceptionHandler. Usage

>>> @exception_handler(priority=-10)
>>> def handle_exc(type_, val, traceback):
>>>     ...

You can use also:

>>> @exception_handler
>>> def handle_exc(type_, val, traceback):
>>>     ...

The default priority is 0. But this way of calling it is not recommended, and will result in a UserWarning.

Returns:

ExceptionHandler instance

Parameters:

priority (int) –