diff options
| -rw-r--r-- | Doc/library/contextlib.rst | 26 | ||||
| -rw-r--r-- | Doc/whatsnew/3.4.rst | 13 | ||||
| -rw-r--r-- | Lib/contextlib.py | 8 | ||||
| -rw-r--r-- | Lib/test/test_contextlib.py | 28 | ||||
| -rw-r--r-- | Misc/ACKS | 1 | ||||
| -rw-r--r-- | Misc/NEWS | 5 |
6 files changed, 50 insertions, 31 deletions
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index 0359750..669c04a 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 befa00d..d7a6b9c 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 <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 41ff9cc..144d6bb 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 48f8fa9..5c1c5c5 100644 --- 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() @@ -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 @@ -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. |