[Python-checkins] bpo-40636: Clarify the zip built-in docstring. (GH-20118)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/c3d025a86a60348f19551bd9921304c5db322531
commit: c3d025a86a60348f19551bd9921304c5db322531
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-05-15T14:43:27-07:00
summary:

bpo-40636: Clarify the zip built-in docstring. (GH-20118)


Clarify the zip built-in docstring.

This puts much simpler text up front along with an example.

As it was, the zip built-in docstring was technically correct.  But too
technical for the reader who shouldn't _need_ to know about `__next__` and
`StopIteration` as most people do not need to understand the internal
implementation details of the iterator protocol in their daily life.

This is a documentation only change, intended to be backported to 3.8; it is
only tangentially related to PEP-618 which might offer new behavior options
in the future.

Wording based a bit more on enumerate per Brandt's suggestion.

This gets rid of the legacy wording paragraph which seems too tied to
implementation details of the iterator protocol which isn't relevant here.

Co-authored-by: Brandt Bucher <brandtbucher at gmail.com>
(cherry picked from commit 6a5d3ff67644af42b1a781be2eacb2e82913441c)

Co-authored-by: Gregory P. Smith <greg at krypto.org>

files:
M Lib/test/test_doctest.py
M Python/bltinmodule.c

diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py
index 502b90e7ed21c..ad30a051b59c6 100644
--- a/Lib/test/test_doctest.py
+++ b/Lib/test/test_doctest.py
@@ -669,7 +669,7 @@ def non_Python_modules(): r"""
     True
     >>> real_tests = [t for t in tests if len(t.examples) > 0]
     >>> len(real_tests) # objects that actually have doctests
-    12
+    13
     >>> for t in real_tests:
     ...     print('{}  {}'.format(len(t.examples), t.name))
     ...
@@ -685,6 +685,7 @@ def non_Python_modules(): r"""
     2  builtins.int.bit_length
     5  builtins.memoryview.hex
     1  builtins.oct
+    1  builtins.zip
 
 Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',
 'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,
diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
index fe22bbdde4e91..e42d5f246c37a 100644
--- a/Python/bltinmodule.c
+++ b/Python/bltinmodule.c
@@ -2648,12 +2648,15 @@ static PyMethodDef zip_methods[] = {
 };
 
 PyDoc_STRVAR(zip_doc,
-"zip(*iterables) --> zip object\n\
+"zip(*iterables) --> A zip object yielding tuples until an input is exhausted.\n\
 \n\
-Return a zip object whose .__next__() method returns a tuple where\n\
-the i-th element comes from the i-th iterable argument.  The .__next__()\n\
-method continues until the shortest iterable in the argument sequence\n\
-is exhausted and then it raises StopIteration.");
+   >>> list(zip('abcdefg', range(3), range(4)))\n\
+   [('a', 0, 0), ('b', 1, 1), ('c', 2, 2)]\n\
+\n\
+The zip object yields n-length tuples, where n is the number of iterables\n\
+passed as positional arguments to zip().  The i-th element in every tuple\n\
+comes from the i-th iterable argument to zip().  This continues until the\n\
+shortest argument is exhausted.");
 
 PyTypeObject PyZip_Type = {
     PyVarObject_HEAD_INIT(&PyType_Type, 0)