Tuple Objects¶

PyTupleObject¶

This subtype ofPyObject represents a Python tuple object.

PyTypeObjectPyTuple_Type¶

This instance ofPyTypeObject represents the Python tuple type; it isthe same object astuple andtypes.TupleType in the Python layer..

intPyTuple_Check(PyObject *p)¶

Return true ifp is a tuple object or an instance of a subtype of the tupletype.

Changed in version 2.2:Allowed subtypes to be accepted.

intPyTuple_CheckExact(PyObject *p)¶

Return true ifp is a tuple object, but not an instance of a subtype of thetuple type.

New in version 2.2.

PyObject*PyTuple_New(Py_ssize_t len)¶

Return value: New reference.

Return a new tuple object of sizelen, orNULL on failure.

Changed in version 2.5:This function used anint type forlen. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyTuple_Pack(Py_ssize_t n, ...)¶

Return value: New reference.

Return a new tuple object of sizen, orNULL on failure. The tuple valuesare initialized to the subsequentn C arguments pointing to Python objects.PyTuple_Pack(2,a,b) is equivalent toPy_BuildValue("(OO)",a,b).

New in version 2.4.

Changed in version 2.5:This function used anint type forn. This might requirechanges in your code for properly supporting 64-bit systems.

Py_ssize_tPyTuple_Size(PyObject *p)¶

Take a pointer to a tuple object, and return the size of that tuple.

Changed in version 2.5:This function returned anint type. This might require changesin your code for properly supporting 64-bit systems.

Py_ssize_tPyTuple_GET_SIZE(PyObject *p)¶

Return the size of the tuplep, which must be non-NULL and point to a tuple;no error checking is performed.

Changed in version 2.5:This function returned anint type. This might require changesin your code for properly supporting 64-bit systems.

PyObject*PyTuple_GetItem(PyObject *p, Py_ssize_t pos)¶

Return value: Borrowed reference.

Return the object at positionpos in the tuple pointed to byp. Ifpos isout of bounds, returnNULL and set anIndexError exception.

Changed in version 2.5:This function used anint type forpos. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)¶

Return value: Borrowed reference.

LikePyTuple_GetItem(), but does no checking of its arguments.

Changed in version 2.5:This function used anint type forpos. This might requirechanges in your code for properly supporting 64-bit systems.

PyObject*PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)¶

Return value: New reference.

Return the slice of the tuple pointed to byp betweenlow andhigh,orNULL on failure. This is the equivalent of the Python expressionp[low:high]. Indexing from the end of the list is not supported.

Changed in version 2.5:This function used anint type forlow andhigh. This mightrequire changes in your code for properly supporting 64-bit systems.

intPyTuple_SetItem(PyObject *p, Py_ssize_t pos,PyObject *o)¶

Insert a reference to objecto at positionpos of the tuple pointed to byp. Return0 on success. Ifpos is out of bounds, return-1and set anIndexError exception.

Note

This function “steals” a reference too and discards a reference toan item already in the tuple at the affected position.

Changed in version 2.5:This function used anint type forpos. This might requirechanges in your code for properly supporting 64-bit systems.

voidPyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos,PyObject *o)¶

LikePyTuple_SetItem(), but does no error checking, and shouldonly beused to fill in brand new tuples.

Note

This macro “steals” a reference too, and, unlikePyTuple_SetItem(), doesnot discard a reference to any item thatis being replaced; any reference in the tuple at positionpos will beleaked.

Changed in version 2.5:This function used anint type forpos. This might requirechanges in your code for properly supporting 64-bit systems.

int_PyTuple_Resize(PyObject **p, Py_ssize_t newsize)¶

Can be used to resize a tuple.newsize will be the new length of the tuple.Because tuples aresupposed to be immutable, this should only be used if thereis only one reference to the object. Donot use this if the tuple may alreadybe known to some other part of the code. The tuple will always grow or shrinkat the end. Think of this as destroying the old tuple and creating a new one,only more efficiently. Returns0 on success. Client code should neverassume that the resulting value of*p will be the same as before callingthis function. If the object referenced by*p is replaced, the original*p is destroyed. On failure, returns-1 and sets*p toNULL, andraisesMemoryError orSystemError.

Changed in version 2.2:Removed unused third parameter,last_is_sticky.

Changed in version 2.5:This function used anint type fornewsize. This mightrequire changes in your code for properly supporting 64-bit systems.

intPyTuple_ClearFreeList()¶

Clear the free list. Return the total number of freed items.

New in version 2.6.