From 3cc2e9cd0fd69102e5b386cc795b1fe2662fa1f9 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Fri, 31 Dec 2021 18:08:05 -0800 Subject: [PATCH 1/2] bpo-46095: Improve SeqIter documentation. --- Doc/library/stdtypes.rst | 10 ++++++++++ Doc/reference/compound_stmts.rst | 21 --------------------- 2 files changed, 10 insertions(+), 21 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 3c0ba94c73c6bd..f837ed0f722f4a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -959,6 +959,16 @@ This means that to compare equal, every element must compare equal and the two sequences must be of the same type and have the same length. (For full details see :ref:`comparisons` in the language reference.) +.. index:: + single: loop; over mutable sequence + single: mutable sequence; loop over + +Forward and reversed iterators over mutable 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). + Notes: (1) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index cf8ad1787b2915..03fc2cb962791f 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -196,27 +196,6 @@ the built-in function :func:`range` returns an iterator of integers suitable to emulate the effect of Pascal's ``for i := a to b do``; e.g., ``list(range(3))`` returns the list ``[0, 1, 2]``. -.. note:: - - .. index:: - single: loop; over mutable sequence - single: mutable sequence; loop over - - There is a subtlety when the sequence is being modified by the loop (this can - only occur for mutable sequences, e.g. lists). An internal counter is used - to keep track of which item is used next, and this is incremented on each - iteration. When this counter has reached the length of the sequence the loop - terminates. This means that if the suite deletes the current (or a previous) - item from the sequence, the next item will be skipped (since it gets the - index of the current item which has already been treated). Likewise, if the - suite inserts an item in the sequence before the current item, the current - item will be treated again the next time through the loop. This can lead to - nasty bugs that can be avoided by making a temporary copy using a slice of - the whole sequence, e.g., :: - - for x in a[:]: - if x < 0: a.remove(x) - .. _try: .. _except: From 496f286aad349a04a12248093b19a93013d85477 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Fri, 31 Dec 2021 18:11:54 -0800 Subject: [PATCH 2/2] Add markup for the exceptions --- Doc/library/stdtypes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index f837ed0f722f4a..10c158f1931809 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -966,8 +966,8 @@ details see :ref:`comparisons` in the language reference.) Forward and reversed iterators over mutable 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). +:exc:`IndexError` or a :exc:`StopIteration` is encountered (or when the index +drops below zero). Notes: