Source code for pysys.utils.logutils
#!/usr/bin/env python
# PySys System Test Framework, Copyright (C) 2006-2020 M.B. Grieve
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
"""
Log formatting classes that can be used or customized from the project configuration, including support for colored
output on the console.
"""
import copy, logging
from pysys.constants import *
from pysys.utils.pycompat import *
import pysys, threading
[docs]class BaseLogFormatter(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 key to add to the extra={} dict of a logger call to specify the category
CATEGORY = 'log_category'
# the key to add to the extra={} dict of a logger call to specify the arg index for the category
ARG_INDEX = 'log_arg_index'
[docs] @classmethod
def tag(cls, category, arg_index=None):
"""Return dictionary to tag a string to format with color encodings.
:param category: The category, as defined in L{ColorLogFormatter.COLOR_CATEGORIES}
:param 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
:return: A dictionary that can then be used in calls to the logger
"""
if type(arg_index) is int: return {cls.CATEGORY:category, cls.ARG_INDEX:[arg_index]}
if type(arg_index) is list and all(isinstance(i, int) for i in arg_index): return {cls.CATEGORY:category, cls.ARG_INDEX:arg_index}
return {cls.CATEGORY:category}
def __init__(self, propertiesDict):
"""Create an instance of the formatter class.
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
:param propertiesDict: dictionary of formatter-specific options
"""
self.name = propertiesDict.pop('name', None)
super(BaseLogFormatter, self).__init__(
propertiesDict.pop('messagefmt', DEFAULT_FORMAT),
propertiesDict.pop('datefmt', None) )
assert not isinstance(self._fmt, binary_type), 'message format must be a unicode not a byte string otherwise % arg formatting will not work consistently'
if propertiesDict: raise Exception('Unknown formatter option(s) specified: %s'%', '.join(list(propertiesDict.keys())))
[docs]class ColorLogFormatter(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>
:ivar dict(str,str) COLOR_CATEGORIES: the color map for the defined logging categories
:ivar dict(str,str) COLOR_ESCAPE_CODES: the escape codes for each of the support colors
"""
# use a lookup map from message "categories" to colors,
COLOR_CATEGORIES = {
LOG_WARN:'MAGENTA',
LOG_ERROR:'RED',
LOG_TRACEBACK:'RED',
LOG_DEBUG:'BLUE',
LOG_FILE_CONTENTS:'BLUE',
LOG_TEST_DETAILS:'CYAN',
LOG_TEST_OUTCOMES: 'CYAN',
LOG_TEST_PROGRESS: 'CYAN',
LOG_TEST_PERFORMANCE: 'CYAN',
LOG_TIMEOUTS: 'MAGENTA',
LOG_FAILURES: 'RED',
LOG_PASSES: 'GREEN',
LOG_SKIPS: 'YELLOW',
LOG_DIFF_ADDED: 'CYAN', LOG_DIFF_REMOVED: 'MAGENTA', # can't use red/green here without confusion with fail/pass
LOG_END:'END',
}
# by default we use standard ANSI escape sequences, supported by most unix terminals
COLOR_ESCAPE_CODES = {
'BLUE': '',
'GREEN': '',
'YELLOW': '',
'RED': '',
'MAGENTA': '',
'CYAN': '',
'WHITE': '',
'BLACK': '',
'END': '',
}
[docs] @staticmethod
def configureANSIEscapeCodes(bright=None):
"""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
:param 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.
"""
if bright is None: bright = os.getenv('PYSYS_COLOR_BRIGHT','true')=='true'
# by default we use standard ANSI escape sequences, supported by most unix terminals
ColorLogFormatter.COLOR_ESCAPE_CODES = {
'BLACK': '\033[%dm' % (30 if not bright else 90),
'RED': '\033[%dm' % (31 if not bright else 91),
'GREEN': '\033[%dm' % (32 if not bright else 92),
'YELLOW': '\033[%dm' % (33 if not bright else 93),
'BLUE': '\033[%dm' % (34 if not bright else 94),
'MAGENTA': '\033[%dm' % (35 if not bright else 95),
'CYAN': '\033[%dm' % (36 if not bright else 96),
'WHITE': '\033[%dm' % (37 if not bright else 97),
'END': '\033[%dm' % (0),
}
__STDOUT_LOCK = threading.Lock() # global lock shared by all instances of this class
def __init__(self, propertiesDict):
"""Create an instance of the formatter class."""
# extract to override entries in the color map from properties
for prop in list(propertiesDict.keys()):
if prop.startswith('color:'):
self.COLOR_CATEGORIES[prop[len('color:'):].lower()] = propertiesDict.pop(prop).upper()
self.color = None
if 'color' in propertiesDict:
self.color = propertiesDict.pop('color','').lower() == 'true'
if os.getenv('PYSYS_COLOR',None):
self.color = os.getenv('PYSYS_COLOR').lower() == 'true'
if self.color is None:
# heuristically decide on an appropriate default if not configured in the project
if not sys.__stdout__.isatty():
self.color = False
elif not IS_WINDOWS: # most unix terminals will support coloring
self.color = True
else:
try:
import colorama
except Exception:
self.color = False
else:
self.color = True
if self.color:
# initColoringLibrary, which might result in sys.stdout getting rewritten; PySys needs control of sys.stdout
# so capture the new stdout then restore the original
with ColorLogFormatter.__STDOUT_LOCK:
stdoutbak = sys.stdout
try:
sys.stdout = sys.__stdout__
self.initColoringLibrary()
finally:
updatedstdout = sys.stdout
sys.stdout = stdoutbak
# now update the stream used by our handler
if 'PySysPrintRedirector' in repr(updatedstdout):
raise Exception('Formatter has redirector: %s'%repr(updatedstdout))
stdoutHandler.stream.updateUnderlyingStream(updatedstdout)
super(ColorLogFormatter, self).__init__(propertiesDict)
# ensure all outcomes are permitted as possible precedents
for outcome in PRECEDENT:
if LOOKUP[outcome].lower() not in self.COLOR_CATEGORIES:
self.COLOR_CATEGORIES[LOOKUP[outcome].lower()] = self.COLOR_CATEGORIES[LOG_FAILURES] if outcome in FAILS else self.COLOR_CATEGORIES[LOG_PASSES]
for cat in self.COLOR_CATEGORIES: assert self.COLOR_CATEGORIES[cat] in self.COLOR_ESCAPE_CODES, cat
[docs] def formatException(self, exc_info):
"""Format an exception for logging, returning the new value.
:param exc_info: The exception info
:return: The formatted message ready for logging
"""
msg = super(ColorLogFormatter, self).formatException(exc_info)
if self.color:
return self.colorCategoryToEscapeSequence(LOG_TRACEBACK)+ msg + \
self.colorCategoryToEscapeSequence(LOG_END)
else:
return msg
[docs] def format(self, record):
"""Format a log record for logging, returning the new value.
:param record: The message to be formatted
:return: The formatted message ready for logging
"""
if self.color:
try:
cat = getattr(record, self.CATEGORY, None)
if not cat:
if record.levelname == 'WARN': cat = LOG_WARN
elif record.levelname == 'ERROR': cat = LOG_ERROR
elif record.levelname == 'DEBUG': cat = LOG_DEBUG
if cat:
cat = cat.lower()
record = copy.copy(record)
indexes = getattr(record, self.ARG_INDEX, None)
if indexes == None:
record.msg = self.colorCategoryToEscapeSequence(cat)+record.msg+self.colorCategoryToEscapeSequence(LOG_END)
else:
args = list(record.args)
for index in indexes: args[index] = self.formatArg(cat, args[index])
record.args = tuple(args)
except Exception as e:
logging.getLogger('pysys.utils.logutils').debug('Failed to format log message "%s": %s'%(record.msg, repr(e)))
return super(ColorLogFormatter, self).format(record)
[docs] def formatArg(self, category, arg):
"""Format a single argument within a record, based on its category.
:param category: The logging category
:param arg: The argument within the record.
"""
if isstring(arg): return self.colorCategoryToEscapeSequence(category)+arg+self.colorCategoryToEscapeSequence(LOG_END)
return arg
[docs] def colorCategoryToEscapeSequence(self, category):
""" Return the escape sequence to be used for the specified category of logging output.
:param category: The category of the log message
:return: The escape sequence
"""
color = self.COLOR_CATEGORIES.get(category, '<%s>'%category)
return self.COLOR_ESCAPE_CODES.get(color.upper(), '<%s>'%color)
[docs] def initColoringLibrary(self):
"""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).
"""
if OSFAMILY=='windows' and os.getenv('PYSYS_DISABLE_COLORAMA','')!='true':
try:
import colorama
colorama.init()
logging.getLogger('pysys.utils.logutils').debug('Successfully initialized the coloring library')
except Exception as e:
logging.getLogger('pysys.utils.logutils').debug('Failed to load coloring library: %s', repr(e))
ColorLogFormatter.configureANSIEscapeCodes()
[docs]def stdoutPrint(s):
"""
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.
:param s: a unicode or bytes string. A newline will be added automatically.
"""
if isinstance(s, binary_type):
s += b'\n'
else:
s += u'\n'
return stdoutHandler.stream.write(s)