SEPLogger¶

Author: Marcel Simader
Date: 12.05.2021

New in version v0.1.2.

Logger Levels¶

class SEPModules.SEPLogger.LevelType(value)¶

Enum for indicating which type of Level an enum entry in a Level subclass is. Possible values are:

NORMAL
ERROR
DEBUG

class SEPModules.SEPLogger.Level(value)¶

Abstract base class for all Logger level enums. Logger values are comparable using the standard compare operators and additionally must be instantiated with a tuple of form (level, prefix, style, level_type) with types int, AnyStr, SEPModules.SEPPrinting.AnsiControl, and LevelType which can be accessed as properties of the instances of this class.

final classmethod get_errors()¶

This function provides those levels which represent an error so that the Logger class can discern between normal outputs and error outputs.

Returns: an iterator of Level enum entry which represent the error levels
Return type: Tuple[SEPModules.SEPLogger.Level, …]

final classmethod get_debug()¶

This function provides the debug enum for use in the Logger class. This function is needed to provide the logger class with a debug level.

Returns: an iterator of Level enum entry which represents the debug levels
Return type: Tuple[SEPModules.SEPLogger.Level, …]

class SEPModules.SEPLogger.DefaultLevel(value)¶: Default set of levels to pass to a Logger instance.

Logger¶

class SEPModules.SEPLogger.Logger(level_class=DefaultLevel, min_level=DefaultLevel.VERBOSE, level_mask=None, print_function=None, use_timestamp=False, use_date=False, ignore_level_restrictions=False, use_color=True)¶

Logger provides a convenient way to handle printing to the console, or to another stream or file.

A logger instance holds configurations on how to print data and what additional meta-data to include. The Level enum can be used to configure different levels of verbosity (e.g. WARNING, ERROR, etc.) with default levels already implemented in DefaultLevels, which are also accessible through their aliases VERBOSE, INFO, WARNING, ERROR, FATAL_ERROR. Logger also includes a convenience method debug() which can be used to debug and includes additional meta-data such as the file name and line number.

For convenience, one might want to set up the logger as a constant, or use the provided DEFAULT_LOGGER instance in the following fashion:

>>> from SEPModules.SEPLogger import DEFAULT_LOGGER
>>> from SEPModules import log # alias to the log method is already provided!
>>> from SEPModules import debug # and so is an alias to the debug method!
>>> fatal_error = lambda *msg: DEFAULT_LOGGER.log(*msg, level=FATAL_ERROR) # alias to an error output of the log function

Now we can simply use the aliases to access the logger:

log("this is an error", level=ERROR)
[Error] [<Timestamp>] this is an error

debug(("_test", "tuple"), 123)
[Debug] [<Timestamp>] [<input>::<function>:<lineno>] ('_test', 'tuple') 123

fatal_error("halting problem is not decidable!")
[Fatal Error] [<Timestamp>] halting problem is not decidable!

Parameters

level_class (Type[LevelEnum]) – which Level subclass to use as enum for the verbosity levels of this instance
min_level (LevelEnum) – the minimum level an entry must have to be printed or written to the log
level_mask (Optional[Container[LevelEnum]]) – a container of levels to ignore when printing or writing to the log
out (TextIO) – the default out TextIO stream to print to
err (TextIO) – the default error TextIO stream to print to (may be the same as out, if desired)
use_timestamp (bool) – whether or not to print a timestamp with each log entry (see _provide_timestamp())
use_date (bool) – whether or not to add the current date to each timestamp
ignore_level_restrictions (bool) – if set to True, this will ignore the values of the min_level and level_mask parameters
use_color (bool) – whether or not to use color when printing or writing to the log

_provide_timestamp()¶

Provides the current time as timestamp.

Returns: a timestamp in the format DAY.MONTH.YEAR HOUR:MINUTE:SECOND.MILLISECOND with the date only appearing if use_date is True, if use_timestamp is False this method will simply return the empty string
Return type: str

final _local_print(msg, level)¶

Prints the message with appropriate level to the appropriate defined output stream (see out, and err). This methods also performs various system-dependent checks and decides whether to use color or not, and what encoding to use.

This method considers any levels marked as debug to be normal output, even if they also occur as error.

Warning

This function only uses color output if the given stream’s isatty() method returns True, along with some other platform-dependent checks.

Raises: UnicodeError – if no encoding attempt was successful

property min_level: SEPModules.SEPLogger.LevelEnum¶

Returns: the minimum level to be logged by this instance

property level_mask: Optional[Collection[SEPModules.SEPLogger.LevelEnum]]¶

Returns: the level mask blocking specific levels from being logged

property level_class: Type[SEPModules.SEPLogger.LevelEnum]¶

Returns: the enum of which all levels used by this instance must be a part of

log(*msg, level=DefaultLevel.INFO, start='', joiner=' ', end='\n')¶

Registers a log entry with this instance.

Parameters

msg (Any) – the message to log, can be any number of objects
level (SEPModules.SEPLogger.LevelEnum) – which level to mark this entry as (see Logger and Level)
start (AnyStr) – the starting character of the message of the log entry (inserted after prefix and timestamp)
joiner (AnyStr) – the character used to join multiple input objects together (akin to str.join)
end (AnyStr) – the ending character of the log entry, similar to the end keyword argument of the print builtin

Raises

TypeError – if level is not part of the enum specified by level_class (see Logger constructor)

newline(level=DefaultLevel.INFO)¶

Registers an empty line with this instance.

Parameters: level (SEPModules.SEPLogger.LevelEnum) – the level to mark this blank line as, this does not print a style or prefix and simply exists so that newlines can be printed conditionally based on what the level requirements of this instance are
Raises: TypeError – if level is not part of the enum specified by level_class (see Logger constructor)

debug(*msg, stack_depth=1, include_function_name=True, start='', joiner=' ', end='\n')¶

Registers a debug log entry with this instance.

Parameters

msg (Any) – the message to log, can be any number of objects
stack_depth (int) – how far back into the stack to trace the origin of this call
include_function_name (bool) – whether to include the name of the function scope of the call or not
start (AnyStr) – the starting character of the message of the log entry (inserted after prefix and timestamp)
joiner (AnyStr) – the character used to join multiple input objects together (akin to str.join)
end (AnyStr) – the ending character of the log entry, similar to the end keyword argument of the print builtin

@log_call(*msg, level=DefaultLevel.INFO, use_qualified_name=True, include_arguments=False, exclude_self=True, start='', joiner=' ', end='\n')¶

Customizable decorator for logging a function call with a message and a level. This log call will automatically include the function name in the output.

Parameters

msg – the message to log, can be any number of objects
level – which level to mark this entry as (see Logger and Level)
use_qualified_name – whether or not to use the fully qualified name of the function in the log output
include_arguments – whether or not to include the arguments passed to the function in the log output
exclude_self – whether or not to exclude the cls argument for methods
start – the starting character of the message of the log entry (inserted after prefix and timestamp)
joiner – the character used to join multiple input objects together (akin to str.join)
end – the ending character of the log entry, similar to the end keyword argument of the print builtin

Returns

the customized decorator function

@log_class(*msg, level=DefaultLevel.INFO, allow_public=True, allow_private=True, include_arguments=False, exclude_self=True, start='', joiner=' ', end='\n')¶

Customizable decorator for logging a function call with a message and a level. This log call will automatically include the function name in the output. DOCS change this docstring

Note

The __str__ and __repr__ methods cannot be logged, since they maybe be used to generate the log output. The __new__ method is also not logged.

Parameters

msg – the message to log, can be any number of objects
level – which level to mark this entry as (see Logger and Level)
allow_public – whether or not to allow public methods (all methods with names not starting with any underscores), for example message
allow_private – whether or not to allow “sunder” or “dunder” methods (all methods with names starting with underscores), for example _calc_runtime
include_arguments – whether or not to include the arguments passed to the function in the log output
exclude_self – whether or not to exclude the cls argument for methods
start – the starting character of the message of the log entry (inserted after prefix and timestamp)
joiner – the character used to join multiple input objects together (akin to str.join)
end – the ending character of the log entry, similar to the end keyword argument of the print builtin

Returns

the customized decorator function