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

[vinay.sajip]

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