---
title: Обойти страницы результата
description: Объявите стратегию в __pages__ и используйте pages() или items().
sources:
  - eazy_sdk.pagination
draft: false
api_fingerprint: "sha256:6e7813bf02a0d0e2213da9125d4a5fc22e1f690c8dbe07307963b8d4f047b592"
---

Стратегия пагинации принадлежит классу операции. Обычный вызов возвращает одну страницу, а
`pages()` и `items()` строят следующие запросы через неизменяемое значение операции.

```{literalinclude} ../../../../../examples/docs/pagination.py
:language: python
:start-after: "# region docs: pagination"
:end-before: "# endregion docs: pagination"
```

`page=` и `size=` называют поля Python-класса, а не параметры на проводе. `items=` извлекает
элементы, `total_pages=` сообщает последнюю страницу. Несовпадающий тип результата или опечатка
в имени поля останавливает объявление роутера при импорте.

:::{dropdown} Файл целиком
```{literalinclude} ../../../../../examples/docs/pagination.py
:language: python
```
:::

<!-- example-output: examples.docs.pagination -->
```text
page 1: Иск, Отзыв
page 2: Решение
```

## Выбрать стратегию

| Стратегия | Поле следующего запроса | Признак окончания |
|---|---|---|
| `Pages.numbered` | Номер страницы | Общее число страниц, короткая или пустая страница |
| `Pages.offset` | Смещение | Общее число элементов, короткая или пустая страница |
| `Pages.cursor` | Cursor из ответа | Отсутствующий следующий cursor |
| `Pages.next_url` | Готовая ссылка | Отсутствующая ссылка |

`items()` разворачивает страницы в один поток. Аргумент `key=` пропускает повторяющиеся элементы
и завершает обход, если новая страница не добавила ни одного значения. `max_pages=` ограничивает
число запросов, а `options=` применяется к каждой странице.

`max_items=` ограничивает число элементов: `items(max_items=5)` отдаёт первые пять и не
запрашивает страницы после той, на которой нашёлся пятый. Повторы, пропущенные по `key=`, в счёт
не идут.

`first()` возвращает первый элемент или `None`, если первая страница пуста, и всегда делает
ровно один запрос: `latest = await api.documents.first(case_id=cid)`.

Тип элемента берётся из `items=` стратегии: если `items=lambda r: r.items` возвращает
`list[Document]`, то `items()` отдаёт `Document`, `first()` возвращает `Document | None`, а
`key=` принимает `Document`. Отдельная аннотация в вызывающем коде не нужна.

Каждая страница проходит обычные retry, middleware, авторизацию, защиту и подпись. Синхронный
роутер возвращает iterator, асинхронный async iterator.

## Дальше

- {doc}`Работать с запросом как со значением </guide/requests/values>`
- {doc}`Настроить retry </guide/reliability/retry>`
- {doc}`Справочник операций </reference/api/api-methods>`