Close #19266: contextlib.ignore -> contextlib.suppress

Patch by Zero Piraeus.

diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
index 0359750ffe3d42c80f9be120e131e3c7f4081990..669c04aedea806675e437edee856fc7ea461d4b3 100644 (file)
--- a/Doc/library/contextlib.rst
+++ b/Doc/library/contextlib.rst
@@ -95,22 +95,27 @@ Functions and classes provided:
    ``page.close()`` will be called when the :keyword:`with` block is exited.
 
 
-.. function:: ignore(*exceptions)
+.. function:: suppress(*exceptions)
 
-   Return a context manager that ignores the specified exceptions if they
-   occur in the body of a with-statement.
+   Return a context manager that suppresses any of the specified exceptions
+   if they occur in the body of a with statement and then resumes execution
+   with the first statement following the end of the with statement.
 
-   As with any other mechanism that completely suppresses exceptions, it
-   should only be used to cover very specific errors where silently
-   ignoring the exception is known to be the right thing to do.
+   As with any other mechanism that completely suppresses exceptions, this
+   context manager should be used only to cover very specific errors where
+   silently continuing with program execution is known to be the right
+   thing to do.
 
    For example::
 
-       from contextlib import ignore
+       from contextlib import suppress
 
-       with ignore(FileNotFoundError):
+       with suppress(FileNotFoundError):
            os.remove('somefile.tmp')
 
+       with suppress(FileNotFoundError):
+           os.remove('someotherfile.tmp')
+
    This code is equivalent to::
 
        try:
@@ -118,6 +123,11 @@ Functions and classes provided:
        except FileNotFoundError:
            pass
 
+       try:
+           os.remove('someotherfile.tmp')
+       except FileNotFoundError:
+           pass
+
    .. versionadded:: 3.4
 
 

diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index befa00d3ef73037a3a065833112db16b53ef1f37..d7a6b9c73275164cfbb35207a7c1f39b3b9c42b7 100644 (file)
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -221,14 +221,17 @@ results should be less than 1% and may better match results found elsewhere.
 contextlib
 ----------
 
-The new :class:`contextlib.ignore` context manager helps to clarify the
-intent of code that deliberately ignores failures from a particular
-operation.
+The new :class:`contextlib.suppress` context manager helps to clarify the
+intent of code that deliberately suppresses exceptions from a single
+statement. (Contributed by Raymond Hettinger in :issue:`15806` and
+Zero Piraeus in :issue:`19266`)
+
 
 The new :class:`contextlib.redirect_stdio` context manager makes it easier
 for utility scripts to handle inflexible APIs that don't provide any
 options to retrieve their output as a string or direct it to somewhere
-other than :data:`sys.stdout`.
+other than :data:`sys.stdout`. (Contribute by Raymond Hettinger in
+:issue:`15805`)
 
 
 dis
@@ -283,7 +286,7 @@ result:  a bytes object containing the fully formatted message.
 A pair of new subclasses of :class:`~email.message.Message` have been added,
 along with a new sub-module, :mod:`~email.contentmanager`.  All documentation
 is currently in the new module, which is being added as part of the new
-:term:`provisional <provosional package>` email API.  These classes provide a
+:term:`provisional <provisional package>` email API.  These classes provide a
 number of new methods that make extracting content from and inserting content
 into email messages much easier.  See the :mod:`~email.contentmanager`
 documentation for details.

diff --git a/Lib/contextlib.py b/Lib/contextlib.py
index 41ff9cc448cc304d26dabe60526607e2a1eee470..144d6bb0f46463334b289808a5d26d84e62a38be 100644 (file)
--- a/Lib/contextlib.py
+++ b/Lib/contextlib.py
@@ -5,7 +5,7 @@ from collections import deque
 from functools import wraps
 
 __all__ = ["contextmanager", "closing", "ContextDecorator", "ExitStack",
-           "ignore", "redirect_stdout"]
+           "redirect_stdout", "suppress"]
 
 
 class ContextDecorator(object):
@@ -179,10 +179,10 @@ class redirect_stdout:
         sys.stdout = self.old_target
 
 @contextmanager
-def ignore(*exceptions):
-    """Context manager to ignore specified exceptions
+def suppress(*exceptions):
+    """Context manager to suppress specified exceptions
 
-         with ignore(OSError):
+         with suppress(OSError):
              os.remove(somefile)
 
     """

diff --git a/Lib/test/test_contextlib.py b/Lib/test/test_contextlib.py
index 48f8fa96379c542b07974bcc75af7fc4e72e32f8..5c1c5c500e5ae229bf1385f554dbe40abb3125cb 100644 (file)
--- a/Lib/test/test_contextlib.py
+++ b/Lib/test/test_contextlib.py
@@ -632,36 +632,36 @@ class TestExitStack(unittest.TestCase):
         stack.push(cm)
         self.assertIs(stack._exit_callbacks[-1], cm)
 
-class TestIgnore(unittest.TestCase):
+class TestRedirectStdout(unittest.TestCase):
+
+    def test_redirect_to_string_io(self):
+        f = io.StringIO()
+        with redirect_stdout(f):
+            help(pow)
+        s = f.getvalue()
+        self.assertIn('pow', s)
+
+class TestSuppress(unittest.TestCase):
 
     def test_no_exception(self):
 
-        with ignore(ValueError):
+        with suppress(ValueError):
             self.assertEqual(pow(2, 5), 32)
 
     def test_exact_exception(self):
 
-        with ignore(TypeError):
+        with suppress(TypeError):
             len(5)
 
     def test_multiple_exception_args(self):
 
-        with ignore(ZeroDivisionError, TypeError):
+        with suppress(ZeroDivisionError, TypeError):
             len(5)
 
     def test_exception_hierarchy(self):
 
-        with ignore(LookupError):
+        with suppress(LookupError):
             'Hello'[50]
 
-class TestRedirectStdout(unittest.TestCase):
-
-    def test_redirect_to_string_io(self):
-        f = io.StringIO()
-        with redirect_stdout(f):
-            help(pow)
-        s = f.getvalue()
-        self.assertIn('pow', s)
-
 if __name__ == "__main__":
     unittest.main()

diff --git a/Misc/ACKS b/Misc/ACKS
index ab39bcf11b0ddfb1bd843d419a51d93b4411aa88..e204bc30df67c7339c4f97a111da4df87f37fa28 100644 (file)
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1003,6 +1003,7 @@ Anand B. Pillai
 François Pinard
 Tom Pinckney
 Zach Pincus
+Zero Piraeus
 Michael Piotrowski
 Antoine Pitrou
 Jean-François Piéronne

diff --git a/Misc/NEWS b/Misc/NEWS
index 28ba51f0fb80f24d6c1fd47536cb04e35c2b1dd2..2a8bfd185d76e8ce5289e6dd10812821359df2c7 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -42,6 +42,11 @@ Core and Builtins
 Library
 -------
 
+- Issue #19266: Rename the new-in-3.4 ``contextlib.ignore`` context manager
+  to ``contextlib.suppress`` in order to be more consistent with existing
+  descriptions of that operation elsewhere in the language and standard
+  library documentation (Patch by Zero Piraeus)
+
 - Issue #18891: Completed the new email package (provisional) API additions
   by adding new classes EmailMessage, MIMEPart, and ContentManager.