Chromalog’s API¶
Here is a comprehensive list of all modules, classes and function provided by Chromalog.
chromalog
¶
Enhance Python logging with colors.
-
chromalog.
basicConfig
(format=None, datefmt=None, level=None, stream=None, colorizer=None)¶ Does basic configuration for the logging system by creating a
chromalog.log.ColorizingStreamHandler
with a defaultchromalog.log.ColorizingFormatter
and adding it to the root logger.This function does nothing if the root logger already has handlers configured for it.
Parameters: - format – The format to be passed to the formatter.
- datefmt – The date format to be passed to the formatter.
- level – Set the root logger to the specified level.
- stream – Use the specified stream to initialize the stream handler.
- colorizer – Set the colorizer to be passed to the stream handler.
chromalog.log
¶
Log-related functions and structures.
-
class
chromalog.log.
ColorizingFormatter
(fmt=None, datefmt=None)¶ A formatter that colorize its output.
Initialize the formatter with specified format strings.
Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument (if omitted, you get the ISO8601 format).
-
format
(record)¶ Colorize the arguments of a record.
Record: A LogRecord instance. Returns: The colorized formatted string. Note
The record object must have a colorizer attribute to be use for colorizing the formatted string. If no such attribute is found, the default non-colorized behaviour is used instead.
-
-
class
chromalog.log.
ColorizingStreamHandler
(stream=None, colorizer=None, highlighter=None, attributes_map=None)¶ A stream handler that colorize its output.
Initializes a colorizing stream handler.
Parameters: - stream – The stream to use for output.
- colorizer – The colorizer to use for colorizing the output. If
not specified, a
chromalog.colorizer.Colorizer
is instantiated. - highlighter – The colorizer to use for highlighting the output when color is not supported.
- attributes_map – A map of LogRecord attributes/color tags.
-
active_colorizer
¶ The active colorizer or highlighter depending on whether color is supported.
-
format
(record)¶ Format a LogRecord and prints it to the associated stream.
chromalog.colorizer
¶
Colorizing functions and structures.
-
class
chromalog.colorizer.
ColorizableMixin
(color_tag=None)¶ Make an object colorizable by a colorizer.
Initialize a colorizable instance.
Parameters: color_tag – The color tag to associate to this instance. color_tag can be either a string or a list of strings.
-
class
chromalog.colorizer.
ColorizedObject
(obj, color_pair=None)¶ Wraps any object to colorize it.
Initialize the colorized object.
Parameters: - obj – The object to colorize.
- color_pair – The (start, stop) pair of color sequences to wrap that object in during string rendering.
-
class
chromalog.colorizer.
Colorizer
(color_map=None, default_color_tag=None)¶ Colorize log entries.
Initialize a new colorizer with a specified color_map.
Parameters: - color_map – A dictionary where the keys are color tags and the value are couples of color sequences (start, stop).
- default_color_tag – The color tag to default to in case an unknown color tag is encountered. If set to a falsy value no default is used.
-
class
chromalog.colorizer.
GenericColorizer
(color_map=None, default_color_tag=None)¶ A class reponsible for colorizing log entries and
chromalog.important.Important
objects.Initialize a new colorizer with a specified color_map.
Parameters: - color_map – A dictionary where the keys are color tags and the value are couples of color sequences (start, stop).
- default_color_tag – The color tag to default to in case an unknown color tag is encountered. If set to a falsy value no default is used.
-
colorize
(obj, color_tag=None, context_color_tag=None)¶ Colorize an object.
Parameters: - obj – The object to colorize.
- color_tag – The color tag to use as a default if
obj
is not marked. - context_color_tag – The color tag to use as context.
Returns: obj
ifobj
is not a colorizable object. A colorized string otherwise.
-
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.
-
get_color_pair
(color_tag, context_color_tag=None, use_default=True)¶ Get the color pairs for the specified color_tag and context_color_tag.
Parameters: - color_tag – A list of color tags.
- context_color_tag – A list of color tags to use as a context.
- use_default – If
False
then the default value won’t be used in case thecolor_tag
is not found in the associated color map.
Returns: A pair of color sequences.
-
class
chromalog.colorizer.
MonochromaticColorizer
(color_map=None, default_color_tag=None)¶ Monochromatic colorizer for non-color-capable streams that only highlights
chromalog.mark.Mark
objects with animportant
color tag.Initialize a new colorizer with a specified color_map.
Parameters: - color_map – A dictionary where the keys are color tags and the value are couples of color sequences (start, stop).
- default_color_tag – The color tag to default to in case an unknown color tag is encountered. If set to a falsy value no default is used.
chromalog.mark
¶
Marking classes and methods.
chromalog.mark.objects
¶
Mark log entries.
-
class
chromalog.mark.objects.
Mark
(obj, color_tag)¶ Wraps any object and mark it for colored output.
Mark
obj
for coloration.Parameters: - obj – The object to mark for colored output.
- color_tag – The color tag to use for coloring. Can be either a
list of a string. If
color_tag
is a string it will be converted into a single-element list automatically.
Note
Nested
chromalog.mark.Mark
objects are flattened automatically and theircolor_tag
are appended.>>> from chromalog.mark.objects import Mark
>>> Mark(42, 'a').color_tag ['a']
>>> Mark(42, ['a']).color_tag ['a']
>>> Mark(42, ['a', 'b']).color_tag ['a', 'b']
>>> Mark(Mark(42, 'c'), ['a', 'b']) == Mark(42, ['a', 'b', 'c']) True
chromalog.mark.helpers
¶
Automatically generate marking helpers functions.
-
class
chromalog.mark.helpers.
ConditionalHelpers
¶ A class that is designed to act as a module and implement magic helper generation.
-
make_helper
(color_tag_true, color_tag_false)¶ Make a conditional helper.
Parameters: - color_tag_true – The color tag if the condition is met.
- color_tag_false – The color tag if the condition is not met.
Returns: The helper function.
-
chromalog.mark.helpers.conditional
¶
Pseudo-module that generates conditional helpers.
See ConditionalHelpers
.