Close #19266: contextlib.ignore -> contextlib.suppress
Patch by Zero Piraeus.
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 @@
``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 @@
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 @@
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 @@
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.