pysys.utils.logutils¶
Log formatting classes that can be used or customized from the project configuration, including support for colored output on the console.
BaseLogFormatter¶
- class pysys.utils.logutils.BaseLogFormatter(propertiesDict)[source]¶
Bases:
logging.Formatter
Base class for formatting log messages.
This implementation delegates everything to logging.Formatter using the messagefmt and datefmt properties. Subclasses may be implemented to provide required customizations, and can be registered by specifying classname in the formatter node of the project configuration file.
The class is constructed with a dictionary of properties, which are configured by providing <property name=”…” value=”…”/> elements or attributes on the formatter node of the project configuration file. Entries in the properties should be specific to the class, and removed when passing the properties to the super class, which will throw an exception if any unexpected options are present
- Parameters
propertiesDict – dictionary of formatter-specific options
- classmethod tag(category, arg_index=None, suppress_prefix=False)[source]¶
Return dictionary to tag a string to format with color encodings.
- Parameters
category – The category, as defined in
ColorLogFormatter.COLOR_CATEGORIES
arg_index – The index of argument in the string expansion to color. This can be either a single integer value representing the index, or a list of integers representing a set of indexes to be colored. Note that format arguments for coloring must be of string type.
suppress_prefix (bool) – Set to True to suppress the timestamp and log level prefix, to save horizontal space on the console. Only do this for log lines where you’re sure these details aren’t needed, for example where a preceding log line with those details) has already been printed and there is no chance of other threads writing interleaving lines to the same device. This flag only affects the colored formatter (as used on the console). Added in v2.1.
- Returns
A dictionary that can then be used in calls to the logger
ColorLogFormatter¶
- class pysys.utils.logutils.ColorLogFormatter(propertiesDict)[source]¶
Bases:
pysys.utils.logutils.BaseLogFormatter
Formatter supporting colored output to a console.
This implementation supports color coding of messages based on the category of the message, and the index of the string in the format encoding. This implementation is the default for console output, with the color coding enabled either by the color option on the formatter set to true.
The
PYSYS_COLOR
environment variable can be set to true or false, overriding any setting specified in the project configuration.The colors used for each category defined by this class can be overridden by specifying “color:XXX” options, e.g.:
<formatter><property name="color:dumped core" value="YELLOW"/></formatter>
- Variables
COLOR_CATEGORIES (dict(str,str)) – the color map for the defined logging categories
COLOR_ESCAPE_CODES (dict(str,str)) – the escape codes for each of the support colors
Create an instance of the formatter class.
- static configureANSIEscapeCodes(bright=None)[source]¶
Sets the ANSI escape codes to be used, either using the extended “bright” colors that look better, or the more widely supported standard ones.
Called during startup, but can also be programatically invoked later
- Parameters
bright – set to False to force only the basic (30-39) codes or True to use the better-looking 90-99 bright codes which are not supported by all terminals. Default is bright=False, but can be overridden by the
PYSYS_COLOR_BASIC
environment var.
- formatException(exc_info)[source]¶
Format an exception for logging, returning the new value.
- Parameters
exc_info – The exception info
- Returns
The formatted message ready for logging
- format(record)[source]¶
Format a log record for logging, returning the new value.
- Parameters
record – The message to be formatted
- Returns
The formatted message ready for logging
- formatArg(category, arg)[source]¶
Format a single argument within a record, based on its category.
- Parameters
category – The logging category
arg – The argument within the record.
- colorCategoryToEscapeSequence(category)[source]¶
Return the escape sequence to be used for the specified category of logging output.
- Parameters
category – The category of the log message
- Returns
The escape sequence
- initColoringLibrary()[source]¶
Initialize any python library required for ensuring ANSI escape sequences can be processed.
The default implementation does nothing on Unix but on Windows attempts to load the “Colorama” library if is is present (unless the environment variable PYSYS_DISABLE_COLORAMA=true is set).
stripANSIEscapeCodes¶
stdoutPrint¶
- pysys.utils.logutils.stdoutPrint(s)[source]¶
Writes the specified bytes or (preferably) unicode character string to stdout, avoiding any redirection to loggers performed by PySys, and performing replacements if needed based on the characters supported by the stdout encoding, and with support for output coloring using escape sequences (if enabled in PySys).
In most cases a logger should be used for output from PySys, but this function is provided as a way to write to stdout for cases where it is truly needed, such as unconditionally writing status messages to a CI system.
- Parameters
s – a unicode or bytes string. A newline will be added automatically.