| 1 |
.. highlight:: c |
| 2 |
|
| 3 |
.. _tupleobjects: |
| 4 |
|
| 5 |
Tuple Objects |
| 6 |
------------- |
| 7 |
|
| 8 |
.. index:: pair: 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 |
| 25 |
tuple type. This function always succeeds. |
| 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. This function always succeeds. |
| 32 |
|
| 33 |
|
| 34 |
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len) |
| 35 |
|
| 36 |
Return a new tuple object of size *len*, |
| 37 |
or ``NULL`` with an exception set on failure. |
| 38 |
|
| 39 |
|
| 40 |
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...) |
| 41 |
|
| 42 |
Return a new tuple object of size *n*, |
| 43 |
or ``NULL`` with an exception set on failure. The tuple values |
| 44 |
are initialized to the subsequent *n* C arguments pointing to Python objects. |
| 45 |
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``. |
| 46 |
|
| 47 |
|
| 48 |
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p) |
| 49 |
|
| 50 |
Take a pointer to a tuple object, and return the size of that tuple. |
| 51 |
On error, return ``-1`` with an exception set. |
| 52 |
|
| 53 |
|
| 54 |
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p) |
| 55 |
|
| 56 |
Like :c:func:`PyTuple_Size`, but without error checking. |
| 57 |
|
| 58 |
|
| 59 |
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos) |
| 60 |
|
| 61 |
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is |
| 62 |
negative or out of bounds, return ``NULL`` and set an :exc:`IndexError` exception. |
| 63 |
|
| 64 |
The returned reference is borrowed from the tuple *p* |
| 65 |
(that is: it is only valid as long as you hold a reference to *p*). |
| 66 |
To get a :term:`strong reference`, use |
| 67 |
:c:func:`Py_NewRef(PyTuple_GetItem(...)) <Py_NewRef>` |
| 68 |
or :c:func:`PySequence_GetItem`. |
| 69 |
|
| 70 |
|
| 71 |
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) |
| 72 |
|
| 73 |
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments. |
| 74 |
|
| 75 |
|
| 76 |
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high) |
| 77 |
|
| 78 |
Return the slice of the tuple pointed to by *p* between *low* and *high*, |
| 79 |
or ``NULL`` with an exception set on failure. |
| 80 |
|
| 81 |
This is the equivalent of the Python expression ``p[low:high]``. |
| 82 |
Indexing from the end of the tuple is not supported. |
| 83 |
|
| 84 |
|
| 85 |
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) |
| 86 |
|
| 87 |
Insert a reference to object *o* at position *pos* of the tuple pointed to by |
| 88 |
*p*. Return ``0`` on success. If *pos* is out of bounds, return ``-1`` |
| 89 |
and set an :exc:`IndexError` exception. |
| 90 |
|
| 91 |
.. note:: |
| 92 |
|
| 93 |
This function "steals" a reference to *o* and discards a reference to |
| 94 |
an item already in the tuple at the affected position. |
| 95 |
|
| 96 |
|
| 97 |
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o) |
| 98 |
|
| 99 |
Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be |
| 100 |
used to fill in brand new tuples. |
| 101 |
|
| 102 |
Bounds checking is performed as an assertion if Python is built in |
| 103 |
:ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`. |
| 104 |
|
| 105 |
.. note:: |
| 106 |
|
| 107 |
This function "steals" a reference to *o*, and, unlike |
| 108 |
:c:func:`PyTuple_SetItem`, does *not* discard a reference to any item that |
| 109 |
is being replaced; any reference in the tuple at position *pos* will be |
| 110 |
leaked. |
| 111 |
|
| 112 |
.. warning:: |
| 113 |
|
| 114 |
This macro should *only* be used on tuples that are newly created. |
| 115 |
Using this macro on a tuple that is already in use (or in other words, has |
| 116 |
a refcount > 1) could lead to undefined behavior. |
| 117 |
|
| 118 |
|
| 119 |
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize) |
| 120 |
|
| 121 |
Can be used to resize a tuple. *newsize* will be the new length of the tuple. |
| 122 |
Because tuples are *supposed* to be immutable, this should only be used if there |
| 123 |
is only one reference to the object. Do *not* use this if the tuple may already |
| 124 |
be known to some other part of the code. The tuple will always grow or shrink |
| 125 |
at the end. Think of this as destroying the old tuple and creating a new one, |
| 126 |
only more efficiently. Returns ``0`` on success. Client code should never |
| 127 |
assume that the resulting value of ``*p`` will be the same as before calling |
| 128 |
this function. If the object referenced by ``*p`` is replaced, the original |
| 129 |
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to ``NULL``, and |
| 130 |
raises :exc:`MemoryError` or :exc:`SystemError`. |
| 131 |
|
| 132 |
|
| 133 |
.. _struct-sequence-objects: |
| 134 |
|
| 135 |
Struct Sequence Objects |
| 136 |
----------------------- |
| 137 |
|
| 138 |
Struct sequence objects are the C equivalent of :func:`~collections.namedtuple` |
| 139 |
objects, i.e. a sequence whose items can also be accessed through attributes. |
| 140 |
To create a struct sequence, you first have to create a specific struct sequence |
| 141 |
type. |
| 142 |
|
| 143 |
.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc) |
| 144 |
|
| 145 |
Create a new struct sequence type from the data in *desc*, described below. Instances |
| 146 |
of the resulting type can be created with :c:func:`PyStructSequence_New`. |
| 147 |
|
| 148 |
Return ``NULL`` with an exception set on failure. |
| 149 |
|
| 150 |
|
| 151 |
.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc) |
| 152 |
|
| 153 |
Initializes a struct sequence type *type* from *desc* in place. |
| 154 |
|
| 155 |
|
| 156 |
.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc) |
| 157 |
|
| 158 |
Like :c:func:`PyStructSequence_InitType`, but returns ``0`` on success |
| 159 |
and ``-1`` with an exception set on failure. |
| 160 |
|
| 161 |
.. versionadded:: 3.4 |
| 162 |
|
| 163 |
|
| 164 |
.. c:type:: PyStructSequence_Desc |
| 165 |
|
| 166 |
Contains the meta information of a struct sequence type to create. |
| 167 |
|
| 168 |
.. c:member:: const char *name |
| 169 |
|
| 170 |
Fully qualified name of the type; null-terminated UTF-8 encoded. |
| 171 |
The name must contain the module name. |
| 172 |
|
| 173 |
.. c:member:: const char *doc |
| 174 |
|
| 175 |
Pointer to docstring for the type or ``NULL`` to omit. |
| 176 |
|
| 177 |
.. c:member:: PyStructSequence_Field *fields |
| 178 |
|
| 179 |
Pointer to ``NULL``-terminated array with field names of the new type. |
| 180 |
|
| 181 |
.. c:member:: int n_in_sequence |
| 182 |
|
| 183 |
Number of fields visible to the Python side (if used as tuple). |
| 184 |
|
| 185 |
|
| 186 |
.. c:type:: PyStructSequence_Field |
| 187 |
|
| 188 |
Describes a field of a struct sequence. As a struct sequence is modeled as a |
| 189 |
tuple, all fields are typed as :c:expr:`PyObject*`. The index in the |
| 190 |
:c:member:`~PyStructSequence_Desc.fields` array of |
| 191 |
the :c:type:`PyStructSequence_Desc` determines which |
| 192 |
field of the struct sequence is described. |
| 193 |
|
| 194 |
.. c:member:: const char *name |
| 195 |
|
| 196 |
Name for the field or ``NULL`` to end the list of named fields, |
| 197 |
set to :c:data:`PyStructSequence_UnnamedField` to leave unnamed. |
| 198 |
|
| 199 |
.. c:member:: const char *doc |
| 200 |
|
| 201 |
Field docstring or ``NULL`` to omit. |
| 202 |
|
| 203 |
|
| 204 |
.. c:var:: const char * const PyStructSequence_UnnamedField |
| 205 |
|
| 206 |
Special value for a field name to leave it unnamed. |
| 207 |
|
| 208 |
.. versionchanged:: 3.9 |
| 209 |
The type was changed from ``char *``. |
| 210 |
|
| 211 |
|
| 212 |
.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type) |
| 213 |
|
| 214 |
Creates an instance of *type*, which must have been created with |
| 215 |
:c:func:`PyStructSequence_NewType`. |
| 216 |
|
| 217 |
Return ``NULL`` with an exception set on failure. |
| 218 |
|
| 219 |
|
| 220 |
.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos) |
| 221 |
|
| 222 |
Return the object at position *pos* in the struct sequence pointed to by *p*. |
| 223 |
|
| 224 |
Bounds checking is performed as an assertion if Python is built in |
| 225 |
:ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`. |
| 226 |
|
| 227 |
|
| 228 |
.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos) |
| 229 |
|
| 230 |
Alias to :c:func:`PyStructSequence_GetItem`. |
| 231 |
|
| 232 |
.. versionchanged:: 3.13 |
| 233 |
Now implemented as an alias to :c:func:`PyStructSequence_GetItem`. |
| 234 |
|
| 235 |
|
| 236 |
.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o) |
| 237 |
|
| 238 |
Sets the field at index *pos* of the struct sequence *p* to value *o*. Like |
| 239 |
:c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new |
| 240 |
instances. |
| 241 |
|
| 242 |
Bounds checking is performed as an assertion if Python is built in |
| 243 |
:ref:`debug mode <debug-build>` or :option:`with assertions <--with-assertions>`. |
| 244 |
|
| 245 |
.. note:: |
| 246 |
|
| 247 |
This function "steals" a reference to *o*. |
| 248 |
|
| 249 |
|
| 250 |
.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o) |
| 251 |
|
| 252 |
Alias to :c:func:`PyStructSequence_SetItem`. |
| 253 |
|
| 254 |
.. versionchanged:: 3.13 |
| 255 |
Now implemented as an alias to :c:func:`PyStructSequence_SetItem`. |