1.. highlight:: c 2 3.. _tupleobjects: 4 5Tuple Objects 6------------- 7 8.. index:: object: tuple 9 10 11.. c:type:: PyTupleObject 12 13 This subtype of :c:type:`PyObject` represents a Python tuple object. 14 15 16.. c:var:: PyTypeObject PyTuple_Type 17 18 This instance of :c:type:`PyTypeObject` represents the Python tuple type; it 19 is the same object as :class:`tuple` in the Python layer. 20 21 22.. c:function:: int PyTuple_Check(PyObject *p) 23 24 Return true if *p* is a tuple object or an instance of a subtype of the tuple 25 type. 26 27 28.. c:function:: int PyTuple_CheckExact(PyObject *p) 29 30 Return true if *p* is a tuple object, but not an instance of a subtype of the 31 tuple type. 32 33 34.. c:function:: PyObject* PyTuple_New(Py_ssize_t len) 35 36 Return a new tuple object of size *len*, or ``NULL`` on failure. 37 38 39.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) 40 41 Return a new tuple object of size *n*, or ``NULL`` on failure. The tuple values 42 are initialized to the subsequent *n* C arguments pointing to Python objects. 43 ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. 44 45 46.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p) 47 48 Take a pointer to a tuple object, and return the size of that tuple. 49 50 51.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) 52 53 Return the size of the tuple *p*, which must be non-``NULL`` and point to a tuple; 54 no error checking is performed. 55 56 57.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) 58 59 Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is 60 out of bounds, return ``NULL`` and set an :exc:`IndexError` exception. 61 62 63.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) 64 65 Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments. 66 67 68.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) 69 70 Return the slice of the tuple pointed to by *p* between *low* and *high*, 71 or ``NULL`` on failure. This is the equivalent of the Python expression 72 ``p[low:high]``. Indexing from the end of the list is not supported. 73 74 75.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) 76 77 Insert a reference to object *o* at position *pos* of the tuple pointed to by 78 *p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1`` 79 and set an :exc:`IndexError` exception. 80 81 .. note:: 82 83 This function "steals" a reference to *o* and discards a reference to 84 an item already in the tuple at the affected position. 85 86 87.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) 88 89 Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be 90 used to fill in brand new tuples. 91 92 .. note:: 93 94 This macro "steals" a reference to *o*, and, unlike 95 :c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that 96 is being replaced; any reference in the tuple at position *pos* will be 97 leaked. 98 99 100.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) 101 102 Can be used to resize a tuple. *newsize* will be the new length of the tuple. 103 Because tuples are *supposed* to be immutable, this should only be used if there 104 is only one reference to the object. Do *not* use this if the tuple may already 105 be known to some other part of the code. The tuple will always grow or shrink 106 at the end. Think of this as destroying the old tuple and creating a new one, 107 only more efficiently. Returns ``0`` on success. Client code should never 108 assume that the resulting value of ``*p`` will be the same as before calling 109 this function. If the object referenced by ``*p`` is replaced, the original 110 ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and 111 raises :exc:`MemoryError` or :exc:`SystemError`. 112 113 114Struct Sequence Objects 115----------------------- 116 117Struct sequence objects are the C equivalent of :func:`~collections.namedtuple` 118objects, i.e. a sequence whose items can also be accessed through attributes. 119To create a struct sequence, you first have to create a specific struct sequence 120type. 121 122.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc) 123 124 Create a new struct sequence type from the data in *desc*, described below. Instances 125 of the resulting type can be created with :c:func:`PyStructSequence_New`. 126 127 128.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc) 129 130 Initializes a struct sequence type *type* from *desc* in place. 131 132 133.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc) 134 135 The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on 136 failure. 137 138 .. versionadded:: 3.4 139 140 141.. c:type:: PyStructSequence_Desc 142 143 Contains the meta information of a struct sequence type to create. 144 145 +-------------------+------------------------------+--------------------------------------+ 146 | Field | C Type | Meaning | 147 +===================+==============================+======================================+ 148 | ``name`` | ``const char *`` | name of the struct sequence type | 149 +-------------------+------------------------------+--------------------------------------+ 150 | ``doc`` | ``const char *`` | pointer to docstring for the type | 151 | | | or ``NULL`` to omit | 152 +-------------------+------------------------------+--------------------------------------+ 153 | ``fields`` | ``PyStructSequence_Field *`` | pointer to ``NULL``-terminated array | 154 | | | with field names of the new type | 155 +-------------------+------------------------------+--------------------------------------+ 156 | ``n_in_sequence`` | ``int`` | number of fields visible to the | 157 | | | Python side (if used as tuple) | 158 +-------------------+------------------------------+--------------------------------------+ 159 160 161.. c:type:: PyStructSequence_Field 162 163 Describes a field of a struct sequence. As a struct sequence is modeled as a 164 tuple, all fields are typed as :c:type:`PyObject*`. The index in the 165 :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which 166 field of the struct sequence is described. 167 168 +-----------+------------------+-----------------------------------------+ 169 | Field | C Type | Meaning | 170 +===========+==================+=========================================+ 171 | ``name`` | ``const char *`` | name for the field or ``NULL`` to end | 172 | | | the list of named fields, set to | 173 | | | :c:data:`PyStructSequence_UnnamedField` | 174 | | | to leave unnamed | 175 +-----------+------------------+-----------------------------------------+ 176 | ``doc`` | ``const char *`` | field docstring or ``NULL`` to omit | 177 +-----------+------------------+-----------------------------------------+ 178 179 180.. c:var:: const char * const PyStructSequence_UnnamedField 181 182 Special value for a field name to leave it unnamed. 183 184 .. versionchanged:: 3.9 185 The type was changed from ``char *``. 186 187 188.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type) 189 190 Creates an instance of *type*, which must have been created with 191 :c:func:`PyStructSequence_NewType`. 192 193 194.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos) 195 196 Return the object at position *pos* in the struct sequence pointed to by *p*. 197 No bounds checking is performed. 198 199 200.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos) 201 202 Macro equivalent of :c:func:`PyStructSequence_GetItem`. 203 204 205.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) 206 207 Sets the field at index *pos* of the struct sequence *p* to value *o*. Like 208 :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new 209 instances. 210 211 .. note:: 212 213 This function "steals" a reference to *o*. 214 215 216.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) 217 218 Macro equivalent of :c:func:`PyStructSequence_SetItem`. 219 220 .. note:: 221 222 This function "steals" a reference to *o*. 223