traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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 2017-12-09 12:28:16 +00:00 committed by GitHub
parent a04ca12e12
commit 63868181a9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 251 additions and 236 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

487
Doc/library/logging.rst
View File

@ -69,260 +69,266 @@ is the module's name in the Python package namespace.
.. class:: Logger .. class:: Logger
.. attribute:: Logger.propagate .. attribute:: Logger.propagate
If this evaluates to true, events logged to this logger will be passed to the If this attribute evaluates to true, events logged to this logger will be
handlers of higher level (ancestor) loggers, in addition to any handlers passed to the handlers of higher level (ancestor) loggers, in addition to
attached to this logger. Messages are passed directly to the ancestor any handlers attached to this logger. Messages are passed directly to the
loggers' handlers - neither the level nor filters of the ancestor loggers in ancestor loggers' handlers - neither the level nor filters of the ancestor
question are considered. loggers in question are considered.
If this evaluates to false, logging messages are not passed to the handlers If this evaluates to false, logging messages are not passed to the handlers
of ancestor loggers. of ancestor loggers.
The constructor sets this attribute to ``True``. The constructor sets this attribute to ``True``.
.. note:: If you attach a handler to a logger *and* one or more of its .. note:: If you attach a handler to a logger *and* one or more of its
ancestors, it may emit the same record multiple times. In general, you ancestors, it may emit the same record multiple times. In general, you
should not need to attach a handler to more than one logger - if you just should not need to attach a handler to more than one logger - if you just
attach it to the appropriate logger which is highest in the logger attach it to the appropriate logger which is highest in the logger
hierarchy, then it will see all events logged by all descendant loggers, hierarchy, then it will see all events logged by all descendant loggers,
provided that their propagate setting is left set to ``True``. A common provided that their propagate setting is left set to ``True``. A common
scenario is to attach handlers only to the root logger, and to let scenario is to attach handlers only to the root logger, and to let
propagation take care of the rest. 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 Sets the threshold for this logger to *level*. Logging messages which are less
severe than *lvl* will be ignored. When a logger is created, the level is set to severe than *level* will be ignored; logging messages which have severity *level*
:const:`NOTSET` (which causes all messages to be processed when the logger is or higher will be emitted by whichever handler or handlers service this logger,
the root logger, or delegation to the parent when the logger is a non-root unless a handler's level has been set to a higher severity level than *level*.
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 When a logger is created, the level is set to :const:`NOTSET` (which causes
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with all messages to be processed when the logger is the root logger, or delegation
a level other than NOTSET is found, or the root is reached. to the parent when the logger is a non-root logger). Note that the root logger
is created with level :const:`WARNING`.
If an ancestor is found with a level other than NOTSET, then that ancestor's The term 'delegation to the parent' means that if a logger has a level of
level is treated as the effective level of the logger where the ancestor search NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
began, and is used to determine how a logging event is handled. a level other than NOTSET is found, or the root is reached.
If the root is reached, and it has a level of NOTSET, then all messages will be If an ancestor is found with a level other than NOTSET, then that ancestor's
processed. Otherwise, the root's level will be used as the effective level. level is treated as the effective level of the logger where the ancestor search
began, and is used to determine how a logging event is handled.
See :ref:`levels` for a list of levels. If the root is reached, and it has a level of NOTSET, then all messages will be
processed. Otherwise, the root's level will be used as the effective level.
.. versionchanged:: 3.2 See :ref:`levels` for a list of levels.
The *lvl* 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.
.. versionchanged:: 3.2
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)
Indicates if a message of severity *lvl* would be processed by this logger. .. method:: Logger.isEnabledFor(lvl)
This method checks first the module-level level set by
``logging.disable(lvl)`` and then the logger's effective level as determined
by :meth:`getEffectiveLevel`.
Indicates if a message of severity *lvl* would be processed by this logger.
This method checks first the module-level level set by
``logging.disable(lvl)`` and then the logger's effective level as determined
by :meth:`getEffectiveLevel`.
.. method:: Logger.getEffectiveLevel()
Indicates the effective level for this logger. If a value other than .. method:: Logger.getEffectiveLevel()
:const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
the hierarchy is traversed towards the root until a value other than
:const:`NOTSET` is found, and that value is returned. The value returned is
an integer, typically one of :const:`logging.DEBUG`, :const:`logging.INFO`
etc.
Indicates the effective level for this logger. If a value other than
:const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
the hierarchy is traversed towards the root until a value other than
:const:`NOTSET` is found, and that value is returned. The value returned is
an integer, typically one of :const:`logging.DEBUG`, :const:`logging.INFO`
etc.
.. method:: Logger.getChild(suffix)
Returns a logger which is a descendant to this logger, as determined by the suffix. .. method:: Logger.getChild(suffix)
Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same
logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a
convenience method, useful when the parent logger is named using e.g. ``__name__``
rather than a literal string.
.. versionadded:: 3.2 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
logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a
convenience method, useful when the parent logger is named using e.g. ``__name__``
rather than a literal string.
.. versionadded:: 3.2
.. method:: Logger.debug(msg, *args, **kwargs)
Logs a message with level :const:`DEBUG` on this logger. The *msg* is the .. method:: Logger.debug(msg, *args, **kwargs)
message format string, and the *args* are the arguments which are merged into
*msg* using the string formatting operator. (Note that this means that you can
use keywords in the format string, together with a single dictionary argument.)
There are three keyword arguments in *kwargs* which are inspected: Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
*exc_info*, *stack_info*, and *extra*. message format string, and the *args* are the arguments which are merged into
*msg* using the string formatting operator. (Note that this means that you can
use keywords in the format string, together with a single dictionary argument.)
If *exc_info* does not evaluate as false, it causes exception information to be There are three keyword arguments in *kwargs* which are inspected:
added to the logging message. If an exception tuple (in the format returned by *exc_info*, *stack_info*, and *extra*.
:func:`sys.exc_info`) or an exception instance is provided, it is used;
otherwise, :func:`sys.exc_info` is called to get the exception information.
The second optional keyword argument is *stack_info*, which defaults to If *exc_info* does not evaluate as false, it causes exception information to be
``False``. If true, stack information is added to the logging added to the logging message. If an exception tuple (in the format returned by
message, including the actual logging call. Note that this is not the same :func:`sys.exc_info`) or an exception instance is provided, it is used;
stack information as that displayed through specifying *exc_info*: The otherwise, :func:`sys.exc_info` is called to get the exception information.
former is stack frames from the bottom of the stack up to the logging call
in the current thread, whereas the latter is information about stack frames
which have been unwound, following an exception, while searching for
exception handlers.
You can specify *stack_info* independently of *exc_info*, e.g. to just show The second optional keyword argument is *stack_info*, which defaults to
how you got to a certain point in your code, even when no exceptions were ``False``. If true, stack information is added to the logging
raised. The stack frames are printed following a header line which says:: message, including the actual logging call. Note that this is not the same
stack information as that displayed through specifying *exc_info*: The
former is stack frames from the bottom of the stack up to the logging call
in the current thread, whereas the latter is information about stack frames
which have been unwound, following an exception, while searching for
exception handlers.
Stack (most recent call last): You can specify *stack_info* independently of *exc_info*, e.g. to just show
how you got to a certain point in your code, even when no exceptions were
raised. The stack frames are printed following a header line which says::
This mimics the ``Traceback (most recent call last):`` which is used when Stack (most recent call last):
displaying exception frames.
The third keyword argument is *extra* which can be used to pass a This mimics the ``Traceback (most recent call last):`` which is used when
dictionary which is used to populate the __dict__ of the LogRecord created for displaying exception frames.
the logging event with user-defined attributes. These custom attributes can then
be used as you like. For example, they could be incorporated into logged
messages. For example::
FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s' The third keyword argument is *extra* which can be used to pass a
logging.basicConfig(format=FORMAT) dictionary which is used to populate the __dict__ of the LogRecord created for
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'} the logging event with user-defined attributes. These custom attributes can then
logger = logging.getLogger('tcpserver') be used as you like. For example, they could be incorporated into logged
logger.warning('Protocol problem: %s', 'connection reset', extra=d) messages. For example::
would print something like :: FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset would print something like ::
The keys in the dictionary passed in *extra* should not clash with the keys used 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
by the logging system. (See the :class:`Formatter` documentation for more
information on which keys are used by the logging system.)
If you choose to use these attributes in logged messages, you need to exercise The keys in the dictionary passed in *extra* should not clash with the keys used
some care. In the above example, for instance, the :class:`Formatter` has been by the logging system. (See the :class:`Formatter` documentation for more
set up with a format string which expects 'clientip' and 'user' in the attribute information on which keys are used by the logging system.)
dictionary of the LogRecord. If these are missing, the message will not be
logged because a string formatting exception will occur. So in this case, you
always need to pass the *extra* dictionary with these keys.
While this might be annoying, this feature is intended for use in specialized If you choose to use these attributes in logged messages, you need to exercise
circumstances, such as multi-threaded servers where the same code executes in some care. In the above example, for instance, the :class:`Formatter` has been
many contexts, and interesting conditions which arise are dependent on this set up with a format string which expects 'clientip' and 'user' in the attribute
context (such as remote client IP address and authenticated user name, in the dictionary of the LogRecord. If these are missing, the message will not be
above example). In such circumstances, it is likely that specialized logged because a string formatting exception will occur. So in this case, you
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s. always need to pass the *extra* dictionary with these keys.
.. versionadded:: 3.2 While this might be annoying, this feature is intended for use in specialized
The *stack_info* parameter was added. circumstances, such as multi-threaded servers where the same code executes in
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
.. versionchanged:: 3.5 .. versionadded:: 3.2
The *exc_info* parameter can now accept exception instances. The *stack_info* parameter was added.
.. versionchanged:: 3.5
The *exc_info* parameter can now accept exception instances.
.. method:: Logger.info(msg, *args, **kwargs)
Logs a message with level :const:`INFO` on this logger. The arguments are .. method:: Logger.info(msg, *args, **kwargs)
interpreted as for :meth:`debug`.
Logs a message with level :const:`INFO` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.warning(msg, *args, **kwargs)
Logs a message with level :const:`WARNING` on this logger. The arguments are .. method:: Logger.warning(msg, *args, **kwargs)
interpreted as for :meth:`debug`.
.. note:: There is an obsolete method ``warn`` which is functionally Logs a message with level :const:`WARNING` on this logger. The arguments are
identical to ``warning``. As ``warn`` is deprecated, please do not use interpreted as for :meth:`debug`.
it - use ``warning`` instead.
.. method:: Logger.error(msg, *args, **kwargs) .. note:: There is an obsolete method ``warn`` which is functionally
identical to ``warning``. As ``warn`` is deprecated, please do not use
it - use ``warning`` instead.
Logs a message with level :const:`ERROR` on this logger. The arguments are .. method:: Logger.error(msg, *args, **kwargs)
interpreted as for :meth:`debug`.
Logs a message with level :const:`ERROR` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.critical(msg, *args, **kwargs)
Logs a message with level :const:`CRITICAL` on this logger. The arguments are .. method:: Logger.critical(msg, *args, **kwargs)
interpreted as for :meth:`debug`.
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)
Logs a message with integer level *lvl* on this logger. The other arguments are .. method:: Logger.log(lvl, msg, *args, **kwargs)
interpreted as for :meth:`debug`.
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)
Logs a message with level :const:`ERROR` on this logger. The arguments are .. method:: Logger.exception(msg, *args, **kwargs)
interpreted as for :meth:`debug`. Exception info is added to the logging
message. This method should only be called from an exception handler.
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)
Adds the specified filter *filt* to this logger. .. method:: Logger.addFilter(filter)
Adds the specified filter *filter* to this logger.
.. method:: Logger.removeFilter(filt)
Removes the specified filter *filt* from this logger. .. method:: Logger.removeFilter(filter)
Removes the specified filter *filter* from this logger.
.. method:: Logger.filter(record)
Applies this logger's filters to the record and returns a true value if the .. method:: Logger.filter(record)
record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record
will be processed (passed to handlers). If one returns a false value, no
further processing of the record occurs.
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
them returns a false value. If none of them return a false value, the record
will be processed (passed to handlers). If one returns a false value, no
further processing of the record occurs.
.. method:: Logger.addHandler(hdlr)
Adds the specified handler *hdlr* to this logger. .. method:: Logger.addHandler(hdlr)
Adds the specified handler *hdlr* to this logger.
.. method:: Logger.removeHandler(hdlr)
Removes the specified handler *hdlr* from this logger. .. method:: Logger.removeHandler(hdlr)
Removes the specified handler *hdlr* from this logger.
.. method:: Logger.findCaller(stack_info=False)
Finds the caller's source filename and line number. Returns the filename, line .. method:: Logger.findCaller(stack_info=False)
number, function name and stack information as a 4-element tuple. The stack
information is returned as ``None`` unless *stack_info* is ``True``.
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)
Handles a record by passing it to all handlers associated with this logger and .. method:: Logger.handle(record)
its ancestors (until a false value of *propagate* is found). This method is used
for unpickled records received from a socket, as well as those created locally.
Logger-level filtering is applied using :meth:`~Logger.filter`.
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
for unpickled records received from a socket, as well as those created locally.
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)
This is a factory method which can be overridden in subclasses to create .. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)
specialized :class:`LogRecord` instances.
.. method:: Logger.hasHandlers() This is a factory method which can be overridden in subclasses to create
specialized :class:`LogRecord` instances.
Checks to see if this logger has any handlers configured. This is done by .. method:: Logger.hasHandlers()
looking for handlers in this logger and its parents in the logger hierarchy.
Returns ``True`` if a handler was found, else ``False``. The method stops searching
up the hierarchy whenever a logger with the 'propagate' attribute set to
false is found - that will be the last logger which is checked for the
existence of handlers.
.. versionadded:: 3.2 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.
Returns ``True`` if a handler was found, else ``False``. The method stops searching
up the hierarchy whenever a logger with the 'propagate' attribute set to
false is found - that will be the last logger which is checked for the
existence of handlers.
.. versionadded:: 3.2
.. versionchanged:: 3.7
Loggers can now be picked and unpickled.
.. _levels: .. _levels:
@ -362,113 +368,115 @@ is never instantiated directly; this class acts as a base for more useful
subclasses. However, the :meth:`__init__` method in subclasses needs to call subclasses. However, the :meth:`__init__` method in subclasses needs to call
:meth:`Handler.__init__`. :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 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 of filters to the empty list and creating a lock (using :meth:`createLock`) for
serializing access to an I/O mechanism. 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 Initializes a thread lock which can be used to serialize access to underlying
I/O functionality which may not be threadsafe. I/O functionality which may not be threadsafe.
.. method:: Handler.acquire() .. method:: Handler.acquire()
Acquires the thread lock created with :meth:`createLock`. Acquires the thread lock created with :meth:`createLock`.
.. method:: Handler.release() .. method:: Handler.release()
Releases the thread lock acquired with :meth:`acquire`. 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 Sets the threshold for this handler to *level*. Logging messages which are
severe than *lvl* will be ignored. When a handler is created, the level is set less severe than *level* will be ignored. When a handler is created, the
to :const:`NOTSET` (which causes all messages to be processed). level is set to :const:`NOTSET` (which causes all messages to be
processed).
See :ref:`levels` for a list of levels. See :ref:`levels` for a list of levels.
.. versionchanged:: 3.2 .. 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 level such as 'INFO' as an alternative to the integer constants
such as :const:`INFO`. 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 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 record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record them returns a false value. If none of them return a false value, the record
will be emitted. If one returns a false value, the handler will not emit the will be emitted. If one returns a false value, the handler will not emit the
record. record.
.. method:: Handler.flush() .. method:: Handler.flush()
Ensure all logging output has been flushed. This version does nothing and is Ensure all logging output has been flushed. This version does nothing and is
intended to be implemented by subclasses. 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 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 removes the handler from an internal list of handlers which is closed when
:func:`shutdown` is called. Subclasses should ensure that this gets called :func:`shutdown` is called. Subclasses should ensure that this gets called
from overridden :meth:`close` methods. from overridden :meth:`close` methods.
.. method:: Handler.handle(record) .. method:: Handler.handle(record)
Conditionally emits the specified logging record, depending on filters which may 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 have been added to the handler. Wraps the actual emission of the record with
acquisition/release of the I/O thread lock. 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 This method should be called from handlers when an exception is encountered
during an :meth:`emit` call. If the module-level attribute during an :meth:`emit` call. If the module-level attribute
``raiseExceptions`` is ``False``, exceptions get silently ignored. This is ``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
what is mostly wanted for a logging system - most users will not care about what is mostly wanted for a logging system - most users will not care about
errors in the logging system, they are more interested in application errors in the logging system, they are more interested in application
errors. You could, however, replace this with a custom handler if you wish. errors. You could, however, replace this with a custom handler if you wish.
The specified record is the one which was being processed when the exception The specified record is the one which was being processed when the exception
occurred. (The default value of ``raiseExceptions`` is ``True``, as that is occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
more useful during development). 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 Do formatting for a record - if a formatter is set, use it. Otherwise, use the
default formatter for the module. 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 Do whatever it takes to actually log the specified logging record. This version
is intended to be implemented by subclasses and so raises a is intended to be implemented by subclasses and so raises a
:exc:`NotImplementedError`. :exc:`NotImplementedError`.
For a list of handlers included as standard, see :mod:`logging.handlers`. For a list of handlers included as standard, see :mod:`logging.handlers`.
@ -772,15 +780,15 @@ the options available to you.
| lineno | ``%(lineno)d`` | Source line number where the logging call was | | lineno | ``%(lineno)d`` | Source line number where the logging call was |
| | | issued (if available). | | | | 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``). | | module | ``%(module)s`` | Module (name portion of ``filename``). |
+----------------+-------------------------+-----------------------------------------------+ +----------------+-------------------------+-----------------------------------------------+
| msecs | ``%(msecs)d`` | Millisecond portion of the time when the | | msecs | ``%(msecs)d`` | Millisecond portion of the time when the |
| | | :class:`LogRecord` was created. | | | | :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 | | msg | You shouldn't need to | The format string passed in the original |
| | format this yourself. | logging call. Merged with ``args`` to | | | format this yourself. | logging call. Merged with ``args`` to |
| | | produce ``message``, or an arbitrary object | | | | produce ``message``, or an arbitrary object |
@ -1023,7 +1031,7 @@ functions.
handlers being added multiple times to the root logger, which can in turn handlers being added multiple times to the root logger, which can in turn
lead to multiple messages for the same event. 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 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 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 overriding level, so that logging output again depends on the effective
levels of individual loggers. 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) .. 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 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 and 2.2.x, which do not include the :mod:`logging` package in the standard
library. library.