from __future__ import print_function
We've seen in quickstart
how to quickly colorize your logging output. But Chromalog has much more to offer than just that !
The chromalog.mark
module contains all Chromalog's marking logic.
Its main component is the Mark <chromalog.mark.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<chromalog.log.ColorizingFormatter>
and transformed into color sequences, as defined in the ColorizingStreamHandler<chromalog.log.ColorizingStreamHandler>
's color map<color_maps>
.
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 <chromalog.mark.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')
Warning
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 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
print(important(42).color_tag)
Which gives the following output:
['important']
An helper function with a color tag similar to its name will be generated and made accessible transparently.
Like Mark<chromalog.mark.Mark>
instances, you can obviously combine several helpers to cumulate the effects.
For instance:
from chromalog.mark.helpers.simple import important, success
print(important(success(42)).color_tag)
Gives:
['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:
chromalog.mark.helpers.simple.success
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) print(success_or_error(42).color_tag) print(success_or_error(0).color_tag)
Which gives:
['success'] ['error'] ['success'] ['error']
Warning
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.
Note
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<chromalog.colorizer.GenericColorizer>
class is responsible for turning color tags into colors (or decoration sequences).
To do so, each GenericColorizer<chromalog.colorizer.GenericColorizer>
instance has a color_map
dictionary<dict>
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': ('{', '}'),
})
print(colorizer.colorize(alpha(beta(42)))) print(colorizer.colorize(beta(alpha(42))))
Which gives:
[{42}] {[42]}
Note that the colorize<chromalog.colorizer.GenericColorizer.colorize>
method takes an optional parameter context_color_tag
which is mainly used by the ColorizingFormatter<chromalog.log.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:
}{[42]}{
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.
Chromalog ships with two default colorizers:
Colorizer<chromalog.colorizer.Colorizer>
which is associated to a color map constitued of color escaping sequences.MonochromaticColorizer<chromalog.colorizer.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
for a comprehensive list of default color tags and their resulting sequences.
One can create its own colorizer by simply deriving from the GenericColorizer<chromalog.colorizer.GenericColorizer>
class and defining the default_color_map
class attribute, like so:
from chromalog.colorizer import GenericColorizer
- from colorama import (
Fore, Back, Style,
)
- class MyColorizer(GenericColorizer):
- default_color_map = {
'success': (Fore.GREEN, Style.RESET_ALL),
}
Colorizers also provide a method to directly colorize a message, regardless of any output stream and its color capabilities:
chromalog.colorizer.GenericColorizer.colorize_message
Here is an example of usage:
from chromalog.colorizer import GenericColorizer from chromalog.mark.helpers.simple import alpha
- colorizer = GenericColorizer(color_map={
'alpha': ('[', ']'),
})
- print(colorizer.colorize_message(
'hello {} ! How {are} you ?', alpha('world'), are=alpha('are'),
))
This gives the following output:
hello [world] ! How [are] you ?
Here is a list of the default color tags and their associated sequences:
Colorizer | Color tag | Effect |
|
|
|
MonochromaticColorizer<chromalog.colorizer.MonochromaticColorizer> |
important | Value surrounded by ** . |