FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

[3.13] GH-138465: Improve documentation for common sequence methods (… · python/cpython@e7bb98a · GitHub

  1. python
  2. cpython

Repository navigation

Commit e7bb98a

Browse files
AA-Turner
and
serhiy-storchaka
authored
[3.13] GH-138465: Improve documentation for common sequence methods (GH-138474) (#138567)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
1 parent bb64bc3 commit e7bb98a

18 files changed

Lines changed: 180 additions & 118 deletions

‎Doc/conf.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,6 @@
237237
('py:attr', '__annotations__'),
238238
('py:meth', '__missing__'),
239239
('py:attr', '__wrapped__'),
240-
('py:meth', 'index'), # list.index, tuple.index, etc.
241240
]
242241

243242
# gh-106948: Copy standard C types declared in the "c:type" domain and C

‎Doc/faq/design.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -589,9 +589,9 @@ exhaustive test suites that exercise every line of code in a module.
589589
An appropriate testing discipline can help build large complex applications in
590590
Python as well as having interface specifications would. In fact, it can be
591591
better because an interface specification cannot test certain properties of a
592-
program. For example, the :meth:`!list.append` method is expected to add new elements
592+
program. For example, the :meth:`list.append` method is expected to add new elements
593593
to the end of some internal list; an interface specification cannot test that
594-
your :meth:`!list.append` implementation will actually do this correctly, but it's
594+
your :meth:`list.append` implementation will actually do this correctly, but it's
595595
trivial to check this property in a test suite.
596596

597597
Writing test suites is very helpful, and you might want to design your code to

‎Doc/faq/programming.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -454,7 +454,7 @@ There are two factors that produce this result:
454454
(the list), and both ``x`` and ``y`` refer to it.
455455
2) Lists are :term:`mutable`, which means that you can change their content.
456456

457-
After the call to :meth:`!append`, the content of the mutable object has
457+
After the call to :meth:`~sequence.append`, the content of the mutable object has
458458
changed from ``[]`` to ``[10]``. Since both the variables refer to the same
459459
object, using either name accesses the modified value ``[10]``.
460460

@@ -1397,9 +1397,9 @@ To see why this happens, you need to know that (a) if an object implements an
13971397
:meth:`~object.__iadd__` magic method, it gets called when the ``+=`` augmented
13981398
assignment
13991399
is executed, and its return value is what gets used in the assignment statement;
1400-
and (b) for lists, :meth:`!__iadd__` is equivalent to calling :meth:`!extend` on the list
1401-
and returning the list. That's why we say that for lists, ``+=`` is a
1402-
"shorthand" for :meth:`!list.extend`::
1400+
and (b) for lists, :meth:`!__iadd__` is equivalent to calling
1401+
:meth:`~sequence.extend` on the list and returning the list.
1402+
That's why we say that for lists, ``+=`` is a "shorthand" for :meth:`list.extend`::
14031403

14041404
>>> a_list = []
14051405
>>> a_list += [1]

‎Doc/glossary.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1205,8 +1205,9 @@ Glossary
12051205
The :class:`collections.abc.Sequence` abstract base class
12061206
defines a much richer interface that goes beyond just
12071207
:meth:`~object.__getitem__` and :meth:`~object.__len__`, adding
1208-
:meth:`!count`, :meth:`!index`, :meth:`~object.__contains__`, and
1209-
:meth:`~object.__reversed__`. Types that implement this expanded
1208+
:meth:`~sequence.count`, :meth:`~sequence.index`,
1209+
:meth:`~object.__contains__`, and :meth:`~object.__reversed__`.
1210+
Types that implement this expanded
12101211
interface can be registered explicitly using
12111212
:func:`~abc.ABCMeta.register`. For more documentation on sequence
12121213
methods generally, see

‎Doc/library/bisect.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ The following functions are provided:
8383
Insert *x* in *a* in sorted order.
8484

8585
This function first runs :py:func:`~bisect.bisect_left` to locate an insertion point.
86-
Next, it runs the :meth:`!insert` method on *a* to insert *x* at the
86+
Next, it runs the :meth:`~sequence.insert` method on *a* to insert *x* at the
8787
appropriate position to maintain sort order.
8888

8989
To support inserting records in a table, the *key* function (if any) is
@@ -103,7 +103,7 @@ The following functions are provided:
103103
entries of *x*.
104104

105105
This function first runs :py:func:`~bisect.bisect_right` to locate an insertion point.
106-
Next, it runs the :meth:`!insert` method on *a* to insert *x* at the
106+
Next, it runs the :meth:`~sequence.insert` method on *a* to insert *x* at the
107107
appropriate position to maintain sort order.
108108

109109
To support inserting records in a table, the *key* function (if any) is

‎Doc/library/collections.abc.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -268,8 +268,9 @@ Collections Abstract Base Classes -- Detailed Descriptions
268268
ABCs for read-only and mutable :term:`sequences <sequence>`.
269269

270270
Implementation note: Some of the mixin methods, such as
271-
:meth:`~container.__iter__`, :meth:`~object.__reversed__` and :meth:`index`, make
272-
repeated calls to the underlying :meth:`~object.__getitem__` method.
271+
:meth:`~container.__iter__`, :meth:`~object.__reversed__`,
272+
and :meth:`~sequence.index` make repeated calls to the underlying
273+
:meth:`~object.__getitem__` method.
273274
Consequently, if :meth:`~object.__getitem__` is implemented with constant
274275
access speed, the mixin methods will have linear performance;
275276
however, if the underlying method is linear (as it would be with a
@@ -285,8 +286,8 @@ Collections Abstract Base Classes -- Detailed Descriptions
285286
Supporting the *start* and *stop* arguments is optional, but recommended.
286287

287288
.. versionchanged:: 3.5
288-
The :meth:`!index` method added support for *stop* and *start*
289-
arguments.
289+
The :meth:`~sequence.index` method gained support for
290+
the *stop* and *start* arguments.
290291

291292
.. deprecated-removed:: 3.12 3.14
292293
The :class:`ByteString` ABC has been deprecated.

‎Doc/library/collections.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -783,10 +783,10 @@ sequence of key-value pairs into a dictionary of lists:
783783

784784
When each key is encountered for the first time, it is not already in the
785785
mapping; so an entry is automatically created using the :attr:`~defaultdict.default_factory`
786-
function which returns an empty :class:`list`. The :meth:`!list.append`
786+
function which returns an empty :class:`list`. The :meth:`list.append`
787787
operation then attaches the value to the new list. When keys are encountered
788788
again, the look-up proceeds normally (returning the list for that key) and the
789-
:meth:`!list.append` operation adds another value to the list. This technique is
789+
:meth:`list.append` operation adds another value to the list. This technique is
790790
simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
791791

792792
>>> d = {}

‎Doc/library/pickle.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -716,8 +716,8 @@ or both.
716716
These items will be appended to the object either using
717717
``obj.append(item)`` or, in batch, using ``obj.extend(list_of_items)``.
718718
This is primarily used for list subclasses, but may be used by other
719-
classes as long as they have
720-
:ref:`append and extend methods <typesseq-common>` with
719+
classes as long as they have :meth:`~sequence.append`
720+
and :meth:`~sequence.extend` methods with
721721
the appropriate signature. (Whether :meth:`!append` or :meth:`!extend` is
722722
used depends on which pickle protocol version is used as well as the number
723723
of items to append, so both must be supported.)

‎Doc/library/stdtypes.rst‎

Lines changed: 135 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -958,8 +958,6 @@ operations have the same priority as the corresponding numeric operations. [3]_
958958
pair: slice; operation
959959
pair: operator; in
960960
pair: operator; not in
961-
single: count() (sequence method)
962-
single: index() (sequence method)
963961

964962
+--------------------------+--------------------------------+----------+
965963
| Operation | Result | Notes |
@@ -976,7 +974,7 @@ operations have the same priority as the corresponding numeric operations. [3]_
976974
| ``s * n`` or | equivalent to adding *s* to | (2)(7) |
977975
| ``n * s`` | itself *n* times | |
978976
+--------------------------+--------------------------------+----------+
979-
| ``s[i]`` | *i*\ th item of *s*, origin 0 | (3)(9) |
977+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | (3)(8) |
980978
+--------------------------+--------------------------------+----------+
981979
| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
982980
+--------------------------+--------------------------------+----------+
@@ -989,13 +987,6 @@ operations have the same priority as the corresponding numeric operations. [3]_
989987
+--------------------------+--------------------------------+----------+
990988
| ``max(s)`` | largest item of *s* | |
991989
+--------------------------+--------------------------------+----------+
992-
| ``s.index(x[, i[, j]])`` | index of the first occurrence | \(8) |
993-
| | of *x* in *s* (at or after | |
994-
| | index *i* and before index *j*)| |
995-
+--------------------------+--------------------------------+----------+
996-
| ``s.count(x)`` | total number of occurrences of | |
997-
| | *x* in *s* | |
998-
+--------------------------+--------------------------------+----------+
999990

1000991
Sequences of the same type also support comparisons. In particular, tuples
1001992
and lists are compared lexicographically by comparing corresponding elements.
@@ -1101,16 +1092,42 @@ Notes:
11011092
concatenation or repetition.
11021093

11031094
(8)
1104-
``index`` raises :exc:`ValueError` when *x* is not found in *s*.
1105-
Not all implementations support passing the additional arguments *i* and *j*.
1106-
These arguments allow efficient searching of subsections of the sequence. Passing
1107-
the extra arguments is roughly equivalent to using ``s[i:j].index(x)``, only
1108-
without copying any data and with the returned index being relative to
1109-
the start of the sequence rather than the start of the slice.
1110-
1111-
(9)
11121095
An :exc:`IndexError` is raised if *i* is outside the sequence range.
11131096

1097+
.. rubric:: Sequence Methods
1098+
1099+
Sequence types also support the following methods:
1100+
1101+
.. method:: list.count(value, /)
1102+
range.count(value, /)
1103+
tuple.count(value, /)
1104+
:no-contents-entry:
1105+
:no-index-entry:
1106+
:no-typesetting:
1107+
.. method:: sequence.count(value, /)
1108+
1109+
Return the total number of occurrences of *value* in *sequence*.
1110+
1111+
.. method:: list.index(value[, start[, stop])
1112+
range.index(value[, start[, stop])
1113+
tuple.index(value[, start[, stop])
1114+
:no-contents-entry:
1115+
:no-index-entry:
1116+
:no-typesetting:
1117+
.. method:: sequence.index(value[, start[, stop])
1118+
1119+
Return the index of the first occurrence of *value* in *sequence*.
1120+
1121+
Raises :exc:`ValueError` if *value* is not found in *sequence*.
1122+
1123+
The *start* or *stop* arguments allow for efficient searching
1124+
of subsections of the sequence, beginning at *start* and ending at *stop*.
1125+
This is roughly equivalent to ``start + sequence[start:stop].index(value)``,
1126+
only without copying any data.
1127+
1128+
.. caution::
1129+
Not all sequence types support passing the *start* and *stop* arguments.
1130+
11141131

11151132
.. _typesseq-immutable:
11161133

@@ -1160,14 +1177,6 @@ accepts integers that meet the value restriction ``0 <= x <= 255``).
11601177
pair: subscript; assignment
11611178
pair: slice; assignment
11621179
pair: statement; del
1163-
single: append() (sequence method)
1164-
single: clear() (sequence method)
1165-
single: copy() (sequence method)
1166-
single: extend() (sequence method)
1167-
single: insert() (sequence method)
1168-
single: pop() (sequence method)
1169-
single: remove() (sequence method)
1170-
single: reverse() (sequence method)
11711180

11721181
+------------------------------+--------------------------------+---------------------+
11731182
| Operation | Result | Notes |
@@ -1191,72 +1200,120 @@ accepts integers that meet the value restriction ``0 <= x <= 255``).
11911200
| ``del s[i:j:k]`` | removes the elements of | |
11921201
| | ``s[i:j:k]`` from the list | |
11931202
+------------------------------+--------------------------------+---------------------+
1194-
| ``s.append(x)`` | appends *x* to the end of the | |
1195-
| | sequence (same as | |
1196-
| | ``s[len(s):len(s)] = [x]``) | |
1197-
+------------------------------+--------------------------------+---------------------+
1198-
| ``s.clear()`` | removes all items from *s* | \(5) |
1199-
| | (same as ``del s[:]``) | |
1200-
+------------------------------+--------------------------------+---------------------+
1201-
| ``s.copy()`` | creates a shallow copy of *s* | \(5) |
1202-
| | (same as ``s[:]``) | |
1203-
+------------------------------+--------------------------------+---------------------+
1204-
| ``s.extend(t)`` or | extends *s* with the | |
1205-
| ``s += t`` | contents of *t* (for the | |
1203+
| ``s += t`` | extends *s* with the | |
1204+
| | contents of *t* (for the | |
12061205
| | most part the same as | |
12071206
| | ``s[len(s):len(s)] = t``) | |
12081207
+------------------------------+--------------------------------+---------------------+
1209-
| ``s *= n`` | updates *s* with its contents | \(6) |
1208+
| ``s *= n`` | updates *s* with its contents | \(2) |
12101209
| | repeated *n* times | |
12111210
+------------------------------+--------------------------------+---------------------+
1212-
| ``s.insert(i, x)`` | inserts *x* into *s* at the | |
1213-
| | index given by *i* | |
1214-
| | (same as ``s[i:i] = [x]``) | |
1215-
+------------------------------+--------------------------------+---------------------+
1216-
| ``s.pop()`` or ``s.pop(i)`` | retrieves the item at *i* and | \(2) |
1217-
| | also removes it from *s* | |
1218-
+------------------------------+--------------------------------+---------------------+
1219-
| ``s.remove(x)`` | removes the first item from | \(3) |
1220-
| | *s* where ``s[i]`` is equal to | |
1221-
| | *x* | |
1222-
+------------------------------+--------------------------------+---------------------+
1223-
| ``s.reverse()`` | reverses the items of *s* in | \(4) |
1224-
| | place | |
1225-
+------------------------------+--------------------------------+---------------------+
1226-
12271211

12281212
Notes:
12291213

12301214
(1)
12311215
If *k* is not equal to ``1``, *t* must have the same length as the slice it is replacing.
12321216

12331217
(2)
1234-
The optional argument *i* defaults to ``-1``, so that by default the last
1235-
item is removed and returned.
1218+
The value *n* is an integer, or an object implementing
1219+
:meth:`~object.__index__`. Zero and negative values of *n* clear
1220+
the sequence. Items in the sequence are not copied; they are referenced
1221+
multiple times, as explained for ``s * n`` under :ref:`typesseq-common`.
12361222

1237-
(3)
1238-
:meth:`remove` raises :exc:`ValueError` when *x* is not found in *s*.
1223+
.. rubric:: Mutable Sequence Methods
12391224

1240-
(4)
1241-
The :meth:`reverse` method modifies the sequence in place for economy of
1242-
space when reversing a large sequence. To remind users that it operates by
1243-
side effect, it does not return the reversed sequence.
1225+
Mutable sequence types also support the following methods:
12441226

1245-
(5)
1246-
:meth:`clear` and :meth:`!copy` are included for consistency with the
1247-
interfaces of mutable containers that don't support slicing operations
1248-
(such as :class:`dict` and :class:`set`). :meth:`!copy` is not part of the
1249-
:class:`collections.abc.MutableSequence` ABC, but most concrete
1250-
mutable sequence classes provide it.
1227+
.. method:: bytearray.append(value, /)
1228+
list.append(value, /)
1229+
:no-contents-entry:
1230+
:no-index-entry:
1231+
:no-typesetting:
1232+
.. method:: sequence.append(value, /)
1233+
1234+
Append *value* to the end of the sequence
1235+
This is equivalent to writing ``seq[len(seq):len(seq)] = [value]``.
1236+
1237+
.. method:: bytearray.clear()
1238+
list.clear()
1239+
:no-contents-entry:
1240+
:no-index-entry:
1241+
:no-typesetting:
1242+
.. method:: sequence.clear()
12511243

12521244
.. versionadded:: 3.3
1253-
:meth:`clear` and :meth:`!copy` methods.
12541245

1255-
(6)
1256-
The value *n* is an integer, or an object implementing
1257-
:meth:`~object.__index__`. Zero and negative values of *n* clear
1258-
the sequence. Items in the sequence are not copied; they are referenced
1259-
multiple times, as explained for ``s * n`` under :ref:`typesseq-common`.
1246+
Remove all items from *sequence*.
1247+
This is equivalent to writing ``del sequence[:]``.
1248+
1249+
.. method:: bytearray.copy()
1250+
list.copy()
1251+
:no-contents-entry:
1252+
:no-index-entry:
1253+
:no-typesetting:
1254+
.. method:: sequence.copy()
1255+
1256+
.. versionadded:: 3.3
1257+
1258+
Create a shallow copy of *sequence*.
1259+
This is equivalent to writing ``sequence[:]``.
1260+
1261+
.. hint:: The :meth:`!copy` method is not part of the
1262+
:class:`~collections.abc.MutableSequence` :class:`~abc.ABC`,
1263+
but most concrete mutable sequence types provide it.
1264+
1265+
.. method:: bytearray.extend(iterable, /)
1266+
list.extend(iterable, /)
1267+
:no-contents-entry:
1268+
:no-index-entry:
1269+
:no-typesetting:
1270+
.. method:: sequence.extend(iterable, /)
1271+
1272+
Extend *sequence* with the contents of *iterable*.
1273+
For the most part, this is the same as writing
1274+
``seq[len(seq):len(seq)] = iterable``.
1275+
1276+
.. method:: bytearray.insert(index, value, /)
1277+
list.insert(index, value, /)
1278+
:no-contents-entry:
1279+
:no-index-entry:
1280+
:no-typesetting:
1281+
.. method:: sequence.insert(index, value, /)
1282+
1283+
Insert *value* into *sequence* at the given *index*.
1284+
This is equivalent to writing ``sequence[index:index] = [value]``.
1285+
1286+
.. method:: bytearray.pop(index=-1, /)
1287+
list.pop(index=-1, /)
1288+
:no-contents-entry:
1289+
:no-index-entry:
1290+
:no-typesetting:
1291+
.. method:: sequence.pop(index=-1, /)
1292+
1293+
Retrieve the item at *index* and also removes it from *sequence*.
1294+
By default, the last item in *sequence* is removed and returned.
1295+
1296+
.. method:: bytearray.remove(value, /)
1297+
list.remove(value, /)
1298+
:no-contents-entry:
1299+
:no-index-entry:
1300+
:no-typesetting:
1301+
.. method:: sequence.remove(value, /)
1302+
1303+
Remove the first item from *sequence* where ``sequence[i] == value``.
1304+
1305+
Raises :exc:`ValueError` if *value* is not found in *sequence*.
1306+
1307+
.. method:: bytearray.reverse()
1308+
list.reverse()
1309+
:no-contents-entry:
1310+
:no-index-entry:
1311+
:no-typesetting:
1312+
.. method:: sequence.reverse()
1313+
1314+
Reverse the items of *sequence* in place.
1315+
This method maintains economy of space when reversing a large sequence.
1316+
To remind users that it operates by side-effect, it returns ``None``.
12601317

12611318

12621319
.. _typesseq-list:
@@ -5562,9 +5619,10 @@ Methods
55625619

55635620
.. index:: pair: object; method
55645621

5565-
Methods are functions that are called using the attribute notation. There are
5566-
two flavors: :ref:`built-in methods <builtin-methods>` (such as :meth:`append`
5567-
on lists) and :ref:`class instance method <instance-methods>`.
5622+
Methods are functions that are called using the attribute notation.
5623+
There are two flavors: :ref:`built-in methods <builtin-methods>`
5624+
(such as :meth:`~list.append` on lists)
5625+
and :ref:`class instance method <instance-methods>`.
55685626
Built-in methods are described with the types that support them.
55695627

55705628
If you access a method (a function defined in a class namespace) through an

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL