diff options
Diffstat (limited to 'Doc/c-api/tuple.rst')
| -rw-r--r-- | Doc/c-api/tuple.rst | 181 |
1 files changed, 62 insertions, 119 deletions
diff --git a/Doc/c-api/tuple.rst b/Doc/c-api/tuple.rst index 62bc9a5..fd85663 100644 --- a/Doc/c-api/tuple.rst +++ b/Doc/c-api/tuple.rst @@ -1,4 +1,4 @@ -.. highlight:: c +.. highlightlang:: c .. _tupleobjects: @@ -15,8 +15,10 @@ Tuple Objects .. c:var:: PyTypeObject PyTuple_Type - This instance of :c:type:`PyTypeObject` represents the Python tuple type; it - is the same object as :class:`tuple` in the Python layer. + .. index:: single: TupleType (in module types) + + This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is + the same object as ``tuple`` and ``types.TupleType`` in the Python layer.. .. c:function:: int PyTuple_Check(PyObject *p) @@ -24,53 +26,88 @@ Tuple Objects Return true if *p* is a tuple object or an instance of a subtype of the tuple type. + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + .. c:function:: int PyTuple_CheckExact(PyObject *p) Return true if *p* is a tuple object, but not an instance of a subtype of the tuple type. + .. versionadded:: 2.2 + .. c:function:: PyObject* PyTuple_New(Py_ssize_t len) - Return a new tuple object of size *len*, or ``NULL`` on failure. + Return a new tuple object of size *len*, or *NULL* on failure. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *len*. This might require + changes in your code for properly supporting 64-bit systems. .. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) - Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values + Return a new tuple object of size *n*, or *NULL* on failure. The tuple values are initialized to the subsequent *n* C arguments pointing to Python objects. ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. + .. versionadded:: 2.4 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *n*. This might require + changes in your code for properly supporting 64-bit systems. + .. c:function:: Py_ssize_t PyTuple_Size(PyObject *p) Take a pointer to a tuple object, and return the size of that tuple. + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + .. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) - Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple; + Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple; no error checking is performed. + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + .. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is - out of bounds, return ``NULL`` and set an :exc:`IndexError` exception. + out of bounds, return *NULL* and set an :exc:`IndexError` exception. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. .. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments. + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + .. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) Return the slice of the tuple pointed to by *p* between *low* and *high*, - or ``NULL`` on failure. This is the equivalent of the Python expression + or *NULL* on failure. This is the equivalent of the Python expression ``p[low:high]``. Indexing from the end of the list is not supported. + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *low* and *high*. This might + require changes in your code for properly supporting 64-bit systems. + .. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) @@ -83,6 +120,10 @@ Tuple Objects This function "steals" a reference to *o* and discards a reference to an item already in the tuple at the affected position. + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + .. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) @@ -96,6 +137,10 @@ Tuple Objects is being replaced; any reference in the tuple at position *pos* will be leaked. + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + .. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) @@ -107,121 +152,19 @@ Tuple Objects only more efficiently. Returns ``0`` on success. Client code should never assume that the resulting value of ``*p`` will be the same as before calling this function. If the object referenced by ``*p`` is replaced, the original - ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and + ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and raises :exc:`MemoryError` or :exc:`SystemError`. + .. versionchanged:: 2.2 + Removed unused third parameter, *last_is_sticky*. -.. c:function:: int PyTuple_ClearFreeList() - - Clear the free list. Return the total number of freed items. - - -Struct Sequence Objects ------------------------ - -Struct sequence objects are the C equivalent of :func:`~collections.namedtuple` -objects, i.e. a sequence whose items can also be accessed through attributes. -To create a struct sequence, you first have to create a specific struct sequence -type. - -.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc) - - Create a new struct sequence type from the data in *desc*, described below. Instances - of the resulting type can be created with :c:func:`PyStructSequence_New`. - - -.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc) - - Initializes a struct sequence type *type* from *desc* in place. - - -.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc) - - The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on - failure. - - .. versionadded:: 3.4 - - -.. c:type:: PyStructSequence_Desc + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *newsize*. This might + require changes in your code for properly supporting 64-bit systems. - Contains the meta information of a struct sequence type to create. - +-------------------+------------------------------+--------------------------------------+ - | Field | C Type | Meaning | - +===================+==============================+======================================+ - | ``name`` | ``const char *`` | name of the struct sequence type | - +-------------------+------------------------------+--------------------------------------+ - | ``doc`` | ``const char *`` | pointer to docstring for the type | - | | | or ``NULL`` to omit | - +-------------------+------------------------------+--------------------------------------+ - | ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array | - | | | with field names of the new type | - +-------------------+------------------------------+--------------------------------------+ - | ``n_in_sequence`` | ``int`` | number of fields visible to the | - | | | Python side (if used as tuple) | - +-------------------+------------------------------+--------------------------------------+ - - -.. c:type:: PyStructSequence_Field - - Describes a field of a struct sequence. As a struct sequence is modeled as a - tuple, all fields are typed as :c:type:`PyObject\*`. The index in the - :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which - field of the struct sequence is described. - - +-----------+------------------+-----------------------------------------+ - | Field | C Type | Meaning | - +===========+==================+=========================================+ - | ``name`` | ``const char *`` | name for the field or ``NULL`` to end | - | | | the list of named fields, set to | - | | | :c:data:`PyStructSequence_UnnamedField` | - | | | to leave unnamed | - +-----------+------------------+-----------------------------------------+ - | ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit | - +-----------+------------------+-----------------------------------------+ - - -.. c:var:: const char * const PyStructSequence_UnnamedField - - Special value for a field name to leave it unnamed. - - .. versionchanged:: 3.9 - The type was changed from ``char *``. - - -.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type) - - Creates an instance of *type*, which must have been created with - :c:func:`PyStructSequence_NewType`. - - -.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos) - - Return the object at position *pos* in the struct sequence pointed to by *p*. - No bounds checking is performed. - - -.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos) - - Macro equivalent of :c:func:`PyStructSequence_GetItem`. - - -.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) - - Sets the field at index *pos* of the struct sequence *p* to value *o*. Like - :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new - instances. - - .. note:: - - This function "steals" a reference to *o*. - - -.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) - - Macro equivalent of :c:func:`PyStructSequence_SetItem`. +.. c:function:: int PyTuple_ClearFreeList() - .. note:: + Clear the free list. Return the total number of freed items. - This function "steals" a reference to *o*. + .. versionadded:: 2.6 |