[3.6] bpo-5945: Improve mappings and sequences C API docs. (GH-7029).… · python/cpython@93e9fb5 (original) (raw)

`@@ -1151,21 +1151,24 @@ Mapping Object Structures

1151

1152

`.. c:member:: lenfunc PyMappingMethods.mp_length

1153

1154

`` -

This function is used by :c:func:PyMapping_Length and

1154

`` +

This function is used by :c:func:PyMapping_Size and

1155

`` :c:func:PyObject_Size, and has the same signature. This slot may be set to

1156

` NULL if the object has no defined length.

1157

1158

`.. c:member:: binaryfunc PyMappingMethods.mp_subscript

1159

1160

`` -

This function is used by :c:func:PyObject_GetItem and has the same

1161

`` -

signature. This slot must be filled for the :c:func:PyMapping_Check

1162


 function to return ``1``, it can be *NULL* otherwise.

1160

`` +

This function is used by :c:func:PyObject_GetItem and

1161

`` +

:c:func:PySequence_GetSlice, and has the same signature as

1162

`` +

:c:func:!PyObject_GetItem. This slot must be filled for the

1163


:c:func:`PyMapping_Check` function to return ``1``, it can be *NULL*

1164

otherwise.

1163

1165

1164

1166

`.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript

1165

1167

1166

`` -

This function is used by :c:func:PyObject_SetItem and

1167

`` -

:c:func:PyObject_DelItem. It has the same signature as

1168

`` -

:c:func:PyObject_SetItem, but v can also be set to NULL to delete

1168

`` +

This function is used by :c:func:PyObject_SetItem,

1169

`` +

:c:func:PyObject_DelItem, :c:func:PyObject_SetSlice and

1170

`` +

:c:func:PyObject_DelSlice. It has the same signature as

1171

`` +

:c:func:!PyObject_SetItem, but v can also be set to NULL to delete

1169

1172

` an item. If this slot is NULL, the object does not support item

1170

1173

` assignment and deletion.

1171

1174

`@@ -1185,26 +1188,29 @@ Sequence Object Structures

1185

1188

1186

1189

`.. c:member:: lenfunc PySequenceMethods.sq_length

1187

1190

1188

`` -

This function is used by :c:func:PySequence_Size and :c:func:PyObject_Size,

1189

and has the same signature.

1191

`` +

This function is used by :c:func:PySequence_Size and

1192

`` +

:c:func:PyObject_Size, and has the same signature. It is also used for

1193

`` +

handling negative indices via the :c:member:~PySequenceMethods.sq_item

1194

`` +

and the :c:member:~PySequenceMethods.sq_ass_item slots.

1190

1195

1191

1196

`.. c:member:: binaryfunc PySequenceMethods.sq_concat

1192

1197

1193

1198

`` This function is used by :c:func:PySequence_Concat and has the same

1194

1199

``` signature. It is also used by the + operator, after trying the numeric


`1195`

``

`` -

addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot.

``

``

`1200`

`` +

addition via the :c:member:`~PyNumberMethods.nb_add` slot.

``

`1196`

`1201`

``

`1197`

`1202`

`.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat

`

`1198`

`1203`

``

`1199`

`1204`

``  This function is used by :c:func:`PySequence_Repeat` and has the same

``

`1200`

`1205`

```  signature. It is also used by the ``*`` operator, after trying numeric

1201

`` -

multiplication via the :c:member:~PyTypeObject.tp_as_number.nb_multiply

1202

slot.

1206

`` +

multiplication via the :c:member:~PyNumberMethods.nb_multiply slot.

1203

1207

1204

1208

`.. c:member:: ssizeargfunc PySequenceMethods.sq_item

1205

1209

1206

1210

`` This function is used by :c:func:PySequence_GetItem and has the same

1207

`` -

signature. This slot must be filled for the :c:func:PySequence_Check

1211

`` +

signature. It is also used by :c:func:PyObject_GetItem, after trying

1212

`` +

the subscription via the :c:member:~PyMappingMethods.mp_subscript slot.

1213

`` +

This slot must be filled for the :c:func:PySequence_Check

1208

1214

``` function to return 1, it can be NULL otherwise.


`1209`

`1215`

``

`1210`

`1216`

``  Negative indexes are handled as follows: if the :attr:`sq_length` slot is

``

`@@ -1215,28 +1221,36 @@ Sequence Object Structures

`

`1215`

`1221`

`.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item

`

`1216`

`1222`

``

`1217`

`1223`

``  This function is used by :c:func:`PySequence_SetItem` and has the same

``

`1218`

``

`-

signature. This slot may be left to *NULL* if the object does not support

`

``

`1224`

`` +

signature. It is also used by :c:func:`PyObject_SetItem` and

``

``

`1225`

`` +

:c:func:`PyObject_DelItem`, after trying the item assignment and deletion

``

``

`1226`

`` +

via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot.

``

``

`1227`

`+

This slot may be left to *NULL* if the object does not support

`

`1219`

`1228`

` item assignment and deletion.

`

`1220`

`1229`

``

`1221`

`1230`

`.. c:member:: objobjproc PySequenceMethods.sq_contains

`

`1222`

`1231`

``

`1223`

`1232`

``  This function may be used by :c:func:`PySequence_Contains` and has the same

``

`1224`

`1233`

` signature. This slot may be left to *NULL*, in this case

`

`1225`

``

`` -

:c:func:`PySequence_Contains` simply traverses the sequence until it finds a

``

`1226`

``

`-

match.

`

``

`1234`

`` +

:c:func:`!PySequence_Contains` simply traverses the sequence until it

``

``

`1235`

`+

finds a match.

`

`1227`

`1236`

``

`1228`

`1237`

`.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat

`

`1229`

`1238`

``

`1230`

`1239`

``  This function is used by :c:func:`PySequence_InPlaceConcat` and has the same

``

`1231`

``

`-

signature. It should modify its first operand, and return it.

`

``

`1240`

`+

signature. It should modify its first operand, and return it. This slot

`

``

`1241`

`` +

may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat`

``

``

`1242`

`` +

will fall back to :c:func:`PySequence_Concat`. It is also used by the

``

``

`1243`

``` +

augmented assignment ``+=``, after trying numeric inplace addition

1244

`` +

via the :c:member:~PyNumberMethods.nb_inplace_add slot.

1232

1245

1233

1246

`.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat

1234

1247

1235

1248

`` This function is used by :c:func:PySequence_InPlaceRepeat and has the same

1236

signature. It should modify its first operand, and return it.

1237

-

1238

.. XXX need to explain precedence between mapping and sequence

1239

.. XXX explains when to implement the sq_inplace_* slots

1249

signature. It should modify its first operand, and return it. This slot

1250

`` +

may be left to NULL, in this case :c:func:!PySequence_InPlaceRepeat

1251

`` +

will fall back to :c:func:PySequence_Repeat. It is also used by the

1252


 augmented assignment ``*=``, after trying numeric inplace multiplication

1253

`` +

via the :c:member:~PyNumberMethods.nb_inplace_multiply slot.

1240

1254

1241

1255

1242

1256

`.. _buffer-structs: