diff options
| -rw-r--r-- | Doc/library/logging.rst | 339 |
1 files changed, 169 insertions, 170 deletions
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index d03cc50..45e1153 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -69,259 +69,259 @@ 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 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(lvl) - 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 *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`. - 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. + 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 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. + 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. - 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 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. - 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`. 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 *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. -.. 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 - ``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() + .. 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. + 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) + .. 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. + 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 + .. 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 - *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.) + 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.) - There are three keyword arguments in *kwargs* which are inspected: - *exc_info*, *stack_info*, and *extra*. + There are three keyword arguments in *kwargs* which are inspected: + *exc_info*, *stack_info*, and *extra*. - 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. + 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. - 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. + 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. - 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:: + 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:: - Stack (most recent call last): + Stack (most recent call last): - This mimics the ``Traceback (most recent call last):`` which is used when - displaying exception frames. + This mimics the ``Traceback (most recent call last):`` which is used when + displaying exception frames. - 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:: + 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:: - 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) + 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) - would print something like :: + would print something like :: - 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset + 2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset - 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.) + 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.) - 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. + 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. - 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. + 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. - .. versionadded:: 3.2 - The *stack_info* parameter was added. + .. versionadded:: 3.2 + The *stack_info* parameter was added. - .. versionchanged:: 3.5 - The *exc_info* parameter can now accept exception instances. + .. versionchanged:: 3.5 + 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`. + 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`. + Logs a message with level :const:`WARNING` on this logger. The arguments are + interpreted as for :meth:`debug`. - .. 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. + .. 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. -.. 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`. + 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`. + 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`. + 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. + 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(filt) - Adds the specified filter *filt* to this logger. + Adds the specified filter *filt* to this logger. -.. method:: Logger.removeFilter(filt) + .. method:: Logger.removeFilter(filt) - Removes the specified filter *filt* from this logger. + Removes the specified filter *filt* 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 - 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) + .. method:: Logger.addHandler(hdlr) - Adds the specified handler *hdlr* to this logger. + Adds the specified handler *hdlr* to this logger. -.. method:: Logger.removeHandler(hdlr) + .. method:: Logger.removeHandler(hdlr) - Removes the specified handler *hdlr* from this logger. + 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``. + 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 - 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) + .. 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. + 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. - 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. + 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 + .. versionadded:: 3.2 .. _levels: @@ -1256,4 +1256,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. - |