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,260 +69,266 @@ 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.
|
||||
If this evaluates to false, logging messages are not passed to the handlers
|
||||
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
|
||||
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
|
||||
attach it to the appropriate logger which is highest in the logger
|
||||
hierarchy, then it will see all events logged by all descendant loggers,
|
||||
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
|
||||
propagation take care of the rest.
|
||||
.. 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
|
||||
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
|
||||
hierarchy, then it will see all events logged by all descendant loggers,
|
||||
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
|
||||
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*.
|
||||
|
||||
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
|
||||
a level other than NOTSET is found, or the root is reached.
|
||||
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`.
|
||||
|
||||
If an ancestor is found with a level other than NOTSET, then that ancestor's
|
||||
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.
|
||||
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
|
||||
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
|
||||
processed. Otherwise, the root's level will be used as the effective level.
|
||||
If an ancestor is found with a level other than NOTSET, then that ancestor's
|
||||
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
|
||||
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.
|
||||
See :ref:`levels` for a list of levels.
|
||||
|
||||
.. 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.
|
||||
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.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
|
||||
``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
|
||||
: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.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,
|
||||
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.
|
||||
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.
|
||||
.. method:: Logger.getChild(suffix)
|
||||
|
||||
.. 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
|
||||
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.)
|
||||
.. method:: Logger.debug(msg, *args, **kwargs)
|
||||
|
||||
There are three keyword arguments in *kwargs* which are inspected:
|
||||
*exc_info*, *stack_info*, and *extra*.
|
||||
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
|
||||
*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
|
||||
added to the logging message. If an exception tuple (in the format returned by
|
||||
: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.
|
||||
There are three keyword arguments in *kwargs* which are inspected:
|
||||
*exc_info*, *stack_info*, and *extra*.
|
||||
|
||||
The second optional keyword argument is *stack_info*, which defaults to
|
||||
``False``. If true, stack information is added to the logging
|
||||
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.
|
||||
If *exc_info* does not evaluate as false, it causes exception information to be
|
||||
added to the logging message. If an exception tuple (in the format returned by
|
||||
: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.
|
||||
|
||||
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::
|
||||
The second optional keyword argument is *stack_info*, which defaults to
|
||||
``False``. If true, stack information is added to the logging
|
||||
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
|
||||
displaying exception frames.
|
||||
Stack (most recent call last):
|
||||
|
||||
The third keyword argument is *extra* which can be used to pass a
|
||||
dictionary which is used to populate the __dict__ of the LogRecord created for
|
||||
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::
|
||||
This mimics the ``Traceback (most recent call last):`` which is used when
|
||||
displaying exception frames.
|
||||
|
||||
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)
|
||||
The third keyword argument is *extra* which can be used to pass a
|
||||
dictionary which is used to populate the __dict__ of the LogRecord created for
|
||||
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::
|
||||
|
||||
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
|
||||
by the logging system. (See the :class:`Formatter` documentation for more
|
||||
information on which keys are used by the logging system.)
|
||||
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
|
||||
|
||||
If you choose to use these attributes in logged messages, you need to exercise
|
||||
some care. In the above example, for instance, the :class:`Formatter` has been
|
||||
set up with a format string which expects 'clientip' and 'user' in the attribute
|
||||
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.
|
||||
The keys in the dictionary passed in *extra* should not clash with the keys used
|
||||
by the logging system. (See the :class:`Formatter` documentation for more
|
||||
information on which keys are used by the logging system.)
|
||||
|
||||
While this might be annoying, this feature is intended for use in specialized
|
||||
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.
|
||||
If you choose to use these attributes in logged messages, you need to exercise
|
||||
some care. In the above example, for instance, the :class:`Formatter` has been
|
||||
set up with a format string which expects 'clientip' and 'user' in the attribute
|
||||
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.
|
||||
|
||||
.. versionadded:: 3.2
|
||||
The *stack_info* parameter was added.
|
||||
While this might be annoying, this feature is intended for use in specialized
|
||||
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
|
||||
The *exc_info* parameter can now accept exception instances.
|
||||
.. versionadded:: 3.2
|
||||
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
|
||||
interpreted as for :meth:`debug`.
|
||||
.. 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)
|
||||
|
||||
Logs a message with level :const:`WARNING` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
.. method:: Logger.warning(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:`WARNING` on this logger. The arguments are
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
.. 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
|
||||
interpreted as for :meth:`debug`.
|
||||
.. 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)
|
||||
|
||||
Logs a message with level :const:`CRITICAL` 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
|
||||
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
|
||||
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
|
||||
interpreted as for :meth:`debug`.
|
||||
|
||||
.. 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.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)
|
||||
|
||||
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
|
||||
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.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
|
||||
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
|
||||
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.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)
|
||||
|
||||
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.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
|
||||
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
|
||||
specialized :class:`LogRecord` instances.
|
||||
.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None, sinfo=None)
|
||||
|
||||
.. 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
|
||||
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.
|
||||
.. method:: Logger.hasHandlers()
|
||||
|
||||
.. 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:
|
||||
|
||||
|
|
@ -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
|
||||
: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.
|
||||
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.
|
||||
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`.
|
||||
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
|
||||
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.
|
||||
See :ref:`levels` for a list of levels.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
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`.
|
||||
.. 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`.
|
||||
|
||||
|
||||
.. 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
|
||||
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
|
||||
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
|
||||
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
|
||||
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.
|
||||
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
|
||||
:func:`shutdown` is called. Subclasses should ensure that this gets called
|
||||
from overridden :meth:`close` methods.
|
||||
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
|
||||
:func:`shutdown` is called. Subclasses should ensure that this gets called
|
||||
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.
|
||||
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
|
||||
``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
|
||||
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. 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
|
||||
occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
|
||||
more useful during development).
|
||||
This method should be called from handlers when an exception is encountered
|
||||
during an :meth:`emit` call. If the module-level attribute
|
||||
``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
|
||||
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. 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
|
||||
occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
|
||||
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.
|
||||
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
|
||||
:exc:`NotImplementedError`.
|
||||
Do whatever it takes to actually log the specified logging record. This version
|
||||
is intended to be implemented by subclasses and so raises a
|
||||
:exc:`NotImplementedError`.
|
||||
|
||||
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 |
|
||||
| | | 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