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 default chromalog.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 if obj 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 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.

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 the color_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 an important 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 their color_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.

class chromalog.mark.helpers.SimpleHelpers

A class that is designed to act as a module and implement magic helper generation.

make_helper(color_tag)

Make a simple helper.

Parameters:color_tag – The color tag to make a helper for.
Returns:The helper function.

chromalog.mark.helpers.simple

Pseudo-module that generates simple helpers.

See SimpleHelpers.

chromalog.mark.helpers.conditional

Pseudo-module that generates conditional helpers.

See ConditionalHelpers.