Commit 04c420f

An easy way in which you can pass contextual information to be output along

with logging event information is to use the :class:`LoggerAdapter` class.

This class is designed to look like a :class:`Logger`, so that you can call

:meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`,

:meth:`exception`, :meth:`critical` and :meth:`log`. These methods have the

same signatures as their counterparts in :class:`Logger`, so you can use the

two types of instances interchangeably.

When you create an instance of :class:`LoggerAdapter`, you pass it a

:class:`Logger` instance and a dict-like object which contains your contextual

information. When you call one of the logging methods on an instance of

:class:`LoggerAdapter`, it delegates the call to the underlying instance of

:class:`Logger` passed to its constructor, and arranges to pass the contextual

information in the delegated call. Here's a snippet from the code of

:class:`LoggerAdapter`::

The :meth:`process` method of :class:`LoggerAdapter` is where the contextual

information is added to the logging output. It's passed the message and

keyword arguments of the logging call, and it passes back (potentially)

modified versions of these to use in the call to the underlying logger. The

default implementation of this method leaves the message alone, but inserts

an "extra" key in the keyword argument whose value is the dict-like object

passed to the constructor. Of course, if you had passed an "extra" keyword

argument in the call to the adapter, it will be silently overwritten.

The advantage of using "extra" is that the values in the dict-like object are

merged into the :class:`LogRecord` instance's __dict__, allowing you to use

customized strings with your :class:`Formatter` instances which know about

the keys of the dict-like object. If you need a different method, e.g. if you

want to prepend or append the contextual information to the message string,

you just need to subclass :class:`LoggerAdapter` and override :meth:`process`

to do what you need. Here's an example script which uses this class, which

also illustrates what dict-like behaviour is needed from an arbitrary

"dict-like" object for use in the constructor::

import logging

class ConnInfo:

"""

An example class which shows how an arbitrary class can be used as

the 'extra' context information repository passed to a LoggerAdapter.

"""

def __getitem__(self, name):

"""

To allow this instance to look like a dict.

"""

from random import choice

if name == "ip":

result = choice(["127.0.0.1", "192.168.0.1"])

elif name == "user":

result = choice(["jim", "fred", "sheila"])

else:

result = self.__dict__.get(name, "?")

return result

def __iter__(self):

"""

To allow iteration over keys, which will be merged into

the LogRecord dict before formatting and output.

"""

keys = ["ip", "user"]

keys.extend(self.__dict__.keys())

return keys.__iter__()

if __name__ == "__main__":

from random import choice

levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)

a1 = logging.LoggerAdapter(logging.getLogger("a.b.c"),

{ "ip" : "123.231.231.123", "user" : "sheila" })

logging.basicConfig(level=logging.DEBUG,

format="%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s")

a1.debug("A debug message")

a1.info("An info message with %s", "some parameters")

a2 = logging.LoggerAdapter(logging.getLogger("d.e.f"), ConnInfo())

for x in range(10):

lvl = choice(levels)

lvlname = logging.getLevelName(lvl)

a2.log(lvl, "A message at %s level with %d %s", lvlname, 2, "parameters")

When this script is run, the output should look something like this::

2008-01-18 14:49:54,023 a.b.c DEBUG IP: 123.231.231.123 User: sheila A debug message

2008-01-18 14:49:54,023 a.b.c INFO IP: 123.231.231.123 User: sheila An info message with some parameters

2008-01-18 14:49:54,023 d.e.f CRITICAL IP: 192.168.0.1 User: jim A message at CRITICAL level with 2 parameters

2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: jim A message at INFO level with 2 parameters

2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters

2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: fred A message at ERROR level with 2 parameters

2008-01-18 14:49:54,033 d.e.f ERROR IP: 127.0.0.1 User: sheila A message at ERROR level with 2 parameters

2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters

2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: jim A message at WARNING level with 2 parameters

2008-01-18 14:49:54,033 d.e.f INFO IP: 192.168.0.1 User: fred A message at INFO level with 2 parameters

2008-01-18 14:49:54,033 d.e.f WARNING IP: 192.168.0.1 User: sheila A message at WARNING level with 2 parameters

2008-01-18 14:49:54,033 d.e.f WARNING IP: 127.0.0.1 User: jim A message at WARNING level with 2 parameters

.. versionadded:: 2.6

The :class:`LoggerAdapter` class was not present in previous versions.

LoggerAdapter Objects

.. versionadded:: 2.6

:class:`LoggerAdapter` instances are used to conveniently pass contextual

information into logging calls. For a usage example , see context-info_.

.. class:: LoggerAdapter(logger, extra)

Returns an instance of :class:`LoggerAdapter` initialized with an

underlying :class:`Logger` instance and a dict-like object.

.. method:: LoggerAdapter.process(msg, kwargs)

Modifies the message and/or keyword arguments passed to a logging call in

order to insert contextual information. This implementation takes the

object passed as *extra* to the constructor and adds it to *kwargs* using

key 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the

(possibly modified) versions of the arguments passed in.

In addition to the above, :class:`LoggerAdapter` supports all the logging

methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,

:meth:`error`, :meth:`exception`, :meth:`critical` and :meth:`log`. These

methods have the same signatures as their counterparts in :class:`Logger`, so

you can use the two types of instances interchangeably.

class block; it does not extend to the code blocks of methods -- this includes

generator expressions since they are implemented using a function scope. This

means that the following will fail::

__version__ = "0.5.0.4"

__date__ = "18 January 2008"

if extra is not None:

class LoggerAdapter:

"""

def __init__(self, logger, extra):

"""

self.logger = logger

self.extra = extra

def process(self, msg, kwargs):

"""

kwargs["extra"] = self.extra

return msg, kwargs

def debug(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.debug(msg, *args, **kwargs)

def info(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.info(msg, *args, **kwargs)

def warning(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.warning(msg, *args, **kwargs)

def error(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.error(msg, *args, **kwargs)

def exception(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

kwargs["exc_info"] = 1

self.logger.error(msg, *args, **kwargs)

def critical(self, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.critical(msg, *args, **kwargs)

def log(self, level, msg, *args, **kwargs):

"""

msg, kwargs = self.process(msg, kwargs)

self.logger.log(level, msg, *args, **kwargs)