rics.logs#

Utility methods for logging tasks.

Module Attributes

`FORMAT_MS`	Default logging format; `<date-format>.378 [rics:DEBUG] I'm a debug message!`
`FORMAT`	Alias of `FORMAT_MS`.
`FORMAT_SEC`	Like `FORMAT_MS`, but without milliseconds; `<date-format> [rics:DEBUG] I'm a debug message!`
`DATE_FORMAT`	Default logging date format; `2022-02-05T11:17:05<logging-format>`
`LogLevel`	Valid input types for `convert_log_level()`.

Functions

`basic_config`(*[, format, datefmt, level, force])	Do basic logging configuration with package defaults.
`convert_log_level`(log_level, *[, verify, name])	Convert `str` or `int` to a valid log level.
`disable_temporarily`(*loggers)	Temporarily disable logging.
`get_logger`(-> ~logging.Logger)	Get a logger.

Classes

LoggingSetupHelper(levels, *[, format, datefmt])

Helper class for logging configuration.

Exceptions

LogLevelError(log_level, argument_name[, ...])

Raised by convert_log_level().

FORMAT_MS: str = '%(asctime)s.%(msecs)03d [%(name)s:%(levelname)s] %(message)s'#: Default logging format; <date-format>.378 [rics:DEBUG] I'm a debug message!

FORMAT = '%(asctime)s.%(msecs)03d [%(name)s:%(levelname)s] %(message)s'#: Alias of FORMAT_MS.

FORMAT_SEC: str = '%(asctime)s [%(name)s:%(levelname)s] %(message)s'#: Like FORMAT_MS, but without milliseconds; <date-format> [rics:DEBUG] I'm a debug message!

DATE_FORMAT: str = '%Y-%m-%dT%H:%M:%S'#: Default logging date format; 2022-02-05T11:17:05<logging-format>

LogLevel = int | str#: Valid input types for convert_log_level().

basic_config(*, format: str = '%(asctime)s.%(msecs)03d [%(name)s:%(levelname)s] %(message)s', datefmt: str = '%Y-%m-%dT%H:%M:%S', level: int | str | None = 'INFO', force: bool = True, **kwargs: Any) → None[source]#

Do basic logging configuration with package defaults.

Simple wrapper for the standard logging.basicConfig()-method, using my personal preferences for defaults.

Parameters:

format – Format string for emitted messages; see FORMAT_MS.
datefmt – Format string for date/time; see DATE_FORMAT. If empty, remove the time components if format == FORMAT_MS (default) or FORMAT_SEC.
level – Log level for the root logger.
force – If True, override existing configuration if it exists.
**kwargs – Keyword arguments for logging.basicConfig().

Keyword Arguments:

_level – Additional log levels to set, replacing double underscores with dots to produce the logger names. For example, passing rics__performance_level=logging.INFO (or the dotted-name equivalent **{"rics.performance_level": "INFO"}) will invoke logging.getLogger("rics.performance").setLevel(logging.INFO).

Examples

Basic usage.

>>> import logging
>>> basic_config(level=logging.INFO, rics_level=logging.DEBUG)
>>> logging.getLogger("rics").debug("I'm a debug message!")
>>> logging.debug("I'm a debug message!")
>>> logging.critical("I'm a critical message!")  # Doctest: +SKIP
2022-02-05T11:17:05.378 [rics:DEBUG] I'm a debug message!
2022-02-05T11:17:05.378 [root:CRITICAL] I'm a critical message!

Removing time from the message template.

>>> import sys
>>> basic_config(datefmt="", stream=sys.stdout)
>>> logging.info("No time!")
[root:INFO] No time!

Note that this only works when format is either FORMAT_MS or FORMAT_SEC.

disable_temporarily(*loggers: str | Logger | LoggerAdapter) → Any[source]#

Temporarily disable logging.

Parameters:: *loggers – Loggers to disable.
Yields:: Nothing.

Examples

Disable all logging temporarily.

>>> import logging
>>> logging.basicConfig()
>>> with disable_temporarily(logging.root):
...     logging.info("This message is ignored.")

exception LogLevelError(log_level: int | str, argument_name: str, extra_notes: Collection[str] = ())[source]#

Bases: Exception

Raised by convert_log_level().

property log_level: int | str#: Log level provided by user.

property argument_name: str#: Argument name seen by user.

convert_log_level(log_level: int | str, *, verify: bool = False, name: str = 'log_level') → int[source]#

Convert str or int to a valid log level.

Parameters:

log_level – Either str or int.
verify – If True and log_level is an int, verify that log_level is a known level.
name – Name to use in error messages.

Returns:

An integer level.

See also

The logging.addLevelName() function.

Raises:

LogLevelError – If log_level is an int without a known level name and verify=True.
LogLevelError – If log_level is a str without a known level name.

Bases: object

Helper class for logging configuration.

Verbosity:

Verbosity levels are assumed to be strictly increasing in the amount of logs emitted. In other words, levels such as

>>> [{"id_translation": "DEBUG"}, {"id_translation": "INFO"}]

are not permitted, since going from verbosity=1 to verbosity=2 would reduce the amount of legts emitted. Calling LoggingSetupHelper.configure_logging() with verbosity=0 disables logging entirely.

Parameters:

levels – An iterable of levels, where each level is a dict {logger_name: log_level}.
format – Format string for emitted messages; see rics.logs.basic_config().
datefmt – Format string for date/time; see rics.logs.basic_config().

Note

You should not include the '_level' suffix that you would use when calling basic_config() directly.

Raises:

TypeError – If any levels are empty.
ValueError – If levels is not strictly increasing in verbosity.

property max: int#: Maximum verbosity level.

get_log_levels(verbosity: int) → dict[str, int][source]#

Get log levels per logger at the given verbosity level.

Parameters:: verbosity – Verbosity level. Pass -1 for max level.
Returns:: A dict {logger: log_level}
Raises:: ValueError – If verbose is zero, less than -1, or too high.

configure_logging(verbosity: int) → None[source]#

Configure logging using basic_config().

Parameters:: verbosity – Verbosity level. Disable logging.root if zero.

get_kwargs(verbosity: int) → dict[str, Any][source]#

Create kwargs for basic_config().

Parameters:: verbosity – Verbosity level.
Returns:: A dict.

get_level_descriptions() → list[str][source]#

Get lines describing the configured verbosity level.

Returns one str item per level.

Returns:: A list of strings.

get_logger(logger: Logger | str | None | Literal[False]) → Logger[source]#

get_logger(logger: LoggerAdapter[Any]) → LoggerAdapter[Any]

Get a logger.

Returns a disabled logger if logger is None. Loggers and adapters are returned as-is.

Parameters:: logger – An adapter, logger, logger name, or None.
Returns:: A logger instance.