This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Improve SeqIter documentation
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: docs@python, eric.araujo, miss-islington, rhettinger, turepalsson
Priority: normal Keywords: patch

Created on 2021-12-16 09:48 by turepalsson, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 30316 merged rhettinger, 2022-01-01 02:09
PR 30330 merged miss-islington, 2022-01-01 18:37
Messages (5)
msg408680 - (view) Author: Ture Pålsson (turepalsson) Date: 2021-12-16 09:48
The language reference about the 'for' statement (https://docs.python.org/3/reference/compound_stmts.html#the-for-statement) has a "Note" box that states that the for statement uses an "internal counter" which is "incremented", and goes into detail about what happens when modifications happen before or after the current loop position. Surely this depends on the underlying iterator? For example, with a balanced tree an insert or a delete could completely re-jigger the tree with hard-to-predict results on an iterator.
msg408808 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2021-12-17 18:54
The note does say it’s about mutable sequences like lists.
msg408832 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-12-18 02:13
I think this note can be removed.  The tutorial now has coverage of mutating while iterating.  That is the correct place for discussion of looping techniques.

The part about the "internal counter" needs to be rewritten and moved to stdtypes.rst section on Sequence types.  Here is a first draft:

"Forward and reversed iterators over sequences access values using an index.  That index will continue to march forward (or backward) even if the underlying sequence is mutated.  The iterator terminates only when an IndexError or StopIteration is encountered (or when the index drops below zero)."

Sequence iterators are roughly equivalent to:

    def seqiter(seq):
        i = 0
        while True:
            try:
                yield seq[i]
            except (IndexError, StopIteration):
                break
            i += 1
msg409469 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-01-01 18:37
New changeset a09bc3a404befca197b5d9959a9c62110ee61d77 by Raymond Hettinger in branch 'main':
bpo-46095: Improve SeqIter documentation. (GH-30316)
https://github.com/python/cpython/commit/a09bc3a404befca197b5d9959a9c62110ee61d77
msg409473 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2022-01-01 19:12
New changeset e9783d6434f28dfb0b531c6760f7642fc7ede278 by Miss Islington (bot) in branch '3.10':
bpo-46095: Improve SeqIter documentation. (GH-30316) (GH-30330)
https://github.com/python/cpython/commit/e9783d6434f28dfb0b531c6760f7642fc7ede278
History
Date User Action Args
2022-04-11 14:59:53adminsetgithub: 90253
2022-01-01 19:12:51rhettingersetmessages: + msg409473
2022-01-01 18:38:20rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2022-01-01 18:37:49rhettingersetmessages: + msg409469
2022-01-01 18:37:34miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request28545
2022-01-01 02:09:23rhettingersetkeywords: + patch
stage: patch review
pull_requests: + pull_request28533
2021-12-18 02:14:21rhettingersettitle: Warning about iterate/modify has unwarranted detail -> Improve SeqIter documentation
type: enhancement ->
versions: + Python 3.11
2021-12-18 02:13:24rhettingersetassignee: docs@python -> rhettinger

messages: + msg408832
nosy: + rhettinger
2021-12-17 18:54:18eric.araujosetnosy: + eric.araujo
messages: + msg408808
2021-12-16 09:48:01turepalssoncreate