misc

Collection of convenience classes that do not fit any other category.

misc.DEFAULT_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name})'

misc.SHORT_FMT = '{asctime:<23s} [{levelname:<8s}] {message}'

misc.PID_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name} | PID-{process})'

misc.RAW_FMT = '{message}'

misc.JSON_FMT = ('levelname', 'name')

class StdLogger(name, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message} ({name})', stream='stdout')[source]

Bases: ArgRepr

Wrapped logger to stdout or stderr with a formatted StreamHandler.

Parameters:

name (str) – Name of the Logger. Typically set to __name__.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
fmt (str, optional) – Format string for the log messages in str.format() format. Defaults to “{asctime:<23s} [{levelname:<8s}] {message} ({name})”.
stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.

Raises:

TypeError – If stream is not a string.
ValueError – If stream is neither “stdout” nor “stderr”

Note

The instantiation of the actual, underlying Logger is delayed until it is first needed to facilitate usage in multiprocessing scenarios.

Warning

To avoid creating and adding a new Handler to the same stream every time the same Logger is requested, one of its existing StreamHandlers will be modified if there are any. A new one will be created and added only if there aren’t. By consequence, requesting the same Logger multiple times with a different level and/or a different fmt might change that Logger globally.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

info(message)[source]

Log an INFO message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (str) – The message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with one StreamHandler configured to specs.

warning(message)[source]

Log a WARNING message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

class FileLogger(file, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message}', mode='a', encoding='utf-8', delay=True)[source]

Bases: ArgRepr

Wrapped logger to file with at least one formatted FileHandler.

Parameters:

file (str) – Full path to the file to log to, including file extension. If the parent directory does not exist, an attempt will be made to create it.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
fmt (str, optional) – Format string for the log messages in str.format() format. Defaults to “{asctime:<23s} [{levelname:<8s}] {message}”.
mode (str, optional) – Mode to open the file. Defaults to “a”.
encoding (str, optional) – Encoding to use when opening the file. Defaults to “utf-8”.
delay (bool, optional) – Whether to delay opening the file until it is first written to. Defaults to True.

Raises:

FileExistsError – If a different Logger already has a FileHandler to the very same file. Because the instantiation of the actual Logger is delayed until it is first needed (to facilitate usage in multiprocessing scenarios), raising the exception is also delayed.

Note

The mode and the encoding can not be changed on an existing log file.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

property handler_exists: Does a Logger with a Handler of the specified file already exist?

info(message)[source]

Log an INFO message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (str) – The message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with one FileHandler configured to specs.

property name: The name given to the Logger based on the provided file name.

warning(message)[source]

Log a WARNING message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

class JsonLogger(name, level=10, stream='stdout', field=('levelname', 'name'), *fields, **extras)[source]

Bases: ArgRepr

Wrapped logger to stdout or stderr with a JSON-formatted StreamHandler.

Parameters:

name (str) – Name of the Logger. Typically set to __name__.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.
field (str or iterable, optional) – A single LogRecord attribute or an iterable thereof. All values that are not marked by “You shouldn’t need to format this yourself.” are allowed. Logged messages will be merged with a dictionary of these keys before being written to stream unless you explicitly refer to the LogRecord attribute “message”, in which case that field will contain the dictionary you want to log. Defaults to ("levelname", "name").
*fields (str) – Additional LogRecord attributes to merge with the log message.
**extras – Additional, static key-value pairs to merge into every log message.

Note

The instantiation of the actual, underlying Logger is delayed until it is first needed to facilitate usage in multiprocessing scenarios.

Warning

If the requested Logger already has a Handler to the requested stream, it will be deleted and replaced with a new one. By consequence, requesting the same Logger multiple times with different options might change that Logger globally.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

info(message)[source]

Log an INFO message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (Mapping) – The (dictionary) message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with exactly one JsonStreamHandler.

warning(message)[source]

Log a WARNING message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

class JsonStreamHandler(stream='stdout', field=('levelname', 'name'), *fields, **extras)[source]

Bases: StreamHandler

StreamHandler for logging JSON-formatted messages.

Parameters:

stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.
field (str or iterable, optional) –
A single LogRecord attribute or an iterable thereof. All values that are not marked by “You shouldn’t need to format this yourself.” are allowed. Logged messages will be merged with a dictionary of these keys before being written to stream unless you explicitly refer to the LogRecord attribute “message”, in which case that field will contain the dictionary you want to log. Defaults to ("levelname", "name").
*fields (str) – Additional LogRecord attributes to merge with the log message.
**extras – Additional, static key-value pairs to merge into every log message.

Raises:

TypeError – If stream is not a string.
ValueError – If stream is neither “stdout” nor “stderr” or if any of the given fields are not a permissible LogRecord attribute.

static asctime(timestamp)[source]: Format a unix timestamp to string, including milliseconds.

property basics: LogRecord attributes to add to the log message.

format(record)[source]: Format the LogRecord as a JSON-serialized string.

class ArgRepr(*args, **kwargs)[source]

Bases: ReprName

Base class for a representation with class name and (keyword) arguments.

This class is not meant to be instantiated by itself. Rather, it is meant to be inherited from. Its constructor is then meant to be called in the child’s constructor (with super().__init__(...)), passing the (keyword) arguments that are desired to appear in the child’s representation.

Parameters:

*args – Appear as arguments within parentheses in the child representation after its class name.
**kwargs – Appear as keyword arguments within parentheses in the child representation after its class name and arguments.

Examples

>>> class Pretty(ArgRepr):
...     def __init__(self, foo, answer):
...         super().__init__(foo, answer=answer)
...
>>> Pretty('good', 42)
Pretty('good', answer=42)

static _name(obj)

Representation for callable objects used for, e.g., error messages.

Parameters:: obj (callable) – Any callable object, e.g., a class, function, method, or lambda
Returns:: A human-readable representation of the callable obj.
Return type:: str

class IndentRepr(items=(), *args, **kwargs)[source]

Bases: ReprName

Base class for a representation with numbered and indented children.

This class is not meant to be instantiated by itself. Rather, it is meant to be inherited from. Its constructor is then meant to be called in the child’s constructor (with super().__init__(...)), passing as arguments all items that are desired to appear in a (zero-based) numbered-list representation. If any of these objects have inherited from IndentRepr themselves, their representation will recursively be indented by another level. Additional (keyword) arguments will be included in the first line of the representation.

Parameters:

items (sequence, optional) – Objects to represent in a (zero-based) numbered list below the class. Defaults to an emtpy tuple.
*args – Additional arguments to appear in the class instantiation signature in the first line of the representation.
**kwargs – Additional keyword arguments to appear in the class instantiation signature in the first line of the representation.

Examples

>>> class Fancy(IndentRepr):
...     def __init__(self, foo, *args, **kwargs) -> None:
...         super().__init__(args, foo, **kwargs)
...
>>> Fancy('bar', 1, 2, Fancy('baz', 3, 4), 5, answer=42)
Fancy('bar', answer=42):
[ 0] 1
[ 1] 2
[ 2] Fancy('baz'):
     [ 0] 3
     [ 1] 4
[ 3] 5

static _name(obj)

Representation for callable objects used for, e.g., error messages.

Parameters:: obj (callable) – Any callable object, e.g., a class, function, method, or lambda
Returns:: A human-readable representation of the callable obj.
Return type:: str

Enums

class NotFound(*values)[source]

Bases: StrEnum

Enum to direct read/load behaviour in case of missing files.

IGNORE = ignore

WARN = warn

RAISE = raise

class Bears(*values)[source]

Bases: StrEnum

Enum to choose pandas versus polars.

PANDAS = pandas

POLARS = polars