Skip to content

Commit e1a78ca

Browse files
miss-islingtonserhiy-storchaka
miss-islington
and
serhiy-storchaka
authored
bpo-5945: Improve mappings and sequences C API docs. (GH-7029)
(cherry picked from commit f5b1183) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
1 parent d9055f8 commit e1a78ca

File tree

5 files changed

+101
-76
lines changed

5 files changed

+101
-76
lines changed

‎Doc/c-api/mapping.rst

+37-29
Original file line numberDiff line numberDiff line change
@@ -5,47 +5,67 @@
55
Mapping Protocol
66
================
77

8+
See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
9+
:c:func:`PyObject_DelItem`.
10+
811

912
.. c:function:: int PyMapping_Check(PyObject *o)
1013
11-
Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
12-
function always succeeds.
14+
Return ``1`` if the object provides mapping protocol or supports slicing,
15+
and ``0`` otherwise. Note that it returns ``1`` for Python classes with
16+
a :meth:`__getitem__` method since in general case it is impossible to
17+
determine what the type of keys it supports. This function always
18+
succeeds.
1319
1420
1521
.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
1622
Py_ssize_t PyMapping_Length(PyObject *o)
1723
1824
.. index:: builtin: len
1925
20-
Returns the number of keys in object *o* on success, and ``-1`` on failure. For
21-
objects that do not provide mapping protocol, this is equivalent to the Python
22-
expression ``len(o)``.
26+
Returns the number of keys in object *o* on success, and ``-1`` on failure.
27+
This is equivalent to the Python expression ``len(o)``.
2328
2429
25-
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
30+
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
31+
32+
Return element of *o* corresponding to the string *key* or *NULL* on failure.
33+
This is the equivalent of the Python expression ``o[key]``.
34+
See also :c:func:`PyObject_GetItem`.
35+
2636
27-
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
28-
failure. This is equivalent to the Python statement ``del o[key]``.
37+
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
38+
39+
Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
40+
failure. This is the equivalent of the Python statement ``o[key] = v``.
41+
See also :c:func:`PyObject_SetItem`.
2942
3043
3144
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
3245
33-
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
34-
failure. This is equivalent to the Python statement ``del o[key]``.
46+
Remove the mapping for the object *key* from the object *o*. Return ``-1``
47+
on failure. This is equivalent to the Python statement ``del o[key]``.
48+
This is an alias of :c:func:`PyObject_DelItem`.
3549
3650
37-
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
51+
.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
3852
39-
On success, return ``1`` if the mapping object has the key *key* and ``0``
40-
otherwise. This is equivalent to the Python expression ``key in o``.
41-
This function always succeeds.
53+
Remove the mapping for the string *key* from the object *o*. Return ``-1``
54+
on failure. This is equivalent to the Python statement ``del o[key]``.
4255
4356
4457
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
4558
46-
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. This
47-
is equivalent to the Python expression ``key in o``. This function always
48-
succeeds.
59+
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
60+
This is equivalent to the Python expression ``key in o``.
61+
This function always succeeds.
62+
63+
64+
.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
65+
66+
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
67+
This is equivalent to the Python expression ``key in o``.
68+
This function always succeeds.
4969
5070
5171
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
@@ -73,15 +93,3 @@ Mapping Protocol
7393
7494
.. versionchanged:: 3.7
7595
Previously, the function returned a list or a tuple.
76-
77-
78-
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
79-
80-
Return element of *o* corresponding to the object *key* or *NULL* on failure.
81-
This is the equivalent of the Python expression ``o[key]``.
82-
83-
84-
.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
85-
86-
Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
87-
This is the equivalent of the Python statement ``o[key] = v``.

‎Doc/c-api/object.rst

+4-4
Original file line numberDiff line numberDiff line change
@@ -379,8 +379,8 @@ Object Protocol
379379
parameters must be non-*NULL*.
380380
381381
382-
.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
383-
Py_ssize_t PyObject_Size(PyObject *o)
382+
.. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
383+
Py_ssize_t PyObject_Length(PyObject *o)
384384
385385
.. index:: builtin: len
386386
@@ -414,8 +414,8 @@ Object Protocol
414414
415415
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
416416
417-
Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
418-
equivalent of the Python statement ``del o[key]``.
417+
Remove the mapping for the object *key* from the object *o*. Return ``-1``
418+
on failure. This is equivalent to the Python statement ``del o[key]``.
419419
420420
421421
.. c:function:: PyObject* PyObject_Dir(PyObject *o)

‎Doc/c-api/sequence.rst

+17-14
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@ Sequence Protocol
99
.. c:function:: int PySequence_Check(PyObject *o)
1010
1111
Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
12-
This function always succeeds.
12+
Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
13+
method unless they are :class:`dict` subclasses since in general case it
14+
is impossible to determine what the type of keys it supports. This
15+
function always succeeds.
1316
1417
1518
.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
@@ -119,18 +122,27 @@ Sequence Protocol
119122
120123
.. index:: builtin: tuple
121124
122-
Return a tuple object with the same contents as the arbitrary sequence *o* or
123-
*NULL* on failure. If *o* is a tuple, a new reference will be returned,
125+
Return a tuple object with the same contents as the sequence or iterable *o*,
126+
or *NULL* on failure. If *o* is a tuple, a new reference will be returned,
124127
otherwise a tuple will be constructed with the appropriate contents. This is
125128
equivalent to the Python expression ``tuple(o)``.
126129
127130
128131
.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
129132
130-
Return the sequence *o* as a list, unless it is already a tuple or list, in
133+
Return the sequence or iterable *o* as a list, unless it is already a tuple or list, in
131134
which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access
132135
the members of the result. Returns *NULL* on failure. If the object is not
133-
a sequence, raises :exc:`TypeError` with *m* as the message text.
136+
a sequence or iterable, raises :exc:`TypeError` with *m* as the message text.
137+
138+
139+
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
140+
141+
Returns the length of *o*, assuming that *o* was returned by
142+
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
143+
gotten by calling :c:func:`PySequence_Size` on *o*, but
144+
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
145+
or tuple.
134146
135147
136148
.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
@@ -155,12 +167,3 @@ Sequence Protocol
155167
:c:func:`PySequence_GetItem` but without checking that
156168
:c:func:`PySequence_Check` on *o* is true and without adjustment for negative
157169
indices.
158-
159-
160-
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
161-
162-
Returns the length of *o*, assuming that *o* was returned by
163-
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
164-
gotten by calling :c:func:`PySequence_Size` on *o*, but
165-
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
166-
or tuple.

‎Doc/c-api/typeobj.rst

+35-21
Original file line numberDiff line numberDiff line change
@@ -1167,21 +1167,24 @@ Mapping Object Structures
11671167

11681168
.. c:member:: lenfunc PyMappingMethods.mp_length
11691169
1170-
This function is used by :c:func:`PyMapping_Length` and
1170+
This function is used by :c:func:`PyMapping_Size` and
11711171
:c:func:`PyObject_Size`, and has the same signature. This slot may be set to
11721172
*NULL* if the object has no defined length.
11731173

11741174
.. c:member:: binaryfunc PyMappingMethods.mp_subscript
11751175
1176-
This function is used by :c:func:`PyObject_GetItem` and has the same
1177-
signature. This slot must be filled for the :c:func:`PyMapping_Check`
1178-
function to return ``1``, it can be *NULL* otherwise.
1176+
This function is used by :c:func:`PyObject_GetItem` and
1177+
:c:func:`PySequence_GetSlice`, and has the same signature as
1178+
:c:func:`!PyObject_GetItem`. This slot must be filled for the
1179+
:c:func:`PyMapping_Check` function to return ``1``, it can be *NULL*
1180+
otherwise.
11791181

11801182
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
11811183
1182-
This function is used by :c:func:`PyObject_SetItem` and
1183-
:c:func:`PyObject_DelItem`. It has the same signature as
1184-
:c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete
1184+
This function is used by :c:func:`PyObject_SetItem`,
1185+
:c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and
1186+
:c:func:`PyObject_DelSlice`. It has the same signature as
1187+
:c:func:`!PyObject_SetItem`, but *v* can also be set to *NULL* to delete
11851188
an item. If this slot is *NULL*, the object does not support item
11861189
assignment and deletion.
11871190

@@ -1201,26 +1204,29 @@ Sequence Object Structures
12011204

12021205
.. c:member:: lenfunc PySequenceMethods.sq_length
12031206
1204-
This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`,
1205-
and has the same signature.
1207+
This function is used by :c:func:`PySequence_Size` and
1208+
:c:func:`PyObject_Size`, and has the same signature. It is also used for
1209+
handling negative indices via the :c:member:`~PySequenceMethods.sq_item`
1210+
and the :c:member:`~PySequenceMethods.sq_ass_item` slots.
12061211

12071212
.. c:member:: binaryfunc PySequenceMethods.sq_concat
12081213
12091214
This function is used by :c:func:`PySequence_Concat` and has the same
12101215
signature. It is also used by the ``+`` operator, after trying the numeric
1211-
addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot.
1216+
addition via the :c:member:`~PyNumberMethods.nb_add` slot.
12121217

12131218
.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat
12141219
12151220
This function is used by :c:func:`PySequence_Repeat` and has the same
12161221
signature. It is also used by the ``*`` operator, after trying numeric
1217-
multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply`
1218-
slot.
1222+
multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot.
12191223

12201224
.. c:member:: ssizeargfunc PySequenceMethods.sq_item
12211225
12221226
This function is used by :c:func:`PySequence_GetItem` and has the same
1223-
signature. This slot must be filled for the :c:func:`PySequence_Check`
1227+
signature. It is also used by :c:func:`PyObject_GetItem`, after trying
1228+
the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot.
1229+
This slot must be filled for the :c:func:`PySequence_Check`
12241230
function to return ``1``, it can be *NULL* otherwise.
12251231

12261232
Negative indexes are handled as follows: if the :attr:`sq_length` slot is
@@ -1231,28 +1237,36 @@ Sequence Object Structures
12311237
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
12321238
12331239
This function is used by :c:func:`PySequence_SetItem` and has the same
1234-
signature. This slot may be left to *NULL* if the object does not support
1240+
signature. It is also used by :c:func:`PyObject_SetItem` and
1241+
:c:func:`PyObject_DelItem`, after trying the item assignment and deletion
1242+
via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot.
1243+
This slot may be left to *NULL* if the object does not support
12351244
item assignment and deletion.
12361245

12371246
.. c:member:: objobjproc PySequenceMethods.sq_contains
12381247
12391248
This function may be used by :c:func:`PySequence_Contains` and has the same
12401249
signature. This slot may be left to *NULL*, in this case
1241-
:c:func:`PySequence_Contains` simply traverses the sequence until it finds a
1242-
match.
1250+
:c:func:`!PySequence_Contains` simply traverses the sequence until it
1251+
finds a match.
12431252

12441253
.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat
12451254
12461255
This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
1247-
signature. It should modify its first operand, and return it.
1256+
signature. It should modify its first operand, and return it. This slot
1257+
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat`
1258+
will fall back to :c:func:`PySequence_Concat`. It is also used by the
1259+
augmented assignment ``+=``, after trying numeric inplace addition
1260+
via the :c:member:`~PyNumberMethods.nb_inplace_add` slot.
12481261

12491262
.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
12501263
12511264
This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
1252-
signature. It should modify its first operand, and return it.
1253-
1254-
.. XXX need to explain precedence between mapping and sequence
1255-
.. XXX explains when to implement the sq_inplace_* slots
1265+
signature. It should modify its first operand, and return it. This slot
1266+
may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceRepeat`
1267+
will fall back to :c:func:`PySequence_Repeat`. It is also used by the
1268+
augmented assignment ``*=``, after trying numeric inplace multiplication
1269+
via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot.
12561270

12571271

12581272
.. _buffer-structs:

‎Include/abstract.h

+8-8
Original file line numberDiff line numberDiff line change
@@ -442,13 +442,14 @@ PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key);
442442
This is the equivalent of the Python statement: o[key]=v. */
443443
PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v);
444444

445-
/* Remove the mapping for object, key, from the object 'o'.
445+
/* Remove the mapping for the string 'key' from the object 'o'.
446446
Returns -1 on failure.
447447
448448
This is equivalent to the Python statement: del o[key]. */
449449
PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key);
450450

451-
/* Delete the mapping for key from object 'o'. Returns -1 on failure.
451+
/* Delete the mapping for the object 'key' from the object 'o'.
452+
Returns -1 on failure.
452453
453454
This is the equivalent of the Python statement: del o[key]. */
454455
PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key);
@@ -1005,8 +1006,7 @@ PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count);
10051006
PyAPI_FUNC(int) PyMapping_Check(PyObject *o);
10061007

10071008
/* Returns the number of keys in mapping object 'o' on success, and -1 on
1008-
failure. For objects that do not provide sequence protocol, this is
1009-
equivalent to the Python expression: len(o). */
1009+
failure. This is equivalent to the Python expression: len(o). */
10101010
PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o);
10111011

10121012
/* For DLL compatibility */
@@ -1019,7 +1019,7 @@ PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
10191019
10201020
int PyMapping_DelItemString(PyObject *o, const char *key);
10211021
1022-
Remove the mapping for object 'key' from the mapping 'o'. Returns -1 on
1022+
Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on
10231023
failure.
10241024
10251025
This is equivalent to the Python statement: del o[key]. */
@@ -1029,7 +1029,7 @@ PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o);
10291029
10301030
int PyMapping_DelItem(PyObject *o, PyObject *key);
10311031
1032-
Remove the mapping for object 'key' from the mapping object 'o'.
1032+
Remove the mapping for the object 'key' from the mapping object 'o'.
10331033
Returns -1 on failure.
10341034
10351035
This is equivalent to the Python statement: del o[key]. */
@@ -1063,13 +1063,13 @@ PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o);
10631063
NULL. */
10641064
PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o);
10651065

1066-
/* Return element of o corresponding to the object, key, or NULL on failure.
1066+
/* Return element of 'o' corresponding to the string 'key' or NULL on failure.
10671067
10681068
This is the equivalent of the Python expression: o[key]. */
10691069
PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o,
10701070
const char *key);
10711071

1072-
/* Map the object 'key' to the value 'v' in the mapping 'o'.
1072+
/* Map the string 'key' to the value 'v' in the mapping 'o'.
10731073
Returns -1 on failure.
10741074
10751075
This is the equivalent of the Python statement: o[key]=v. */

0 commit comments

Comments
 (0)