Объекты кортежей¶Tuple Objects

type PyTupleObject¶: Этот подтип PyObject представляет объект кортежа Python.

PyTypeObject PyTuple_Type¶: Часть Stable ABI.
Этот экземпляр PyTypeObject представляет тип кортежа Python; это tот же объект, что и tuple на уровне Python.

int PyTuple_Check(PyObject *p)¶: Возвращает истину, если p является объектом кортежа или экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно.

int PyTuple_CheckExact(PyObject *p)¶: Возвращает истину, если p является объектом кортежа, но не экземпляром подтипа типа кортежа. Эта функция всегда завершается успешно.

PyObject *PyTuple_New(Py_ssize_t len)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.
Возвращает новый объект кортежа размером len или NULL с установленным исключением в случае ошибки.

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)¶

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

Создаёт кортеж из size элементов и копирует ссылки из array в новый кортеж.

array может быть NULL, если size равен 0.

При успехе возвращает новую ссылку. При ошибке устанавливает исключение и возвращает NULL.

Добавлено в версии 3.15.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)¶: Возвращаемое значение: новая ссылка. Часть стабильного ABI. Потокобезопасность: атомарно.
Возвращает новый объект кортежа размером n или NULL с установленным исключением в случае ошибки. Значения кортежа инициализируются последующими n аргументами C, указывающими на объекты Python. PyTuple_Pack(2, a, b) эквивалентно Py_BuildValue("(OO)", a, b).

Py_ssize_t PyTuple_Size(PyObject *p)¶: Часть Stable ABI.Потокобезопасность: Атомарно.
Принимает указатель на объект кортежа и возвращает размер этого кортежа. В случае ошибки возвращает -1 с установленным исключением.

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)¶: Потокобезопасность: атомарно.
Как PyTuple_Size(), но без проверки ошибок.

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)¶

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

Возвращает объект на позиции pos в кортеже, на который указывает p. Если pos отрицательно или выходит за границы, возвращает NULL и устанавливает исключение IndexError.

Возвращаемая ссылка является заимствованной из кортежа p (то есть она действительна только до тех пор, пока удерживается ссылка на p). Чтобы получить сильную ссылку, используйте Py_NewRef(PyTuple_GetItem(...)) или PySequence_GetItem().

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)¶: Возвращаемое значение: заимствованная ссылка. Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Как PyTuple_GetItem(), но не проверяет свои аргументы.

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)¶

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

Возвращает срез кортежа, на который указывает p, между low и high, или NULL с установленным исключением в случае ошибки.

Это эквивалент выражения Python p[low:high]. Индексация с конца кортежа не поддерживается.

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)¶: Часть Stable ABI. Потокобезопасность: Безопасен для вызова из нескольких потоков только с внешней синхронизацией.
Вставляет ссылку на объект o в позицию pos кортежа, на который указывает p. Возвращает 0 при успехе. Если pos выходит за границы, возвращает -1 и устанавливает исключение IndexError. Эта функция должна использоваться только для заполнения новых кортежей; использование её на существующем кортеже не является потокобезопасным.

Примечание

Эта функция «перехватывает» ссылку на o и отбрасывает ссылку на элемент, уже находящийся в кортеже на изменяемой позиции (если только он не был NULL).

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)¶

Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.

Как и PyTuple_SetItem(), но не выполняет проверку ошибок и должен использоваться только для заполнения совершенно новых кортежей; использовать его на существующем кортеже небезопасно для потоков.

Проверка границ выполняется как утверждение, если Python собран в режиме отладки или with assertions.

Примечание

Эта функция «перехватывает» ссылку на o и, в отличие от PyTuple_SetItem(), не отбрасывает ссылку на заменяемый элемент; любая ссылка в кортеже на позиции pos будет потеряна.

Предупреждение

Этот макрос следует использовать только для только что созданных кортежей. Использование этого макроса для кортежа, который уже используется (иными словами, имеет счётчик ссылок > 1), может привести к неопределённому поведению.

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)¶: Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Может использоваться для изменения размера кортежа. newsize будет новой длиной кортежа. Поскольку кортежи считаются неизменяемыми, этот макрос следует использовать только при наличии единственной ссылки на объект. Не используйте его, если кортеж может быть уже известен другой части кода. Кортеж всегда увеличивается или уменьшается с конца. Эту операцию можно рассматривать как уничтожение старого кортежа и создание нового, только более эффективное. Возвращает 0 в случае успеха. Клиентский код не должен предполагать, что результирующее значение *p останется тем же, что и до вызова этой функции. Если объект, на который ссылается *p, заменяется, оригинальный *p уничтожается. В случае неудачи возвращает -1, устанавливает *p в NULL и возбуждает MemoryError или SystemError.

Объекты структурных кортежей¶Struct Sequence Objects

Объект структурного кортежа – это именованный кортеж, то есть последовательность, элементы которой также могут быть доступны через атрибуты. Он похож на collections.namedtuple(), но предоставляет немного другой интерфейс.

Чтобы создать структурный кортеж, сначала необходимо создать конкретный тип структурного кортежа.

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)¶

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

Создаёт новый тип структурного кортежа из данных в desc, описанных ниже. Экземпляры полученного типа могут быть созданы с помощью PyStructSequence_New().

Возвращает NULL с установленным исключением при сбое.

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)¶: Потокобезопасность: Можно безопасно вызывать без внешней синхронизации для разных объектов.
Инициализирует тип структурного кортежа type из desc на месте.

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)¶: Потокобезопасность: Можно безопасно вызывать без внешней синхронизации для разных объектов.
Как и PyStructSequence_InitType(), но возвращает 0 в случае успеха и -1 с установленным исключением в случае неудачи.

Добавлено в версии 3.4.

type PyStructSequence_Desc¶

Часть Stable ABI (включая все члены).

Содержит метаинформацию о типе структурного кортежа, который необходимо создать.

const char *name¶: Полное имя типа; завершается нулевым символом, кодировка UTF-8. Имя должно содержать имя модуля.

const char *doc¶: Указатель на строку документации типа или NULL, чтобы опустить.

PyStructSequence_Field *fields¶: Указатель на массив, завершающийся NULL, с именами полей нового типа.

int n_in_sequence¶: Количество полей, видимых на стороне Python (если используется как кортеж).

type PyStructSequence_Field¶

Часть Stable ABI (включая все члены).

Описывает поле структурного кортежа. Поскольку структурный кортеж моделируется как кортеж, все поля имеют тип PyObject*. Индекс в массиве fields структуры PyStructSequence_Desc определяет, какое поле структурного кортежа описывается.

const char *name¶: Имя поля или NULL, чтобы завершить список именованных полей, установите в PyStructSequence_UnnamedField, чтобы оставить безымянным.

const char *doc¶: Докстринг поля или NULL, чтобы опустить.

const char *const PyStructSequence_UnnamedField¶: Часть Stable ABI начиная с версии 3.11.
Специальное значение для имени поля, чтобы оставить его безымянным.

Изменено в версии 3.9: Тип был изменён с char *.

PyObject *PyStructSequence_New(PyTypeObject *type)¶

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

Создаёт экземпляр type, который должен быть создан с помощью PyStructSequence_NewType().

Возвращает NULL с установленным исключением при сбое.

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)¶

Возвращает объект в позиции pos в struct sequence, на который указывает p. Возвращаемая ссылка заимствуется из struct sequence p (то есть она действительна только до тех пор, пока удерживается ссылка на p).

Проверка границ выполняется как утверждение, если Python собран в режиме отладки или with assertions.

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)¶: Возвращаемое значение: заимствованная ссылка. Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Псевдоним для PyStructSequence_GetItem().

Изменено в версии 3.13: Теперь реализован как псевдоним для PyStructSequence_GetItem().

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)¶

Часть Stable ABI. Потокобезопасность: Безопасен для вызова из нескольких потоков только с внешней синхронизацией.

Устанавливает поле по индексу pos в struct sequence p в значение o. Как и PyTuple_SET_ITEM(), это следует использовать только для заполнения совсем новых экземпляров.

Проверка границ выполняется как утверждение, если Python собран в режиме отладки или with assertions.

Примечание

Эта функция «крадёт» ссылку на o.

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)¶: Потокобезопасность: Безопасно вызывать из нескольких потоков только с внешней синхронизацией.
Псевдоним для PyStructSequence_SetItem().

Изменено в версии 3.13: Теперь реализован как псевдоним для PyStructSequence_SetItem().