cpython/Lib
Gregory P. Smith 6a5d3ff676
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@gmail.com>
2020-05-15 14:26:00 -07:00
..
asyncio bpo-40607: Reraise exception during task cancelation in asyncio.wait_for() (GH-20054) 2020-05-15 13:12:05 -07:00
collections Expand the implementation comments (GH-19699) 2020-04-24 02:33:07 -07:00
concurrent bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
ctypes bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
curses
dbm
distutils bpo-40055: test_distutils leaves warnings filters unchanged (GH-20095) 2020-05-15 18:06:23 +02:00
email bpo-40597: email: Use CTE if lines are longer than max_line_length consistently (gh-20038) 2020-05-13 20:53:26 -04:00
encodings bpo-30566: Fix IndexError when using punycode codec (GH-18632) 2020-02-25 06:19:03 +03:00
ensurepip bpo-38662: ensurepip invokes pip via runpy (GH-18901) 2020-03-10 22:16:28 +01:00
html
http bpo-39481: PEP 585 for a variety of modules (GH-19423) 2020-04-10 07:46:36 -07:00
idlelib bpo-40460: Fix typo in idlelib/zzdummy.py (GH-20093) 2020-05-15 00:51:51 +02:00
importlib bpo-39791: Add files() to importlib.resources (GH-19722) 2020-05-08 19:20:26 -04:00
json bpo-39828: Fix json.tool to catch BrokenPipeError (GH-18779) 2020-03-10 08:41:44 +01:00
lib2to3 bpo-40360: Deprecate lib2to3 module in light of PEP 617 (GH-19663) 2020-04-24 11:19:46 -07:00
logging bpo-40300: Allow empty logging.Formatter.default_msec_format. (GH-19551) 2020-04-17 17:02:47 +01:00
msilib Remove binding of captured exceptions when not used to reduce the chances of creating cycles (GH-17246) 2019-11-19 21:34:03 +00:00
multiprocessing bpo-40443: Remove unused imports in stdlib (GH-19815) 2020-05-01 02:38:00 +02:00
pydoc_data Python 3.9.0a6 2020-04-27 22:44:04 +02:00
site-packages
sqlite3 bpo-39652: Truncate the column name after '[' only if PARSE_COLNAMES is set. (GH-18942) 2020-03-21 15:53:28 +02:00
test bpo-40636: Clarify the zip built-in docstring. (GH-20118) 2020-05-15 14:26:00 -07:00
tkinter bpo-39152: add missing ttk.Scale.configure return value (GH-17815) 2020-01-05 11:23:58 -05:00
turtledemo bpo-40431: Fix syntax typo in turtledemo (GH-19777) 2020-04-29 02:00:07 +02:00
unittest bpo-40462: fix variable and function names (GH-19832) 2020-05-01 05:49:35 -07:00
urllib bpo-39481: PEP 585 for a variety of modules (GH-19423) 2020-04-10 07:46:36 -07:00
venv bpo-38972: Link to instructions to change PowerShell execution policy (GH-19131) 2020-04-02 12:00:21 -07:00
wsgiref
xml bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
xmlrpc bpo-38786: Add parsing of https links to pydoc (GH-17143) 2019-11-13 18:13:52 +02:00
__future__.py bpo-39562: Prevent collision of future and compiler flags (GH-19230) 2020-04-22 18:09:03 +02:00
__phello__.foo.py
_aix_support.py bpo-39936: _aix_support uses _bootsubprocess (GH-18970) 2020-03-12 23:15:34 +01:00
_bootlocale.py
_bootsubprocess.py bpo-40094: Add os.waitstatus_to_exitcode() (GH-19201) 2020-04-01 18:49:29 +02:00
_collections_abc.py bpo-39481: Implementation for PEP 585 (#18239) 2020-04-07 09:50:06 -07:00
_compat_pickle.py
_compression.py
_markupbase.py
_osx_support.py bpo-38360: macOS: support alternate form of -isysroot flag (GH-16480) 2020-04-22 03:44:10 -04:00
_py_abc.py
_pydecimal.py bpo-39794: Add --without-decimal-contextvar (#18702) 2020-02-29 19:43:42 +01:00
_pyio.py bpo-39674: Revert "bpo-37330: open() no longer accept 'U' in file mode (GH-16959)" (GH-18767) 2020-03-04 18:50:22 +01:00
_sitebuiltins.py
_strptime.py Fix outdated comment in _strptime.py (GH-17929) 2020-01-12 12:53:00 -08:00
_threading_local.py
_weakrefset.py bpo-39481: Make weakref and WeakSet generic (GH-19497) 2020-04-13 21:54:40 -07:00
abc.py
aifc.py
antigravity.py bpo-9216: Nobody expects the geohashing FIPS inquisition (GH-19520) 2020-04-14 12:49:11 -07:00
argparse.py bpo-39546: argparse: Honor allow_abbrev=False for specified prefix_chars (GH-18337) 2020-02-18 01:48:57 -08:00
ast.py bpo-40355: Improve error messages in ast.literal_eval with malformed Dict nodes (GH-19868) 2020-05-05 20:40:56 +01:00
asynchat.py Remove binding of captured exceptions when not used to reduce the chances of creating cycles (GH-17246) 2019-11-19 21:34:03 +00:00
asyncore.py
base64.py bpo-39351: Remove base64.encodestring() (GH-18022) 2020-01-16 10:24:16 +01:00
bdb.py bpo-39649: Remove obsolete check for `__args__` in bdb.Bdb.format_stack_entry (GH-18531) 2020-02-23 22:14:53 -05:00
binhex.py bpo-39353: binascii.crc_hqx() is no longer deprecated (GH-18276) 2020-01-30 09:56:40 +01:00
bisect.py bpo-38626: Add comment explaining why __lt__ is used. (GH-16978) 2019-10-28 21:38:50 -07:00
bz2.py bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
cProfile.py
calendar.py
cgi.py bpo-20504 : in cgi.py, fix bug when a multipart/form-data request has… (#10638) 2019-09-11 12:05:53 +01:00
cgitb.py
chunk.py
cmd.py
code.py Fix documentation in code.py (GH-17988) 2020-01-15 01:17:25 +05:30
codecs.py bpo-38971: Open file in codecs.open() closes if exception raised. (GH-17666) 2020-03-02 08:39:50 +02:00
codeop.py bpo-38872: Document exec symbol for codeop.compile_command (GH-20047) 2020-05-14 21:59:46 -03:00
colorsys.py
compileall.py bpo-40495: compileall option to hardlink duplicate pyc files (GH-19901) 2020-05-14 16:17:22 +02:00
configparser.py
contextlib.py bpo-39481: Implementation for PEP 585 (#18239) 2020-04-07 09:50:06 -07:00
contextvars.py
copy.py bpo-38293: Allow shallow and deep copying of property objects (GH-16438) 2020-01-12 09:41:49 -08:00
copyreg.py
crypt.py closes bpo-38402: Check error of primitive crypt/crypt_r. (GH-16599) 2019-10-07 21:22:17 -07:00
csv.py
dataclasses.py bpo-39481: PEP 585 for dataclasses, mailbox, contextvars (GH-19425) 2020-04-14 16:14:15 -07:00
datetime.py bpo-38155: Add __all__ to datetime module (GH-16203) 2019-09-19 14:34:41 +01:00
decimal.py
difflib.py bpo-40394 - difflib.SequenceMatched.find_longest_match default args (GH-19742) 2020-04-29 22:42:45 -05:00
dis.py bpo-38115: Deal with invalid bytecode offsets in lnotab (GH-16079) 2019-09-28 07:49:15 -07:00
doctest.py bpo-1812: Fix newline conversion when doctest.testfile loads from a package whose loader has a get_data method (GH-17385) 2020-03-26 10:53:16 -05:00
enum.py bpo-40025: Require _generate_next_value_ to be defined before members (GH-19098) 2020-04-28 10:20:55 -07:00
filecmp.py bpo-39481: PEP 585 for difflib, filecmp, fileinput (#19422) 2020-04-09 21:47:31 -07:00
fileinput.py bpo-39481: PEP 585 for difflib, filecmp, fileinput (#19422) 2020-04-09 21:47:31 -07:00
fnmatch.py bpo-40480: restore ability to join fnmatch.translate() results (GH-20049) 2020-05-11 21:19:20 -05:00
formatter.py
fractions.py bpo-39350: Fix fractions for int subclasses (GH-18375) 2020-02-07 23:42:51 +01:00
ftplib.py bpo-39380: Change ftplib encoding from latin-1 to utf-8 (GH-18048) 2020-04-14 01:07:56 +02:00
functools.py bpo-40571: Make lru_cache(maxsize=None) more discoverable (GH-20019) 2020-05-11 17:00:53 -07:00
genericpath.py bpo-38807: Add os.PathLike to exception message raised by _check_arg_types (#17160) 2019-11-18 21:54:00 -08:00
getopt.py
getpass.py Remove binding of captured exceptions when not used to reduce the chances of creating cycles (GH-17246) 2019-11-19 21:34:03 +00:00
gettext.py bpo-40275: Import locale module lazily in gettext (GH-19905) 2020-05-14 03:22:30 +02:00
glob.py bpo-38149: Call sys.audit() only once per call for glob.glob(). (GH-18360) 2020-02-06 10:26:37 +02:00
gzip.py bpo-39389: gzip: fix compression level metadata (GH-18077) 2020-01-21 13:25:24 +02:00
hashlib.py bpo-38153: Normalize hashlib algorithm names (GH-16083) 2019-09-13 14:31:19 +01:00
heapq.py
hmac.py bpo-33604: Raise TypeError on missing hmac arg. (GH-16805) 2019-10-17 20:30:42 -07:00
imaplib.py bpo-40375: Implement imaplib.IMAP4.unselect (GH-19712) 2020-04-27 23:52:55 +09:00
imghdr.py
imp.py bpo-39674: Revert "bpo-37330: open() no longer accept 'U' in file mode (GH-16959)" (GH-18767) 2020-03-04 18:50:22 +01:00
inspect.py bpo-35113: Fix inspect.getsource to return correct source for inner classes (#10307) 2020-04-18 21:49:32 +05:30
io.py
ipaddress.py bpo-39481: remove generic classes from ipaddress/mmap (GH-20045) 2020-05-11 19:32:40 -07:00
keyword.py
linecache.py issue-25872: Fix KeyError using linecache from multiple threads (GH-18007) 2020-05-13 18:41:57 -04:00
locale.py bpo-38536: locale: Remove trailing space in formatted currency (GH-16864) 2020-01-20 12:45:50 +09:00
lzma.py
mailbox.py bpo-39481: PEP 585 for dataclasses, mailbox, contextvars (GH-19425) 2020-04-14 16:14:15 -07:00
mailcap.py bpo-40094: mailcap.test() uses waitstatus_to_exitcode() (GH-19287) 2020-04-02 02:00:06 +02:00
mimetypes.py bpo-39299: Add more tests for mimetypes and its cli. (GH-17949) 2020-01-13 20:09:36 +05:30
modulefinder.py bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
netrc.py
nntplib.py bpo-39366: Remove xpath() and xgtitle() methods of NNTP (GH-18035) 2020-01-23 00:59:43 +03:00
ntpath.py bpo-38453: Ensure ntpath.realpath correctly resolves relative paths (GH-16967) 2019-11-15 09:49:21 -08:00
nturl2path.py
numbers.py
opcode.py bpo-39320: Handle unpacking of **values in compiler (GH-18141) 2020-01-27 09:57:45 +00:00
operator.py
optparse.py
os.py bpo-39481: Implementation for PEP 585 (#18239) 2020-04-07 09:50:06 -07:00
pathlib.py bpo-40148: Add PurePath.with_stem() (GH-19295) 2020-04-19 17:29:49 +02:00
pdb.py bpo-38723: Pdb._runscript should use io.open_code() instead of open() (GH-17127) 2019-11-12 14:42:47 -08:00
pickle.py bpo-39435: Make the first argument of pickle.loads() positional-only. (GH-19846) 2020-05-02 09:38:01 +03:00
pickletools.py
pipes.py
pkgutil.py bpo-12915: Improve Unicode support for package names and attributes. (GH-18517) 2020-02-28 14:26:27 +00:00
platform.py bpo-40570: Improve compatibility of uname_result with late-bound .platform (#20015) 2020-05-09 10:12:41 -04:00
plistlib.py bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
poplib.py bpo-39259: poplib now rejects timeout = 0 (GH-17912) 2020-01-10 15:34:05 +01:00
posixpath.py
pprint.py
profile.py
pstats.py bpo-37958: Adding get_profile_dict to pstats (GH-15495) 2020-01-15 14:51:54 -08:00
pty.py bpo-39184: Add audit events to command execution functions in os and pty modules (GH-17824) 2020-02-05 11:15:00 +11:00
py_compile.py
pyclbr.py
pydoc.py bpo-40257: Improve help for the typing module (GH-19546) 2020-04-18 17:13:21 +03:00
queue.py bpo-39481: PEP 585 for a variety of modules (GH-19423) 2020-04-10 07:46:36 -07:00
quopri.py
random.py bpo-40541: Add optional *counts* parameter to random.sample() (GH-19970) 2020-05-08 07:53:15 -07:00
re.py bpo-40016: re docstring: Clarify relationship of inline and argument flags (#19078) 2020-03-25 14:44:47 -04:00
reprlib.py
rlcompleter.py
runpy.py bpo-40108: Improve the error message in runpy when importing a module that includes the extension (GH-19239) 2020-03-31 12:23:55 +01:00
sched.py
secrets.py bpo-40286: Add randbytes() method to random.Random (GH-19527) 2020-04-17 19:05:35 +02:00
selectors.py bpo-29255: Wait in KqueueSelector.select when no fds are registered (GH-19508) 2020-04-15 11:57:06 -07:00
shelve.py
shlex.py bpo-33262: Deprecate passing None for `s` to shlex.split() (GH-6514) 2020-04-01 09:58:55 -04:00
shutil.py bpo-39184: Add audit events to functions in `fcntl`, `msvcrt`, `os`, `resource`, `shutil`, `signal`, `syslog` (GH-18407) 2020-02-13 07:47:42 +00:00
signal.py
site.py bpo-1294959: Add sys.platlibdir attribute (GH-18381) 2020-03-10 09:53:09 +01:00
smtpd.py bpo-35800: Deprecate smtpd.MailmanProxy (GH-11675) 2019-10-12 10:24:26 -07:00
smtplib.py bpo-39329: Add timeout parameter for smtplib.LMTP constructor (GH-17998) 2020-01-14 22:42:09 +01:00
sndhdr.py
socket.py Fix host in address of socket.create_server example. (GH-17706) 2020-01-11 10:46:30 +05:30
socketserver.py Change 'exception happened' to 'exception occurred' in two places (#19767) 2020-04-30 21:30:10 -07:00
sre_compile.py
sre_constants.py
sre_parse.py
ssl.py bpo-40443: Remove unused imports in stdlib (GH-19815) 2020-05-01 02:38:00 +02:00
stat.py bpo-38109: Add missing constants to Lib/stat.py (GH-16665) 2019-10-10 09:34:46 +02:00
statistics.py Minor code cleanups for statistics (GH-19873) 2020-05-02 19:30:24 -07:00
string.py bpo-38208: Simplify string.Template by using __init_subclass__(). (GH-16256) 2019-10-21 09:36:21 +03:00
stringprep.py
struct.py
subprocess.py bpo-40334: Rename PyConfig.use_peg to _use_peg_parser (GH-19670) 2020-04-23 03:03:24 +02:00
sunau.py
symbol.py
symtable.py bpo-40208: Remove deprecated has_exec method of SymbolTable (GH-19396) 2020-04-14 08:51:32 +09:00
sysconfig.py bpo-24916: Remove an outdated comment. (GH-19101) 2020-03-21 15:45:30 +02:00
tabnanny.py
tarfile.py bpo-18819: tarfile: only set device fields for device files (GH-18080) 2020-02-12 11:56:02 -08:00
telnetlib.py
tempfile.py bpo-40287: Fix SpooledTemporaryFile.seek() return value (GH-19540) 2020-04-17 15:56:35 +09:00
textwrap.py
this.py
threading.py bpo-40234: Revert "bpo-37266: Daemon threads are now denied in subinterpreters (GH-14049)" (GH-19456) 2020-04-12 23:45:09 +02:00
timeit.py bpo-40419: timeit CLI docs now mention 1,2,5,10,... trials instead of powers of 10 (GH-19752) 2020-05-02 19:12:05 +03:00
token.py
tokenize.py
trace.py bpo-21016: pydoc and trace use sysconfig (GH-18476) 2020-02-12 13:02:29 +01:00
traceback.py bpo-40612: Fix SyntaxError edge cases in traceback formatting (GH-20072) 2020-05-14 19:22:48 -07:00
tracemalloc.py bpo-37961, tracemalloc: add Traceback.total_nframe (GH-15545) 2019-10-15 14:00:16 +02:00
tty.py
turtle.py
types.py bpo-39481: Implementation for PEP 585 (#18239) 2020-04-07 09:50:06 -07:00
typing.py bpo-40257: Tweak docstrings for special generic aliases. (GH-20022) 2020-05-10 15:14:27 +03:00
uu.py bpo-38945: UU Encoding: Don't let newline in filename corrupt the output format (#17418) 2019-12-02 14:25:21 -08:00
uuid.py bpo-40501: Replace ctypes code in uuid with native module (GH-19948) 2020-05-12 23:32:32 +01:00
warnings.py bpo-39056: Fix handling invalid warning category in the -W option. (GH-17618) 2020-01-05 14:15:27 +02:00
wave.py Fix a typo in wave module docstring (GH-17009) 2019-11-04 22:32:10 -06:00
weakref.py bpo-36144: Add union operators to WeakValueDictionary584 (#19127) 2020-03-24 18:51:29 -07:00
webbrowser.py bpo-40561: Add docstrings for webbrowser open functions (GH-19999) 2020-05-11 14:50:11 -04:00
xdrlib.py
zipapp.py
zipfile.py bpo-40443: Remove unused imports in the stdlib (GH-19803) 2020-04-30 11:26:33 +02:00
zipimport.py bpo-39033: Fix NameError in zipimport during hash validation (GH-17588) 2019-12-16 09:34:12 +10:00