`list.md`

216 строк · 18.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.14/c-api/list.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты списков89#### `type PyListObject`1011Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект списка Python.1213#### `PyTypeObject PyList_Type`1415*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*1617Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип списка Python. Это тот же объект, что и [`list`](https://python-all.ru/3.14/library/stdtypes.html#list) в слое Python.1819#### `int PyList_Check(PyObject *p)`2021*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*2223Возвращает true, если *p* является объектом списка или экземпляром подтипа типа списка. Эта функция всегда завершается успешно.2425#### `int PyList_CheckExact(PyObject *p)`2627*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*2829Возвращает true, если *p* является объектом списка, но не экземпляром подтипа типа списка. Эта функция всегда завершается успешно.3031#### `PyObject *PyList_New(Py_ssize_t len)`3233*Возвращаемое значение: новая ссылка.*3435*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*3637*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*3839Возвращает новый список длины *len* в случае успеха или `NULL` в случае ошибки.4041> **Примечание**42>43> Если *len* больше нуля, элементы возвращаемого объекта списка устанавливаются в `NULL`. Поэтому нельзя использовать абстрактные функции API, такие как [`PySequence_SetItem()`](https://python-all.ru/3.14/c-api/sequence.html#c.PySequence_SetItem), или предоставлять объект коду Python до установки всех элементов в реальный объект с помощью [`PyList_SetItem()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_SetItem) или [`PyList_SET_ITEM()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_SET_ITEM). Следующие API безопасны до полной инициализации списка: `PyList_SetItem()` и `PyList_SET_ITEM()`.4445#### `Py_ssize_t PyList_Size(PyObject *list)`4647*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*4849*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*5051Возвращает длину объекта списка в *list*; это эквивалентно `len(list)` для объекта списка.5253#### `Py_ssize_t PyList_GET_SIZE(PyObject *list)`5455*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*5657Аналогично [`PyList_Size()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_Size), но без проверки ошибок.5859#### `PyObject *PyList_GetItemRef(PyObject *list, Py_ssize_t index)`6061*Возвращаемое значение: новая ссылка.*6263*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.13.*6465*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*6667Возвращает объект на позиции *index* в списке, на который указывает *list*. Позиция должна быть неотрицательной; индексация от конца списка не поддерживается. Если *index* выходит за границы (`<0 or >=len(list)`), возвращается `NULL` и устанавливается исключение [`IndexError`](https://python-all.ru/3.14/library/exceptions.html#IndexError).6869Добавлено в версии 3.13.7071#### `PyObject *PyList_GetItem(PyObject *list, Py_ssize_t index)`7273*Возвращаемое значение: заимствованная ссылка.*7475*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*7677*Потокобезопасность: [Безопасно вызывать из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*7879Как [`PyList_GetItemRef()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_GetItemRef), но возвращает [заимствованную ссылку](https://python-all.ru/3.14/glossary.html#term-borrowed-reference) вместо [сильной ссылки](https://python-all.ru/3.14/glossary.html#term-strong-reference).8081> **Примечание**82>83> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build) возвращаемая [заимствованная ссылка](https://python-all.ru/3.14/glossary.html#term-borrowed-reference) может стать недействительной, если другой поток изменяет список конкурентно. Предпочтительнее [`PyList_GetItemRef()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_GetItemRef), которая возвращает [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference).8485#### `PyObject *PyList_GET_ITEM(PyObject *list, Py_ssize_t i)`8687*Возвращаемое значение: заимствованная ссылка.*8889*Потокобезопасность: [Безопасно вызывать из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*9091Аналогично [`PyList_GetItem()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_GetItem), но без проверки ошибок.9293> **Примечание**94>95> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build) возвращаемая [заимствованная ссылка](https://python-all.ru/3.14/glossary.html#term-borrowed-reference) может стать недействительной, если другой поток изменяет список конкурентно. Предпочтительнее [`PyList_GetItemRef()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_GetItemRef), которая возвращает [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference).9697#### `int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)`9899*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*100101*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*102103Устанавливает элемент на индексе *index* в списке в значение *item*. Возвращает `0` в случае успеха. Если *index* выходит за границы, возвращает `-1` и устанавливает исключение [`IndexError`](https://python-all.ru/3.14/library/exceptions.html#IndexError).104105> **Примечание**106>107> Эта функция «[крадёт](https://python-all.ru/3.14/glossary.html#term-steal)» ссылку на *item*, даже в случае ошибки. В случае успеха она отбрасывает ссылку на элемент, уже находящийся в списке на соответствующей позиции (если только это не `NULL`).108109#### `void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)`110111*Потокобезопасность: [Безопасно вызывать из нескольких потоков только с внешней синхронизацией](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-compatible).*112113Макро-форма [`PyList_SetItem()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_SetItem) без проверки ошибок. Обычно используется только для заполнения новых списков, где нет предыдущего содержимого.114115Проверка границ выполняется как утверждение, если Python собран в [режиме отладки](https://python-all.ru/3.14/using/configure.html#debug-build) или [`with assertions`](https://python-all.ru/3.14/using/configure.html#cmdoption-with-assertions).116117> **Примечание**118>119> Этот макрос «[крадёт](https://python-all.ru/3.14/glossary.html#term-steal)» ссылку на *item* и, в отличие от [`PyList_SetItem()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_SetItem), *не* отбрасывает ссылку на любой элемент, который заменяется; любая ссылка в *list* на позиции *i* будет утеряна (утечка).120121> **Примечание**122>123> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build) этот макрос не имеет внутренней синхронизации. Обычно он используется только для заполнения новых списков, на которые нет ссылок из других потоков. Если список может быть общим, используйте [`PyList_SetItem()`](https://python-all.ru/3.14/c-api/list.html#c.PyList_SetItem), который использует [блокировку на объект](https://python-all.ru/3.14/glossary.html#term-per-object-lock).124125#### `int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)`126127*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*128129*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*130131Вставляет элемент *item* в список *list* перед индексом *index*. Возвращает `0` при успехе; возвращает `-1` и устанавливает исключение при неудаче. Аналогично `list.insert(index, item)`.132133#### `int PyList_Append(PyObject *list, PyObject *item)`134135*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*136137*Потокобезопасность: [Атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*138139Добавляет объект *item* в конец списка *list*. Возвращает `0` при успехе; возвращает `-1` и устанавливает исключение при неудаче. Аналогично `list.append(item)`.140141#### `PyObject *PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)`142143*Возвращаемое значение: новая ссылка.*144145*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*146147*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*148149Возвращает список объектов из *list*, содержащий объекты *между* *low* и *high*. Возвращает `NULL` и устанавливает исключение при неудаче. Аналогично `list[low:high]`. Индексация с конца списка не поддерживается.150151#### `int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)`152153*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*154155*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*156157Устанавливает срез *list* между *low* и *high* равным содержимому *itemlist*. Аналогично `list[low:high] = itemlist`. *itemlist* может быть `NULL`, что означает присваивание пустого списка (удаление среза). Возвращает `0` при успехе, `-1` при неудаче. Индексация с конца списка не поддерживается.158159> **Примечание**160>161> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build), когда *itemlist* является [`list`](https://python-all.ru/3.14/library/stdtypes.html#list), оба *list* и *itemlist* блокируются на время операции. Для других итерируемых объектов (или `NULL`) блокируется только *list*.162163#### `int PyList_Extend(PyObject *list, PyObject *iterable)`164165*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*166167Расширяет *list* содержимым *iterable*. Это то же самое, что `PyList_SetSlice(list, PY_SSIZE_T_MAX, PY_SSIZE_T_MAX, iterable)` и аналогично `list.extend(iterable)` или `list += iterable`.168169Вызывает исключение и возвращает `-1`, если *list* не является объектом [`list`](https://python-all.ru/3.14/library/stdtypes.html#list). Возвращает 0 при успехе.170171Добавлено в версии 3.13.172173> **Примечание**174>175> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build), когда *iterable* является [`list`](https://python-all.ru/3.14/library/stdtypes.html#list), [`set`](https://python-all.ru/3.14/library/stdtypes.html#set), [`dict`](https://python-all.ru/3.14/library/stdtypes.html#dict) или представлением словаря (dict view), оба *list* и *iterable* (или его базовый словарь) блокируются на время операции. Для других итерируемых объектов блокируется только *list*; *iterable* может одновременно изменяться другим потоком.176177#### `int PyList_Clear(PyObject *list)`178179*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*180181Удаляет все элементы из *list*. Это то же самое, что `PyList_SetSlice(list, 0, PY_SSIZE_T_MAX, NULL)` и аналогично `list.clear()` или `del list[:]`.182183Вызывает исключение и возвращает `-1`, если *list* не является объектом [`list`](https://python-all.ru/3.14/library/stdtypes.html#list). Возвращает 0 при успехе.184185Добавлено в версии 3.13.186187#### `int PyList_Sort(PyObject *list)`188189*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*190191*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*192193Сортирует элементы *list* на месте. Возвращает `0` при успехе, `-1` при неудаче. Эквивалентно `list.sort()`.194195> **Примечание**196>197> В [сборке со свободными потоками](https://python-all.ru/3.14/glossary.html#term-free-threaded-build) сравнение элементов через [`__lt__()`](https://python-all.ru/3.14/reference/datamodel.html#object.__lt__) может выполнять произвольный код Python, во время которого [побъектная блокировка](https://python-all.ru/3.14/glossary.html#term-per-object-lock) может временно сниматься. Для встроенных типов ([`str`](https://python-all.ru/3.14/library/stdtypes.html#str), [`int`](https://python-all.ru/3.14/library/functions.html#int), [`float`](https://python-all.ru/3.14/library/functions.html#float)) блокировка не снимается во время сравнения.198199#### `int PyList_Reverse(PyObject *list)`200201*Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*202203*Потокобезопасность: [Безопасно для одновременного использования на одном объекте](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-shared).*204205Разворачивает элементы *list* на месте. Возвращает `0` при успехе, `-1` при неудаче. Эквивалентно `list.reverse()`.206207#### `PyObject *PyList_AsTuple(PyObject *list)`208209*Возвращаемое значение: новая ссылка.*210211*Часть [стабильного ABI](https://python-all.ru/3.14/c-api/stable.html#stable).*212213*Потокобезопасность: [атомарно](https://python-all.ru/3.14/library/threadsafety.html#threadsafety-level-atomic).*214215Возвращает новый объект кортежа, содержащий содержимое *list*; эквивалентно `tuple(list)`.216