List Objects¶

PyListObject¶

This subtype ofPyObject represents a Python list object.

PyTypeObjectPyList_Type¶

This instance ofPyTypeObject represents the Python list type. Thisis the same object aslist in the Python layer.

intPyList_Check(PyObject *p)¶

Return true ifp is a list object or an instance of a subtype of the listtype.

Changed in version 2.2:Allowed subtypes to be accepted.

intPyList_CheckExact(PyObject *p)¶

Return true ifp is a list object, but not an instance of a subtype ofthe list type.

New in version 2.2.

PyObject*PyList_New(Py_ssize_t len)¶

Return value: New reference.

Return a new list of lengthlen on success, orNULL on failure.

Note

Iflen is greater than zero, the returned list object’s items areset toNULL. Thus you cannot use abstract API functions such asPySequence_SetItem() or expose the object to Python code beforesetting all items to a real object withPyList_SetItem().

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

Py_ssize_tPyList_Size(PyObject *list)¶

Return the length of the list object inlist; this is equivalent tolen(list) on a list object.

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

Py_ssize_tPyList_GET_SIZE(PyObject *list)¶

Macro form ofPyList_Size() without error checking.

Changed in version 2.5:This macro returned anint. This might require changes in yourcode for properly supporting 64-bit systems.

PyObject*PyList_GetItem(PyObject *list, Py_ssize_t index)¶

Return value: Borrowed reference.

Return the object at positionindex in the list pointed to bylist. Theposition must be non-negative; indexing from the end of the list is notsupported. Ifindex is out of bounds (<0 or >=len(list)),returnNULL and set anIndexError exception.

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

PyObject*PyList_GET_ITEM(PyObject *list, Py_ssize_t i)¶

Return value: Borrowed reference.

Macro form ofPyList_GetItem() without error checking.

Changed in version 2.5:This macro used anint fori. This might require changes inyour code for properly supporting 64-bit systems.

intPyList_SetItem(PyObject *list, Py_ssize_t index,PyObject *item)¶

Set the item at indexindex in list toitem. Return0 on success.Ifindex is out of bounds, return-1 and set anIndexErrorexception.

Note

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

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

voidPyList_SET_ITEM(PyObject *list, Py_ssize_t i,PyObject *o)¶

Macro form ofPyList_SetItem() without error checking. This isnormally only used to fill in new lists where there is no previous content.

Note

This macro “steals” a reference toitem, and, unlikePyList_SetItem(), doesnot discard a reference to any item thatit being replaced; any reference inlist at positioni will beleaked.

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

intPyList_Insert(PyObject *list, Py_ssize_t index,PyObject *item)¶

Insert the itemitem into listlist in front of indexindex. Return0 if successful; return-1 and set an exception if unsuccessful.Analogous tolist.insert(index,item).

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

intPyList_Append(PyObject *list,PyObject *item)¶

Append the objectitem at the end of listlist. Return0 ifsuccessful; return-1 and set an exception if unsuccessful. Analogoustolist.append(item).

PyObject*PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)¶

Return value: New reference.

Return a list of the objects inlist containing the objectsbetweenlowandhigh. ReturnNULL and set an exception if unsuccessful. Analogoustolist[low:high]. Indexing from the end of the list is not supported.

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

intPyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high,PyObject *itemlist)¶

Set the slice oflist betweenlow andhigh to the contents ofitemlist. Analogous tolist[low:high]=itemlist. Theitemlist maybeNULL, indicating the assignment of an empty list (slice deletion).Return0 on success,-1 on failure. Indexing from the end of thelist is not supported.

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

intPyList_Sort(PyObject *list)¶

Sort the items oflist in place. Return0 on success,-1 onfailure. This is equivalent tolist.sort().

intPyList_Reverse(PyObject *list)¶

Reverse the items oflist in place. Return0 on success,-1 onfailure. This is the equivalent oflist.reverse().

PyObject*PyList_AsTuple(PyObject *list)¶

Return value: New reference.

Return a new tuple object containing the contents oflist; equivalent totuple(list).