cs.excutils 20190220

Convenience facilities for managing exceptions.

Function logexc(func)

Decorator to log exceptions and reraise.

Function logexc_gen(genfunc)

Decorator to log exceptions and reraise for generators.

Function LogExceptions(conceal=False)

Wrapper of NoExceptions which reports exceptions and optionally suppresses them.

Function noexc(func)

Decorator to wrap a function which should never raise an exception. Instead, any raised exception is attempted to be logged.

A significant side effect is of course that if the function raises an exception it now returns None. My primary use case is actually to wrap logging functions, which I have had abort otherwise sensible code.

Function noexc_gen(func)

Decorator to wrap a generator which should never raise an exception. Instead, any raised exception is attempted to be logged and iteration ends.

My primary use case is wrapping generators chained in a pipeline, as in cs.later.Later.pipeline.

Class NoExceptions

A context manager to catch all exceptions and log them. Arguably this should be a bare try...except but that's syntacticly noisy and separates the catch from the top. For simple function calls return_exc_info() is probably better.

Function return_exc_info(func, *args, **kwargs)

Run the supplied function and arguments. Return (func_return, None) in the case of successful operation and (None, exc_info) in the case of an exception.

exc_info is a 3-tuple of (exc_type, exc_value, exc_traceback) as returned by sys.exc_info(). If you need to protect a whole suite and would rather not move it into its own function, consider the NoExceptions context manager.

Function returns_exc_info(func)

Decorator function to wrap functions whose exceptions should be caught, such as inside event loops or worker threads.

It causes a function to return (func_return, None) in the case of successful operation and (None, exc_info) in the case of an exception.

exc_info is a 3-tuple of (exc_type, exc_value, exc_traceback) as returned by sys.exc_info().

Function safe_property(func)

Substitute for @property which lets AttributeErrors escape as RuntimeErrors.

Function transmute(exc_from, exc_to=None)

Decorator to transmute an inner exception to another exception type.

The motivating use case is properties in a class with a getattr method; if some inner operation of the property function raises AttributeError then the property is bypassed in favour of getattr. Confusion ensues.

In principle this can be an issue with any exception raised from "deeper" in the call chain, which can be mistaken for a "shallow" exception raise by the function itself.

Function unattributable(func)

Decorator to transmute AttributeError into a RuntimeError.

Function unimplemented(func)

Decorator for stub methods that must be implemented by a stub class.