8 .. index:: object: tuple
11 .. ctype:: PyTupleObject
13 This subtype of :ctype:`PyObject` represents a Python tuple object.
16 .. cvar:: PyTypeObject PyTuple_Type
18 .. index:: single: TupleType (in module types)
20 This instance of :ctype:`PyTypeObject` represents the Python tuple type; it is
21 the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
24 .. cfunction:: int PyTuple_Check(PyObject *p)
26 Return true if *p* is a tuple object or an instance of a subtype of the tuple
29 .. versionchanged:: 2.2
30 Allowed subtypes to be accepted.
33 .. cfunction:: int PyTuple_CheckExact(PyObject *p)
35 Return true if *p* is a tuple object, but not an instance of a subtype of the
41 .. cfunction:: PyObject* PyTuple_New(Py_ssize_t len)
43 Return a new tuple object of size *len*, or *NULL* on failure.
45 .. versionchanged:: 2.5
46 This function used an :ctype:`int` type for *len*. This might require
47 changes in your code for properly supporting 64-bit systems.
50 .. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
52 Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
53 are initialized to the subsequent *n* C arguments pointing to Python objects.
54 ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
58 .. versionchanged:: 2.5
59 This function used an :ctype:`int` type for *n*. This might require
60 changes in your code for properly supporting 64-bit systems.
63 .. cfunction:: Py_ssize_t PyTuple_Size(PyObject *p)
65 Take a pointer to a tuple object, and return the size of that tuple.
67 .. versionchanged:: 2.5
68 This function returned an :ctype:`int` type. This might require changes
69 in your code for properly supporting 64-bit systems.
72 .. cfunction:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
74 Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
75 no error checking is performed.
77 .. versionchanged:: 2.5
78 This function returned an :ctype:`int` type. This might require changes
79 in your code for properly supporting 64-bit systems.
82 .. cfunction:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
84 Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
85 out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
87 .. versionchanged:: 2.5
88 This function used an :ctype:`int` type for *pos*. This might require
89 changes in your code for properly supporting 64-bit systems.
92 .. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
94 Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
96 .. versionchanged:: 2.5
97 This function used an :ctype:`int` type for *pos*. This might require
98 changes in your code for properly supporting 64-bit systems.
101 .. cfunction:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
103 Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
106 .. versionchanged:: 2.5
107 This function used an :ctype:`int` type for *low* and *high*. This might
108 require changes in your code for properly supporting 64-bit systems.
111 .. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
113 Insert a reference to object *o* at position *pos* of the tuple pointed to by
114 *p*. Return ``0`` on success.
118 This function "steals" a reference to *o*.
120 .. versionchanged:: 2.5
121 This function used an :ctype:`int` type for *pos*. This might require
122 changes in your code for properly supporting 64-bit systems.
125 .. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
127 Like :cfunc:`PyTuple_SetItem`, but does no error checking, and should *only* be
128 used to fill in brand new tuples.
132 This function "steals" a reference to *o*.
134 .. versionchanged:: 2.5
135 This function used an :ctype:`int` type for *pos*. This might require
136 changes in your code for properly supporting 64-bit systems.
139 .. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
141 Can be used to resize a tuple. *newsize* will be the new length of the tuple.
142 Because tuples are *supposed* to be immutable, this should only be used if there
143 is only one reference to the object. Do *not* use this if the tuple may already
144 be known to some other part of the code. The tuple will always grow or shrink
145 at the end. Think of this as destroying the old tuple and creating a new one,
146 only more efficiently. Returns ``0`` on success. Client code should never
147 assume that the resulting value of ``*p`` will be the same as before calling
148 this function. If the object referenced by ``*p`` is replaced, the original
149 ``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
150 raises :exc:`MemoryError` or :exc:`SystemError`.
152 .. versionchanged:: 2.2
153 Removed unused third parameter, *last_is_sticky*.
155 .. versionchanged:: 2.5
156 This function used an :ctype:`int` type for *newsize*. This might
157 require changes in your code for properly supporting 64-bit systems.
160 .. cfunction:: int PyTuple_ClearFreeList(void)
162 Clear the free list. Return the total number of freed items.
164 .. versionadded:: 2.6