Module utilities.log_utils

exception handler with logging and dynamic continuation

Functions

def log_stack_trace(ex=None, tb=None, n_outer=5)

Prepend outer frames to the default traceback and print to log.

This function logs a stack trace with additional outer frames for better context. It collects a specified number of outer frames and appends them to the default traceback. If no exception is currently being handled, it indicates that the outer traces are approximate.

Args

ex : Exception

Optional. The exception to log. Defaults to None, in which case the current exception from sys.exc_info() is used.

tb : traceback

Optional. The traceback to log. Defaults to None, in which case the current traceback from sys.exc_info() is used.

n_outer : int

Optional. The number of outer frames to collect. Defaults to 5.

def logprint(msg: ~T, level: log_levels.LogMsgLevelType = LogLevel.INFO, newline: str = '\n') ‑> ~T

Write a message or object repr to stdout or an in-memory log buffer.

This function logs a message to either stdout or an in-memory log buffer, depending on the configuration. It prepends the log level and gvars.LOG_NAME if logging to stdout, and prepends the level and appends a newline if logging to a file.

Args

msg : gvars.T

The message or object to log. Can be any object.

level : log_levels.LogMsgLevelType

Optional. The log level. Defaults to log_levels.INFO.

newline : str

Optional. The newline character to append if logging to a file. Defaults to "\n".

Returns

gvars.T

The original value of the msg parameter, unchanged. Useful for debugging comprehensions.

Classes

class LogExHandler (continue_on_error: bool, default_return=False, *, is_generator=False, **kwargs)

A decorator class to handle exceptions, log them, and optionally continue execution.

This decorator can be used to wrap functions and handle exceptions by logging them along with their trace information. It provides options to continue execution or stop it based on the configuration. It also supports generator functions.

Usage

>>> @LogExHandler(True)
... def your_func(arg_1, arg_2, **kwargs):
...     pass

Args

continue_on_error : bool

If False, raises an additional exception after saving the log to disk to stop execution.

default_return : Optional

If a literal, returns the literal. If a string, checks if 'self.', 'args' or 'kwargs' is in default_return. If so, sets return_val = eval(default_return). If is_generator is False, this can be used to return an argument supplied to the original function for continued processing. If is_generator is True, eval(default_return) should generate a new and complete "args" object. This new "args" object will then be passed to another instance of the generator to allow processing to continue in a fully transparent fashion for the caller. NOTE: the new "args" object should be modified from the original to exclude the object that resulted in the original error. Otherwise, exceptions will be logged until depth >= gvars.MAX_EX_DEPTH.

KwArgs

is_generator : bool

Set to True if decorating a generator function that utilizes the "yield" statement. Otherwise, the LogExHandler wrapper immediately returns the generator object to the caller without evaluating any of the internal generator logic, and exceptions raised during iteration will not be caught or logged by this decorator. Modifies "default_return" behavior (see above).

max_depth : int

Set the maximum number of attempts at re-entering a wrapped generator. No effect when is_generator==False. Default is gvars.MAX_EX_DEPTH.

exit_code : int

Sets a custom exit code in implementations where continue_on_error=False. Should be a positive integer. Defaults to 1.

notify : bool

If True, capture logged exceptions in gvars.NOTIFICATIONS to send an email notification at the conclusion of the run. Default is False.

**kwargs

Additional arbitrary keyword args are captured as class attributes. Allows the caller to pass in classes and/or objects not present in this module for use when evaluating a custom default_return (see above).

Example

>>> import contextlib, io  # NOTE: required for stdout redirect during doctest evaluation
>>> @LogExHandler(continue_on_error=True, default_return=0)
... def example_function(x, y):
...     return x / y
>>> with contextlib.redirect_stdout(io.StringIO()):
...     test = example_function(10, 0)
>>> test
0

class LogExOverrideError (*args, **kwargs)

Raise this exception to force all nested LogExHandlers to propagate an error upward to the first wrapped function with continue_on_error=False.

Ancestors

• builtins.Exception
• builtins.BaseException