Объекты списка

type PyListObject

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

PyTypeObject PyList_Type

Часть стабильного 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)

Часть стабильного ABI.Потокобезопасность: атомарно.

Возвращает длину объекта списка в list; для объекта списка это эквивалентно len(list).

Py_ssize_t PyList_GET_SIZE(PyObject *list)

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

Аналогична PyList_Size(), но не выполняет проверку ошибок.

PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)

Возвращаемое значение: новая ссылка. Часть стабильного 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)

Часть стабильного ABI.Потокобезопасность: атомарно.

Устанавливает элемент item в списке по индексу index. В случае успеха возвращает 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)

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

Вставляет элемент item в список list перед индексом index. В случае успеха возвращает 0; в случае неудачи возвращает -1 и устанавливает исключение. Аналогична list.insert(index, item).

int PyList_Append(PyObject *list, PyObject *item)

Часть стабильного 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)

Часть стабильного 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 или представлением словаря, блокировки 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)

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

Сортирует элементы list на месте. В случае успеха возвращает 0, в случае неудачи — -1. Это эквивалентно list.sort().

Примечание

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

int PyList_Reverse(PyObject *list)

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

Разворачивает порядок элементов list на месте. В случае успеха возвращает 0, в случае неудачи — -1. Это эквивалент list.reverse().

PyObject *PyList_AsTuple(PyObject *list)

Возвращаемое значение: новая ссылка. Часть стабильного ABI.Потокобезопасность: атомарно.

Возвращает новый объект-кортеж, содержащий элементы list; эквивалентно tuple(list).