mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-13 07:26:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Markup consistency fixes.

Browse source
This commit is contained in:
Georg Brandl 2010-12-03 15:30:09 +00:00
parent a5240701fc
commit 1eb40bc945
1 changed files with 40 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

87
Doc/library/logging.rst
View file

@ -548,10 +548,7 @@ what handlers are most appropriate for their application: if you add handlers
unit tests and deliver logs which suit their requirements. unit tests and deliver logs which suit their requirements.
.. versionadded:: 3.1 .. versionadded:: 3.1
The :class:`NullHandler` class.
The :class:`NullHandler` class was not present in previous versions, but is
now included, so that it need not be defined in library code.
Logging Levels Logging Levels
@ -688,12 +685,10 @@ provided:
more information. more information.
.. versionadded:: 3.1 .. versionadded:: 3.1
The :class:`NullHandler` class.
The :class:`NullHandler` class was not present in previous versions.
.. versionadded:: 3.2 .. versionadded:: 3.2
The :class:`QueueHandler` class.
The :class:`QueueHandler` class was not present in previous versions.
The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
classes are defined in the core logging package. The other handlers are classes are defined in the core logging package. The other handlers are
@ -755,7 +750,6 @@ functions.
Return a callable which is used to create a :class:`LogRecord`. Return a callable which is used to create a :class:`LogRecord`.
.. versionadded:: 3.2 .. versionadded:: 3.2
This function has been provided, along with :func:`setLogRecordFactory`, This function has been provided, along with :func:`setLogRecordFactory`,
to allow developers more control over how the :class:`LogRecord` to allow developers more control over how the :class:`LogRecord`
representing a logging event is constructed. representing a logging event is constructed.
@ -986,6 +980,7 @@ functions.
function is typically called before any loggers are instantiated by applications function is typically called before any loggers are instantiated by applications
which need to use custom logger behavior. which need to use custom logger behavior.
.. function:: setLogRecordFactory(factory) .. function:: setLogRecordFactory(factory)
Set a callable which is used to create a :class:`LogRecord`. Set a callable which is used to create a :class:`LogRecord`.
@ -993,14 +988,13 @@ functions.
:param factory: The factory callable to be used to instantiate a log record. :param factory: The factory callable to be used to instantiate a log record.
.. versionadded:: 3.2 .. 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 The factory has the following signature:
allow developers more control over how the :class:`LogRecord` representing
a logging event is constructed.
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. :name: The logger name.
:level: The logging level (numeric). :level: The logging level (numeric).
@ -1015,6 +1009,7 @@ functions.
:func:`traceback.print_stack`, showing the call hierarchy. :func:`traceback.print_stack`, showing the call hierarchy.
:kwargs: Additional keyword arguments. :kwargs: Additional keyword arguments.
.. seealso:: .. seealso::
:pep:`282` - A Logging System :pep:`282` - A Logging System
@ -1253,9 +1248,8 @@ instantiated directly, but always through the module-level function
False is found - that will be the last logger which is checked for the False is found - that will be the last logger which is checked for the
existence of handlers. existence of handlers.
.. versionadded:: 3.2 .. versionadded:: 3.2
The :meth:`hasHandlers` method was not present in previous versions.
.. _minimal-example: .. _minimal-example:
@ -2239,6 +2233,7 @@ sends logging output to a disk file. It inherits the output functionality from
Outputs the record to the file. Outputs the record to the file.
.. _null-handler: .. _null-handler:
NullHandler NullHandler
@ -2250,12 +2245,10 @@ The :class:`NullHandler` class, located in the core :mod:`logging` package,
does not do any formatting or output. It is essentially a "no-op" handler does not do any formatting or output. It is essentially a "no-op" handler
for use by library developers. for use by library developers.
.. class:: NullHandler() .. class:: NullHandler()
Returns a new instance of the :class:`NullHandler` class. Returns a new instance of the :class:`NullHandler` class.
.. method:: emit(record) .. method:: emit(record)
This method does nothing. This method does nothing.
@ -2849,6 +2842,8 @@ supports sending logging messages to a Web server, using either ``GET`` or
QueueHandler QueueHandler
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. versionadded:: 3.2
The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module, The :class:`QueueHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to a queue, such as those implemented in the supports sending logging messages to a queue, such as those implemented in the
:mod:`queue` or :mod:`multiprocessing` modules. :mod:`queue` or :mod:`multiprocessing` modules.
@ -2892,15 +2887,14 @@ possible, while any potentially slow operations (such as sending an email via
timeout, or a customised queue implementation. timeout, or a customised queue implementation.
.. versionadded:: 3.2
The :class:`QueueHandler` class was not present in previous versions.
.. queue-listener: .. queue-listener:
QueueListener QueueListener
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
.. versionadded:: 3.2
The :class:`QueueListener` class, located in the :mod:`logging.handlers` The :class:`QueueListener` class, located in the :mod:`logging.handlers`
module, supports receiving logging messages from a queue, such as those module, supports receiving logging messages from a queue, such as those
implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The implemented in the :mod:`queue` or :mod:`multiprocessing` modules. The
@ -2961,9 +2955,6 @@ possible, while any potentially slow operations (such as sending an email via
Note that if you don't call this before your application exits, there 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. 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: .. _zeromq-handlers:
@ -3006,6 +2997,7 @@ data needed by the handler to create the socket::
def close(self): def close(self):
self.queue.close() self.queue.close()
Subclassing QueueListener Subclassing QueueListener
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
@ -3023,6 +3015,7 @@ of queues, for example a ZeroMQ "subscribe" socket. Here's an example::
msg = self.queue.recv() msg = self.queue.recv()
return logging.makeLogRecord(json.loads(msg)) return logging.makeLogRecord(json.loads(msg))
.. _formatter-objects: .. _formatter-objects:
Formatter Objects Formatter Objects
@ -3291,22 +3284,23 @@ wire).
set using :func:`getLogRecordFactory` and :func:`setLogRecordFactory` set using :func:`getLogRecordFactory` and :func:`setLogRecordFactory`
(see this for the factory's signature). (see this for the factory's signature).
This functionality can be used to inject your own values into a This functionality can be used to inject your own values into a
LogRecord at creation time. You can use the following pattern:: LogRecord at creation time. You can use the following pattern::
old_factory = logging.getLogRecordFactory() old_factory = logging.getLogRecordFactory()
def record_factory(*args, **kwargs): def record_factory(*args, **kwargs):
record = old_factory(*args, **kwargs) record = old_factory(*args, **kwargs)
record.custom_attribute = 0xdecafbad record.custom_attribute = 0xdecafbad
return record 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: .. _logger-adapter:
@ -3315,22 +3309,21 @@ LoggerAdapter Objects
:class:`LoggerAdapter` instances are used to conveniently pass contextual :class:`LoggerAdapter` instances are used to conveniently pass contextual
information into logging calls. For a usage example , see the section on 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) .. class:: LoggerAdapter(logger, extra)
Returns an instance of :class:`LoggerAdapter` initialized with an Returns an instance of :class:`LoggerAdapter` initialized with an
underlying :class:`Logger` instance and a dict-like object. 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 Modifies the message and/or keyword arguments passed to a logging call in
order to insert contextual information. This implementation takes the object order to insert contextual information. This implementation takes the object
passed as *extra* to the constructor and adds it to *kwargs* using key 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 'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
(possibly modified) versions of the arguments passed in. (possibly modified) versions of the arguments passed in.
In addition to the above, :class:`LoggerAdapter` supports the following In addition to the above, :class:`LoggerAdapter` supports the following
methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`, methods of :class:`Logger`, i.e. :meth:`debug`, :meth:`info`, :meth:`warning`,