thinlog package

thinlog package#

Thinlog – a lightweight, fully-typed logging toolkit built on Python’s standard logging.

Thinlog extends logging with advanced filtering, structured JSON formatting, and remote log delivery (HTTP and Telegram) while staying thin and transparent.

Public API:

class thinlog.KeywordFriendlyLogger(logger: Logger, extra: dict[str, Any] | None = None)[source]#

Bases: LoggerAdapter[Logger]

A logging.LoggerAdapter that passes arbitrary keyword arguments as extra fields.

Standard logging requires extra data to be wrapped in an extra dict. KeywordFriendlyLogger lets callers pass keyword arguments directly – they are automatically moved into extra so that filters, formatters, and handlers can access them as record attributes.

Parameters:

  • logger – The underlying logging.Logger to adapt.

  • extra – Optional default extra fields attached to every record.

ignored_meta_keys = ('exc_info', 'stack_info', 'stacklevel')#
process(msg: Any, metadata: MutableMapping[str, Any]) → tuple[Any, MutableMapping[str, Any]][source]#

Move keyword arguments into the extra dict.

Keys listed in ignored_meta_keys are left in metadata so that the standard logging machinery can handle them.

Parameters:

  • msg – The log message.

  • metadata – Keyword arguments passed to the logging call.

Returns:

A (msg, metadata) tuple ready for the underlying logger.

class thinlog.LoggingSettings(version: int = 1, formatters: dict[str, dict[str, ~typing.Any]]=<factory>, filters: dict[str, dict[str, ~typing.Any]]=<factory>, handlers: dict[str, dict[str, ~typing.Any]]=<factory>, loggers: dict[str, dict[str, ~typing.Any]]=<factory>, incremental: bool = False, disable_existing_loggers: bool = False, root: dict[str, ~typing.Any]=<factory>)[source]#

Bases: object

Configuration container for logging.config.dictConfig().

All fields mirror the keys accepted by logging.config.dictConfig(). Convert to a plain dict with dataclasses.asdict() before passing to dictConfig (this is handled automatically by configure_logging()).

Parameters:

  • version – Schema version – must be 1.

  • formatters – Formatter definitions keyed by name.

  • filters – Filter definitions keyed by name.

  • handlers – Handler definitions keyed by name.

  • loggers – Logger definitions keyed by name.

  • incremental – If True, merge into the existing configuration.

  • disable_existing_loggers – If True, disable loggers not in loggers.

  • root – Configuration for the root logger.

disable_existing_loggers: bool = False#
filters: dict[str, dict[str, Any]]#
formatters: dict[str, dict[str, Any]]#
handlers: dict[str, dict[str, Any]]#
incremental: bool = False#
loggers: dict[str, dict[str, Any]]#
root: dict[str, Any]#
version: int = 1#
class thinlog.RegisteredLoggers[source]#

Bases: object

Stores logger names so configure_logging() can apply wildcard configs to them.

Loggers are registered automatically when created via get_logger().

classmethod get_registered_logger_names() → list[str][source]#
loggers: ClassVar[set[str]] = {}#
thinlog.configure_logging(name: str, config: LoggingSettings | dict[str, Any], extra: dict[str, Any] | None = None, more_loggers: list[str] | None = None, include_default_logger: bool = False, include_registered_loggers: bool = False, include_root_logger: bool = False, disable_log_errors: bool = True) → KeywordFriendlyLogger[source]#

Set up the logging system and return a ready-to-use logger.

Applies the configuration, starts any QueueHandler listener, and registers an atexit() handler that stops the listener and calls logging.shutdown() on interpreter exit.

Wildcard loggers: If the config contains a logger named "*", its settings are copied to every logger listed in more_loggers (and those gathered from RegisteredLoggers). A specific logger can set "merge": true to extend rather than replace the wildcard config.

Parameters:

  • name – Name of the primary logger to return.

  • config – A LoggingSettings instance or a raw dict suitable for logging.config.dictConfig().

  • extra – Default extra fields for the returned logger.

  • more_loggers – Additional logger names to configure via the wildcard.

  • include_default_logger – If True, add name to more_loggers.

  • include_registered_loggers – If True, include all names from RegisteredLoggers.

  • include_root_logger – If True, apply the wildcard config to the root logger as well.

  • disable_log_errors – If True (default), set logging.raiseExceptions to False.

Returns:

A KeywordFriendlyLogger instance.

thinlog.get_logger(name: str, extra: dict[str, Any] | None, register: bool = True) → KeywordFriendlyLogger[source]#

Create a KeywordFriendlyLogger and optionally register it.

Parameters:

  • name – Logger name (passed to logging.getLogger()).

  • extra – Default extra fields attached to every record.

  • register – If True (default), add name to RegisteredLoggers so it is picked up by the wildcard feature in configure_logging().

Returns:

A LoggerAdapter wrapping the named logger.

Subpackages#

Submodules#

Contents