bpo-34067: Include a more easily understood example for nullcontext (GH-8158)

banool · ncoghlan · commit c287545d62ed · 2018-07-09T23:49:29.000+10:00
Include a more easily understood example for nullcontext
diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst
@@ -152,10 +152,22 @@ Functions and classes provided:
 
 .. function:: nullcontext(enter_result=None)
 
-   Return a context manager that returns enter_result from ``__enter__``, but
+   Return a context manager that returns *enter_result* from ``__enter__``, but
    otherwise does nothing. It is intended to be used as a stand-in for an
    optional context manager, for example::
 
+      def myfunction(arg, ignore_exceptions=False):
+          if ignore_exceptions:
+              # Use suppress to ignore all exceptions.
+              cm = contextlib.suppress(Exception)
+          else:
+              # Do not ignore any exceptions, cm has no effect.
+              cm = contextlib.nullcontext()
+          with cm:
+              # Do something
+
+   An example using *enter_result*::
+
       def process_file(file_or_path):
           if isinstance(file_or_path, str):
               # If string, open file
