Logger

class logboss.logger.Logger

Bases: object

Creates a singleton instance of the logger.

Set these properties prior to starting the logger if the default is undesired.

  • default_log_tag (default: INFO): LogTagType to use in log() when the log_tag isn’t specified.

  • default_exception_tag (default: CRITICAL): LogTagType that will be called in log_exception().

  • date_format (default: %Y/%m/%d %H:%M:%S): String compatible with Python’s strftime.

  • default_rule (default: lambda x: (False, False)): Callable function that returns one or two booleans. If one boolean, then both console and persistence apply that value. Otherwise return a boolean in the order of (do not send to console, do not persist).

  • redirect (default: None): String path to the text file to create. The path is created if it doesn’t exist.

  • add_log_tags(): Call this method to add custom log tags prior to starting the logger.

static add_cleanup(func, *args, **kwargs)

Add a cleanup action using Python’s atexit module.

Parameters

  • func – Callable function.

  • *args – Function arguments.

  • **kwargs – Function keyword arguments.

add_log_tags(value)

Appends the log tags to the list of custom log tags. This will fail after the logger has been started. The log tags must be stored in a class like this:

class LogTags:
    some_tag = LogTagTypes.Info(name='Some Tag')

logger.add_log_tags(LogTags)
Parameters

value – A class of Log

clear_logs()

Clears the log entries.

critical(msg: Any, num_prev_callers: int = 0)

Logs a message with the default CRITICAL log tag.

Parameters

  • msg – Log message.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

debug(msg: Any, num_prev_callers: int = 0)

Logs a message with the default DEBUG log tag.

Parameters

  • msg – Log message.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

disabled(log_tag: Union[logboss.config.LogTagBase, str] = None, why: str = '')

WARNING! This disables all logging in a context. This trumps all rules and modes as no logs will be processed or printed to the console. Use carefully. Upon exit of the context the logger will reset to the original state. Upon exit the logger will raise an error if any exceptions were raised in the context and the original state of the logger was enabled. In other words, if the logger was never started with start(), then it will not log the exceptions.

logger = Logger(...)

with logger.disabled(log_tag=log_tags.default, why='Suppressing redundant logs...'):
    for i in range(5000):
        logger.info('I will not be logged at all. Period.')
logger.info('I am logged!')
Parameters

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • why – A description of why logging is being disabled.

dump(path: Union[pathlib.Path, str])

Dump the logs to path. This option is still under development. Its intent is to dump logs to a file on disk to free memory. Currently memory isn’t freed by default, so use only if you know what you are doing.

Parameters

path – Path to the JSON file to dump the logs.

error(msg: Any, num_prev_callers: int = 0)

Logs a message with the default ERROR log tag.

Parameters

  • msg – Log message.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

generate(format_generator: Union[str, Callable], log_file: Union[pathlib.Path, str], persist: bool = True, **kwargs)

A context manager that generates a log file from the logs persisted in the context using a format generator. The format_generator currently only supports HTML, but a custom one could be built.

A custom log generator must be a class whose __init__ accepts the logs from get_logs() and must have a generate() method that accepts the log file path and kwargs. For example

class CustomLogGenerator:
    def __init__(self, logs: dict):
        self._log_tags = logs['log_tags']
        self._log_entries = logs['log_entries']
        self._main_thread_id = logs['main_thread_id']

    def generate(log_file: str, **kwargs):
        # Define the generation logic here.
        pass
Parameters

  • format_generator – If a string type then only ‘html’ is supported, which uses the HtmlLogGenerator class. Otherwise a custom callable object can be used to generate the logs.

  • log_file – The path to the log file. It is created if it doesn’t already exist.

  • persist – If True then the data is persisted and the output is generated. Otherwise the generator does not run.

get_logs()

Use this to get the logs to pass to the HtmlLogGenerator parser. Not required if you are using the logger.generate() context manager.

Returns: A dictionary with the log tags, entries, and main thread id.

info(msg: Any, num_prev_callers: int = 0)

Logs a message with the default INFO log tag.

Parameters

  • msg – Log message.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

load(json_file)

Loads logs from a JSON file, which would come from dump(). This feature is still under development, so only use if you know what you are doing.

Parameters

json_file – Path to the JSON file.

log(msg: Any, log_tag: Union[logboss.config.LogTagBase, str] = None, num_prev_callers: int = 0)

Logs a message with the log_tag log tag if given, else the default_log_tag, which, if not explicitly set, defaults to the INFO log tag.

Parameters

  • msg – Log message.

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

log_exception(log_tag: Union[logboss.config.LogTagBase, str] = None)

Logs an exception using traceback.format_exc() with the log_tag log tag if given, else the default_exception_tag, which, if not explicitly set, defaults to the CRITICAL log tag.

Parameters

log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’. The default_exception_tag is used by default.

log_method(func: callable, msg: Any, log_tag: Union[logboss.config.LogTagBase, str] = None, returning: bool = False)

Logs a call or exit of a method or function with the name of the callable and the given msg with the log_tag log tag if given, else the default_log_tag, which, if not explicitly set, defaults to the INFO log tag. This is generally not needed and should only be used by wrap_func().

Parameters

  • func – A callable object.

  • msg – The log message.

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • returning – If True gets the last line number of the function instead of the first for the log.

rule(log_tag: Union[logboss.config.LogTagBase, str] = None, min_level: str = None, blacklist_function: Callable[[logboss.config.LogTagBase], Tuple[bool, bool]] = None, why: str = '')

The context manager equivalent of set_rule(). When the context exits the default_log_rule is applied, which if unset defaults to lambda x: (False, False), which means there are no restrictions enforced by the rules.

Parameters

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • min_level – If a string, must be one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’, from which the value of the respective default log tag type is used as a minimum threshold for a log event to occur. Otherwise it must be an integer.

  • blacklist_function – A custom callable that accepts a single argument (the log tag) and returns either a single boolean (which applies to both console and persistent modes) or a tuple of booleans where the first applies to the console and the second to persistence. A value of True means the log event will be ignored (hence blacklisted).

  • why – The reason why the rule is being created, which is logged using the log_tag.

set_mode(mode: str, log_tag: Union[logboss.config.LogTagBase, str] = None, why: str = '')

The log mode can be used to change where the logs are recorded. This is useful for simply reducing noise in the log output.

There are four modes: current, console, persistence, and all.

  • current: Do not change the mode. Default.

  • console: Change the mode to log to the console only.

  • persistence: Change the mode to log to the SQLite DB file only.

  • all: Change the mode to use both console and persistent logging.

Parameters

  • mode – One of ‘current’, ‘console’, ‘persistence’, or ‘all’. Default is ‘current’. Case sensitive.

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • why – A description of why the mode is being set.

set_rule(log_tag: Union[logboss.config.LogTagBase, str] = None, min_level: str = None, blacklist_function: Callable[[logboss.config.LogTagBase], Tuple[bool, bool]] = None, reset: bool = False, why: str = '')

Sets a rule for blacklisting log messages. This is particularly useful when reducing noise in the log output. Only one of min_level, blacklist_function, or reset can be specified.

Parameters

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • min_level – If a string, must be one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’, from which the value of the respective default log tag type is used as a minimum threshold for a log event to occur. Otherwise it must be an integer.

  • blacklist_function – A custom callable that accepts a single argument (the log tag) and returns either a single boolean (which applies to both console and persistent modes) or a tuple of booleans where the first applies to the console and the second to persistence. A value of True means the log event will be ignored (hence blacklisted).

  • reset – If True then the default_log_rule is applied.

  • why – The reason why the rule is being created, which is logged using the log_tag.

start(persist: bool = False)

Starts the logger. If not called, no log events occur. Once the logger is started then the log tags cannot be modified. Also, it is wise to NOT modify the redirect, default_log_tag, default_exception_tag, default_log_rule, or any of the private variables associated to the logger. In general, once the logger is started, then the only calls to the logger should be setting rules/modes and logging messages.

Parameters

persist – If True the logs will also persist in memory. Otherwise logs are only sent to the console or redirect path.

warning(msg: Any, num_prev_callers: int = 0)

Logs a message with the default WARNING log tag.

Parameters

  • msg – Log message.

  • num_prev_callers – Number of previous calls in the call stack that identifies the originator of the log message. This should rarely, if ever, be set, but is configurable should a a previous caller be tied to the log message.

wrap_class(log_tag: Union[logboss.config.LogTagBase, str] = None, func_regex_exclude: str = '', mask_input_regexes: List = None, mask_output: bool = False, mask_output_regexes: List = None)

Applies wrap_func() to each callable member of a class that does not start with “__” and does not match the func_regex_exclude. If a callable member starting with “__” should be wrapped, then it must be explicitly wrapped with the wrap_func() method. The mask_input_regexes and mask_output parameters are passed to the wrap_func() method.

Parameters

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • func_regex_exclude – A regular expression matching method names that should not be wrapped.

  • mask_input_regexes – Passed to wrap_func().

  • mask_output – Passed to wrap_func().

  • mask_output_regexes – Passed to wrap_func()..

wrap_func(log_tag: Union[logboss.config.LogTagBase, str] = None, mask_input_regexes: List = None, mask_output: bool = False, mask_output_regexes: List = None, is_staticmethod: bool = False, is_classmethod: bool = False)
Wrapper for a function or method. This wrapper performs a few important steps:

  1. Increases the depth of the call, which controls its relation to all previous and subsequent logs in the log hierarchy.

  2. Logs the function’s name, inputs, and outputs.

  3. Catches any exceptions raised by the function and logs them.

  4. Decreases the depth of the call to return to the original depth of the call hierarchy.

The depth is the defining marker for the position of a function in the logged hierarchy. Without it, all logs would be flat an hard to parse through.

@logger.wrap_func(
    log_tag=Tags.SomeTag,
    mask_input_regexes=['cls', 'password'],
    mask_output_regexes=['.*api.*token.*']
)
@classmethod
def do_something(cls, username, password):
    # Do some stuff
    return {'API Token': 'xyz'}

  • The above example will use the Tags.SomeTag tag to log the calling and the returning message.

  • The cls and password parameters will be masked. The message will show this:

    Called do_something
Arguments:
{
    "cls": "********",
    "username": "Admin",
    "password": "********"
}

  • The output is not masked entirely, but the output will be partially masked like this:

    do_something returned.
Return Values:
{
    "API Token": "********"
}
Parameters

  • log_tag – The LogTagBase object or one of ‘debug’, ‘info’, ‘warning’, ‘error’, or ‘critical’.

  • mask_input_regexes – A list of regular expressions matching input variable names.

  • mask_output – When True the entire output is masked like this: “****”.

  • mask_output_regexes – A list of regular expressions of keys whose values ought to be masked in the output. This only applies to return values with key/value pair associations. Use mask_output if the output is not a dictionary-like object (such as a string)

  • is_classmethod – If True then the method is intended to be a classmethod.

  • is_staticmethod – If True the the method is intended to be a staticmethod.