[Python-checkins] cpython (3.4): Issue #22436: Improved documentation for getEffectiveLevel() and getLevelName().

Thu Sep 18 19:02:59 CEST 2014

http://hg.python.org/cpython/rev/72a91df86b07
changeset: 92469:72a91df86b07
branch: 3.4
parent: 92466:1e81c7a261a7
user: Vinay Sajip <vinay_sajip at yahoo.co.uk>
date: Thu Sep 18 18:01:12 2014 +0100
summary:
 Issue #22436: Improved documentation for getEffectiveLevel() and getLevelName().
files:
 Doc/library/logging.rst | 13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -118,7 +118,9 @@
 .. 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 @@
 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 @@
 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.
-- 
Repository URL: http://hg.python.org/cpython
