API documentation

The following documentation is based on the source code of version 15.0.1 of the coloredlogs package.

The most useful entry points into the documentation are install(), ColoredFormatter and enable_system_logging().

The coloredlogs module

Colored terminal output for Python’s logging module.

Getting started

The easiest way to get started is by importing coloredlogs and calling coloredlogs.install() (similar to logging.basicConfig()):

>>> import coloredlogs, logging
>>> coloredlogs.install(level='DEBUG')
>>> logger = logging.getLogger('some.module.name')
>>> logger.info("this is an informational message")
2015-10-22 19:13:52 peter-macbook some.module.name[28036] INFO this is an informational message

The install() function creates a ColoredFormatter that injects ANSI escape sequences into the log output.

Environment variables

The following environment variables can be used to configure the coloredlogs module without writing any code:

Environment variable	Default value	Type of value
$COLOREDLOGS_AUTO_INSTALL	‘false’	a boolean that controls whether auto_install() is called
$COLOREDLOGS_LOG_LEVEL	‘INFO’	a log level name
$COLOREDLOGS_LOG_FORMAT	DEFAULT_LOG_FORMAT	a log format string
$COLOREDLOGS_DATE_FORMAT	DEFAULT_DATE_FORMAT	a date/time format string
$COLOREDLOGS_LEVEL_STYLES	DEFAULT_LEVEL_STYLES	see parse_encoded_styles()
$COLOREDLOGS_FIELD_STYLES	DEFAULT_FIELD_STYLES	see parse_encoded_styles()

If the environment variable $NO_COLOR is set (the value doesn’t matter, even an empty string will do) then coloredlogs.install() will take this as a hint that colors should not be used (unless the isatty=True override was passed by the caller).

Examples of customization

Here we’ll take a look at some examples of how you can customize coloredlogs using environment variables.

About the defaults

Here’s a screen shot of the default configuration for easy comparison with the screen shots of the following customizations (this is the same screen shot that is shown in the introduction):

The screen shot above was taken from urxvt which doesn’t support faint text colors, otherwise the color of green used for debug messages would have differed slightly from the color of green used for spam messages.

Apart from the faint style of the spam level, the default configuration of coloredlogs sticks to the eight color palette defined by the original ANSI standard, in order to provide a somewhat consistent experience across terminals and terminal emulators.

Available text styles and colors

Of course you are free to customize the default configuration, in this case you can use any text style or color that you know is supported by your terminal. You can use the humanfriendly --demo command to try out the supported text styles and colors:

Changing the log format

The simplest customization is to change the log format, for example:

$ export COLOREDLOGS_LOG_FORMAT='[%(hostname)s] %(asctime)s %(message)s'
$ coloredlogs --demo
[peter-mbp] 2018-01-14 15:45:44 message with level spam (5)
[peter-mbp] 2018-01-14 15:45:45 message with level debug (10)
[peter-mbp] 2018-01-14 15:45:46 message with level verbose (15)
[peter-mbp] 2018-01-14 15:45:47 message with level info (20)
[peter-mbp] 2018-01-14 15:45:48 message with level notice (25)
[peter-mbp] 2018-01-14 15:45:49 message with level warning (30)
[peter-mbp] 2018-01-14 15:45:50 message with level success (35)
[peter-mbp] 2018-01-14 15:45:51 message with level error (40)
[peter-mbp] 2018-01-14 15:45:52 message with level critical (50)

Here’s what that looks like in a terminal (I always work in terminals with a black background and white text):

Changing the date/time format

You can also change the date/time format, for example you can remove the date part and leave only the time:

$ export COLOREDLOGS_LOG_FORMAT='%(asctime)s - %(message)s'
$ export COLOREDLOGS_DATE_FORMAT='%H:%M:%S'
$ coloredlogs --demo
15:45:34 - message with level spam (5)
15:45:35 - message with level debug (10)
15:45:36 - message with level verbose (15)
15:45:37 - message with level info (20)
15:45:38 - message with level notice (25)
15:45:39 - message with level warning (30)
15:45:40 - message with level success (35)
15:45:41 - message with level error (40)
15:45:42 - message with level critical (50)

Here’s what it looks like in a terminal:

Changing the colors/styles

Finally you can customize the colors and text styles that are used:

$ export COLOREDLOGS_LOG_FORMAT='%(asctime)s - %(message)s'
$ export COLOREDLOGS_DATE_FORMAT='%H:%M:%S'
$ export COLOREDLOGS_FIELD_STYLES='' # no styles
$ export COLOREDLOGS_LEVEL_STYLES='spam=22;debug=28;verbose=34;notice=220;warning=202;success=118,bold;error=124;critical=background=red'
$ coloredlogs --demo
15:45:23 - message with level spam (5)
15:45:24 - message with level debug (10)
15:45:25 - message with level verbose (15)
15:45:26 - message with level info (20)
15:45:27 - message with level notice (25)
15:45:28 - message with level warning (30)
15:45:29 - message with level success (35)
15:45:30 - message with level error (40)
15:45:31 - message with level critical (50)

Here’s an explanation of the features used here:

• The numbers used in $COLOREDLOGS_LEVEL_STYLES demonstrate the use of 256 color mode (the numbers refer to the 256 color mode palette which is fixed).

• The success level demonstrates the use of a text style (bold).

• The critical level demonstrates the use of a background color (red).

Of course none of this can be seen in the shell transcript quoted above, but take a look at the following screen shot:

Some notes about log levels

With regards to the handling of log levels, the coloredlogs package differs from Python’s logging module in two aspects:

1. While the logging module uses the default logging level logging.WARNING, the coloredlogs package has always used logging.INFO as its default log level.

2. When logging to the terminal or system log is initialized by install() or enable_system_logging() the effective level [1] of the selected logger [2] is compared against the requested level [3] and if the effective level is more restrictive than the requested level, the logger’s level will be set to the requested level (this happens in adjust_level()). The reason for this is to work around a combination of design choices in Python’s logging module that can easily confuse people who aren’t already intimately familiar with it:

   • All loggers are initialized with the level logging.NOTSET.

   • When a logger’s level is set to logging.NOTSET the getEffectiveLevel() method will fall back to the level of the parent logger.

   • The parent of all loggers is the root logger and the root logger has its level set to logging.WARNING by default (after importing the logging module).

   Effectively all user defined loggers inherit the default log level logging.WARNING from the root logger, which isn’t very intuitive for those who aren’t already familiar with the hierarchical nature of the logging module.

   By avoiding this potentially confusing behavior (see #14, #18, #21, #23 and #24), while at the same time allowing the caller to specify a logger object, my goal and hope is to provide sane defaults that can easily be changed when the need arises.

   [1]

   Refer to logging.Logger.getEffectiveLevel() for details.

   [2]

   The logger that is passed as an argument by the caller or the root logger which is selected as a default when no logger is provided.

   [3]

   The log level that is passed as an argument by the caller or the default log level logging.INFO when no level is provided.

Classes and functions

coloredlogs.DEFAULT_LOG_LEVEL = 20

The default log level for coloredlogs (logging.INFO).

coloredlogs.DEFAULT_LOG_FORMAT = '%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s'

The default log format for ColoredFormatter objects (a string).

coloredlogs.DEFAULT_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'

The default date/time format for ColoredFormatter objects (a string).

coloredlogs.CHROOT_FILES = ['/etc/debian_chroot']

A list of filenames that indicate a chroot and contain the name of the chroot.

coloredlogs.DEFAULT_FIELD_STYLES = {'asctime': {'color': 'green'}, 'hostname': {'color': 'magenta'}, 'levelname': {'bold': True, 'color': 'black'}, 'name': {'color': 'blue'}, 'programname': {'color': 'cyan'}, 'username': {'color': 'yellow'}}

Mapping of log format names to default font styles.

coloredlogs.DEFAULT_LEVEL_STYLES = {'critical': {'bold': True, 'color': 'red'}, 'debug': {'color': 'green'}, 'error': {'color': 'red'}, 'info': {}, 'notice': {'color': 'magenta'}, 'spam': {'color': 'green', 'faint': True}, 'success': {'bold': True, 'color': 'green'}, 'verbose': {'color': 'blue'}, 'warning': {'color': 'yellow'}}

Mapping of log level names to default font styles.

coloredlogs.DEFAULT_FORMAT_STYLE = '%'

The default logging format style (a single character).

coloredlogs.FORMAT_STYLE_PATTERNS = {'$': '\\$(\\w+)|\\${(\\w+)}', '%': '%\\((\\w+)\\)[#0 +-]*\\d*(?:\\.\\d+)?[hlL]?[diouxXeEfFgGcrs%]', '{': '{(\\w+)[^}]*}'}

A dictionary that maps the style characters %, { and $ (see the documentation of the logging.Formatter class in Python 3.2+) to strings containing regular expression patterns that can be used to parse format strings in the corresponding style:

%

A string containing a regular expression that matches a “percent conversion specifier” as defined in the String Formatting Operations section of the Python documentation. Here’s an example of a logging format string in this format: %(levelname)s:%(name)s:%(message)s.

{

A string containing a regular expression that matches a “replacement field” as defined in the Format String Syntax section of the Python documentation. Here’s an example of a logging format string in this format: {levelname}:{name}:{message}.

$

A string containing a regular expression that matches a “substitution placeholder” as defined in the Template Strings section of the Python documentation. Here’s an example of a logging format string in this format: $levelname:$name:$message.

These regular expressions are used by FormatStringParser to introspect and manipulate logging format strings.

coloredlogs.auto_install()

Automatically call install() when $COLOREDLOGS_AUTO_INSTALL is set.

The coloredlogs package includes a path configuration file that automatically imports the coloredlogs module and calls auto_install() when the environment variable $COLOREDLOGS_AUTO_INSTALL is set.

This function uses coerce_boolean() to check whether the value of $COLOREDLOGS_AUTO_INSTALL should be considered True.

coloredlogs.install(level=None, **kw)

Enable colored terminal output for Python’s logging module.

Parameters:

• level – The default logging level (an integer or a string with a level name, defaults to DEFAULT_LOG_LEVEL).

• logger – The logger to which the stream handler should be attached (a Logger object, defaults to the root logger).

• fmt – Set the logging format (a string like those accepted by Formatter, defaults to DEFAULT_LOG_FORMAT).

• datefmt – Set the date/time format (a string, defaults to DEFAULT_DATE_FORMAT).

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE). See the documentation of the logging.Formatter class in Python 3.2+. On older Python versions only % is supported.

• milliseconds – True to show milliseconds like logging does by default, False to hide milliseconds (the default is False, see #16).

• level_styles – A dictionary with custom level styles (defaults to DEFAULT_LEVEL_STYLES).

• field_styles – A dictionary with custom field styles (defaults to DEFAULT_FIELD_STYLES).

• stream – The stream where log messages should be written to (a file-like object). This defaults to None which means StandardErrorHandler is used.

• isatty – True to use a ColoredFormatter, False to use a normal Formatter (defaults to auto-detection using terminal_supports_colors()).

• reconfigure – If True (the default) multiple calls to coloredlogs.install() will each override the previous configuration.

• use_chroot – Refer to HostNameFilter.

• programname – Refer to ProgramNameFilter.

• username – Refer to UserNameFilter.

• syslog – If True then enable_system_logging() will be called without arguments (defaults to False). The syslog argument may also be a number or string, in this case it is assumed to be a logging level which is passed on to enable_system_logging().

The coloredlogs.install() function is similar to logging.basicConfig(), both functions take a lot of optional keyword arguments but try to do the right thing by default:

1. If reconfigure is True (it is by default) and an existing StreamHandler is found that is connected to either stdout or stderr the handler will be removed. This means that first calling logging.basicConfig() and then calling coloredlogs.install() will replace the stream handler instead of adding a duplicate stream handler. If reconfigure is False and an existing handler is found no further steps are taken (to avoid installing a duplicate stream handler).

2. A StreamHandler is created and connected to the stream given by the stream keyword argument (sys.stderr by default). The stream handler’s level is set to the value of the level keyword argument.

3. A ColoredFormatter is created if the isatty keyword argument allows it (or auto-detection allows it), otherwise a normal Formatter is created. The formatter is initialized with the fmt and datefmt keyword arguments (or their computed defaults).

   The environment variable $NO_COLOR is taken as a hint by auto-detection that colors should not be used.

4. HostNameFilter.install(), ProgramNameFilter.install() and UserNameFilter.install() are called to enable the use of additional fields in the log format.

5. If the logger’s level is too restrictive it is relaxed (refer to notes about log levels for details).

6. The formatter is added to the handler and the handler is added to the logger.

coloredlogs.check_style(value)

Validate a logging format style.

Parameters:

value – The logging format style to validate (any value).

Returns:

The logging format character (a string of one character).

Raises:

ValueError when the given style isn’t supported.

On Python 3.2+ this function accepts the logging format styles %, { and $ while on older versions only % is accepted (because older Python versions don’t support alternative logging format styles).

coloredlogs.increase_verbosity()

Increase the verbosity of the root handler by one defined level.

Understands custom logging levels like defined by my verboselogs module.

coloredlogs.decrease_verbosity()

Decrease the verbosity of the root handler by one defined level.

Understands custom logging levels like defined by my verboselogs module.

coloredlogs.is_verbose()

Check whether the log level of the root handler is set to a verbose level.

Returns:

True if the root handler is verbose, False if not.

coloredlogs.get_level()

Get the logging level of the root handler.

Returns:

The logging level of the root handler (an integer) or DEFAULT_LOG_LEVEL (if no root handler exists).

coloredlogs.set_level(level)

Set the logging level of the root handler.

Parameters:

level – The logging level to filter on (an integer or string).

If no root handler exists yet this automatically calls install().

coloredlogs.adjust_level(logger, level)

Increase a logger’s verbosity up to the requested level.

Parameters:

• logger – The logger to change (a Logger object).

• level – The log level to enable (a string or number).

This function is used by functions like install(), increase_verbosity() and enable_system_logging() to adjust a logger’s level so that log messages up to the requested log level are propagated to the configured output handler(s).

It uses logging.Logger.getEffectiveLevel() to check whether logger propagates or swallows log messages of the requested level and sets the logger’s level to the requested level if it would otherwise swallow log messages.

Effectively this function will “widen the scope of logging” when asked to do so but it will never “narrow the scope of logging”. This is because I am convinced that filtering of log messages should (primarily) be decided by handlers.

coloredlogs.find_defined_levels()

Find the defined logging levels.

Returns:

A dictionary with level names as keys and integers as values.

Here’s what the result looks like by default (when no custom levels or level names have been defined):

>>> find_defined_levels()
{'NOTSET': 0,
 'DEBUG': 10,
 'INFO': 20,
 'WARN': 30,
 'WARNING': 30,
 'ERROR': 40,
 'FATAL': 50,
 'CRITICAL': 50}

coloredlogs.level_to_number(value)

Coerce a logging level name to a number.

Parameters:

value – A logging level (integer or string).

Returns:

The number of the log level (an integer).

This function translates log level names into their numeric values..

coloredlogs.find_level_aliases()

Find log level names which are aliases of each other.

Returns:

A dictionary that maps aliases to their canonical name.

Note

Canonical names are chosen to be the alias with the longest string length so that e.g. WARN is an alias for WARNING instead of the other way around.

Here’s what the result looks like by default (when no custom levels or level names have been defined):

>>> from coloredlogs import find_level_aliases
>>> find_level_aliases()
{'WARN': 'WARNING', 'FATAL': 'CRITICAL'}

coloredlogs.parse_encoded_styles(text, normalize_key=None)

Parse text styles encoded in a string into a nested data structure.

Parameters:

text – The encoded styles (a string).

Returns:

A dictionary in the structure of the DEFAULT_FIELD_STYLES and DEFAULT_LEVEL_STYLES dictionaries.

Here’s an example of how this function works:

>>> from coloredlogs import parse_encoded_styles
>>> from pprint import pprint
>>> encoded_styles = 'debug=green;warning=yellow;error=red;critical=red,bold'
>>> pprint(parse_encoded_styles(encoded_styles))
{'debug': {'color': 'green'},
 'warning': {'color': 'yellow'},
 'error': {'color': 'red'},
 'critical': {'bold': True, 'color': 'red'}}

coloredlogs.find_hostname(use_chroot=True)

Find the host name to include in log messages.

Parameters:

use_chroot – Use the name of the chroot when inside a chroot? (boolean, defaults to True)

Returns:

A suitable host name (a string).

Looks for CHROOT_FILES that have a nonempty first line (taken to be the chroot name). If none are found then socket.gethostname() is used as a fall back.

coloredlogs.find_program_name()

Select a suitable program name to embed in log messages.

Returns:

One of the following strings (in decreasing order of preference):

1. The base name of the currently running Python program or script (based on the value at index zero of sys.argv).

2. The base name of the Python executable (based on sys.executable).

3. The string ‘python’.

coloredlogs.find_username()

Find the username to include in log messages.

Returns:

A suitable username (a string).

On UNIX systems this uses the pwd module which means root will be reported when sudo is used (as it should). If this fails (for example on Windows) then getpass.getuser() is used as a fall back.

coloredlogs.replace_handler(logger, match_handler, reconfigure)

Prepare to replace a handler.

Parameters:

• logger – Refer to find_handler().

• match_handler – Refer to find_handler().

• reconfigure – True if an existing handler should be replaced, False otherwise.

Returns:

A tuple of two values:

1. The matched Handler object or None if no handler was matched.

2. The Logger to which the matched handler was attached or the logger given to replace_handler().

coloredlogs.find_handler(logger, match_handler)

Find a (specific type of) handler in the propagation tree of a logger.

Parameters:

• logger – The logger to check (a Logger object).

• match_handler – A callable that receives a Handler object and returns True to match a handler or False to skip that handler and continue searching for a match.

Returns:

A tuple of two values:

1. The matched Handler object or None if no handler was matched.

2. The Logger object to which the handler is attached or None if no handler was matched.

This function finds a logging handler (of the given type) attached to a logger or one of its parents (see walk_propagation_tree()). It uses the undocumented handlers attribute to find handlers attached to a logger, however it won’t raise an exception if the attribute isn’t available. The advantages of this approach are:

• This works regardless of whether coloredlogs attached the handler or other Python code attached the handler.

• This will correctly recognize the situation where the given logger has no handlers but propagate is enabled and the logger has a parent logger that does have a handler attached.

coloredlogs.match_stream_handler(handler, streams=[])

Identify stream handlers writing to the given streams(s).

Parameters:

• handler – The Handler class to check.

• streams – A sequence of streams to match (defaults to matching stdout and stderr).

Returns:

True if the handler is a StreamHandler logging to the given stream(s), False otherwise.

This function can be used as a callback for find_handler().

coloredlogs.walk_propagation_tree(logger)

Walk through the propagation hierarchy of the given logger.

Parameters:

logger – The logger whose hierarchy to walk (a Logger object).

Returns:

A generator of Logger objects.

Note

This uses the undocumented logging.Logger.parent attribute to find higher level loggers, however it won’t raise an exception if the attribute isn’t available.

class coloredlogs.BasicFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Log Formatter that supports %f for millisecond formatting.

This class extends Formatter to enable the use of %f for millisecond formatting in date/time strings, to allow for the type of flexibility requested in issue #45.

formatTime(record, datefmt=None)

Format the date/time of a log record.

Parameters:

• record – A LogRecord object.

• datefmt – A date/time format string (defaults to DEFAULT_DATE_FORMAT).

Returns:

The formatted date/time (a string).

This method overrides formatTime() to set datefmt to DEFAULT_DATE_FORMAT when the caller hasn’t specified a date format.

When datefmt contains the token %f it will be replaced by the value of %(msecs)03d (refer to issue #45 for use cases).

class coloredlogs.ColoredFormatter(fmt=None, datefmt=None, style='%', level_styles=None, field_styles=None)

Log Formatter that uses ANSI escape sequences to create colored logs.

ColoredFormatter inherits from BasicFormatter to enable the use of %f for millisecond formatting in date/time strings.

Note

If you want to use ColoredFormatter on Windows then you need to call enable_ansi_support(). This is done for you when you call coloredlogs.install().

__init__(fmt=None, datefmt=None, style='%', level_styles=None, field_styles=None)

Initialize a ColoredFormatter object.

Parameters:

• fmt – A log format string (defaults to DEFAULT_LOG_FORMAT).

• datefmt – A date/time format string (defaults to None, but see the documentation of BasicFormatter.formatTime()).

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE)

• level_styles – A dictionary with custom level styles (defaults to DEFAULT_LEVEL_STYLES).

• field_styles – A dictionary with custom field styles (defaults to DEFAULT_FIELD_STYLES).

Raises:

Refer to check_style().

This initializer uses colorize_format() to inject ANSI escape sequences in the log format string before it is passed to the initializer of the base class.

colorize_format(fmt, style='%')

Rewrite a logging format string to inject ANSI escape sequences.

Parameters:

• fmt – The log format string.

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE).

Returns:

The logging format string with ANSI escape sequences.

This method takes a logging format string like the ones you give to logging.Formatter and processes it as follows:

1. First the logging format string is separated into formatting directives versus surrounding text (according to the given style).

2. Then formatting directives and surrounding text are grouped based on whitespace delimiters (in the surrounding text).

3. For each group styling is selected as follows:

   1. If the group contains a single formatting directive that has a style defined then the whole group is styled accordingly.

   2. If the group contains multiple formatting directives that have styles defined then each formatting directive is styled individually and surrounding text isn’t styled.

As an example consider the default log format (DEFAULT_LOG_FORMAT):

%(asctime)s %(hostname)s %(name)s[%(process)d] %(levelname)s %(message)s

The default field styles (DEFAULT_FIELD_STYLES) define a style for the name field but not for the process field, however because both fields are part of the same whitespace delimited token they’ll be highlighted together in the style defined for the name field.

format(record)

Apply level-specific styling to log records.

Parameters:

record – A LogRecord object.

Returns:

The result of logging.Formatter.format().

This method injects ANSI escape sequences that are specific to the level of each log record (because such logic cannot be expressed in the syntax of a log format string). It works by making a copy of the log record, changing the msg field inside the copy and passing the copy into the format() method of the base class.

class coloredlogs.Empty

An empty class used to copy LogRecord objects without reinitializing them.

class coloredlogs.HostNameFilter(use_chroot=True)

Log filter to enable the %(hostname)s format.

Python’s logging module doesn’t expose the system’s host name while I consider this to be a valuable addition. Fortunately it’s very easy to expose additional fields in format strings: filter() simply sets the hostname attribute of each LogRecord object it receives and this is enough to enable the use of the %(hostname)s expression in format strings.

You can install this log filter as follows:

>>> import coloredlogs, logging
>>> handler = logging.StreamHandler()
>>> handler.addFilter(coloredlogs.HostNameFilter())
>>> handler.setFormatter(logging.Formatter('[%(hostname)s] %(message)s'))
>>> logger = logging.getLogger()
>>> logger.addHandler(handler)
>>> logger.setLevel(logging.INFO)
>>> logger.info("Does it work?")
[peter-macbook] Does it work?

Of course coloredlogs.install() does all of this for you :-).

classmethod install(handler, fmt=None, use_chroot=True, style='%')

Install the HostNameFilter on a log handler (only if needed).

Parameters:

• fmt – The log format string to check for %(hostname).

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE).

• handler – The logging handler on which to install the filter.

• use_chroot – Refer to find_hostname().

If fmt is given the filter will only be installed if fmt uses the hostname field. If fmt is not given the filter is installed unconditionally.

__init__(use_chroot=True)

Initialize a HostNameFilter object.

Parameters:

use_chroot – Refer to find_hostname().

filter(record)

Set each LogRecord’s hostname field.

class coloredlogs.ProgramNameFilter(programname=None)

Log filter to enable the %(programname)s format.

Python’s logging module doesn’t expose the name of the currently running program while I consider this to be a useful addition. Fortunately it’s very easy to expose additional fields in format strings: filter() simply sets the programname attribute of each LogRecord object it receives and this is enough to enable the use of the %(programname)s expression in format strings.

Refer to HostNameFilter for an example of how to manually install these log filters.

classmethod install(handler, fmt, programname=None, style='%')

Install the ProgramNameFilter (only if needed).

Parameters:

• fmt – The log format string to check for %(programname).

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE).

• handler – The logging handler on which to install the filter.

• programname – Refer to __init__().

If fmt is given the filter will only be installed if fmt uses the programname field. If fmt is not given the filter is installed unconditionally.

__init__(programname=None)

Initialize a ProgramNameFilter object.

Parameters:

programname – The program name to use (defaults to the result of find_program_name()).

filter(record)

Set each LogRecord’s programname field.

class coloredlogs.UserNameFilter(username=None)

Log filter to enable the %(username)s format.

Python’s logging module doesn’t expose the username of the currently logged in user as requested in #76. Given that HostNameFilter and ProgramNameFilter are already provided by coloredlogs it made sense to provide UserNameFilter as well.

Refer to HostNameFilter for an example of how to manually install these log filters.

classmethod install(handler, fmt, username=None, style='%')

Install the UserNameFilter (only if needed).

Parameters:

• fmt – The log format string to check for %(username).

• style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE).

• handler – The logging handler on which to install the filter.

• username – Refer to __init__().

If fmt is given the filter will only be installed if fmt uses the username field. If fmt is not given the filter is installed unconditionally.

__init__(username=None)

Initialize a UserNameFilter object.

Parameters:

username – The username to use (defaults to the result of find_username()).

filter(record)

Set each LogRecord’s username field.

class coloredlogs.StandardErrorHandler(level=0)

A StreamHandler that gets the value of sys.stderr for each log message.

The StandardErrorHandler class enables monkey patching of sys.stderr. It’s basically the same as the logging._StderrHandler class present in Python 3 but it will be available regardless of Python version. This handler is used by coloredlogs.install() to improve compatibility with the Python standard library.

__init__(level=0)

Initialize a StandardErrorHandler object.

property stream

Get the value of sys.stderr (a file-like object).

class coloredlogs.FormatStringParser(style='%')

Shallow logging format string parser.

This class enables introspection and manipulation of logging format strings in the three styles supported by the logging module starting from Python 3.2 (%, { and $).

__init__(style='%')

Initialize a FormatStringParser object.

Parameters:

style – One of the characters %, { or $ (defaults to DEFAULT_FORMAT_STYLE).

Raises:

Refer to check_style().

contains_field(format_string, field_name)

Get the field names referenced by a format string.

Parameters:

format_string – The logging format string.

Returns:

A list of strings with field names.

get_field_names(format_string)

Get the field names referenced by a format string.

Parameters:

format_string – The logging format string.

Returns:

A list of strings with field names.

get_grouped_pairs(format_string)

Group the results of get_pairs() separated by whitespace.

Parameters:

format_string – The logging format string.

Returns:

A list of lists of FormatStringToken objects.

get_pairs(format_string)

Tokenize a logging format string and extract field names from tokens.

Parameters:

format_string – The logging format string.

Returns:

A generator of FormatStringToken objects.

get_pattern(field_name)

Get a regular expression to match a formatting directive that references the given field name.

Parameters:

field_name – The name of the field to match (a string).

Returns:

A compiled regular expression object.

get_tokens(format_string)

Tokenize a logging format string.

Parameters:

format_string – The logging format string.

Returns:

A list of strings with formatting directives separated from surrounding text.

class coloredlogs.FormatStringToken(text, name)

A named tuple for the results of FormatStringParser.get_pairs().

name

The field name referenced in text (a string). If text doesn’t contain a formatting directive this will be None.

text

The text extracted from the logging format string (a string).

class coloredlogs.NameNormalizer

Responsible for normalizing field and level names.

__init__()

Initialize a NameNormalizer object.

normalize_name(name)

Normalize a field or level name.

Parameters:

name – The field or level name (a string).

Returns:

The normalized name (a string).

Transforms all strings to lowercase and resolves level name aliases (refer to find_level_aliases()) to their canonical name:

>>> from coloredlogs import NameNormalizer
>>> from humanfriendly import format_table
>>> nn = NameNormalizer()
>>> sample_names = ['DEBUG', 'INFO', 'WARN', 'WARNING', 'ERROR', 'FATAL', 'CRITICAL']
>>> print(format_table([(n, nn.normalize_name(n)) for n in sample_names]))
-----------------------
| DEBUG    | debug    |
| INFO     | info     |
| WARN     | warning  |
| WARNING  | warning  |
| ERROR    | error    |
| FATAL    | critical |
| CRITICAL | critical |
-----------------------

normalize_keys(value)

Normalize the keys of a dictionary using normalize_name().

Parameters:

value – The dictionary to normalize.

Returns:

A dictionary with normalized keys.

get(normalized_dict, name)

Get a value from a dictionary after normalizing the key.

Parameters:

• normalized_dict – A dictionary produced by normalize_keys().

• name – A key to normalize and get from the dictionary.

Returns:

The value of the normalized key (if any).

The coloredlogs.converter module

Convert text with ANSI escape sequences to HTML.

coloredlogs.converter.capture(command, encoding='UTF-8')

Capture the output of an external command as if it runs in an interactive terminal.

Parameters:

• command – The command name and its arguments (a list of strings).

• encoding – The encoding to use to decode the output (a string).

Returns:

The output of the command.

This function runs an external command under script (emulating an interactive terminal) to capture the output of the command as if it was running in an interactive terminal (including ANSI escape sequences).

coloredlogs.converter.convert(text, code=True, tabsize=4)

Convert text with ANSI escape sequences to HTML.

Parameters:

• text – The text with ANSI escape sequences (a string).

• code – Whether to wrap the returned HTML fragment in a <code>...</code> element (a boolean, defaults to True).

• tabsize – Refer to str.expandtabs() for details.

Returns:

The text converted to HTML (a string).

coloredlogs.converter.encode_whitespace(text, tabsize=4)

Encode whitespace so that web browsers properly render it.

Parameters:

• text – The plain text (a string).

• tabsize – Refer to str.expandtabs() for details.

Returns:

The text converted to HTML (a string).

The purpose of this function is to encode whitespace in such a way that web browsers render the same whitespace regardless of whether ‘preformatted’ styling is used (by wrapping the text in a <pre>...</pre> element).

Note

While the string manipulation performed by this function is specifically intended not to corrupt the HTML generated by convert() it definitely does have the potential to corrupt HTML from other sources. You have been warned :-).

coloredlogs.converter.encode_whitespace_cb(match)

Replace runs of multiple spaces with non-breaking spaces.

Parameters:

match – A regular expression match object.

Returns:

The replacement string.

This function is used by func:encode_whitespace() as a callback for replacement using a regular expression pattern.

coloredlogs.converter.html_encode(text)

Encode characters with a special meaning as HTML.

Parameters:

text – The plain text (a string).

Returns:

The text converted to HTML (a string).

coloredlogs.converter.parse_hex_color(value)

Convert a CSS color in hexadecimal notation into its R, G, B components.

Parameters:

value – A CSS color in hexadecimal notation (a string like ‘#000000’).

Returns:

A tuple with three integers (with values between 0 and 255) corresponding to the R, G and B components of the color.

Raises:

ValueError on values that can’t be parsed.

coloredlogs.converter.select_text_color(r, g, b)

Choose a suitable color for the inverse text style.

Parameters:

• r – The amount of red (an integer between 0 and 255).

• g – The amount of green (an integer between 0 and 255).

• b – The amount of blue (an integer between 0 and 255).

Returns:

A CSS color in hexadecimal notation (a string).

In inverse mode the color that is normally used for the text is instead used for the background, however this can render the text unreadable. The purpose of select_text_color() is to make an effort to select a suitable text color. Based on http://stackoverflow.com/a/3943023/112731.

class coloredlogs.converter.ColoredCronMailer

Easy to use integration between coloredlogs and the UNIX cron daemon.

By using ColoredCronMailer as a context manager in the command line interface of your Python program you make it trivially easy for users of your program to opt in to HTML output under cron: The only thing the user needs to do is set CONTENT_TYPE="text/html" in their crontab!

Under the hood this requires quite a bit of magic and I must admit that I developed this code simply because I was curious whether it could even be done :-). It requires my capturer package which you can install using pip install 'coloredlogs[cron]'. The [cron] extra will pull in the capturer 2.4 or newer which is required to capture the output while silencing it - otherwise you’d get duplicate output in the emails sent by cron.

__init__()

Initialize output capturing when running under cron with the correct configuration.

__enter__()

Start capturing output (when applicable).

__exit__(exc_type=None, exc_value=None, traceback=None)

Stop capturing output and convert the output to HTML (when applicable).

silence()

Tell __exit__() to swallow all output (things will be silent).

This can be useful when a Python program is written in such a way that it has already produced output by the time it becomes apparent that nothing useful can be done (say in a cron job that runs every few minutes :-p). By calling silence() the output can be swallowed retroactively, avoiding useless emails from cron.

The coloredlogs.syslog module

Easy to use UNIX system logging for Python’s logging module.

Admittedly system logging has little to do with colored terminal output, however:

• The coloredlogs package is my attempt to do Python logging right and system logging is an important part of that equation.

• I’ve seen a surprising number of quirks and mistakes in system logging done in Python, for example including %(asctime)s in a format string (the system logging daemon is responsible for adding timestamps and thus you end up with duplicate timestamps that make the logs awful to read :-).

• The %(programname)s filter originated in my system logging code and I wanted it in coloredlogs so the step to include this module wasn’t that big.

• As a bonus this Python module now has a test suite and proper documentation.

So there :-P. Go take a look at enable_system_logging().

coloredlogs.syslog.LOG_DEVICE_MACOSX = '/var/run/syslog'

The pathname of the log device on Mac OS X (a string).

coloredlogs.syslog.LOG_DEVICE_UNIX = '/dev/log'

The pathname of the log device on Linux and most other UNIX systems (a string).

coloredlogs.syslog.DEFAULT_LOG_FORMAT = '%(programname)s[%(process)d]: %(levelname)s %(message)s'

The default format for log messages sent to the system log (a string).

The %(programname)s format requires ProgramNameFilter but enable_system_logging() takes care of this for you.

The name[pid]: construct (specifically the colon) in the format allows rsyslogd to extract the $programname from each log message, which in turn allows configuration files in /etc/rsyslog.d/*.conf to filter these log messages to a separate log file (if the need arises).

class coloredlogs.syslog.SystemLogging(*args, **kw)

Context manager to enable system logging.

__init__(*args, **kw)

Initialize a SystemLogging object.

Parameters:

• args – Positional arguments to enable_system_logging().

• kw – Keyword arguments to enable_system_logging().

__enter__()

Enable system logging when entering the context.

__exit__(exc_type=None, exc_value=None, traceback=None)

Disable system logging when leaving the context.

Note

If an exception is being handled when we leave the context a warning message including traceback is logged before system logging is disabled.

coloredlogs.syslog.enable_system_logging(programname=None, fmt=None, logger=None, reconfigure=True, **kw)

Redirect logging messages to the system log (e.g. /var/log/syslog).

Parameters:

• programname – The program name to embed in log messages (a string, defaults to the result of find_program_name()).

• fmt – The log format for system log messages (a string, defaults to DEFAULT_LOG_FORMAT).

• logger – The logger to which the SysLogHandler should be connected (defaults to the root logger).

• level – The logging level for the SysLogHandler (defaults to DEFAULT_LOG_LEVEL). This value is coerced using level_to_number().

• reconfigure – If True (the default) multiple calls to enable_system_logging() will each override the previous configuration.

• kw – Refer to connect_to_syslog().

Returns:

A SysLogHandler object or None. If an existing handler is found and reconfigure is False the existing handler object is returned. If the connection to the system logging daemon fails None is returned.

As of release 15.0 this function uses is_syslog_supported() to check whether system logging is supported and appropriate before it’s enabled.

Note

When the logger’s effective level is too restrictive it is relaxed (refer to notes about log levels for details).

coloredlogs.syslog.connect_to_syslog(address=None, facility=None, level=None)

Create a SysLogHandler.

Parameters:

• address – The device file or network address of the system logging daemon (a string or tuple, defaults to the result of find_syslog_address()).

• facility – Refer to SysLogHandler. Defaults to LOG_USER.

• level – The logging level for the SysLogHandler (defaults to DEFAULT_LOG_LEVEL). This value is coerced using level_to_number().

Returns:

A SysLogHandler object or None (if the system logging daemon is unavailable).

The process of connecting to the system logging daemon goes as follows:

• The following two socket types are tried (in decreasing preference):

  1. SOCK_RAW avoids truncation of log messages but may not be supported.

  2. SOCK_STREAM (TCP) supports longer messages than the default (which is UDP).

coloredlogs.syslog.find_syslog_address()

Find the most suitable destination for system log messages.

Returns:

The pathname of a log device (a string) or an address/port tuple as supported by SysLogHandler.

On Mac OS X this prefers LOG_DEVICE_MACOSX, after that LOG_DEVICE_UNIX is checked for existence. If both of these device files don’t exist the default used by SysLogHandler is returned.

coloredlogs.syslog.is_syslog_supported()

Determine whether system logging is supported.

Returns:

True if system logging is supported and can be enabled, False if system logging is not supported or there are good reasons for not enabling it.

The decision making process here is as follows:

Override

If the environment variable $COLOREDLOGS_SYSLOG is set it is evaluated using coerce_boolean() and the resulting value overrides the platform detection discussed below, this allows users to override the decision making process if they disagree / know better.

Linux / UNIX

On systems that are not Windows or MacOS (see below) we assume UNIX which means either syslog is available or sending a bunch of UDP packets to nowhere won’t hurt anyone…

Microsoft Windows

Over the years I’ve had multiple reports of coloredlogs spewing extremely verbose errno 10057 warning messages to the console (once for each log message I suppose) so I now assume it a default that “syslog-style system logging” is not generally available on Windows.

Apple MacOS

There’s cPython issue #38780 which seems to result in a fatal exception when the Python interpreter shuts down. This is (way) worse than not having system logging enabled. The error message mentioned in #38780 has actually been following me around for years now, see for example:

• https://github.com/xolox/python-rotate-backups/issues/9 mentions Docker images implying Linux, so not strictly the same as #38780.

• https://github.com/xolox/python-npm-accel/issues/4 is definitely related to #38780 and is what eventually prompted me to add the is_syslog_supported() logic.

coloredlogs.syslog.match_syslog_handler(handler)

Identify system logging handlers.

Parameters:

handler – The Handler class to check.

Returns:

True if the handler is a SysLogHandler, False otherwise.

This function can be used as a callback for find_handler().