API

All public visible symbols can be directly imported from the kaviar module. This is also the preferred method to use Kaviar.

Formatting Functions

kaviar.kv_format_pairs(pairs, separator=' ')

Formats the given Key-Value pairs in kv_pairs.

For more details see kv_format().

Parameters:
  • kv_pairs (collections.Iterable) – List of Key-Value pairs to format.
  • separator (str) – Value between two pairs.
Returns:

Key-Value formatted content generated from kv_pairs.
Return type:

six.text_type
kaviar.kv_format_dict(d, keys=None, separator=' ')

Formats the given dictionary d.

For more details see kv_format().

Parameters:
Returns:

Key-Value formatted content generated from d.
Return type:

six.text_type
kaviar.kv_format_object(o, keys=None, separator=' ')

Formats an object’s attributes. Useful for object representation implementation. Will skip methods or private attributes.

For more details see kv_format().

Parameters:
  • o – Object to format.
  • keys (collections.Sequence) – Explicit list of attributes to format. None means all public visible attribute for the given object will be formatted.
  • separator (str) – Value between two pairs.
Returns:

Formatted Object attributes.
Return type:

six.text_type
kaviar.kv_format(*args, **kwargs)

Formats any given list of Key-Value pairs or dictionaries in *args and any given keyword argument in **kwargs.

Any item within a given list or dictionary will also be visited and added to the output. Strings will be escaped to prevent leaking binary data, ambiguous characters or other control sequences. Strings with escaped characters or spaces will be encapsulated in quotes. Other objects will be converted into a string and will be treated as a string afterwards.

Parameters:
  • *args (any Iterable or Mapping) – Values to format.
  • **kwargs – Keyword Values to format
Returns:

Formatted content of *args and **kwargs.
Return type:

six.text_type

Logging Adapters

class kaviar.KvLoggerAdapter(logger, extra=None)

Simple Adapter for loggers to produce Key-Value structured log messages.

Parameters:
define_logger_func(self, level, field_names, default=NO_DEFAULT, filters=None, include_exc_info=False)

Define a new logger function that will log the given arguments with the given predefined keys.

Parameters:
  • level – The log level to use for each call.
  • field_names – Set of predefined keys.
  • default – A default value for each key.
  • filters – Additional filters for treating given arguments.
  • include_exc_info – Include a stack trace with the log. Useful for the ERROR log level.
Returns:

A function that will log given values with the predefined keys and the given log level.
critical(*args, **kwargs)

Delegate a critical call to the underlying logger.

debug(*args, **kwargs)

Delegate a debug call to the underlying logger.

error(*args, **kwargs)

Delegate a error call to the underlying logger.

exception(*args, **kwargs)

Delegate a exception call to the underlying logger.

classmethod get_logger(name=None, extra=None)

Construct a new KvLoggerAdapter which encapsulates the logging.Logger specified by name.

Parameters:
  • name – The logger name.
  • extra – Additional context relevant information.
Returns:

A new KvLoggerAdapter instance ready to use.
Return type:

KvLoggerAdapter
info(*args, **kwargs)

Delegate a info call to the underlying logger.

log(level, *args, **kwargs)

Delegate a log call to the underlying logger.

warning(*args, **kwargs)

Delegate a warning call to the underlying logger.

class kaviar.PositionalArgsAdapter(logger, extra=None)

Adapter for loggers similar to KvLoggerAdapter with support for positional arguments for predefined keys.

positional_args = []

List of predefined keys. The order will be preserved when formatting.

class kaviar.EventKvLoggerAdapter(logger, extra=None)

Adapter for loggers which will always have the event key in front of each message for easing differentiating between different log events.

Filtering

class kaviar.TextFilter(value, quotes_on=DEFAULT_QUOTE_ON, plaintext=False, max_length=UNLIMITED_LENGTH)

Provides a filtering facility to specify how a string will be seen in a Key-Value formatted line.

Parameters:
  • value – Value to log. Can be anything from a string to an object which implements object.__str__.
  • quotes_on (str) – Put output in parentheses if output contains any of the given arguments.
  • plaintext (bool) – Don’t escape characters beyond Basic Latin and Latin-1 Unicode block.
  • max_length (int) – Truncate values beyond given value. Truncated values will be explicitly marked.
class kaviar.ListFilter(value, quotes_on=DEFAULT_QUOTE_ON, plaintext=False, max_length=UNLIMITED_LENGTH)

Allows to embed iterable values in a comma separated format instead of the default format.

Parameters:value (abc.Iterable) – Anything that can be iterated. Items will be converted to string if necessary. Also supports TextFilter instances.
class kaviar.NamedTupleFilter(value, quotes_on=DEFAULT_QUOTE_ON, plaintext=False, max_length=UNLIMITED_LENGTH)

Dump namedtuple() based instances in a key-value format where the corresponding name for a field will be used instead of the index. The Order of fields will be preserved.

Parameters:value – namedtuple() or namedlist() based instances. Or anything else that can be iterated and has a _fields attribute.

Function Tools

class kaviar.KvFormatter(self, field_names, default=namedlist.NO_DEFAULT, filters=None)

Predefine a list of fields with optional default values and filters. The resulting object allows to reuse the field names for formatting purpose when called.