From 2f1cd8a7fcda6080888553b3c0f9ac34b1caad37 Mon Sep 17 00:00:00 2001 From: Vinay Sajip Date: Thu, 18 Sep 2014 18:01:12 +0100 Subject: [PATCH] Issue #22436: Improved documentation for getEffectiveLevel() and getLevelName(). --- Doc/library/logging.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 99837116443..96861a7b9e3 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -118,7 +118,9 @@ is the module's name in the Python package namespace. .. 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`. + 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) @@ -134,7 +136,9 @@ is the module's name in the Python package namespace. 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. + :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) @@ -1049,6 +1053,11 @@ functions. of the defined levels is passed in, the corresponding string representation is returned. Otherwise, the string 'Level %s' % lvl is returned. + .. note:: Levels are internally integers (as they need to be compared in the + logging logic). This function is used to convert between an integer level + and the level name displayed in the formatted log output by means of the + ``%(levelname)s`` format specifier (see :ref:`logrecord-attributes`). + .. versionchanged:: 3.4 In Python versions earlier than 3.4, this function could also be passed a text level, and would return the corresponding numeric value of the level.