gain package

Subpackages

Submodules

gain.logging module

Drop-in replacement for stdlib logging with GAIn’s custom levels.

Import this instead of stdlib logging to guarantee TRACE and USER_INFO are registered before any logger is created:

from gain import logging logger = logging.getLogger(__name__) logger.trace(“fine-grained diagnostic”) logger.user_info(“message for the end user”)

Everything exported by stdlib logging is re-exported here (via a star import that honours stdlib’s __all__), so this module tracks the stdlib surface across Python versions instead of a hand-maintained name list. The config and handlers submodules are re-exported too, so from gain import logging; logging.config.dictConfig(...) keeps working.

The custom TRACE / USER_INFO levels (and the Logger.trace / Logger.user_info methods) are registered as an import side effect of gain.utils.log_levels, which monkeypatches logging.Logger globally so that every logger — including the root logger and any already created — gains the methods at runtime.

The same import installs the url-userinfo log-record seam of gain.utils.url_redaction (ADR 0023, gain#1363). Both bootstraps also run from gain/__init__, so importing anything under gain is enough.

For type checkers, getLogger is declared to return a Logger subclass advertising .trace / .user_info. This is a pure typing shim: it is declared before the star import so the type checker adopts the richer return type, while at runtime the star import rebinds getLogger to the stdlib function (identical behaviour — the methods come from the monkeypatch above). Call sites therefore need no # type: ignore[attr-defined] for the custom methods.

Module contents