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')
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.
Helpers¶
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
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 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:
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)
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.
Colorizers¶
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': ('{', '}'),
})
print(colorizer.colorize(alpha(beta(42))))
print(colorizer.colorize(beta(alpha(42))))
Which gives:
[{42}]
{[42]}
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:
}{[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.
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 (
Fore,
Back,
Style,
)
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. Warning
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': ('[', ']'),
})
print(colorizer.colorize_message(
'hello {} ! How {are} you ?',
alpha('world'),
are=alpha('are'),
))
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 **. |