Tuple Objects¶

PyTupleObject¶

This subtype ofPyObject represents a Python tuple object.

PyTypeObjectPyTuple_Type¶

This instance ofPyTypeObject represents the Python tuple type; itis the same object astuple in the Python layer.

intPyTuple_Check(PyObject *p)¶

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

intPyTuple_CheckExact(PyObject *p)¶

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

PyObject*PyTuple_New(Py_ssize_t len)¶

Return value: New reference.

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

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).

Py_ssize_tPyTuple_Size(PyObject *p)¶

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

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.

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.

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

Return value: Borrowed reference.

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

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.

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.

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.

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.

intPyTuple_ClearFreeList()¶

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

Struct Sequence Objects¶

Struct sequence objects are the C equivalent ofnamedtuple()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 sequencetype.

PyTypeObject*PyStructSequence_NewType(PyStructSequence_Desc *desc)¶

Return value: New reference.

Create a new struct sequence type from the data indesc, described below. Instancesof the resulting type can be created withPyStructSequence_New().

voidPyStructSequence_InitType(PyTypeObject *type,PyStructSequence_Desc *desc)¶

Initializes a struct sequence typetype fromdesc in place.

intPyStructSequence_InitType2(PyTypeObject *type,PyStructSequence_Desc *desc)¶

The same asPyStructSequence_InitType, but returns0 on success and-1 onfailure.

New in version 3.4.

PyStructSequence_Desc¶

Contains the meta information of a struct sequence type to create.

Field	C Type	Meaning
name	constchar*	name of the struct sequence type
doc	constchar*	pointer to docstring for the typeorNULL to omit
fields	PyStructSequence_Field*	pointer toNULL-terminated arraywith field names of the new type
n_in_sequence	int	number of fields visible to thePython side (if used as tuple)

PyStructSequence_Field¶

Describes a field of a struct sequence. As a struct sequence is modeled as atuple, all fields are typed asPyObject*. The index in thefields array of thePyStructSequence_Desc determines whichfield of the struct sequence is described.

Field	C Type	Meaning
name	constchar*	name for the field orNULL to endthe list of named fields, set toPyStructSequence_UnnamedFieldto leave unnamed
doc	constchar*	field docstring orNULL to omit

char*PyStructSequence_UnnamedField¶

Special value for a field name to leave it unnamed.

PyObject*PyStructSequence_New(PyTypeObject *type)¶

Return value: New reference.

Creates an instance oftype, which must have been created withPyStructSequence_NewType().

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

Return value: Borrowed reference.

Return the object at positionpos in the struct sequence pointed to byp.No bounds checking is performed.

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

Return value: Borrowed reference.

Macro equivalent ofPyStructSequence_GetItem().

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

Sets the field at indexpos of the struct sequencep to valueo. LikePyTuple_SET_ITEM(), this should only be used to fill in brand newinstances.

Note

This function “steals” a reference too.

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

Macro equivalent ofPyStructSequence_SetItem().

Note

This function “steals” a reference too.