Асинхронный итератор по страницам API

Решение

async def fetch_items(session, url, page_size=100):
    cursor = None

    while True:
        params = {"limit": page_size}
        if cursor:
            params["cursor"] = cursor

        async with session.get(url, params=params) as response:
            response.raise_for_status()
            payload = await response.json()

        for item in payload["items"]:
            yield item                    # отдаём по одной записи

        cursor = payload.get("next_cursor")
        if not cursor:
            return


# Тот же смысл классом, если нужно хранить состояние снаружи:
class Pages:
    def __init__(self, session, url):
        self.session = session
        self.url = url

    def __aiter__(self):
        return fetch_items(self.session, self.url)

Почему так

Почему генератор, а не список страниц

• Вызывающий получает записи по одной и может остановиться на первой подходящей — остальные страницы не запрашиваются
• Память не зависит от объёма данных: в ней одна страница, а не весь ответ API
• Такой интерфейс скрывает пагинацию: снаружи просто поток записей

Почему курсор лучше offset

• offset при вставках и удалениях между запросами пропускает и дублирует записи — данные едут
• В базе OFFSET 100000 заставляет сервер пролистать сто тысяч строк на каждой странице
• Курсор фиксирует позицию по отсортированному ключу — стабильно и дёшево

Что происходит при break

• Прерывание async for закрывает генератор: внутрь на текущем yield прилетает GeneratorExit
• Если внутри есть try/finally, он отработает — там и закрывают ресурсы
• Именно поэтому сессию сюда передают снаружи: генератор не должен закрывать то, чем не владеет