loggers
Loggers specifically designed to keep your functions clean and tidy.
To avoid polluting your code, these loggers are meant to be inserted into your functional workflow between its building blocks. Arguments passed in are simply passed through to the next step, but you still have access to them to customize the logged message.
- class PassThroughFileLogger(file, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message}', mode='a', encoding='utf-8', delay=True)[source]
Bases:
ArgRepr,Generic[P]Pass-through Logger to file with a 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.
- class Log(parent, level, msg)[source]
Bases:
objectReturn type of the logging methods.
Note
This class is not intended to ever be instantiated directly.
See also
PassThroughFileLogger.debug,PassThroughFileLogger.info,PassThroughFileLogger.warning,PassThroughFileLogger.error,PassThroughFileLogger.critical- __call__(*args)[source]
Log the cached message and pass through the input argument(s).
- Parameters:
*args – If msg is a string, these arguments are inconsequential, and it will simply be logged. If, however, the msg is callable, it will be called with these arguments and the return value will be logged instead.
- Returns:
Single argument if called with only one, otherwise all of them.
- Return type:
object or tuple
- critical(message)[source]
Log a CRITICAL message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- debug(message)[source]
Log a DEBUG message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- error(message)[source]
Log an ERROR message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- property handler_exists
Does a Logger with a Handler of the specified file already exist?
- info(message)[source]
Log an INFO message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- log(level, message)[source]
Log message at a level, optionally depending on call arguments.
- Parameters:
level (int) – The level to log at.
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- 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, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- class PassThroughJsonLogger(name, level=10, stream='stdout', field=('levelname', 'name'), *fields, **extras)[source]
Bases:
ArgRepr,Generic[P]Pass-through Logger to stdout or stderr with a JSON-formatted messages.
- 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 log-record 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.
- class Log(parent, level, msg)[source]
Bases:
objectReturn type of the logging methods.
Note
This class is not intended to ever be instantiated directly.
See also
PassThroughJsonLogger.debug,PassThroughJsonLogger.info,PassThroughJsonLogger.warning,PassThroughJsonLogger.error,PassThroughJsonLogger.critical- __call__(*args)[source]
Log the cached message and pass through the input argument(s).
- Parameters:
*args – If msg is dictionary-like, the arguments are inconsequential, and it will simply be logged. If, however, the msg is callable, it will be called with these arguments and the return value will be logged instead.
- Returns:
Single argument if called with only one, otherwise all of them.
- Return type:
object or tuple
- critical(message)[source]
Log a CRITICAL (dict) message, optionally depending on call args.
- Parameters:
message (Mapping or callable) – (Dictionary) message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- debug(message)[source]
Log a DEBUG (dictionary) message, optionally depending on call args.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- error(message)[source]
Log an ERROR (dict-like) message, optionally depending on call args.
- Parameters:
message (Mapping or callable) – (Dictionary) message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- info(message)[source]
Log an INFO (dictionary) message, optionally depending on call args.
- Parameters:
message (Mapping or callable) – (Dictionary) message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- log(level, message)[source]
Log a (dictionary) message, optionally depending on call args.
- Parameters:
level (int) – The level to log at.
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- property logger
The requested Logger with exactly one JsonStreamHandler.
- warning(message)[source]
Log a WARNING (dict) message, optionally depending on call args.
- Parameters:
message (Mapping or callable) – (Dictionary) message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- class PassThroughStdLogger(name, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message} ({name})', stream='stdout')[source]
Bases:
ArgRepr,Generic[P]Pass-through 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.
- class Log(parent, level, msg)[source]
Bases:
objectReturn type of the logging methods.
Note
This class is not intended to ever be instantiated directly.
See also
PassThroughStdLogger.debug,PassThroughStdLogger.info,PassThroughStdLogger.warning,PassThroughStdLogger.error,PassThroughStdLogger.critical- __call__(*args)[source]
Log the cached message and pass through the input argument(s).
- Parameters:
*args – If msg is a string, these arguments are inconsequential, and it will simply be logged. If, however, the msg is callable, it will be called with these arguments and the return value will be logged instead.
- Returns:
Single argument if called with only one, otherwise all of them.
- Return type:
object or tuple
- critical(message)[source]
Log a CRITICAL message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- debug(message)[source]
Log a DEBUG message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- error(message)[source]
Log an ERROR message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- info(message)[source]
Log an INFO message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- log(level, message)[source]
Log a message a a level, optionally depending on call arguments.
- Parameters:
level (int) – The level to log at.
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
- property logger
The requested Logger with one StreamHandler configured to specs.
- warning(message)[source]
Log a WARNING message, optionally depending on call arguments.
- Parameters:
message (str or callable) – Message to log when the returned object is called. If it is callable, then it will be called with whatever argument(s) the returned object is called with and the result will be logged.
- Returns:
A callable object that logs the message when called.
- Return type:
formats
- loggers.DEFAULT_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name})'
- loggers.SHORT_FMT = '{asctime:<23s} [{levelname:<8s}] {message}'
- loggers.PID_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name} | PID-{process})'
- loggers.RAW_FMT = '{message}'
- loggers.JSON_FMT = ('levelname', 'name')