`tuple.md`

202 строк · 13.7 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/c-api/tuple.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты кортежей89#### `type PyTupleObject`1011Этот подтип [`PyObject`](https://python-all.ru/3.11/c-api/structures.html#c.PyObject) представляет объект кортежа Python.1213#### `PyTypeObject PyTuple_Type`1415*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*1617Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.11/c-api/type.html#c.PyTypeObject) представляет тип кортежа Python; это tот же объект, что и [`tuple`](https://python-all.ru/3.11/library/stdtypes.html#tuple) на уровне Python.1819#### `int PyTuple_Check(PyObject *p)`2021Возвращает истину, если *p* является объектом кортежа или экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно.2223#### `int PyTuple_CheckExact(PyObject *p)`2425Возвращает истину, если *p* является объектом кортежа, но не экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно.2627#### `PyObject *PyTuple_New(Py_ssize_t len)`2829*Возвращаемое значение: новая ссылка.*3031*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*3233Возвращает новый объект кортежа размера *len* или `NULL` в случае ошибки.3435#### `PyObject *PyTuple_Pack(Py_ssize_t n, ...)`3637*Возвращаемое значение: новая ссылка.*3839*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*4041Возвращает новый объект кортежа размера *n* или `NULL` в случае ошибки. Значения кортежа инициализируются следующими *n* аргументами C, указывающими на объекты Python. `PyTuple_Pack(2, a, b)` эквивалентно `Py_BuildValue("(OO)", a, b)`.4243#### `Py_ssize_t PyTuple_Size(PyObject *p)`4445*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*4647Принимает указатель на объект кортежа и возвращает размер этого кортежа.4849#### `Py_ssize_t PyTuple_GET_SIZE(PyObject *p)`5051Возвращает размер кортежа *p*, который должен быть не-`NULL` и указывать на кортеж; проверка ошибок не выполняется.5253#### `PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)`5455*Возвращаемое значение: заимствованная ссылка.*5657*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*5859Возвращает объект на позиции *pos* в кортеже, на который указывает *p*. Если *pos* отрицательно или выходит за границы, возвращает `NULL` и устанавливает исключение [`IndexError`](https://python-all.ru/3.11/library/exceptions.html#IndexError).6061#### `PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)`6263*Возвращаемое значение: заимствованная ссылка.*6465Как [`PyTuple_GetItem()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyTuple_GetItem), но не проверяет свои аргументы.6667#### `PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)`6869*Возвращаемое значение: новая ссылка.*7071*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*7273Возвращает срез кортежа, на который указывает *p*, между *low* и *high*, или `NULL` в случае ошибки. Это эквивалент выражения Python `p[low:high]`. Индексация с конца списка не поддерживается.7475#### `int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)`7677*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*7879Вставляет ссылку на объект *o* в позицию *pos* кортежа, на который указывает *p*. В случае успеха возвращает `0`. Если *pos* выходит за границы, возвращает `-1` и устанавливает исключение [`IndexError`](https://python-all.ru/3.11/library/exceptions.html#IndexError).8081> **Примечание**82>83> Эта функция «крадет» ссылку на *o* и удаляет ссылку на элемент, уже находящийся в кортеже на соответствующей позиции.8485#### `void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)`8687Как [`PyTuple_SetItem()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyTuple_SetItem), но без проверки ошибок; должен *использоваться только* для заполнения только что созданных кортежей.8889> **Примечание**90>91> Эта функция «крадет» ссылку на *o* и, в отличие от [`PyTuple_SetItem()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyTuple_SetItem), *не* удаляет ссылку на заменяемый элемент; любая ссылка в кортеже на позиции *pos* приведет к утечке.9293#### `int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)`9495Может использоваться для изменения размера кортежа. *newsize* будет новой длиной кортежа. Поскольку кортежи *считаются* неизменяемыми, этот макрос следует использовать только при наличии единственной ссылки на объект. *Не* используйте его, если кортеж может быть уже известен другой части кода. Кортеж всегда увеличивается или уменьшается с конца. Эту операцию можно рассматривать как уничтожение старого кортежа и создание нового, только более эффективное. Возвращает `0` в случае успеха. Клиентский код не должен предполагать, что результирующее значение `*p` останется тем же, что и до вызова этой функции. Если объект, на который ссылается `*p`, заменяется, оригинальный `*p` уничтожается. В случае неудачи возвращает `-1`, устанавливает `*p` в `NULL` и возбуждает [`MemoryError`](https://python-all.ru/3.11/library/exceptions.html#MemoryError) или [`SystemError`](https://python-all.ru/3.11/library/exceptions.html#SystemError).9697# Объекты структурных кортежей9899Объекты структурных последовательностей – это C-аналог объектов [`namedtuple()`](https://python-all.ru/3.11/library/collections.html#collections.namedtuple), т.е. последовательности, элементы которой также доступны через атрибуты. Чтобы создать структурную последовательность, сначала нужно создать конкретный тип структурной последовательности.100101#### `PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)`102103*Возвращаемое значение: новая ссылка.*104105*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*106107Создаёт новый тип структурного кортежа из данных в *desc*, описанных ниже. Экземпляры полученного типа могут быть созданы с помощью [`PyStructSequence_New()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_New).108109#### `void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)`110111Инициализирует тип структурного кортежа *type* из *desc* на месте.112113#### `int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)`114115То же, что и `PyStructSequence_InitType`, но возвращает `0` в случае успеха и `-1` в случае ошибки.116117Новое в версии 3.4.118119#### `type PyStructSequence_Desc`120121*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) (включая все члены).*122123Содержит метаинформацию о типе структурного кортежа, который необходимо создать.124125#### `const char *name`126127Имя типа структурированной последовательности.128129#### `const char *doc`130131Указатель на строку документации типа или `NULL`, чтобы опустить.132133#### `PyStructSequence_Field *fields`134135Указатель на массив, завершающийся `NULL`, с именами полей нового типа.136137#### `int n_in_sequence`138139Количество полей, видимых на стороне Python (если используется как кортеж).140141#### `type PyStructSequence_Field`142143*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) (включая все члены).*144145Описывает поле структурного кортежа. Поскольку структурный кортеж моделируется как кортеж, все поля имеют тип [PyObject](https://python-all.ru/3.11/c-api/structures.html#c.PyObject)\*. Индекс в массиве [`fields`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_Desc.fields) структуры [`PyStructSequence_Desc`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_Desc) определяет, какое поле структурного кортежа описывается.146147#### `const char *name`148149Имя поля или `NULL`, чтобы завершить список именованных полей, установите в [`PyStructSequence_UnnamedField`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_UnnamedField), чтобы оставить безымянным.150151#### `const char *doc`152153Докстринг поля или `NULL`, чтобы опустить.154155#### `const char *const PyStructSequence_UnnamedField`156157*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable) начиная с версии 3.11.*158159Специальное значение для имени поля, чтобы оставить его безымянным.160161Изменено в версии 3.9: Тип был изменён с `char *`.162163#### `PyObject *PyStructSequence_New(PyTypeObject *type)`164165*Возвращаемое значение: новая ссылка.*166167*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*168169Создаёт экземпляр *type*, который должен быть создан с помощью [`PyStructSequence_NewType()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_NewType).170171#### `PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)`172173*Возвращаемое значение: заимствованная ссылка.*174175*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*176177Возвращает объект на позиции *pos* в структурированной последовательности, на которую указывает *p*. Проверка границ не выполняется.178179#### `PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)`180181*Возвращаемое значение: заимствованная ссылка.*182183Макрос, эквивалентный [`PyStructSequence_GetItem()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_GetItem).184185#### `void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)`186187*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*188189Устанавливает поле по индексу *pos* в struct sequence *p* в значение *o*. Как и [`PyTuple_SET_ITEM()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyTuple_SET_ITEM), это следует использовать только для заполнения совсем новых экземпляров.190191> **Примечание**192>193> Эта функция «крадёт» ссылку на *o*.194195#### `void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)`196197Аналогичен [`PyStructSequence_SetItem()`](https://python-all.ru/3.11/c-api/tuple.html#c.PyStructSequence_SetItem), но реализован как статическая встраиваемая функция.198199> **Примечание**200>201> Эта функция «крадёт» ссылку на *o*.202