> **Источник:** https://python-all.ru/3.14/c-api/tuple.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # Объекты кортежей #### `type PyTupleObject` Этот подтип [`PyObject`](https://python-all.ru/3.14/c-api/structures.html#c.PyObject) представляет объект кортежа Python. #### `PyTypeObject PyTuple_Type` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.14/c-api/type.html#c.PyTypeObject) представляет тип кортежа Python; это tот же объект, что и [`tuple`](https://python-all.ru/3.14/library/stdtypes.html#tuple) на уровне Python. #### `int PyTuple_Check(PyObject *p)` Возвращает истину, если *p* является объектом кортежа или экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно. #### `int PyTuple_CheckExact(PyObject *p)` Возвращает истину, если *p* является объектом кортежа, но не экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно. #### `PyObject *PyTuple_New(Py_ssize_t len)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Возвращает новый объект кортежа размером *len* или `NULL` с установленным исключением в случае ошибки. #### `PyObject *PyTuple_Pack(Py_ssize_t n, ...)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Возвращает новый объект кортежа размером *n* или `NULL` с установленным исключением в случае ошибки. Значения кортежа инициализируются последующими *n* аргументами C, указывающими на объекты Python. `PyTuple_Pack(2, a, b)` эквивалентно `Py_BuildValue("(OO)", a, b)`. #### `Py_ssize_t PyTuple_Size(PyObject *p)` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Принимает указатель на объект кортежа и возвращает размер этого кортежа. В случае ошибки возвращает `-1` с установленным исключением. #### `Py_ssize_t PyTuple_GET_SIZE(PyObject *p)` Как [`PyTuple_Size()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyTuple_Size), но без проверки ошибок. #### `PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)` *Возвращаемое значение: заимствованная ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Возвращает объект на позиции *pos* в кортеже, на который указывает *p*. Если *pos* отрицательно или выходит за границы, возвращает `NULL` и устанавливает исключение [`IndexError`](https://python-all.ru/3.14/library/exceptions.html#IndexError). Возвращаемая ссылка является заимствованной из кортежа *p* (то есть она действительна только до тех пор, пока удерживается ссылка на *p*). Чтобы получить [сильную ссылку](https://python-all.ru/3.14/glossary.html#term-strong-reference), используйте [`Py_NewRef(PyTuple_GetItem(...))`](https://python-all.ru/3.14/c-api/refcounting.html#c.Py_NewRef) или [`PySequence_GetItem()`](https://python-all.ru/3.14/c-api/sequence.html#c.PySequence_GetItem). #### `PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)` *Возвращаемое значение: заимствованная ссылка.* Как [`PyTuple_GetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyTuple_GetItem), но не проверяет свои аргументы. #### `PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Возвращает срез кортежа, на который указывает *p*, между *low* и *high*, или `NULL` с установленным исключением в случае ошибки. Это эквивалент выражения Python `p[low:high]`. Индексация с конца кортежа не поддерживается. #### `int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Вставляет ссылку на объект *o* в позицию *pos* кортежа, на который указывает *p*. В случае успеха возвращает `0`. Если *pos* выходит за границы, возвращает `-1` и устанавливает исключение [`IndexError`](https://python-all.ru/3.14/library/exceptions.html#IndexError). > **Примечание** > > Эта функция «[перехватывает](https://python-all.ru/3.14/glossary.html#term-steal)» ссылку на *o* и отбрасывает ссылку на элемент, уже находящийся в кортеже на изменяемой позиции (если только он не был NULL). #### `void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)` Как [`PyTuple_SetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyTuple_SetItem), но без проверки ошибок; должен *использоваться только* для заполнения только что созданных кортежей. Проверка границ выполняется как утверждение, если 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). > **Примечание** > > Эта функция «[перехватывает](https://python-all.ru/3.14/glossary.html#term-steal)» ссылку на *o* и, в отличие от [`PyTuple_SetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyTuple_SetItem), *не* отбрасывает ссылку на заменяемый элемент; любая ссылка в кортеже на позиции *pos* будет потеряна. > **Предупреждение** > > Этот макрос *следует использовать только* для только что созданных кортежей. Использование этого макроса для кортежа, который уже используется (иными словами, имеет счётчик ссылок \> 1), может привести к неопределённому поведению. #### `int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)` Может использоваться для изменения размера кортежа. *newsize* будет новой длиной кортежа. Поскольку кортежи *считаются* неизменяемыми, этот макрос следует использовать только при наличии единственной ссылки на объект. *Не* используйте его, если кортеж может быть уже известен другой части кода. Кортеж всегда увеличивается или уменьшается с конца. Эту операцию можно рассматривать как уничтожение старого кортежа и создание нового, только более эффективное. Возвращает `0` в случае успеха. Клиентский код не должен предполагать, что результирующее значение `*p` останется тем же, что и до вызова этой функции. Если объект, на который ссылается `*p`, заменяется, оригинальный `*p` уничтожается. В случае неудачи возвращает `-1`, устанавливает `*p` в `NULL` и возбуждает [`MemoryError`](https://python-all.ru/3.14/library/exceptions.html#MemoryError) или [`SystemError`](https://python-all.ru/3.14/library/exceptions.html#SystemError). # Объекты структурных кортежей Объекты структурных последовательностей – это C-аналог объектов [`namedtuple()`](https://python-all.ru/3.14/library/collections.html#collections.namedtuple), т.е. последовательности, элементы которой также доступны через атрибуты. Чтобы создать структурную последовательность, сначала нужно создать конкретный тип структурной последовательности. #### `PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Создаёт новый тип структурного кортежа из данных в *desc*, описанных ниже. Экземпляры полученного типа могут быть созданы с помощью [`PyStructSequence_New()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_New). Возвращает `NULL` с установленным исключением при сбое. #### `void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)` Инициализирует тип структурного кортежа *type* из *desc* на месте. #### `int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)` Как и [`PyStructSequence_InitType()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_InitType), но возвращает `0` в случае успеха и `-1` с установленным исключением в случае неудачи. Добавлено в версии 3.4. #### `type PyStructSequence_Desc` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) (включая все члены).* Содержит метаинформацию о типе структурного кортежа, который необходимо создать. #### `const char *name` Полное имя типа; завершается нулевым символом, кодировка UTF-8. Имя должно содержать имя модуля. #### `const char *doc` Указатель на строку документации типа или `NULL`, чтобы опустить. #### `PyStructSequence_Field *fields` Указатель на массив, завершающийся `NULL`, с именами полей нового типа. #### `int n_in_sequence` Количество полей, видимых на стороне Python (если используется как кортеж). #### `type PyStructSequence_Field` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) (включая все члены).* Описывает поле структурного кортежа. Поскольку структурный кортеж моделируется как кортеж, все поля имеют тип [PyObject](https://python-all.ru/3.14/c-api/structures.html#c.PyObject)\*. Индекс в массиве [`fields`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_Desc.fields) структуры [`PyStructSequence_Desc`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_Desc) определяет, какое поле структурного кортежа описывается. #### `const char *name` Имя поля или `NULL`, чтобы завершить список именованных полей, установите в [`PyStructSequence_UnnamedField`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_UnnamedField), чтобы оставить безымянным. #### `const char *doc` Докстринг поля или `NULL`, чтобы опустить. #### `const char *const PyStructSequence_UnnamedField` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable) начиная с версии 3.11.* Специальное значение для имени поля, чтобы оставить его безымянным. Изменено в версии 3.9: Тип был изменён с `char *`. #### `PyObject *PyStructSequence_New(PyTypeObject *type)` *Возвращаемое значение: новая ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Создаёт экземпляр *type*, который должен быть создан с помощью [`PyStructSequence_NewType()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_NewType). Возвращает `NULL` с установленным исключением при сбое. #### `PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)` *Возвращаемое значение: заимствованная ссылка.* *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Возвращает объект в позиции *pos* структурной последовательности, на которую указывает *p*. Проверка границ выполняется как утверждение, если 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). #### `PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)` *Возвращаемое значение: заимствованная ссылка.* Псевдоним для [`PyStructSequence_GetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_GetItem). Изменено в версии 3.13: Теперь реализован как псевдоним для [`PyStructSequence_GetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_GetItem). #### `void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)` *Часть [Stable ABI](https://python-all.ru/3.14/c-api/stable.html#stable).* Устанавливает поле по индексу *pos* в struct sequence *p* в значение *o*. Как и [`PyTuple_SET_ITEM()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyTuple_SET_ITEM), это следует использовать только для заполнения совсем новых экземпляров. Проверка границ выполняется как утверждение, если 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). > **Примечание** > > Эта функция «[крадёт](https://python-all.ru/3.14/glossary.html#term-steal)» ссылку на *o*. #### `void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)` Псевдоним для [`PyStructSequence_SetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_SetItem). Изменено в версии 3.13: Теперь реализован как псевдоним для [`PyStructSequence_SetItem()`](https://python-all.ru/3.14/c-api/tuple.html#c.PyStructSequence_SetItem).