[Python-checkins] [3.9] bpo-43353: Document that logging.getLevelName() accepts string representation of logging level. (GH-24693) (GH-24826)

[miss-islington]

https://github.com/python/cpython/commit/4d7f11e05731f67fd2c07ec2972c6cb9861d52be
commit: 4d7f11e05731f67fd2c07ec2972c6cb9861d52be
branch: 3.9
author: Mariusz Felisiak <felisiak.mariusz at gmail.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2021-03-12T00:46:07-08:00
summary:

[3.9] bpo-43353: Document that logging.getLevelName() accepts string representation of logging level. (GH-24693) (GH-24826)



(cherry picked from commit bbba28212ce0f58096a4043f32442c6e727b74fc)

Automerge-Triggered-By: GH:vsajip

files:
M Doc/library/logging.rst
M Lib/logging/__init__.py

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index e63475d3b5a02..788925fed52ac 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1106,18 +1106,27 @@ functions.
 
 .. function:: getLevelName(level)
 
-   Returns the textual representation of logging level *level*. If the level is one
-   of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,
-   :const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you
-   have associated levels with names using :func:`addLevelName` then the name you
-   have associated with *level* is returned. If a numeric value corresponding to one
-   of the defined levels is passed in, the corresponding string representation is
-   returned. Otherwise, the string 'Level %s' % level is returned.
+   Returns the textual or numeric representation of logging level *level*.
+
+   If *level* is one of the predefined levels :const:`CRITICAL`, :const:`ERROR`,
+   :const:`WARNING`, :const:`INFO` or :const:`DEBUG` then you get the
+   corresponding string. If you have associated levels with names using
+   :func:`addLevelName` then the name you have associated with *level* is
+   returned. If a numeric value corresponding to one of the defined levels is
+   passed in, the corresponding string representation is returned.
+
+   The *level* parameter also accepts a string representation of the level such
+   as 'INFO'. In such cases, this functions returns the corresponding numeric
+   value of the level.
+
+   If no matching numeric or string value is passed in, the string
+   'Level %s' % level 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`).
+      ``%(levelname)s`` format specifier (see :ref:`logrecord-attributes`), and
+      vice versa.
 
    .. versionchanged:: 3.4
       In Python versions earlier than 3.4, this function could also be passed a
diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py
index 6920a7b654a59..1ab35a8c21a10 100644
--- a/Lib/logging/__init__.py
+++ b/Lib/logging/__init__.py
@@ -118,7 +118,7 @@
 
 def getLevelName(level):
     """
-    Return the textual representation of logging level 'level'.
+    Return the textual or numeric representation of logging level 'level'.
 
     If the level is one of the predefined levels (CRITICAL, ERROR, WARNING,
     INFO, DEBUG) then you get the corresponding string. If you have
@@ -128,7 +128,11 @@ def getLevelName(level):
     If a numeric value corresponding to one of the defined levels is passed
     in, the corresponding string representation is returned.
 
-    Otherwise, the string "Level %s" % level is returned.
+    If a string representation of the level is passed in, the corresponding
+    numeric value is returned.
+
+    If no matching numeric or string value is passed in, the string
+    'Level %s' % level is returned.
     """
     # See Issues #22386, #27937 and #29220 for why it's this way
     result = _levelToName.get(level)