diff options
| -rw-r--r-- | Doc/c-api/mapping.rst | 66 | ||||
| -rw-r--r-- | Doc/c-api/object.rst | 8 | ||||
| -rw-r--r-- | Doc/c-api/sequence.rst | 31 | ||||
| -rw-r--r-- | Doc/c-api/typeobj.rst | 56 | ||||
| -rw-r--r-- | Include/abstract.h | 16 |
5 files changed, 101 insertions, 76 deletions
diff --git a/Doc/c-api/mapping.rst b/Doc/c-api/mapping.rst index 308a976..b8eaadb 100644 --- a/Doc/c-api/mapping.rst +++ b/Doc/c-api/mapping.rst @@ -5,11 +5,17 @@ Mapping Protocol ================ +See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and +:c:func:`PyObject_DelItem`. + .. c:function:: int PyMapping_Check(PyObject *o) - Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This - function always succeeds. + Return ``1`` if the object provides mapping protocol or supports slicing, + and ``0`` otherwise. Note that it returns ``1`` for Python classes with + a :meth:`__getitem__` method since in general case it is impossible to + determine what the type of keys it supports. This function always + succeeds. .. c:function:: Py_ssize_t PyMapping_Size(PyObject *o) @@ -17,35 +23,49 @@ Mapping Protocol .. index:: builtin: len - Returns the number of keys in object *o* on success, and ``-1`` on failure. For - objects that do not provide mapping protocol, this is equivalent to the Python - expression ``len(o)``. + Returns the number of keys in object *o* on success, and ``-1`` on failure. + This is equivalent to the Python expression ``len(o)``. -.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key) +.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) + + Return element of *o* corresponding to the string *key* or *NULL* on failure. + This is the equivalent of the Python expression ``o[key]``. + See also :c:func:`PyObject_GetItem`. + - Remove the mapping for object *key* from the object *o*. Return ``-1`` on - failure. This is equivalent to the Python statement ``del o[key]``. +.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v) + + Map the string *key* to the value *v* in object *o*. Returns ``-1`` on + failure. This is the equivalent of the Python statement ``o[key] = v``. + See also :c:func:`PyObject_SetItem`. .. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key) - Remove the mapping for object *key* from the object *o*. Return ``-1`` on - failure. This is equivalent to the Python statement ``del o[key]``. + Remove the mapping for the object *key* from the object *o*. Return ``-1`` + on failure. This is equivalent to the Python statement ``del o[key]``. + This is an alias of :c:func:`PyObject_DelItem`. -.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) +.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key) - On success, return ``1`` if the mapping object has the key *key* and ``0`` - otherwise. This is equivalent to the Python expression ``key in o``. - This function always succeeds. + Remove the mapping for the string *key* from the object *o*. Return ``-1`` + on failure. This is equivalent to the Python statement ``del o[key]``. .. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key) - Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. This - is equivalent to the Python expression ``key in o``. This function always - succeeds. + Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. + This is equivalent to the Python expression ``key in o``. + This function always succeeds. + + +.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key) + + Return ``1`` if the mapping object has the key *key* and ``0`` otherwise. + This is equivalent to the Python expression ``key in o``. + This function always succeeds. .. c:function:: PyObject* PyMapping_Keys(PyObject *o) @@ -73,15 +93,3 @@ Mapping Protocol .. versionchanged:: 3.7 Previously, the function returned a list or a tuple. - - -.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key) - - Return element of *o* corresponding to the object *key* or *NULL* on failure. - This is the equivalent of the Python expression ``o[key]``. - - -.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v) - - Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure. - This is the equivalent of the Python statement ``o[key] = v``. diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 754dedc..f0b2005 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -379,8 +379,8 @@ Object Protocol parameters must be non-*NULL*. -.. c:function:: Py_ssize_t PyObject_Length(PyObject *o) - Py_ssize_t PyObject_Size(PyObject *o) +.. c:function:: Py_ssize_t PyObject_Size(PyObject *o) + Py_ssize_t PyObject_Length(PyObject *o) .. index:: builtin: len @@ -414,8 +414,8 @@ Object Protocol .. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key) - Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the - equivalent of the Python statement ``del o[key]``. + Remove the mapping for the object *key* from the object *o*. Return ``-1`` + on failure. This is equivalent to the Python statement ``del o[key]``. .. c:function:: PyObject* PyObject_Dir(PyObject *o) diff --git a/Doc/c-api/sequence.rst b/Doc/c-api/sequence.rst index 81f8557..6d22f35 100644 --- a/Doc/c-api/sequence.rst +++ b/Doc/c-api/sequence.rst @@ -9,7 +9,10 @@ Sequence Protocol .. c:function:: int PySequence_Check(PyObject *o) Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. - This function always succeeds. + Note that it returns ``1`` for Python classes with a :meth:`__getitem__` + method unless they are :class:`dict` subclasses since in general case it + is impossible to determine what the type of keys it supports. This + function always succeeds. .. c:function:: Py_ssize_t PySequence_Size(PyObject *o) @@ -119,18 +122,27 @@ Sequence Protocol .. index:: builtin: tuple - Return a tuple object with the same contents as the arbitrary sequence *o* or - *NULL* on failure. If *o* is a tuple, a new reference will be returned, + Return a tuple object with the same contents as the sequence or iterable *o*, + or *NULL* on failure. If *o* is a tuple, a new reference will be returned, otherwise a tuple will be constructed with the appropriate contents. This is equivalent to the Python expression ``tuple(o)``. .. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m) - Return the sequence *o* as a list, unless it is already a tuple or list, in + Return the sequence or iterable *o* as a list, unless it is already a tuple or list, in which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access the members of the result. Returns *NULL* on failure. If the object is not - a sequence, raises :exc:`TypeError` with *m* as the message text. + a sequence or iterable, raises :exc:`TypeError` with *m* as the message text. + + +.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) + + Returns the length of *o*, assuming that *o* was returned by + :c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be + gotten by calling :c:func:`PySequence_Size` on *o*, but + :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list + or tuple. .. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) @@ -155,12 +167,3 @@ Sequence Protocol :c:func:`PySequence_GetItem` but without checking that :c:func:`PySequence_Check` on *o* is true and without adjustment for negative indices. - - -.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o) - - Returns the length of *o*, assuming that *o* was returned by - :c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be - gotten by calling :c:func:`PySequence_Size` on *o*, but - :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list - or tuple. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 3bdf45a..6cbcc27 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1167,21 +1167,24 @@ Mapping Object Structures .. c:member:: lenfunc PyMappingMethods.mp_length - This function is used by :c:func:`PyMapping_Length` and + This function is used by :c:func:`PyMapping_Size` and :c:func:`PyObject_Size`, and has the same signature. This slot may be set to *NULL* if the object has no defined length. .. c:member:: binaryfunc PyMappingMethods.mp_subscript - This function is used by :c:func:`PyObject_GetItem` and has the same - signature. This slot must be filled for the :c:func:`PyMapping_Check` - function to return ``1``, it can be *NULL* otherwise. + This function is used by :c:func:`PyObject_GetItem` and + :c:func:`PySequence_GetSlice`, and has the same signature as + :c:func:`!PyObject_GetItem`. This slot must be filled for the + :c:func:`PyMapping_Check` function to return ``1``, it can be *NULL* + otherwise. .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript - This function is used by :c:func:`PyObject_SetItem` and - :c:func:`PyObject_DelItem`. It has the same signature as - :c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete + This function is used by :c:func:`PyObject_SetItem`, + :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and + :c:func:`PyObject_DelSlice`. It has the same signature as + :c:func:`!PyObject_SetItem`, but *v* can also be set to *NULL* to delete an item. If this slot is *NULL*, the object does not support item assignment and deletion. @@ -1201,26 +1204,29 @@ Sequence Object Structures .. c:member:: lenfunc PySequenceMethods.sq_length - This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`, - and has the same signature. + This function is used by :c:func:`PySequence_Size` and + :c:func:`PyObject_Size`, and has the same signature. It is also used for + handling negative indices via the :c:member:`~PySequenceMethods.sq_item` + and the :c:member:`~PySequenceMethods.sq_ass_item` slots. .. c:member:: binaryfunc PySequenceMethods.sq_concat This function is used by :c:func:`PySequence_Concat` and has the same signature. It is also used by the ``+`` operator, after trying the numeric - addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot. + addition via the :c:member:`~PyNumberMethods.nb_add` slot. .. c:member:: ssizeargfunc PySequenceMethods.sq_repeat This function is used by :c:func:`PySequence_Repeat` and has the same signature. It is also used by the ``*`` operator, after trying numeric - multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply` - slot. + multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot. .. c:member:: ssizeargfunc PySequenceMethods.sq_item This function is used by :c:func:`PySequence_GetItem` and has the same - signature. This slot must be filled for the :c:func:`PySequence_Check` + signature. It is also used by :c:func:`PyObject_GetItem`, after trying + the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. + This slot must be filled for the :c:func:`PySequence_Check` function to return ``1``, it can be *NULL* otherwise. Negative indexes are handled as follows: if the :attr:`sq_length` slot is @@ -1231,28 +1237,36 @@ Sequence Object Structures .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item This function is used by :c:func:`PySequence_SetItem` and has the same - signature. This slot may be left to *NULL* if the object does not support + signature. It is also used by :c:func:`PyObject_SetItem` and + :c:func:`PyObject_DelItem`, after trying the item assignment and deletion + via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot. + This slot may be left to *NULL* if the object does not support item assignment and deletion. .. c:member:: objobjproc PySequenceMethods.sq_contains This function may be used by :c:func:`PySequence_Contains` and has the same signature. This slot may be left to *NULL*, in this case - :c:func:`PySequence_Contains` simply traverses the sequence until it finds a - match. + :c:func:`!PySequence_Contains` simply traverses the sequence until it + finds a match. .. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat This function is used by :c:func:`PySequence_InPlaceConcat` and has the same - signature. It should modify its first operand, and return it. + signature. It should modify its first operand, and return it. This slot + may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat` + will fall back to :c:func:`PySequence_Concat`. It is also used by the + augmented assignment ``+=``, after trying numeric inplace addition + via the :c:member:`~PyNumberMethods.nb_inplace_add` slot. .. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same - signature. It should modify its first operand, and return it. - -.. XXX need to explain precedence between mapping and sequence -.. XXX explains when to implement the sq_inplace_* slots + signature. It should modify its first operand, and return it. This slot + may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceRepeat` + will fall back to :c:func:`PySequence_Repeat`. It is also used by the + augmented assignment ``*=``, after trying numeric inplace multiplication + via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot. .. _buffer-structs: diff --git a/Include/abstract.h b/Include/abstract.h index 3133cd1..4088f75 100644 --- a/Include/abstract.h +++ b/Include/abstract.h @@ -442,13 +442,14 @@ PyAPI_FUNC(PyObject *) PyObject_GetItem(PyObject *o, PyObject *key); This is the equivalent of the Python statement: o[key]=v. */ PyAPI_FUNC(int) PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v); -/* Remove the mapping for object, key, from the object 'o'. +/* Remove the mapping for the string 'key' from the object 'o'. Returns -1 on failure. This is equivalent to the Python statement: del o[key]. */ PyAPI_FUNC(int) PyObject_DelItemString(PyObject *o, const char *key); -/* Delete the mapping for key from object 'o'. Returns -1 on failure. +/* Delete the mapping for the object 'key' from the object 'o'. + Returns -1 on failure. This is the equivalent of the Python statement: del o[key]. */ PyAPI_FUNC(int) PyObject_DelItem(PyObject *o, PyObject *key); @@ -1005,8 +1006,7 @@ PyAPI_FUNC(PyObject *) PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count); PyAPI_FUNC(int) PyMapping_Check(PyObject *o); /* Returns the number of keys in mapping object 'o' on success, and -1 on - failure. For objects that do not provide sequence protocol, this is - equivalent to the Python expression: len(o). */ + failure. This is equivalent to the Python expression: len(o). */ PyAPI_FUNC(Py_ssize_t) PyMapping_Size(PyObject *o); /* For DLL compatibility */ @@ -1019,7 +1019,7 @@ PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o); int PyMapping_DelItemString(PyObject *o, const char *key); - Remove the mapping for object 'key' from the mapping 'o'. Returns -1 on + Remove the mapping for the string 'key' from the mapping 'o'. Returns -1 on failure. This is equivalent to the Python statement: del o[key]. */ @@ -1029,7 +1029,7 @@ PyAPI_FUNC(Py_ssize_t) PyMapping_Length(PyObject *o); int PyMapping_DelItem(PyObject *o, PyObject *key); - Remove the mapping for object 'key' from the mapping object 'o'. + Remove the mapping for the object 'key' from the mapping object 'o'. Returns -1 on failure. This is equivalent to the Python statement: del o[key]. */ @@ -1063,13 +1063,13 @@ PyAPI_FUNC(PyObject *) PyMapping_Values(PyObject *o); NULL. */ PyAPI_FUNC(PyObject *) PyMapping_Items(PyObject *o); -/* Return element of o corresponding to the object, key, or NULL on failure. +/* Return element of 'o' corresponding to the string 'key' or NULL on failure. This is the equivalent of the Python expression: o[key]. */ PyAPI_FUNC(PyObject *) PyMapping_GetItemString(PyObject *o, const char *key); -/* Map the object 'key' to the value 'v' in the mapping 'o'. +/* Map the string 'key' to the value 'v' in the mapping 'o'. Returns -1 on failure. This is the equivalent of the Python statement: o[key]=v. */ |