Объекты-кортежи

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

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

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

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

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

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): Входит в стабильный 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): Входит в стабильный 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 будет утрачена.

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

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

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