.. 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:
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.
-
projects / python / commitdiff