`tuple.md`

164 строк · 12.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.7/c-api/tuple.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты кортежей89**`PyTupleObject`**1011Этот подтип [`PyObject`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject) представляет объект кортежа Python.1213**[PyTypeObject](https://python-all.ru/3.7/c-api/type.html#c.PyTypeObject) `PyTuple_Type`**1415Этот экземпляр [`PyTypeObject`](https://python-all.ru/3.7/c-api/type.html#c.PyTypeObject) представляет тип кортежа Python; это tот же объект, что и [`tuple`](https://python-all.ru/3.7/library/stdtypes.html#tuple) на уровне Python.1617#### `int PyTuple_Check(PyObject *p)`1819Возвращает истину, если *p* является объектом кортежа или экземпляром подтипа типа tuple type.2021#### `int PyTuple_CheckExact(PyObject *p)`2223Возвращает истину, если *p* является объектом кортежа, но не экземпляром подтипа tuple type.2425#### `PyObject* PyTuple_New(Py_ssize_t len)`2627*Возвращаемое значение: новая ссылка.*2829Возвращает новый объект кортежа размера *len* или `NULL` в случае ошибки.3031#### `PyObject* PyTuple_Pack(Py_ssize_t n, ...)`3233*Возвращаемое значение: новая ссылка.*3435Возвращает новый объект кортежа размера *n* или `NULL` в случае ошибки. Значения кортежа инициализируются следующими *n* аргументами C, указывающими на объекты Python. `PyTuple_Pack(2, a, b)` эквивалентно `Py_BuildValue("(OO)", a, b)`.3637#### `Py_ssize_t PyTuple_Size(PyObject *p)`3839Принимает указатель на объект кортежа и возвращает размер этого кортежа.4041#### `Py_ssize_t PyTuple_GET_SIZE(PyObject *p)`4243Возвращает размер кортежа *p*, который должен быть не-`NULL` и указывать на кортеж; проверка ошибок не выполняется.4445#### `PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)`4647*Возвращаемое значение: заимствованная ссылка.*4849Возвращает объект в позиции *pos* кортежа, на который указывает *p*. Если *pos* выходит за границы, возвращает `NULL` и возбуждает исключение [`IndexError`](https://python-all.ru/3.7/library/exceptions.html#IndexError).5051#### `PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)`5253*Возвращаемое значение: заимствованная ссылка.*5455Как [`PyTuple_GetItem()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyTuple_GetItem), но не проверяет свои аргументы.5657#### `PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)`5859*Возвращаемое значение: новая ссылка.*6061Возвращает срез кортежа, на который указывает *p*, между *low* и *high*, или `NULL` в случае ошибки. Это эквивалент выражения Python `p[low:high]`. Индексация с конца списка не поддерживается.6263#### `int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)`6465Вставляет ссылку на объект *o* в позицию *pos* кортежа, на который указывает *p*. В случае успеха возвращает `0`. Если *pos* выходит за границы, возвращает `-1` и устанавливает исключение [`IndexError`](https://python-all.ru/3.7/library/exceptions.html#IndexError).6667> **Примечание**68>69> Эта функция «крадет» ссылку на *o* и удаляет ссылку на элемент, уже находящийся в кортеже на соответствующей позиции.7071#### `void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)`7273Как [`PyTuple_SetItem()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyTuple_SetItem), но без проверки ошибок; должен *использоваться только* для заполнения только что созданных кортежей.7475> **Примечание**76>77> Этот макрос «перехватывает» ссылку на *o* и, в отличие от [`PyTuple_SetItem()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyTuple_SetItem), *не* отбрасывает ссылку на заменяемый элемент; любая ссылка в кортеже на позиции *pos* будет утеряна.7879#### `int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)`8081Может использоваться для изменения размера кортежа. *newsize* будет новой длиной кортежа. Поскольку кортежи *считаются* неизменяемыми, этот макрос следует использовать только при наличии единственной ссылки на объект. *Не* используйте его, если кортеж может быть уже известен другой части кода. Кортеж всегда увеличивается или уменьшается с конца. Эту операцию можно рассматривать как уничтожение старого кортежа и создание нового, только более эффективное. Возвращает `0` в случае успеха. Клиентский код не должен предполагать, что результирующее значение `*p` останется тем же, что и до вызова этой функции. Если объект, на который ссылается `*p`, заменяется, оригинальный `*p` уничтожается. В случае неудачи возвращает `-1`, устанавливает `*p` в `NULL` и возбуждает [`MemoryError`](https://python-all.ru/3.7/library/exceptions.html#MemoryError) или [`SystemError`](https://python-all.ru/3.7/library/exceptions.html#SystemError).8283#### `int PyTuple_ClearFreeList()`8485Очищает список свободных элементов. Возвращает общее количество освобождённых элементов.8687# Объекты структурных кортежей8889Объекты структурных последовательностей – это C-аналог объектов [`namedtuple()`](https://python-all.ru/3.7/library/collections.html#collections.namedtuple), т.е. последовательности, элементы которой также доступны через атрибуты. Чтобы создать структурную последовательность, сначала нужно создать конкретный тип структурной последовательности.9091#### `PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)`9293*Возвращаемое значение: новая ссылка.*9495Создаёт новый тип структурного кортежа из данных в *desc*, описанных ниже. Экземпляры полученного типа могут быть созданы с помощью [`PyStructSequence_New()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_New).9697#### `void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)`9899Инициализирует тип структурного кортежа *type* из *desc* на месте.100101#### `int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)`102103То же, что и `PyStructSequence_InitType`, но возвращает `0` в случае успеха и `-1` в случае ошибки.104105Новое в версии 3.4.106107**`PyStructSequence_Desc`**108109Содержит метаинформацию о типе структурного кортежа, который необходимо создать.110111| Поле | Тип C | Значение |112| --- | --- | --- |113| `name` | `const char *` | имя типа структурной последовательности |114| `doc` | `const char *` | указатель на строку документации для типа или `NULL`, чтобы пропустить |115| `fields` | `PyStructSequence_Field *` | указатель на массив, завершающийся `NULL`, с именами полей нового типа |116| `n_in_sequence` | `int` | количество полей, доступных со стороны Python (при использовании в качестве кортежа) |117118**`PyStructSequence_Field`**119120Описывает поле структурной последовательности. Поскольку структурная последовательность моделируется как кортеж, все поля имеют тип [`PyObject*`](https://python-all.ru/3.7/c-api/structures.html#c.PyObject). Индекс в массиве `fields` объекта [`PyStructSequence_Desc`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_Desc) определяет, какое поле структурной последовательности описывается.121122| Поле | Тип C | Значение |123| --- | --- | --- |124| `name` | `const char *` | имя поля или `NULL` для завершения списка именованных полей; присваивается [`PyStructSequence_UnnamedField`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_UnnamedField), чтобы оставить поле безымянным |125| `doc` | `const char *` | строка документации поля или `NULL`, чтобы пропустить |126127**char\* `PyStructSequence_UnnamedField`**128129Специальное значение для имени поля, чтобы оставить его безымянным.130131#### `PyObject* PyStructSequence_New(PyTypeObject *type)`132133*Возвращаемое значение: новая ссылка.*134135Создаёт экземпляр *type*, который должен быть создан с помощью [`PyStructSequence_NewType()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_NewType).136137#### `PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)`138139*Возвращаемое значение: заимствованная ссылка.*140141Возвращает объект на позиции *pos* в структурированной последовательности, на которую указывает *p*. Проверка границ не выполняется.142143#### `PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)`144145*Возвращаемое значение: заимствованная ссылка.*146147Макрос, эквивалентный [`PyStructSequence_GetItem()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_GetItem).148149#### `void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)`150151Устанавливает поле по индексу *pos* в struct sequence *p* в значение *o*. Как и [`PyTuple_SET_ITEM()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyTuple_SET_ITEM), это следует использовать только для заполнения совсем новых экземпляров.152153> **Примечание**154>155> Эта функция «крадёт» ссылку на *o*.156157#### `void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)`158159Макрос, эквивалентный [`PyStructSequence_SetItem()`](https://python-all.ru/3.7/c-api/tuple.html#c.PyStructSequence_SetItem).160161> **Примечание**162>163> Эта функция «крадёт» ссылку на *o*.164