Пагинация
=========

Все ресурсы (сделки, контакты, компании, задачи) поддерживают два режима
работы метода ``list()``.

Режимы работы ``list()``
------------------------

.. list-table::
   :header-rows: 1
   :widths: 40 30 30

   * - Вызов
     - Поведение
     - Тип возврата
   * - ``client.leads.list()``
     - Авто-пагинация: обходит все страницы
     - ``Iterator[Lead]``
   * - ``client.leads.list(page=2)``
     - Одна конкретная страница
     - ``list[Lead]``

Авто-пагинация (рекомендуется)
-------------------------------

Если ``page`` не передан, SDK автоматически запрашивает страницы одну за другой
и выдаёт элементы по мере загрузки (ленивый ``Iterator``). Цикл завершается,
когда API возвращает пустую страницу или страницу с числом элементов меньше ``limit``.

.. code-block:: python

   # Обойти все сделки
   for lead in client.leads.list():
       print(lead.id, lead.name)

   # Собрать всё в список
   all_leads = list(client.leads.list())

   # Кастомный размер страницы при авто-пагинации
   for contact in client.contacts.list(limit=100):
       process(contact)

   # С фильтром и сортировкой
   for task in client.tasks.list(
       filter={"responsible_user_id": 42},
       order={"created_at": "desc"},
   ):
       print(task.text)

По умолчанию авто-пагинация запрашивает **50 элементов** на страницу.

Одна страница
-------------

Передайте ``page`` явно — метод вернёт обычный ``list`` и сделает ровно один запрос:

.. code-block:: python

   leads = client.leads.list(page=1, limit=250)
   contacts = client.contacts.list(page=3, limit=50, query="Иван")

Это поведение аналогично предыдущим версиям SDK.

Сигнал конца данных
-------------------

SDK считает страницу последней в двух случаях:

1. API вернул пустой список (``_embedded.{entity} == []``).
2. Количество элементов на странице меньше ``limit`` (неполная страница).

Оба случая соответствуют поведению AmoCRM REST API (включая ответ 204,
который ``_request`` возвращает как ``{}``).