From d96a399a258e2e5655c63d4b03aa8fb8878f692e Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Tue, 18 Dec 2018 22:36:52 +0100 Subject: [PATCH 1/9] improve example of iter() with 2nd arg --- Doc/library/functions.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 24a158fd5a85cb..140525000a3c5d 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -810,13 +810,15 @@ 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 simple example application of the second form of :func:`iter` is to roll + two dice and sum the two rolled values until a certain number is observed:: + + >>> from random import randint + >>> def roll_dice(): + ... return randint(1, 6) + randint(1, 6) + ... + >>> list(iter(roll_dice, 7)) # roll until 7 is seen + [8, 6] .. function:: len(s) From f6f086007e0dbcaa07ee1dd93d980ec2fb27a358 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 09:52:25 +0100 Subject: [PATCH 2/9] change example --- Doc/library/functions.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 140525000a3c5d..e3d8cafeb8f1fc 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -810,15 +810,13 @@ are always available. They are listed here in alphabetical order. See also :ref:`typeiter`. - One simple example application of the second form of :func:`iter` is to roll - two dice and sum the two rolled values until a certain number is observed:: - - >>> from random import randint - >>> def roll_dice(): - ... return randint(1, 6) + randint(1, 6) - ... - >>> list(iter(roll_dice, 7)) # roll until 7 is seen - [8, 6] + One application of the second form of :func:`iter` is build a block-reader. + For example, read fixed-width blocks from a database file: + + >>> from functools import partial + >>> with open('mydata.db') as f: + ... for block in iter(partial(f.read, 64)): + ... print(block) .. function:: len(s) From 289716f406b1cc68afd59216bc1830845e0e5c59 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 10:20:14 +0100 Subject: [PATCH 3/9] fix missing arg in example --- Doc/library/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index e3d8cafeb8f1fc..3f68fb265ab513 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -815,7 +815,7 @@ are always available. They are listed here in alphabetical order. >>> from functools import partial >>> with open('mydata.db') as f: - ... for block in iter(partial(f.read, 64)): + ... for block in iter(partial(f.read, 64), ''): ... print(block) From fc05a24a8e993ccc359c4cc3e977cf48a2d34b53 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 13:03:10 +0100 Subject: [PATCH 4/9] do not make example doctest --- Doc/library/functions.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 3f68fb265ab513..b13ae5942f5f4a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -811,12 +811,12 @@ are always available. They are listed here in alphabetical order. See also :ref:`typeiter`. One application of the second form of :func:`iter` is build a block-reader. - For example, read fixed-width blocks from a database file: + For example, reading fixed-width blocks from a database file: - >>> from functools import partial - >>> with open('mydata.db') as f: - ... for block in iter(partial(f.read, 64), ''): - ... print(block) + from functools import partial + with open('mydata.db') as f: + for block in iter(partial(f.read, 64), ''): + print(block) .. function:: len(s) From e15c552aa7135d36aa57217078c0452978ab0bf7 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 13:17:28 +0100 Subject: [PATCH 5/9] match style of original example --- Doc/library/functions.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index b13ae5942f5f4a..e9cee3d36de1c4 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -811,12 +811,13 @@ are always available. They are listed here in alphabetical order. See also :ref:`typeiter`. One application of the second form of :func:`iter` is build a block-reader. - For example, reading fixed-width blocks from a database file: + For example, reading fixed-width blocks from a text file until the end of + file is reached: from functools import partial - with open('mydata.db') as f: - for block in iter(partial(f.read, 64), ''): - print(block) + with open('mydata.txt') as fp: + for block in iter(partial(fp.read, 64), ''): + process_block(block) .. function:: len(s) From ab611ebae5e2b0056a3336769dae973e83fc6520 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 13:32:33 +0100 Subject: [PATCH 6/9] improve English --- Doc/library/functions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index e9cee3d36de1c4..f5a7bb5c68c6d8 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -810,9 +810,9 @@ are always available. They are listed here in alphabetical order. See also :ref:`typeiter`. - One application of the second form of :func:`iter` is build a block-reader. - For example, reading fixed-width blocks from a text file until the end of - file is reached: + One useful application of the second form of :func:`iter` is to build a + block-reader. For example, reading fixed-width blocks from a text file + until the end of file is reached: from functools import partial with open('mydata.txt') as fp: From 747ee530b4b4b1118a9fbed630599d723a7b12e3 Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Sun, 23 Dec 2018 14:20:11 +0100 Subject: [PATCH 7/9] fix indentation --- Doc/library/functions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index f5a7bb5c68c6d8..e510fc2ff6e5ab 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -814,10 +814,10 @@ are always available. They are listed here in alphabetical order. block-reader. For example, reading fixed-width blocks from a text file until the end of file is reached: - from functools import partial - with open('mydata.txt') as fp: - for block in iter(partial(fp.read, 64), ''): - process_block(block) + from functools import partial + with open('mydata.txt') as fp: + for block in iter(partial(fp.read, 64), ''): + process_block(block) .. function:: len(s) From b01f506d429ecedd9f75e88c148c002478fcc2be Mon Sep 17 00:00:00 2001 From: Chris Rands Date: Mon, 24 Dec 2018 00:50:23 +0100 Subject: [PATCH 8/9] make example binary; fix indentation --- Doc/library/functions.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index e510fc2ff6e5ab..b49d752b16a390 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -811,13 +811,13 @@ 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 build a - block-reader. For example, reading fixed-width blocks from a text file - until the end of file is reached: + 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.txt') as fp: - for block in iter(partial(fp.read, 64), ''): - process_block(block) + 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) From 2e13d8982a7866b16b7ee171880e4ad7e8783a96 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" Date: Sun, 23 Dec 2018 23:52:32 +0000 Subject: [PATCH 9/9] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Documentation/2018-12-23-23-52-31.bpo-34764.DwOGeT.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2018-12-23-23-52-31.bpo-34764.DwOGeT.rst 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 index 00000000000000..d2a7f1b52b750e --- /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