列表对象¶
-
PyTypeObject PyList_Type¶
- 属于 稳定 ABI.
这是个属于
PyTypeObject的代表 Python 列表类型的实例。在 Python 层面和类型list是同一个对象。
-
int PyList_Check(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一个 list 对象或者 list 类型的子类型的实例则返回真值。此函数总是会成功执行。
-
int PyList_CheckExact(PyObject *p)¶
- Thread safety: Atomic.
如果 p 是一个 list 对象但不是 list 类型的子类型的实例则返回真值。此函数总是会成功执行。
-
PyObject *PyList_New(Py_ssize_t len)¶
- 返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.
成功时返回一个长度为 len 的新列表，失败时返回
NULL。备注
当 len 大于零时，被返回的列表对象的条目将被设为
NULL。因此你不能使用抽象 API 函数如PySequence_SetItem()或者在使用PyList_SetItem()或PyList_SET_ITEM()将所有条目设为真实对象之前将对象暴露给 Python 代码。以下 API 在该列表完全初始化之前将是安全的 API:PyList_SetItem()和PyList_SET_ITEM()宏。
-
Py_ssize_t PyList_Size(PyObject *list)¶
- 属于 稳定 ABI. Thread safety: Atomic.
返回 list 中列表对象的长度；这等于在列表对象调用
len(list)。
-
Py_ssize_t PyList_GET_SIZE(PyObject *list)¶
- Thread safety: Atomic.
类似于
PyList_Size()，但是不带错误检测。
-
PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)¶
- 返回值：新的引用。 属于 稳定 ABI 自 3.13 版起. Thread safety: Atomic.
返回 list 所指向的列表中 index 位置上的对象。位置值必须为非负数；不支持从列表末尾反向索引。如果 index 超出范围 (
<0 or >=len(list))，则返回NULL并设置IndexError异常。在 3.13 版本加入.
-
PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)¶
- 返回值：借入的引用。 属于 稳定 ABI. Thread safety: Safe to call from multiple threads with external synchronization only.
类似于
PyList_GetItemRef()，但返回一个 borrowed reference 而不是 strong reference 引用。备注
在 free-threaded build 中，如果另一个线程同时修改该列表，则返回的 borrowed reference 可能会变得无效。建议采用
PyList_GetItemRef()，它会返回一个 strong reference。
-
PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)¶
- 返回值：借入的引用。 Thread safety: Safe to call from multiple threads with external synchronization only.
类似于
PyList_GetItem()，但是不带错误检测。备注
在 free-threaded build 中，如果另一个线程同时修改该列表，则返回的 borrowed reference 可能会变得无效。建议采用
PyList_GetItemRef()，它会返回一个 strong reference。
-
int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)¶
- 属于 稳定 ABI. Thread safety: Atomic.
将列表中索引为 index 的项设为 item。成功时返回
0。如果 index 超出范围则返回-1并设定IndexError异常。备注
此函数即使在出错时也会 "偷取" 一个对 item 的引用。 成功时，它会丢弃在受影响位置已存在于列表中的项的引用（除非该项为
NULL）。
-
void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)¶
- Thread safety: Safe to call from multiple threads with external synchronization only.
PyList_SetItem()的不带错误检测的宏版本。这通常只被用于填充之前没有内容的新列表。当 Python 以 调试模式 或
启用断言构建时将把边界检测作为断言来执行。备注
此宏会 "偷取" 对 item 的引用，并且不同于
PyList_SetItem()，它并不会丢弃被替换项的引用；在 list 中位置 i 处的任何引用都将被泄漏。备注
在 free-threaded build 中，该宏不具备内部同步机制。通常仅用于在没有任何其他线程对该列表持有引用的情况下填充新列表。如果该列表可能被共享，则应改用
PyList_SetItem()；后者会使用 per-object lock。
-
int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
将条目 item 插入到列表 list 索引号 index 之前的位置。如果成功将返回
0；如果不成功则返回-1并设置一个异常。相当于list.insert(index, item)。
-
int PyList_Append(PyObject *list, PyObject *item)¶
- 属于 稳定 ABI. Thread safety: Atomic.
将对象 item 添加到列表 list 的末尾。如果成功将返回
0；如果不成功则返回-1并设置一个异常。相当于list.append(item)。
-
PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)¶
- 返回值：新的引用。 属于 稳定 ABI. Thread safety: Atomic.
返回一个对象列表，包含 list 当中位于 low 和 high 之间 的对象。如果不成功则返回
NULL并设置异常。相当于list[low:high]。不支持从列表末尾进行索引。
-
int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
将 list 当中 low 与 high 之间的切片设为 itemlist 的内容。相当于
list[low:high] = itemlist。itemlist 可以为NULL，表示赋值为一个空列表（删除切片）。成功时返回0，失败时返回-1。这里不支持从列表末尾进行索引。备注
在 free-threaded build 中，当 itemlist 为
list时，list 和 itemlist 在整个操作期间均被锁定；对于其他可迭代对象（或NULL），则仅 list 被锁定。
-
int PyList_Extend(PyObject *list, PyObject *iterable)¶
- Thread safety: Safe for concurrent use on the same object.
使用 iterable 的内容扩展 list。这与
PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)相同并与list.extend(iterable)或list += iterable类似。如果 list 不是
list对象则会引发异常并返回-1。成功时返回 0。在 3.13 版本加入.
备注
在 free-threaded build 中，当 iterable 为
list、set、dict或 dict view 时，list 和 iterable*（或其底层 dict）在整个操作期间均处于锁定状态。对于其他可迭代对象，仅 *list 处于锁定状态；iterable 可被其他线程同时修改。
-
int PyList_Clear(PyObject *list)¶
- Thread safety: Atomic.
从 list 移除所有条目。这与
PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)相同并与list.clear()或del list[:]类似。如果 list 不是
list对象则会引发异常并返回-1。成功时返回 0。在 3.13 版本加入.
-
int PyList_Sort(PyObject *list)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
对 list 中的条目进行原地排序。成功时返回
0，失败时返回-1。这等价于list.sort()。备注
在 free-threaded build 中，通过
__lt__()进行的元素比较可以执行任意 Python 代码；在此过程中，per-object lock 可能会暂时被释放。对于内置类型（str、int、float），比较期间不会释放锁。
-
int PyList_Reverse(PyObject *list)¶
- 属于 稳定 ABI. Thread safety: Safe for concurrent use on the same object.
对 list 中的条目进行原地反转。成功时返回
0，失败时返回-1。这等价于list.reverse()。