1.. highlightlang:: 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 sets 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 Take a slice of the tuple pointed to by *p* from *low* to *high* and return it 71 as a new tuple. 72 73 74.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) 75 76 Insert a reference to object *o* at position *pos* of the tuple pointed to by 77 *p*. Return ``0`` on success. 78 79 .. note:: 80 81 This function "steals" a reference to *o*. 82 83 84.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) 85 86 Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be 87 used to fill in brand new tuples. 88 89 .. note:: 90 91 This function "steals" a reference to *o*. 92 93 94.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) 95 96 Can be used to resize a tuple. *newsize* will be the new length of the tuple. 97 Because tuples are *supposed* to be immutable, this should only be used if there 98 is only one reference to the object. Do *not* use this if the tuple may already 99 be known to some other part of the code. The tuple will always grow or shrink 100 at the end. Think of this as destroying the old tuple and creating a new one, 101 only more efficiently. Returns ``0`` on success. Client code should never 102 assume that the resulting value of ``*p`` will be the same as before calling 103 this function. If the object referenced by ``*p`` is replaced, the original 104 ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and 105 raises :exc:`MemoryError` or :exc:`SystemError`. 106 107 108.. c:function:: int PyTuple_ClearFreeList() 109 110 Clear the free list. Return the total number of freed items. 111 112 113Struct Sequence Objects 114----------------------- 115 116Struct sequence objects are the C equivalent of :func:`~collections.namedtuple` 117objects, i.e. a sequence whose items can also be accessed through attributes. 118To create a struct sequence, you first have to create a specific struct sequence 119type. 120 121.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc) 122 123 Create a new struct sequence type from the data in *desc*, described below. Instances 124 of the resulting type can be created with :c:func:`PyStructSequence_New`. 125 126 127.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc) 128 129 Initializes a struct sequence type *type* from *desc* in place. 130 131 132.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc) 133 134 The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on 135 failure. 136 137 .. versionadded:: 3.4 138 139 140.. c:type:: PyStructSequence_Desc 141 142 Contains the meta information of a struct sequence type to create. 143 144 +-------------------+------------------------------+------------------------------------+ 145 | Field | C Type | Meaning | 146 +===================+==============================+====================================+ 147 | ``name`` | ``const char *`` | name of the struct sequence type | 148 +-------------------+------------------------------+------------------------------------+ 149 | ``doc`` | ``const char *`` | pointer to docstring for the type | 150 | | | or NULL to omit | 151 +-------------------+------------------------------+------------------------------------+ 152 | ``fields`` | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array | 153 | | | with field names of the new type | 154 +-------------------+------------------------------+------------------------------------+ 155 | ``n_in_sequence`` | ``int`` | number of fields visible to the | 156 | | | Python side (if used as tuple) | 157 +-------------------+------------------------------+------------------------------------+ 158 159 160.. c:type:: PyStructSequence_Field 161 162 Describes a field of a struct sequence. As a struct sequence is modeled as a 163 tuple, all fields are typed as :c:type:`PyObject\*`. The index in the 164 :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which 165 field of the struct sequence is described. 166 167 +-----------+------------------+--------------------------------------+ 168 | Field | C Type | Meaning | 169 +===========+==================+======================================+ 170 | ``name`` | ``const char *`` | name for the field or *NULL* to end | 171 | | | the list of named fields, set to | 172 | | | PyStructSequence_UnnamedField to | 173 | | | leave unnamed | 174 +-----------+------------------+--------------------------------------+ 175 | ``doc`` | ``const char *`` | field docstring or *NULL* to omit | 176 +-----------+------------------+--------------------------------------+ 177 178 179.. c:var:: char* PyStructSequence_UnnamedField 180 181 Special value for a field name to leave it unnamed. 182 183 184.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type) 185 186 Creates an instance of *type*, which must have been created with 187 :c:func:`PyStructSequence_NewType`. 188 189 190.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos) 191 192 Return the object at position *pos* in the struct sequence pointed to by *p*. 193 No bounds checking is performed. 194 195 196.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos) 197 198 Macro equivalent of :c:func:`PyStructSequence_GetItem`. 199 200 201.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) 202 203 Sets the field at index *pos* of the struct sequence *p* to value *o*. Like 204 :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new 205 instances. 206 207 .. note:: 208 209 This function "steals" a reference to *o*. 210 211 212.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) 213 214 Macro equivalent of :c:func:`PyStructSequence_SetItem`. 215 216 .. note:: 217 218 This function "steals" a reference to *o*. 219