bpo-43858: Add logging.getLevelNamesMapping() (GH-26459)

Added a function that returns a copy of a dict of logging levels.

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 70a703dde18a0335252a9f832aa731b057b447a7..313cff4ff9658f72191449b766670b99ceb819da 100644 (file)
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -1111,6 +1111,14 @@ functions.
    .. note:: If you are thinking of defining your own levels, please see the
       section on :ref:`custom-levels`.
 
+.. function:: getLevelNamesMapping()
+
+   Returns a mapping from level names to their corresponding logging levels. For example, the
+   string "CRITICAL" maps to :const:`CRITICAL`. The returned mapping is copied from an internal
+   mapping on each call to this function.
+
+   .. versionadded:: 3.11
+
 .. function:: getLevelName(level)
 
    Returns the textual or numeric representation of logging level *level*.

diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py
index 7865b71c8737b4fb1d3c5fbf9942802074617a5e..3538f0670aa3c85d45ea4c76ab37a02d5800717e 100644 (file)
--- a/Lib/logging/__init__.py
+++ b/Lib/logging/__init__.py
@@ -37,7 +37,7 @@ __all__ = ['BASIC_FORMAT', 'BufferingFormatter', 'CRITICAL', 'DEBUG', 'ERROR',
            'exception', 'fatal', 'getLevelName', 'getLogger', 'getLoggerClass',
            'info', 'log', 'makeLogRecord', 'setLoggerClass', 'shutdown',
            'warn', 'warning', 'getLogRecordFactory', 'setLogRecordFactory',
-           'lastResort', 'raiseExceptions']
+           'lastResort', 'raiseExceptions', 'getLevelNamesMapping']
 
 import threading
 
@@ -116,6 +116,9 @@ _nameToLevel = {
     'NOTSET': NOTSET,
 }
 
+def getLevelNamesMapping():
+    return _nameToLevel.copy()
+
 def getLevelName(level):
     """
     Return the textual or numeric representation of logging level 'level'.

diff --git a/Lib/test/test_logging.py b/Lib/test/test_logging.py
index ee00a32026f65ec39c72f73f4f1aa60b198f3d20..6d111908e7c3951c30f651436b4359987c862b37 100644 (file)
--- a/Lib/test/test_logging.py
+++ b/Lib/test/test_logging.py
@@ -4390,6 +4390,14 @@ class ModuleLevelMiscTest(BaseTest):
         self.assertNotIn("Cannot recover from stack overflow.", err)
         self.assertEqual(rc, 1)
 
+    def test_get_level_names_mapping(self):
+        mapping = logging.getLevelNamesMapping()
+        self.assertEqual(logging._nameToLevel, mapping)  # value is equivalent
+        self.assertIsNot(logging._nameToLevel, mapping)  # but not the internal data
+        new_mapping = logging.getLevelNamesMapping()     # another call -> another copy
+        self.assertIsNot(mapping, new_mapping)           # verify not the same object as before
+        self.assertEqual(mapping, new_mapping)           # but equivalent in value
+
 
 class LogRecordTest(BaseTest):
     def test_str_rep(self):

diff --git a/Misc/NEWS.d/next/Library/2021-05-31-04-51-02.bpo-43858.r7LOu6.rst b/Misc/NEWS.d/next/Library/2021-05-31-04-51-02.bpo-43858.r7LOu6.rst
new file mode 100644 (file)
index 0000000..d864e1b
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2021-05-31-04-51-02.bpo-43858.r7LOu6.rst
@@ -0,0 +1 @@
+Added a function that returns a copy of a dict of logging levels: :func:`logging.getLevelNamesMapping`