Объекты списков¶List Objects

type PyListObject¶: Этот подтип PyObject представляет объект списка Python.

PyTypeObject PyList_Type¶: Часть Stable ABI.
Этот экземпляр PyTypeObject представляет тип списка Python. Это тот же объект, что и list в слое Python.

int PyList_Check(PyObject *p)¶: Потокобезопасность: атомарно.
Возвращает true, если p является объектом списка или экземпляром подтипа типа списка. Эта функция всегда завершается успешно.

int PyList_CheckExact(PyObject *p)¶: Потокобезопасность: атомарно.
Возвращает true, если p является объектом списка, но не экземпляром подтипа типа списка. Эта функция всегда завершается успешно.

PyObject *PyList_New(Py_ssize_t len)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.
Возвращает новый список длины len в случае успеха или NULL в случае ошибки.

Примечание

Если len больше нуля, элементы возвращаемого объекта списка устанавливаются в NULL. Поэтому нельзя использовать абстрактные функции API, такие как PySequence_SetItem(), или предоставлять объект коду Python до установки всех элементов в реальный объект с помощью PyList_SetItem() или PyList_SET_ITEM(). Следующие API безопасны до полной инициализации списка: PyList_SetItem() и PyList_SET_ITEM().

Py_ssize_t PyList_Size(PyObject *list)¶: Часть Stable ABI.Потокобезопасность: Атомарно.
Возвращает длину объекта списка в list; это эквивалентно len(list) для объекта списка.

Py_ssize_t PyList_GET_SIZE(PyObject *list)¶: Потокобезопасность: атомарно.
Аналогично PyList_Size(), но без проверки ошибок.

PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI начиная с версии 3.13. Потокобезопасность: атомарно.
Возвращает объект на позиции index в списке, на который указывает list. Позиция должна быть неотрицательной; индексация от конца списка не поддерживается. Если index выходит за границы (<0 or >=len(list)), возвращается NULL и устанавливается исключение IndexError.

Добавлено в версии 3.13.

PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)¶: Возвращаемое значение: заимствованная ссылка. Часть стабильного ABI. Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Как PyList_GetItemRef(), но возвращает заимствованную ссылку вместо сильной ссылки.

Примечание

В сборке со свободными потоками возвращаемая заимствованная ссылка может стать недействительной, если другой поток изменяет список конкурентно. Предпочтительнее PyList_GetItemRef(), которая возвращает сильную ссылку.

PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)¶: Возвращаемое значение: заимствованная ссылка. Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Аналогично PyList_GetItem(), но без проверки ошибок.

Примечание

В сборке со свободными потоками возвращаемая заимствованная ссылка может стать недействительной, если другой поток изменяет список конкурентно. Предпочтительнее PyList_GetItemRef(), которая возвращает сильную ссылку.

int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)¶: Часть Stable ABI.Потокобезопасность: Атомарно.
Устанавливает элемент на индексе index в списке в значение item. Возвращает 0 в случае успеха. Если index выходит за границы, возвращает -1 и устанавливает исключение IndexError.

Примечание

Эта функция «крадёт» ссылку на item, даже в случае ошибки. В случае успеха она отбрасывает ссылку на элемент, уже находящийся в списке на соответствующей позиции (если только это не NULL).

void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)¶

Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.

Макро-форма PyList_SetItem() без проверки ошибок. Обычно используется только для заполнения новых списков, где нет предыдущего содержимого.

Проверка границ выполняется как утверждение, если Python собран в режиме отладки или with assertions.

Примечание

Этот макрос «крадёт» ссылку на item и, в отличие от PyList_SetItem(), не отбрасывает ссылку на любой элемент, который заменяется; любая ссылка в list на позиции i будет утеряна (утечка).

Примечание

В сборке со свободными потоками этот макрос не имеет внутренней синхронизации. Обычно он используется только для заполнения новых списков, на которые нет ссылок из других потоков. Если список может быть общим, используйте PyList_SetItem(), который использует блокировку на объект.

int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)¶: Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.
Вставляет элемент item в список list перед индексом index. Возвращает 0 при успехе; возвращает -1 и устанавливает исключение при неудаче. Аналогично list.insert(index, item).

int PyList_Append(PyObject *list, PyObject *item)¶: Часть Stable ABI.Потокобезопасность: Атомарно.
Добавляет объект item в конец списка list. Возвращает 0 при успехе; возвращает -1 и устанавливает исключение при неудаче. Аналогично list.append(item).

PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.
Возвращает список объектов из list, содержащий объекты между low и high. Возвращает NULL и устанавливает исключение при неудаче. Аналогично list[low:high]. Индексация с конца списка не поддерживается.

int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)¶: Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.
Устанавливает срез list между low и high равным содержимому itemlist. Аналогично list[low:high] = itemlist. itemlist может быть NULL, что означает присваивание пустого списка (удаление среза). Возвращает 0 при успехе, -1 при неудаче. Индексация с конца списка не поддерживается.

Примечание

В сборке со свободными потоками, когда itemlist является list, оба list и itemlist блокируются на время операции. Для других итерируемых объектов (или NULL) блокируется только list.

int PyList_Extend(PyObject *list, PyObject *iterable)¶

Потокобезопасность: Безопасно для одновременного использования на одном объекте.

Расширяет list содержимым iterable. Это то же самое, что PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable) и аналогично list.extend(iterable) или list += iterable.

Вызывает исключение и возвращает -1, если list не является объектом list. Возвращает 0 при успехе.

Добавлено в версии 3.13.

Примечание

В сборке со свободными потоками, когда iterable является list, set, dict или представлением словаря (dict view), оба list и iterable (или его базовый словарь) блокируются на время операции. Для других итерируемых объектов блокируется только list; iterable может одновременно изменяться другим потоком.

int PyList_Clear(PyObject *list)¶

Потокобезопасность: атомарно.

Удаляет все элементы из list. Это то же самое, что PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL) и аналогично list.clear() или del list[:].

Вызывает исключение и возвращает -1, если list не является объектом list. Возвращает 0 при успехе.

Добавлено в версии 3.13.

int PyList_Sort(PyObject *list)¶: Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.
Сортирует элементы list на месте. Возвращает 0 при успехе, -1 при неудаче. Эквивалентно list.sort().

Примечание

В сборке со свободными потоками сравнение элементов через __lt__() может выполнять произвольный код Python, во время которого побъектная блокировка может временно сниматься. Для встроенных типов (str, int, float) блокировка не снимается во время сравнения.

int PyList_Reverse(PyObject *list)¶: Часть Stable ABI. Потокобезопасность: Безопасно для одновременного использования на одном объекте.
Разворачивает элементы list на месте. Возвращает 0 при успехе, -1 при неудаче. Эквивалентно list.reverse().

PyObject *PyList_AsTuple(PyObject *list)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.
Возвращает новый объект кортежа, содержащий содержимое list; эквивалентно tuple(list).