Advanced usage

We’ve seen in Quickstart how to quickly colorize your logging output. But Chromalog has much more to offer than just that !

Marking functions

The chromalog.mark module contains all Chromalog‘s marking logic.

Its main component is the Mark class which wraps any Python object and associates it with one or several color tags.

Those color tags are evaluated during the formatting phase by the ColorizingFormatter and transformed into color sequences, as defined in the ColorizingStreamHandler‘s color map.

To decorate a Python object, one can just do:

from chromalog.mark import Mark

marked_value = Mark('value', 'my_color_tag')

You may define several color tags at once, by specifying a list:

from chromalog.mark import Mark

marked_value = Mark('value', ['my_color_tag', 'some_other_tag'])

Nested Mark instances are actually flattened automatically and their color tags appended.

from chromalog.mark import Mark

marked_value = Mark(Mark('value', 'some_other_tag'), 'my_color_tag')


Be careful when specifying several color tags: their order matters !

Depending on the color sequences of your color map, the formatted result might differ.

See Color maps for an example.


Chromalog also comes with several built-in helpers which make marking objects even more readable. Those helpers are generated automatically by several magic modules.

Simple helpers

Simple helpers are a quick way of marking an object and an explicit way of highlighting a value.

You can generate simple helpers by importing them from the chromalog.mark.helpers.simple magic module, like so:

from chromalog.mark.helpers.simple import important


Which gives the following output:


An helper function with a color tag similar to its name will be generated and made accessible transparently.

Like Mark instances, you can obviously combine several helpers to cumulate the effects.

For instance:

from chromalog.mark.helpers.simple import important, success



['important', 'success']

If the name of the helper you want to generate is not a suitable python identifier, you can use the chromalog.mark.helpers.simple.make_helper() function instead.

Note that, should you need it, documentation is generated for each helper. For instance, here is the generated documentation for the chromalog.mark.helpers.simple.success() function:


Mark an object for coloration.

The color tag is set to ‘success’.

Parameters:obj – The object to mark for coloration.
Returns:A Mark instance.
>>> from chromalog.mark.helpers.simple import success
>>> success(42).color_tag

Conditional helpers

Conditional helpers are a quick way of associating a color tag to an object depending on a boolean condition.

You can generate conditional helpers by importing them from the chromalog.mark.helpers.conditional magic module:

from chromalog.mark.helpers.conditional import success_or_error

print(success_or_error(42, True).color_tag)
print(success_or_error(42, False).color_tag)

Which gives:



Automatically generated conditional helpers must have a name of the form a_or_b where a and b are color tags.

If the name of the helper you want to generate is not a suitable python identifier, you can use the chromalog.mark.helpers.conditional.make_helper() function instead.


If no condition is specified, then the value itself is evaluated as a boolean value.

This is useful for outputing exit codes for instance.


The GenericColorizer class is responsible for turning color tags into colors (or decoration sequences).

Color maps

To do so, each GenericColorizer instance has a color_map dictionary which has the following structure:

color_map = {
   'alpha': ('[', ']'),
   'beta': ('{', '}'),

That is, each key is the color tag, and each value is a pair (start_sequence, stop_sequence) of start and stop sequences that will surround the decorated value when it is output.

Values are decorated in order with the seqauences that match their associated color tags. For instance:

from chromalog.mark.helpers.simple import alpha, beta
from chromalog.colorizer import GenericColorizer

colorizer = GenericColorizer(color_map={
   'alpha': ('[', ']'),
   'beta': ('{', '}'),


Which gives:


Context colorizing

Note that the colorize method takes an optional parameter context_color_tag which is mainly used by the ColorizingFormatter to colorize subparts of a colorized message.

context_color_tag should match the color tag used to colorize the contextual message as a whole. Unless you write your own formatter, you shouldn’t have to care much about it.

Here is an example on how context_color_tag modifies the output:

from chromalog.mark.helpers.simple import alpha
from chromalog.colorizer import GenericColorizer

colorizer = GenericColorizer(color_map={
   'alpha': ('[', ']'),
   'beta': ('{', '}'),

print(colorizer.colorize(alpha(42), context_color_tag='beta'))

Which gives:


As you can see, the context color tag is first closed then reopened, then the usual color tags are used. This behavior is required as it prevents some color escaping sequences to persist after the tags get closed on some terminals.

Built-in colorizers

Chromalog ships with two default colorizers:

  • Colorizer which is associated to a color map constitued of color escaping sequences.
  • MonochromaticColorizer which may be used on non color-capable output streams and that only decorates objects marked with the 'important' color tag.

See Default color maps and sequences for a comprehensive list of default color tags and their resulting sequences.

Custom colorizers

One can create its own colorizer by simply deriving from the GenericColorizer class and defining the default_color_map class attribute, like so:

from chromalog.colorizer import GenericColorizer

from colorama import (

class MyColorizer(GenericColorizer):
   default_color_map = {
      'success': (Fore.GREEN, Style.RESET_ALL),

Decorating messages

Colorizers also provide a method to directly colorize a message, regardless of any output stream and its color capabilities:

GenericColorizer.colorize_message(message, *args, **kwargs)

Colorize a message.

Parameters:message – The message to colorize. If message is a marked object, its color tag will be used as a context_color_tag. message may contain formatting placeholders as described in str.format().
Returns:The colorized message.


This function has no way of check the color-capability of any stream that the resulting string might be printed to.

Here is an example of usage:

from chromalog.colorizer import GenericColorizer
from chromalog.mark.helpers.simple import alpha

colorizer = GenericColorizer(color_map={
    'alpha': ('[', ']'),

    'hello {0} ! How {are} you ?',

This gives the following output:

hello [world] ! How [are] you ?

Default color maps and sequences

Here is a list of the default color tags and their associated sequences:

Colorizer Color tag Effect
Colorizer debug Light blue color.
info Default terminal style.
important Brighter output.
success Green color.
warning Yellow color.
error Red color.
critical Red background.
MonochromaticColorizer important Value surrounded by **.