gouge.colourcli module#

This module contains everything needed to emit colourful messages on the CLI

class gouge.colourcli.Simple(fmt: str | None = None, datefmt: str | None = None, style: str = '%', validate: bool = True, *, defaults: Mapping[str, Any] | None = None, show_exc: bool = False, show_threads: bool = False, force_styling: bool = False, show_pid: bool = False)#

Bases: Formatter

Fancy, colorised log output adding ANSI escape codes to the log output.

Params show_threads:: Whether to display thread names or not.
Params show_exc:: Whether to display tracebacks or not.

Note

This formatter suppresses tracebacks by default! Remember that is is meant to give a concise, readable output. If you need to see tracebacks on the console, you can override this setting using show_exc.

static basicConfig(show_exc: bool = True, show_threads: bool = False, force_styling: bool = False, show_pid: bool = False, **kwargs: Any) → List[Handler]#

Convenience method to have a one-liner set-up.

show_exc, show_threads, show_pid and force_styling are directly passed to Simple. The remaining kwargs are passed on to logging.basicConfig().

After returning from logging.basicConfig(), it will fetch the stderr and stdout handlers and replace the formatter.

The function also returns a list of all handlers which have been modified. This is useful if you want to modify the handlers any further (for example using ShiftingFilter).

colorised_exception(level: int, exc_text: str) → str#: Colorises the exception text based on log level

format(record: LogRecord) → str#

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

gouge.filters module#

This module contains generally useful filters.

class gouge.filters.ShiftingFilter(shift_by: int = 0, logger: str = '', min: int = 0, max: int = 50, offset: int = 0)#

Bases: Filter

This filter will shift the logging level of log records a certain number of log levels.

For example:

ShiftingFilter(1) will convert a message with level INFO to WARNING, and ShiftingFilter(-1) will do the reverse.

An example use-case is controlling log levels of libraries: It is possible that a library emits error-messages, but in the context of your application you would like to see those as warning messages only. If you have no control over that library your hands are tied and the only thing you can do is suppress these messages by changing the level of the associated logger. By modifying the log level using this filter still allows you to see the messages, albeit with another level which is more appropriate to your application.

Note

Filters can either be attached to handlers or loggers. But be aware that when attaching to loggers, they will only trigger on the exact logger they were attached to. Not in the parent hierarchy! See logging.Filter.filter() for details. To simplify attaching to loggers, this class offers the method inject().

Parameters:

shift_by – The number of levels to shift. Positive integers will increase the level, negative integers will decrease it.
logger – This and all child loggers will be shifted.
min – Don’t shift below this level.
max – Don’t shift above this level.
offset – An explicit, fine-grained offset value. This overrides shift_by!

cleanup() → None#: Remove all filters applied via inject().

filter(record: LogRecord) → bool#

Always returns True but will modify the logging level of record by the rules defined in this filter.

See logging.Filter.filter()

inject(parent: str) → None#

Loop over each known logger and attach this filter.

You can remove the attached filters again using cleanup().

Note

This will only attach the filter to loggers which already exist! If you see that something is not working as expected, make sure the logger exists before calling this! You can look at all the existing loggers using logging.Logger.manager.loggerDict.

Parameters:: parent – Attach the filter to this and all descendant loggers.

gouge.parseable module#

class gouge.parseable.CSVLog(fmt: str | None = None, datefmt: str | None = None)#

Bases: Formatter

CSV formatter for python loggers.

The columns correspond to the following fields:

created
filename
funcName
levelname
levelno
lineno
module
msecs
name
pathname
process
processName
relativeCreated
thread
threadName
message
exc_text

static basicConfig(**kwargs: Any) → None#

format(record: LogRecord) → str#

Format the specified record as text.

class gouge.parseable.XMLLog(fmt: str | None = None, datefmt: str | None = None)#

Bases: Formatter

XML formatter for python loggers.

The records have the following schema:

<record>
    <created />
    <filename />
    <funcName />
    <levelname />
    <levelno />
    <lineno />
    <module />
    <msecs />
    <name />
    <pathname />
    <process />
    <processName />
    <relativeCreated />
    <thread />
    <threadName />
    <message />
    <exc_text />
</record>

static basicConfig(**kwargs: Any) → None#

format(record: LogRecord) → str#

Format the specified record as text.