Протокол итератора¶Iterator Protocol

Есть две функции, предназначенные для работы с итераторами.

int PyIter_Check(PyObject *o)¶: Часть Stable ABI с версии 3.8.
Возвращает ненулевое значение, если объект o можно безопасно передать в PyIter_Next(), и 0 в противном случае. Эта функция всегда завершается успешно.

int PyAIter_Check(PyObject *o)¶: Часть Stable ABI начиная с версии 3.10.
Возвращает ненулевое значение, если объект o предоставляет AsyncIterator протокол, и 0 в противном случае.

Новое в версии 3.10.

PyObject *PyIter_Next(PyObject *o)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Возвращает следующее значение из итератора o. Объект должен быть итератором согласно PyIter_Check() (проверка этого возлагается на вызывающего). Если значений больше нет, возвращает NULL без установки исключения. Если при получении элемента происходит ошибка, возвращает NULL и передаёт исключение.

Чтобы написать цикл, который выполняет итерацию по итератору, код на C должен выглядеть примерно так:

PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;

if (iterator == NULL) {
    /* распространить ошибку */
}

while ((item = PyIter_Next(iterator))) {
    /* сделать что-то с элементом */
    ...
    /* освободить ссылку по завершении */
    Py_DECREF(item);
}

Py_DECREF(iterator);

if (PyErr_Occurred()) {
    /* распространить ошибку */
}
else {
    /* продолжить выполнение полезной работы */
}

type PySendResult¶: Значение перечисления, используемое для представления различных результатов PyIter_Send().

Новое в версии 3.10.

PySendResult PyIter_Send(PyObject *iter, PyObject *arg, PyObject **presult)¶

Часть Stable ABI начиная с версии 3.10.

Отправляет значение arg в итератор iter. Возвращает:

PYGEN_RETURN, если итератор возвращает значение. Возвращаемое значение передаётся через presult.
PYGEN_NEXT, если итератор выдаёт значение. Полученное значение передаётся через presult.
PYGEN_ERROR если итератор выбросил исключение. presult устанавливается в NULL.

Новое в версии 3.10.