Issue #23406: Clarify documentation on multiplying a sequence
Patch from Matheus Vieira Portela.
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 23891be..135ae52 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -1280,6 +1280,8 @@
usually a lot slower than using Python lists.
+.. _faq-multidimensional-list:
+
How do I create a multidimensional list?
----------------------------------------
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index bb918df..86aae51 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -736,8 +736,8 @@
| ``s + t`` | the concatenation of *s* and | \(6) |
| | *t* | |
+------------------+--------------------------------+----------+
-| ``s * n, n * s`` | *n* shallow copies of *s* | \(2) |
-| | concatenated | |
+| ``s * n, n * s`` | equivalent to adding *s* to | \(2) |
+| | itself *n* times | |
+------------------+--------------------------------+----------+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) |
+------------------+--------------------------------+----------+
@@ -789,9 +789,9 @@
(2)
Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
- sequence of the same type as *s*). Note also that the copies are shallow;
- nested structures are not copied. This often haunts new Python programmers;
- consider:
+ sequence of the same type as *s*). Note that items in the sequence *s*
+ are not copied; they are referenced multiple times. This often haunts
+ new Python programmers; consider:
>>> lists = [[]] * 3
>>> lists
@@ -801,7 +801,7 @@
[[3], [3], [3]]
What has happened is that ``[[]]`` is a one-element list containing an empty
- list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
+ list, so all three elements of ``[[]] * 3`` are references to this single empty
list. Modifying any of the elements of ``lists`` modifies this single list.
You can create a list of different lists this way:
@@ -812,6 +812,9 @@
>>> lists
[[3], [5], [7]]
+ Further explanation is available in the FAQ entry
+ :ref:`faq-multidimensional-list`.
+
(3)
If *i* or *j* is negative, the index is relative to the end of the string:
``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still