bpo-34764: improve docs example of iter() with sentinel value (GH-11222) (#11301)

(cherry picked from commit d378b1f8ed7919f65a89f026bc899204be3773d4)

Co-authored-by: Chris Rands <c_rands100@hotmail.com>

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 5e37204a24461ae1eb7faab3c3f48bb6f1ea8a28..ec3388346a65b533166cb4df53a85cc5b10bb3ec 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -809,13 +809,14 @@ are always available.  They are listed here in alphabetical order.
 
    See also :ref:`typeiter`.
 
-   One useful application of the second form of :func:`iter` is to read lines of
-   a file until a certain line is reached.  The following example reads a file
-   until the :meth:`~io.TextIOBase.readline` method returns an empty string::
-
-      with open('mydata.txt') as fp:
-          for line in iter(fp.readline, ''):
-              process_line(line)
+   One useful application of the second form of :func:`iter` is to build a
+   block-reader. For example, reading fixed-width blocks from a binary
+   database file until the end of file is reached::
+
+      from functools import partial
+      with open('mydata.db', 'rb') as f:
+          for block in iter(partial(f.read, 64), ''):
+              process_block(block)
 
 
 .. function:: len(s)

diff --git a/Misc/NEWS.d/next/Documentation/2018-12-23-23-52-31.bpo-34764.DwOGeT.rst b/Misc/NEWS.d/next/Documentation/2018-12-23-23-52-31.bpo-34764.DwOGeT.rst
new file mode 100644 (file)
index 0000000..d2a7f1b
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-12-23-23-52-31.bpo-34764.DwOGeT.rst
@@ -0,0 +1 @@
+Improve example of iter() with 2nd sentinel argument.
\ No newline at end of file