[Python-checkins] bpo-46095: Improve SeqIter documentation. (GH-30316) (GH-30330)

[rhettinger]

https://github.com/python/cpython/commit/e9783d6434f28dfb0b531c6760f7642fc7ede278
commit: e9783d6434f28dfb0b531c6760f7642fc7ede278
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2022-01-01T11:12:43-08:00
summary:

bpo-46095: Improve SeqIter documentation. (GH-30316) (GH-30330)

files:
M Doc/library/stdtypes.rst
M Doc/reference/compound_stmts.rst

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 101bbca7be8b2..8fa252b04d706 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -921,6 +921,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
+:exc:`IndexError` or a :exc:`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 63d885deae93f..7f37bb4fdf9c9 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: