diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 0359750ffe3..669c04aedea 100644 --- 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 befa00d3ef7..d7a6b9c7327 100644 --- 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 ` email API. These classes provide a +:term:`provisional ` 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 41ff9cc448c..144d6bb0f46 100644 --- 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 48f8fa96379..5c1c5c500e5 100644 --- a/Lib/test/test_contextlib.py +++ b/Lib/test/test_contextlib.py @@ -632,28 +632,6 @@ class TestExitStack(unittest.TestCase): stack.push(cm) self.assertIs(stack._exit_callbacks[-1], cm) -class TestIgnore(unittest.TestCase): - - def test_no_exception(self): - - with ignore(ValueError): - self.assertEqual(pow(2, 5), 32) - - def test_exact_exception(self): - - with ignore(TypeError): - len(5) - - def test_multiple_exception_args(self): - - with ignore(ZeroDivisionError, TypeError): - len(5) - - def test_exception_hierarchy(self): - - with ignore(LookupError): - 'Hello'[50] - class TestRedirectStdout(unittest.TestCase): def test_redirect_to_string_io(self): @@ -663,5 +641,27 @@ class TestRedirectStdout(unittest.TestCase): s = f.getvalue() self.assertIn('pow', s) +class TestSuppress(unittest.TestCase): + + def test_no_exception(self): + + with suppress(ValueError): + self.assertEqual(pow(2, 5), 32) + + def test_exact_exception(self): + + with suppress(TypeError): + len(5) + + def test_multiple_exception_args(self): + + with suppress(ZeroDivisionError, TypeError): + len(5) + + def test_exception_hierarchy(self): + + with suppress(LookupError): + 'Hello'[50] + if __name__ == "__main__": unittest.main() diff --git a/Misc/ACKS b/Misc/ACKS index ab39bcf11b0..e204bc30df6 100644 --- 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 28ba51f0fb8..2a8bfd185d7 100644 --- 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.