cs-excutils 20250306

Convenience facilities for managing exceptions.

Convenience facilities for managing exceptions.

Latest release 20250306: Drop @safe_property, will be using @property @unattributable instead.

exc_fold(*da, **dkw)

Decorator to catch specific exception types and return a defined default value.

logexc(*da, **dkw)

Decorator to log exceptions and reraise.

logexc_gen(*da, **dkw)

Decorator to log exceptions and reraise for generators.

LogExceptions(log=None, conceal=False)

Wrapper for NoExceptions which reports exceptions and optionally suppresses them.

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.

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.

NoExceptions.__init__(self, handler): Initialise the NoExceptions context manager.

The handler is a callable which expects (exc_type,exc_value,traceback) and returns True or False for the __exit__ method of the manager. If handler is None, the __exit__ method always returns True, suppressing any exception.

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.

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().

transmute(*da, **dkw)

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 raised by the function itself.

unattributable(func)

Decorator to transmute AttributeError into a RuntimeError.

unimplemented(func)

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

Release Log

Release 20250306: Drop @safe_property, will be using @property @unattributable instead.

Release 20240630:

• LogExceptions: new optinal log param for the lgging call.
• @logexc: use @decorator like other civilised decorators, pass decorator params to LogExceptions.

Release 20230212.1: Fix imports.

Release 20230212: Import cs.gimmicks instead of cs.logutils, reduces dependencies.

Release 20221228: Get warning etc from cs.gimmicks, breaks circular import with cs.logutils.

Release 20221207: @unattributable: bugfix decorator construction to accomodate callable() @decorator precheck.

Release 20210123: @transmute: refactor to raise chained exceptions in Python 3+.

Release 20190812: LogExceptions: drop stack trace noise.

Release 20190220: New decorator @exc_fold to catch particular exceptions, log an error and return a defined value.

Release 20190101: @logexc: handle missing func.name.

Release 20170904: Minor updates, improved docstring.

Release 20160828:

• @unattributable and @safe_property decorators, used to protect properties from inner AttributeErrors.
• Improved exception practices.

Release 20150118: metadata updates

Release 20150110: Initial distinfo for pypi release.