pocketutils.misc.loguru_utils

Loguru logging extension that provides some additional features. Specifically:

• redirects built-in logging to your loguru logger

• remembers the handlers added

• auto-detects compression and serialization from filenames

• includes extras in non-serializing handlers

• has a few alternative (possibly better) choices for colors, icons, and levels

• will complain when you do really stupid things

• has a convenient notation for configuring from a CLI (e.g. --stderr debug --log :INFO:run.log.gz)

• mandates utf-8

Module Contents

class pocketutils.misc.loguru_utils.HandlerInfo

Information about a loguru handler.

class pocketutils.misc.loguru_utils.InterceptHandler(level=NOTSET)

Redirects standard logging to loguru.

Initializes the instance - basically setting the formatter to None and the filter list to empty.

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

class pocketutils.misc.loguru_utils.LoggerWithCautionAndNotice

A wrapper that has fake methods to trick static analysis.

class pocketutils.misc.loguru_utils.FancyLoguru(logger: T = _logger)

Refer to module documentation instead.

property logger → T

Returns the stored logger.

property levels → Mapping[str, int]

Returns the global loguru levels.

property aliases → Mapping[str, Optional[str]]

Returns the aliases to levels. A None means no logging (“OFF”).

property recent_messages → Sequence[str]

Returns some number of recent messages, if recording.

See also

remember()

property main → Optional[HandlerInfo]

Returns the main handler info, if configured.

property paths → AbstractSet[HandlerInfo]

Lists all path handlers configured in this object.

get_path(p: pocketutils.core.PathLike) → Optional[HandlerInfo]

Returns a path handler to this path, or None if it does not exist. The path is resolved, following symlinks, via pathlib.Path.resolve.

set_control(enabled: bool) → __qualname__

Enables/disables handler control. If control is disabled, subsequent calls to methods like from_cli() and add_path() do nothing.

config_levels(*, levels: Mapping[str, int] = _SENTINEL, colors: Mapping[str, str] = _SENTINEL, icons: Mapping[str, str] = _SENTINEL, aliases: Mapping[str, str] = _SENTINEL) → __qualname__

Modify loguru’s levels. This is a global operation and will run regardless of is_control_enabled.

config_level(name: str, level: int, *, color: Union[None, str, _SENTINEL] = _SENTINEL, icon: Union[None, str, _SENTINEL] = _SENTINEL, replace: bool = True) → __qualname__

Add a new loguru level. This is a global operation and will run regardless of is_control_enabled.

enable(*names: str) → __qualname__

Calls loguru.logger.enable on multiple items.

disable(*names: str) → __qualname__

Calls loguru.logger.disable on multiple items.

intercept_std(*, warnings: bool = True) → __qualname__

Sets python builtin logging to redirect to loguru. Uses InterceptHandler.

Parameters

warnings – Call logging.captureWarnings(True) to intercept builtin warnings

config_main(*, sink: TextIO = _SENTINEL, level: Optional[str] = _SENTINEL, fmt: Formatter = _SENTINEL, filter=_SENTINEL) → __qualname__

Sets the logging level for the main handler (normally stderr).

remember(*, n_messages: int = 100) → __qualname__

Adds a handler that stores the last n_messages. Retrieve the stored messages with recent_messages().

add_path(path: pocketutils.core.PathLike, level: str = _SENTINEL, *, fmt: str = _SENTINEL, filter=_SENTINEL) → __qualname__

Adds a handler to a file.

See also

remove_path()

Parameters

• path – If it ends with .gz, .zip, .etc., will use compression If (ignoring compression) ends with .json, will serialize as JSON. Calls pathlib.Path.resolve, meaning that symlinks are followed

• level – Min log level

• fmt – Formatting string; will wrap into a Formatter Include {{EXTRA}} to include all extras See: FormatFactory

• filter – Filtration function of records

remove_paths() → __qualname__

Removes all path handlers stored here.

See also

remove_path()

remove_path(path: pathlib.Path) → __qualname__

Removes a path handler (limited to those stored here). Will log an error and continue if the path is not found.

See also

remove_paths()

from_cli(path: Union[None, str, pathlib.Path] = None, main: Optional[str] = None, _msg_level: str = 'OFF') → __qualname__

This function controls logging set via command-line. Deletes any existing path handlers.

Parameters

• main – The level for stderr; if None, does not modify

• path – If set, the path to a file. Can be prefixed with :level: to set the level (e.g. :INFO:mandos-run.log.gz). Can serialize to JSON if .json is used instead of .log or .txt.

• _msg_level – Level for messages about this logging change

rewire_streams_to_utf8() → __qualname__

Calls reconfigure on sys.stderr, sys.stdout, and sys.stdin to use utf-8. Use at your own risk.

classmethod built_in(*, enable_control: bool = True, sink=sys.stderr, level: str = _SENTINEL) → FancyLoguru[loguru._logger.Logger]

Creates a new FancyLoguru using standard loguru levels, etc.

Parameters

• enable_control – If False, all calls to add/remove handlers (except remember()) will be ignored. rewire_streams() will also be ignored. This is provided so that you can configure both an “application” and a library that works for the same code with enable_control=<is-command-line>.

• sink – The main sink to start with

• level – The min log level for the main sink

classmethod extended(*, enable_control: bool = True, sink=sys.stderr, level: str = _SENTINEL, simplify_fmt: bool = True, red_green_safe: bool = True) → FancyLoguru[LoggerWithCautionAndNotice]

Creates a new FancyLoguru with extra levels “caution” and “notice”. These are:: - CAUTION: Bad, but between levels INFO and SUCCESS - NOTICE: Good/neutral, but between levels WARNING and ERROR

Parameters

• enable_control – See built_in()

• sink – See built_in()

• level – See built_in()

• simplify_fmt – Use DEFAULT_FMT_STRING

• red_green_safe – Modify the standard colors to use blue instead of green