unit tests and deliver logs which suit their requirements.
.. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions, but is
-now included, so that it need not be defined in library code.
-
+ The :class:`NullHandler` class.
Logging Levels
more information.
.. versionadded:: 3.1
-
-The :class:`NullHandler` class was not present in previous versions.
+ The :class:`NullHandler` class.
.. versionadded:: 3.2
-
-The :class:`QueueHandler` class was not present in previous versions.
+ The :class:`QueueHandler` class.
The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
classes are defined in the core logging package. The other handlers are
Return a callable which is used to create a :class:`LogRecord`.
.. versionadded:: 3.2
-
This function has been provided, along with :func:`setLogRecordFactory`,
to allow developers more control over how the :class:`LogRecord`
representing a logging event is constructed.
function is typically called before any loggers are instantiated by applications
which need to use custom logger behavior.
+
.. function:: setLogRecordFactory(factory)
Set a callable which is used to create a :class:`LogRecord`.
:param factory: The factory callable to be used to instantiate a log record.
.. versionadded:: 3.2
+ This function has been provided, along with :func:`getLogRecordFactory`, to
+ allow developers more control over how the :class:`LogRecord` representing
+ a logging event is constructed.
- This function has been provided, along with :func:`getLogRecordFactory`, to
- allow developers more control over how the :class:`LogRecord` representing
- a logging event is constructed.
+ The factory has the following signature:
- The factory has the following signature.
-
- factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, \*\*kwargs)
+ ``factory(name, level, fn, lno, msg, args, exc_info, func=None, sinfo=None, \*\*kwargs)``
:name: The logger name.
:level: The logging level (numeric).
:func:`traceback.print_stack`, showing the call hierarchy.
:kwargs: Additional keyword arguments.
+
.. seealso::
:pep:`282` - A Logging System
False is found - that will be the last logger which is checked for the
existence of handlers.
-.. versionadded:: 3.2
+ .. versionadded:: 3.2
-The :meth:`hasHandlers` method was not present in previous versions.
.. _minimal-example:
Outputs the record to the file.
+
.. _null-handler:
NullHandler
does not do any formatting or output. It is essentially a "no-op" handler
for use by library developers.
-
.. class:: NullHandler()
Returns a new instance of the :class:`NullHandler` class.
-
.. method:: emit(record)
This method does nothing.
QueueHandler
^^^^^^^^^^^^
+.. versionadded:: 3.2
+
The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to a queue, such as those implemented in the
:mod:`queue` or :mod:`multiprocessing` modules.
timeout, or a customised queue implementation.
-.. versionadded:: 3.2
-
-The :class:`QueueHandler` class was not present in previous versions.
.. queue-listener:
QueueListener
^^^^^^^^^^^^^
+.. versionadded:: 3.2
+
The :class:`QueueListener` class, located in the :mod:`logging.handlers`
module, supports receiving logging messages from a queue, such as those
implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
Note that if you don't call this before your application exits, there
may be some records still left on the queue, which won't be processed.
-.. versionadded:: 3.2
-
-The :class:`QueueListener` class was not present in previous versions.
.. _zeromq-handlers:
def close(self):
self.queue.close()
+
Subclassing QueueListener
^^^^^^^^^^^^^^^^^^^^^^^^^
msg = self.queue.recv()
return logging.makeLogRecord(json.loads(msg))
+
.. _formatter-objects:
Formatter Objects
set using :func:`getLogRecordFactory` and :func:`setLogRecordFactory`
(see this for the factory's signature).
- This functionality can be used to inject your own values into a
- LogRecord at creation time. You can use the following pattern::
+ This functionality can be used to inject your own values into a
+ LogRecord at creation time. You can use the following pattern::
+
+ old_factory = logging.getLogRecordFactory()
- old_factory = logging.getLogRecordFactory()
+ def record_factory(*args, **kwargs):
+ record = old_factory(*args, **kwargs)
+ record.custom_attribute = 0xdecafbad
+ return record
- def record_factory(*args, **kwargs):
- record = old_factory(*args, **kwargs)
- record.custom_attribute = 0xdecafbad
- return record
+ logging.setLogRecordFactory(record_factory)
- logging.setLogRecordFactory(record_factory)
+ With this pattern, multiple factories could be chained, and as long
+ as they don't overwrite each other's attributes or unintentionally
+ overwrite the standard attributes listed above, there should be no
+ surprises.
- With this pattern, multiple factories could be chained, and as long
- as they don't overwrite each other's attributes or unintentionally
- overwrite the standard attributes listed above, there should be no
- surprises.
.. _logger-adapter:
:class:`LoggerAdapter` instances are used to conveniently pass contextual
information into logging calls. For a usage example , see the section on
-`adding contextual information to your logging output`__.
+:ref:`adding contextual information to your logging output <context-info>`.
-__ context-info_
.. class:: LoggerAdapter(logger, extra)
- Returns an instance of :class:`LoggerAdapter` initialized with an
- underlying :class:`Logger` instance and a dict-like object.
+ Returns an instance of :class:`LoggerAdapter` initialized with an
+ underlying :class:`Logger` instance and a dict-like object.
- .. method:: process(msg, kwargs)
+ .. method:: 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.
+ 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 the following
methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,
projects / python / commitdiff