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 instr.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 {0} ! 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 ** . |