bpo-32212: Updated logging documentation to make parameter names more consistent with source. (GH-4765) (GH-4767)
(cherry picked from commit a9f8df646a)
This commit is contained in:
Vinay Sajip
GitHub
parent
a04ca12e12
commit
63868181a9
|
|
@ -69,13 +69,13 @@ is the module's name in the Python package namespace.
|
|||
|
||||
.. class:: Logger
|
||||
|
||||
.. attribute:: Logger.propagate
|
||||
.. attribute:: Logger.propagate
|
||||
|
||||
If this evaluates to true, events logged to this logger will be passed to the
|
||||
handlers of higher level (ancestor) loggers, in addition to any handlers
|
||||
attached to this logger. Messages are passed directly to the ancestor
|
||||
loggers' handlers - neither the level nor filters of the ancestor loggers in
|
||||
question are considered.
|
||||
If this attribute evaluates to true, events logged to this logger will be
|
||||
passed to the handlers of higher level (ancestor) loggers, in addition to
|
||||
any handlers attached to this logger. Messages are passed directly to the
|
||||
ancestor loggers' handlers - neither the level nor filters of the ancestor
|
||||
loggers in question are considered.
|
||||
|
||||
If this evaluates to false, logging messages are not passed to the handlers
|
||||
of ancestor loggers.
|
||||
|
|
@ -91,13 +91,17 @@ is the module's name in the Python package namespace.
|
|||
scenario is to attach handlers only to the root logger, and to let
|
||||
propagation take care of the rest.
|
||||
|
||||
.. method:: Logger.setLevel(lvl)
|
||||
.. method:: Logger.setLevel(level)
|
||||
|
||||
Sets the threshold for this logger to *lvl*. Logging messages which are less
|
||||
severe than *lvl* will be ignored. When a logger is created, the level is set to
|
||||
:const:`NOTSET` (which causes all messages to be processed when the logger is
|
||||
the root logger, or delegation to the parent when the logger is a non-root
|
||||
logger). Note that the root logger is created with level :const:`WARNING`.
|
||||
Sets the threshold for this logger to *level*. Logging messages which are less
|
||||
severe than *level* will be ignored; logging messages which have severity *level*
|
||||
or higher will be emitted by whichever handler or handlers service this logger,
|
||||
unless a handler's level has been set to a higher severity level than *level*.
|
||||
|
||||
When a logger is created, the level is set to :const:`NOTSET` (which causes
|
||||
all messages to be processed when the logger is the root logger, or delegation
|
||||
to the parent when the logger is a non-root logger). Note that the root logger
|
||||
is created with level :const:`WARNING`.
|
||||
|
||||
The term 'delegation to the parent' means that if a logger has a level of
|
||||
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
|
||||
|
|
@ -113,14 +117,14 @@ is the module's name in the Python package namespace.
|
|||
See :ref:`levels` for a list of levels.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The *lvl* parameter now accepts a string representation of the
|
||||
The *level* parameter now accepts a string representation of the
|
||||
level such as 'INFO' as an alternative to the integer constants
|
||||
such as :const:`INFO`. Note, however, that levels are internally stored
|
||||
as integers, and methods such as e.g. :meth:`getEffectiveLevel` and
|
||||
:meth:`isEnabledFor` will return/expect to be passed integers.
|
||||
|
||||
|
||||
.. method:: Logger.isEnabledFor(lvl)
|
||||
.. method:: Logger.isEnabledFor(lvl)
|
||||
|
||||
Indicates if a message of severity *lvl* would be processed by this logger.
|
||||
This method checks first the module-level level set by
|
||||
|
|
@ -128,7 +132,7 @@ is the module's name in the Python package namespace.
|
|||
by :meth:`getEffectiveLevel`.
|
||||
|
||||
|
||||
.. method:: Logger.getEffectiveLevel()
|
||||
.. method:: Logger.getEffectiveLevel()
|
||||
|
||||
Indicates the effective level for this logger. If a value other than
|
||||
:const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
|
||||
|
|
@ -138,7 +142,7 @@ is the module's name in the Python package namespace.
|
|||
etc.
|
||||
|
||||
|
||||
.. method:: Logger.getChild(suffix)
|
||||
.. method:: Logger.getChild(suffix)
|
||||
|
||||
Returns a logger which is a descendant to this logger, as determined by the suffix.
|
||||
Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same
|
||||
|
|
@ -149,7 +153,7 @@ is the module's name in the Python package namespace.
|
|||
.. versionadded:: 3.2
|
||||
|
||||
|
||||
.. method:: Logger.debug(msg, *args, **kwargs)
|
||||
.. method:: Logger.debug(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
|
||||
message format string, and the *args* are the arguments which are merged into
|
||||
|
|
@ -223,13 +227,13 @@ is the module's name in the Python package namespace.
|
|||
The *exc_info* parameter can now accept exception instances.
|
||||
|
||||
|
||||
.. method:: Logger.info(msg, *args, **kwargs)
|
||||
.. method:: Logger.info(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`INFO` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
|
||||
.. method:: Logger.warning(msg, *args, **kwargs)
|
||||
.. method:: Logger.warning(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`WARNING` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
|
@ -238,42 +242,42 @@ is the module's name in the Python package namespace.
|
|||
identical to ``warning``. As ``warn`` is deprecated, please do not use
|
||||
it - use ``warning`` instead.
|
||||
|
||||
.. method:: Logger.error(msg, *args, **kwargs)
|
||||
.. method:: Logger.error(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`ERROR` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
|
||||
.. method:: Logger.critical(msg, *args, **kwargs)
|
||||
.. method:: Logger.critical(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`CRITICAL` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
|
||||
.. method:: Logger.log(lvl, msg, *args, **kwargs)
|
||||
.. method:: Logger.log(lvl, msg, *args, **kwargs)
|
||||
|
||||
Logs a message with integer level *lvl* on this logger. The other arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
|
||||
.. method:: Logger.exception(msg, *args, **kwargs)
|
||||
.. method:: Logger.exception(msg, *args, **kwargs)
|
||||
|
||||
Logs a message with level :const:`ERROR` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`. Exception info is added to the logging
|
||||
message. This method should only be called from an exception handler.
|
||||
|
||||
|
||||
.. method:: Logger.addFilter(filt)
|
||||
.. method:: Logger.addFilter(filter)
|
||||
|
||||
Adds the specified filter *filt* to this logger.
|
||||
Adds the specified filter *filter* to this logger.
|
||||
|
||||
|
||||
.. method:: Logger.removeFilter(filt)
|
||||
.. method:: Logger.removeFilter(filter)
|
||||
|
||||
Removes the specified filter *filt* from this logger.
|
||||
Removes the specified filter *filter* from this logger.
|
||||
|
||||
|
||||
.. method:: Logger.filter(record)
|
||||
.. method:: Logger.filter(record)
|
||||
|
||||
Applies this logger's filters to the record and returns a true value if the
|
||||
record is to be processed. The filters are consulted in turn, until one of
|
||||
|
|
@ -282,24 +286,24 @@ is the module's name in the Python package namespace.
|
|||
further processing of the record occurs.
|
||||
|
||||
|
||||
.. method:: Logger.addHandler(hdlr)
|
||||
.. method:: Logger.addHandler(hdlr)
|
||||
|
||||
Adds the specified handler *hdlr* to this logger.
|
||||
|
||||
|
||||
.. method:: Logger.removeHandler(hdlr)
|
||||
.. method:: Logger.removeHandler(hdlr)
|
||||
|
||||
Removes the specified handler *hdlr* from this logger.
|
||||
|
||||
|
||||
.. method:: Logger.findCaller(stack_info=False)
|
||||
.. method:: Logger.findCaller(stack_info=False)
|
||||
|
||||
Finds the caller's source filename and line number. Returns the filename, line
|
||||
number, function name and stack information as a 4-element tuple. The stack
|
||||
information is returned as ``None`` unless *stack_info* is ``True``.
|
||||
|
||||
|
||||
.. method:: Logger.handle(record)
|
||||
.. method:: Logger.handle(record)
|
||||
|
||||
Handles a record by passing it to all handlers associated with this logger and
|
||||
its ancestors (until a false value of *propagate* is found). This method is used
|
||||
|
|
@ -307,12 +311,12 @@ is the module's name in the Python package namespace.
|
|||
Logger-level filtering is applied using :meth:`~Logger.filter`.
|
||||
|
||||
|
||||
.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)
|
||||
.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)
|
||||
|
||||
This is a factory method which can be overridden in subclasses to create
|
||||
specialized :class:`LogRecord` instances.
|
||||
|
||||
.. method:: Logger.hasHandlers()
|
||||
.. method:: Logger.hasHandlers()
|
||||
|
||||
Checks to see if this logger has any handlers configured. This is done by
|
||||
looking for handlers in this logger and its parents in the logger hierarchy.
|
||||
|
|
@ -323,6 +327,8 @@ is the module's name in the Python package namespace.
|
|||
|
||||
.. versionadded:: 3.2
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
Loggers can now be picked and unpickled.
|
||||
|
||||
.. _levels:
|
||||
|
||||
|
|
@ -362,60 +368,62 @@ is never instantiated directly; this class acts as a base for more useful
|
|||
subclasses. However, the :meth:`__init__` method in subclasses needs to call
|
||||
:meth:`Handler.__init__`.
|
||||
|
||||
.. class:: Handler
|
||||
|
||||
.. method:: Handler.__init__(level=NOTSET)
|
||||
.. method:: Handler.__init__(level=NOTSET)
|
||||
|
||||
Initializes the :class:`Handler` instance by setting its level, setting the list
|
||||
of filters to the empty list and creating a lock (using :meth:`createLock`) for
|
||||
serializing access to an I/O mechanism.
|
||||
|
||||
|
||||
.. method:: Handler.createLock()
|
||||
.. method:: Handler.createLock()
|
||||
|
||||
Initializes a thread lock which can be used to serialize access to underlying
|
||||
I/O functionality which may not be threadsafe.
|
||||
|
||||
|
||||
.. method:: Handler.acquire()
|
||||
.. method:: Handler.acquire()
|
||||
|
||||
Acquires the thread lock created with :meth:`createLock`.
|
||||
|
||||
|
||||
.. method:: Handler.release()
|
||||
.. method:: Handler.release()
|
||||
|
||||
Releases the thread lock acquired with :meth:`acquire`.
|
||||
|
||||
|
||||
.. method:: Handler.setLevel(lvl)
|
||||
.. method:: Handler.setLevel(level)
|
||||
|
||||
Sets the threshold for this handler to *lvl*. Logging messages which are less
|
||||
severe than *lvl* will be ignored. When a handler is created, the level is set
|
||||
to :const:`NOTSET` (which causes all messages to be processed).
|
||||
Sets the threshold for this handler to *level*. Logging messages which are
|
||||
less severe than *level* will be ignored. When a handler is created, the
|
||||
level is set to :const:`NOTSET` (which causes all messages to be
|
||||
processed).
|
||||
|
||||
See :ref:`levels` for a list of levels.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
The *lvl* parameter now accepts a string representation of the
|
||||
The *level* parameter now accepts a string representation of the
|
||||
level such as 'INFO' as an alternative to the integer constants
|
||||
such as :const:`INFO`.
|
||||
|
||||
|
||||
.. method:: Handler.setFormatter(form)
|
||||
.. method:: Handler.setFormatter(fmt)
|
||||
|
||||
Sets the :class:`Formatter` for this handler to *form*.
|
||||
Sets the :class:`Formatter` for this handler to *fmt*.
|
||||
|
||||
|
||||
.. method:: Handler.addFilter(filt)
|
||||
.. method:: Handler.addFilter(filter)
|
||||
|
||||
Adds the specified filter *filt* to this handler.
|
||||
Adds the specified filter *filter* to this handler.
|
||||
|
||||
|
||||
.. method:: Handler.removeFilter(filt)
|
||||
.. method:: Handler.removeFilter(filter)
|
||||
|
||||
Removes the specified filter *filt* from this handler.
|
||||
Removes the specified filter *filter* from this handler.
|
||||
|
||||
|
||||
.. method:: Handler.filter(record)
|
||||
.. method:: Handler.filter(record)
|
||||
|
||||
Applies this handler's filters to the record and returns a true value if the
|
||||
record is to be processed. The filters are consulted in turn, until one of
|
||||
|
|
@ -424,13 +432,13 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
|
|||
record.
|
||||
|
||||
|
||||
.. method:: Handler.flush()
|
||||
.. method:: Handler.flush()
|
||||
|
||||
Ensure all logging output has been flushed. This version does nothing and is
|
||||
intended to be implemented by subclasses.
|
||||
|
||||
|
||||
.. method:: Handler.close()
|
||||
.. method:: Handler.close()
|
||||
|
||||
Tidy up any resources used by the handler. This version does no output but
|
||||
removes the handler from an internal list of handlers which is closed when
|
||||
|
|
@ -438,14 +446,14 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
|
|||
from overridden :meth:`close` methods.
|
||||
|
||||
|
||||
.. method:: Handler.handle(record)
|
||||
.. method:: Handler.handle(record)
|
||||
|
||||
Conditionally emits the specified logging record, depending on filters which may
|
||||
have been added to the handler. Wraps the actual emission of the record with
|
||||
acquisition/release of the I/O thread lock.
|
||||
|
||||
|
||||
.. method:: Handler.handleError(record)
|
||||
.. method:: Handler.handleError(record)
|
||||
|
||||
This method should be called from handlers when an exception is encountered
|
||||
during an :meth:`emit` call. If the module-level attribute
|
||||
|
|
@ -458,13 +466,13 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
|
|||
more useful during development).
|
||||
|
||||
|
||||
.. method:: Handler.format(record)
|
||||
.. method:: Handler.format(record)
|
||||
|
||||
Do formatting for a record - if a formatter is set, use it. Otherwise, use the
|
||||
default formatter for the module.
|
||||
|
||||
|
||||
.. method:: Handler.emit(record)
|
||||
.. method:: Handler.emit(record)
|
||||
|
||||
Do whatever it takes to actually log the specified logging record. This version
|
||||
is intended to be implemented by subclasses and so raises a
|
||||
|
|
@ -772,15 +780,15 @@ the options available to you.
|
|||
| lineno | ``%(lineno)d`` | Source line number where the logging call was |
|
||||
| | | issued (if available). |
|
||||
+----------------+-------------------------+-----------------------------------------------+
|
||||
| message | ``%(message)s`` | The logged message, computed as ``msg % |
|
||||
| | | args``. This is set when |
|
||||
| | | :meth:`Formatter.format` is invoked. |
|
||||
+----------------+-------------------------+-----------------------------------------------+
|
||||
| module | ``%(module)s`` | Module (name portion of ``filename``). |
|
||||
+----------------+-------------------------+-----------------------------------------------+
|
||||
| msecs | ``%(msecs)d`` | Millisecond portion of the time when the |
|
||||
| | | :class:`LogRecord` was created. |
|
||||
+----------------+-------------------------+-----------------------------------------------+
|
||||
| message | ``%(message)s`` | The logged message, computed as ``msg % |
|
||||
| | | args``. This is set when |
|
||||
| | | :meth:`Formatter.format` is invoked. |
|
||||
+----------------+-------------------------+-----------------------------------------------+
|
||||
| msg | You shouldn't need to | The format string passed in the original |
|
||||
| | format this yourself. | logging call. Merged with ``args`` to |
|
||||
| | | produce ``message``, or an arbitrary object |
|
||||
|
|
@ -1023,7 +1031,7 @@ functions.
|
|||
handlers being added multiple times to the root logger, which can in turn
|
||||
lead to multiple messages for the same event.
|
||||
|
||||
.. function:: disable(lvl)
|
||||
.. function:: disable(lvl=CRITICAL)
|
||||
|
||||
Provides an overriding level *lvl* for all loggers which takes precedence over
|
||||
the logger's own level. When the need arises to temporarily throttle logging
|
||||
|
|
@ -1036,6 +1044,14 @@ functions.
|
|||
overriding level, so that logging output again depends on the effective
|
||||
levels of individual loggers.
|
||||
|
||||
Note that if you have defined any custom logging level higher than
|
||||
``CRITICAL`` (this is not recommended), you won't be able to rely on the
|
||||
default value for the *lvl* parameter, but will have to explicitly supply a
|
||||
suitable value.
|
||||
|
||||
.. versionchanged:: 3.7
|
||||
The *lvl* parameter was defaulted to level ``CRITICAL``. See Issue
|
||||
#28524 for more information about this change.
|
||||
|
||||
.. function:: addLevelName(lvl, levelName)
|
||||
|
||||
|
|
@ -1248,4 +1264,3 @@ with the :mod:`warnings` module.
|
|||
package available from this site is suitable for use with Python 1.5.2, 2.1.x
|
||||
and 2.2.x, which do not include the :mod:`logging` package in the standard
|
||||
library.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue