List Objects¶

typePyListObject¶

This subtype ofPyObject represents a Python list object.

PyTypeObjectPyList_Type¶

Part of theStable ABI.

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

intPyList_Check(PyObject*p)¶

Thread safety:Atomic.

Return true ifp is a list object or an instance of a subtype of the listtype. This function always succeeds.

intPyList_CheckExact(PyObject*p)¶

Thread safety:Atomic.

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

PyObject*PyList_New(Py_ssize_tlen)¶

Return value: New reference. Part of theStable ABI.Thread safety:Atomic.

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() orPyList_SET_ITEM(). The following APIs are safe APIs beforethe list is fully initialized:PyList_SetItem() andPyList_SET_ITEM().

Py_ssize_tPyList_Size(PyObject*list)¶

Part of theStable ABI.Thread safety:Atomic.

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

Py_ssize_tPyList_GET_SIZE(PyObject*list)¶

Thread safety:Atomic.

Similar toPyList_Size(), but without error checking.

PyObject*PyList_GetItemRef(PyObject*list,Py_ssize_tindex)¶

Return value: New reference. Part of theStable ABI since version 3.13.Thread safety:Atomic.

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 (<0or>=len(list)),returnNULL and set anIndexError exception.

Added in version 3.13.

PyObject*PyList_GetItem(PyObject*list,Py_ssize_tindex)¶

Return value: Borrowed reference. Part of theStable ABI.Thread safety:Safe to call from multiple threads with external synchronization only.

LikePyList_GetItemRef(), but returns aborrowed reference instead of astrong reference.

Note

In thefree-threaded build, the returnedborrowed reference may become invalid if another thread modifiesthe list concurrently. PreferPyList_GetItemRef(), which returnsastrong reference.

PyObject*PyList_GET_ITEM(PyObject*list,Py_ssize_ti)¶

Return value: Borrowed reference.Thread safety:Safe to call from multiple threads with external synchronization only.

Similar toPyList_GetItem(), but without error checking.

Note

In thefree-threaded build, the returnedborrowed reference may become invalid if another thread modifiesthe list concurrently. PreferPyList_GetItemRef(), which returnsastrong reference.

intPyList_SetItem(PyObject*list,Py_ssize_tindex,PyObject*item)¶

Part of theStable ABI.Thread safety:Atomic.

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.

voidPyList_SET_ITEM(PyObject*list,Py_ssize_ti,PyObject*o)¶

Thread safety:Safe to call from multiple threads with external synchronization only.

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

Bounds checking is performed as an assertion if Python is built indebug mode orwithassertions.

Note

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

Note

In thefree-threaded build, this macro has no internalsynchronization. It is normally only used to fill in new lists where noother thread has a reference to the list. If the list may be shared,usePyList_SetItem() instead, which uses aper-objectlock.

intPyList_Insert(PyObject*list,Py_ssize_tindex,PyObject*item)¶

Part of theStable ABI.Thread safety:Safe for concurrent use on the same object.

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

intPyList_Append(PyObject*list,PyObject*item)¶

Part of theStable ABI.Thread safety:Atomic.

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_tlow,Py_ssize_thigh)¶

Return value: New reference. Part of theStable ABI.Thread safety:Atomic.

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.

intPyList_SetSlice(PyObject*list,Py_ssize_tlow,Py_ssize_thigh,PyObject*itemlist)¶

Part of theStable ABI.Thread safety:Safe for concurrent use on the same object.

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.

Note

In thefree-threaded build, whenitemlist is alist,bothlist anditemlist are locked for the duration of the operation.For other iterables (orNULL), onlylist is locked.

intPyList_Extend(PyObject*list,PyObject*iterable)¶

Thread safety:Safe for concurrent use on the same object.

Extendlist with the contents ofiterable. This is the same asPyList_SetSlice(list,PY_SSIZE_T_MAX,PY_SSIZE_T_MAX,iterable)and analogous tolist.extend(iterable) orlist+=iterable.

Raise an exception and return-1 iflist is not alistobject. Return 0 on success.

Added in version 3.13.

Note

In thefree-threaded build, wheniterable is alist,set,dict, or dict view, bothlist anditerable(or its underlying dict) are locked for the duration of the operation.For other iterables, onlylist is locked;iterable may beconcurrently modified by another thread.

intPyList_Clear(PyObject*list)¶

Thread safety:Atomic.

Remove all items fromlist. This is the same asPyList_SetSlice(list,0,PY_SSIZE_T_MAX,NULL) and analogous tolist.clear() ordellist[:].

Raise an exception and return-1 iflist is not alistobject. Return 0 on success.

Added in version 3.13.

intPyList_Sort(PyObject*list)¶

Part of theStable ABI.Thread safety:Safe for concurrent use on the same object.

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

Note

In thefree-threaded build, element comparison via__lt__() can execute arbitrary Python code, during whichtheper-object lock may be temporarily released. For built-intypes (str,int,float), the lock is notreleased during comparison.

intPyList_Reverse(PyObject*list)¶

Part of theStable ABI.Thread safety:Safe for concurrent use on the same object.

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. Part of theStable ABI.Thread safety:Atomic.

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