pagination

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """判断是否还能继续迭代."""
    ...

def next_params(self, params: PaginationParams, response: T_Resp_contra) -> PaginationParams:
    """计算并返回下一次请求使用的全新参数字典."""
    ...

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """判断是否还能继续翻页."""
    if self.has_more_extractor is not None:
        explicit_flag = self.has_more_extractor(response)
        if explicit_flag is not None:
            return explicit_flag

    if self.total_extractor is not None and self.page_size is not None:
        total = self.total_extractor(response)
        if total is not None:
            current_page = params.get(self.page_key, self.start_page)
            if not isinstance(current_page, int):
                raise TypeError("分页请求缺少有效的页码参数, 无法判断是否存在下一页")
            consumed_pages = current_page - self.start_page + 1
            return consumed_pages * self.page_size < total

    if self.count_extractor is not None:
        count = self.count_extractor(response)
        if count is not None:
            if self.page_size is not None:
                return count >= self.page_size and count > 0
            return count > 0

    return False

def next_params(self, params: PaginationParams, response: T_Resp_contra) -> PaginationParams:
    """获取下一次请求的参数."""
    new_params = copy.deepcopy(params)
    current_page = new_params.get(self.page_key, self.start_page)
    if not isinstance(current_page, int):
        raise TypeError("分页请求缺少有效的页码参数, 无法计算下一页")
    new_params[self.page_key] = current_page + 1
    return new_params

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """检查是否有下一页."""
    if self.has_more_extractor is not None:
        explicit_flag = self.has_more_extractor(response)
        if explicit_flag is not None:
            return explicit_flag

    if self.total_extractor is not None:
        total = self.total_extractor(response)
        if total is not None:
            current_offset = params.get(self.offset_key, self.start_offset)
            if current_offset is None:
                raise ValueError("分页请求缺少有效的 offset 参数, 无法计算下一页")
            step = self._resolve_step(params, response)
            if step <= 0:
                return False
            return current_offset + step < total

    if self.count_extractor is not None:
        count = self.count_extractor(response)
        if count is not None:
            page_size = self._resolve_page_size(params)
            return count >= page_size and count > 0

    return False

def next_params(self, params: PaginationParams, response: T_Resp_contra) -> PaginationParams:
    """获取下一页的请求参数."""
    new_params = copy.deepcopy(params)
    current_offset = new_params.get(self.offset_key, self.start_offset)
    if current_offset is None:
        raise ValueError("分页请求缺少有效的 offset 参数, 无法计算下一页")
    step = self._resolve_step(params, response)
    if step <= 0:
        raise ValueError("分页响应未提供有效的当前页数量, 无法计算下一页偏移量")
    new_params[self.offset_key] = current_offset + step
    return new_params

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """检查是否有下一页."""
    if self._is_terminated(response):
        return False

    try:
        next_cursor = self._extract_cursor(response)
    except ValueError:
        return False

    return params.get(self.cursor_key) != next_cursor

def next_params(self, params: PaginationParams, response: T_Resp_contra) -> PaginationParams:
    """获取下一页的请求参数."""
    new_params = copy.deepcopy(params)
    new_params[self.cursor_key] = self._extract_cursor(response)
    return new_params

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """检查是否有下一批."""
    if self._is_terminated(response):
        return False

    if self.allow_repeat:
        try:
            self._extract_cursor(response)
            return True
        except ValueError:
            return False

    return super().has_next(params, response)

def has_next(self, params: PaginationParams, response: T_Resp_contra) -> bool:
    """检查是否有下一页."""
    if self.has_more_extractor is not None:
        explicit_flag = self.has_more_extractor(response)
        if explicit_flag is not None and not explicit_flag:
            return False

    if self.count_extractor is not None:
        count = self.count_extractor(response)
        if count is not None:  # noqa: SIM102
            if (self.page_size is not None and count < self.page_size) or count == 0:
                return False

    return self._build_next_params_candidate(params, response) is not None

def next_params(self, params: PaginationParams, response: T_Resp_contra) -> PaginationParams:
    """获取下一页的请求参数."""
    return self._resolve_next_params(params, response)

def next_request(self, previous_response: RequestResultT) -> "PaginatedRequestProtocol[RequestResultT] | None":
    """根据上一次的响应数据, 生成下一页的请求描述符."""
    ...

def has_more(self) -> bool:
    """判断是否还有更多页数据可拉取."""
    if self._limit is not None and self._yielded_count >= self._limit:
        return False
    if self._yielded_count == 0:
        return True
    return self._has_more and self._current_request is not None

async def first(self) -> RequestResultT:
    """获取或拉取首批/首页响应数据.

    Returns:
        首个页面响应对象.

    Raises:
        StopAsyncIteration: 当达到 limit 且第一页尚未拉取时抛出.
    """
    if self._first_response is not None:
        return self._first_response

    if not self.has_more():
        raise StopAsyncIteration

    res = await self._initial_request
    self._first_response = res
    if self._yielded_count == 0:
        self._yielded_count = 1
        self._last_response = res
        self._current_request = self._initial_request.next_request(res)
        if self._current_request is None:
            self._has_more = False
    return res

async def next(self) -> RequestResultT:
    """拉取并返回下一页响应数据.

    Returns:
        下一页的响应对象.

    Raises:
        StopAsyncIteration: 当没有更多页或达到 limit 时抛出.
    """
    if not self.has_more() or self._current_request is None:
        raise StopAsyncIteration

    req = self._current_request
    response = await req
    if self._first_response is None:
        self._first_response = response
    self._last_response = response
    self._yielded_count += 1
    self._current_request = req.next_request(response)
    if self._current_request is None:
        self._has_more = False

    return response

async def iter_items(self, limit: int | None = None) -> AsyncGenerator[ItemT_co, None]:
    """执行单次请求并逐个产出提取的实体.

    Args:
        limit: 最大提取条目数量. 如果为 None, 则提取所有返回的条目.

    Yields:
        从响应中提取的数据项实体.
    """
    response = await self
    items = self.items_extractor(response)

    if not items:
        return

    for count, item in enumerate(items):
        if limit is not None and count >= limit:
            break
        yield item

async def collect_items(self, limit: int | None = None) -> list[ItemT_co]:
    """执行请求并提取指定数量的条目返回列表.

    Args:
        limit: 最大提取条目数量. 如果为 None, 则提取所有返回的条目.

    Returns:
        提取的数据项列表.
    """
    return [item async for item in self.iter_items(limit=limit)]

def next_request(self, previous_response: RequestResultT) -> Self | None:
    """根据上一次请求的响应, 构建下一次翻页的请求.

    Args:
        previous_response: 上一次请求得到的解析后响应对象.

    Returns:
        下一次请求的描述符, 如果没有更多数据则返回 None.
    """
    if self.pager_strategy.has_next(self._page_params, previous_response):
        next_param = self.pager_strategy.next_params(self._page_params, previous_response)
        return self._with_page_params(next_param)
    return None

def pager(self, limit: int | None = None) -> "AsyncPager[RequestResultT]":
    """返回有状态异步分页器.

    Args:
        limit: 最大可拉取页数限制. 如果为 None, 则无限制拉取直到结束.

    Returns:
        管理当前请求翻页状态的异步分页器实例.
    """
    return AsyncPager(self, limit=limit)

async def collect(self, limit: int | None = None) -> list[RequestResultT]:
    """收集指定页数的响应数据为列表.

    Args:
        limit: 最大可拉取页数限制. 如果为 None, 则拉取所有页.

    Returns:
        包含各页解析后响应对象的列表.
    """
    return [response async for response in self.paginate(limit=limit)]

async def paginate(self, limit: int | None = None) -> AsyncGenerator[RequestResultT, None]:
    """返回响应的分页迭代器.

    Args:
        limit: 最大可拉取页数限制. 如果为 None, 则无限制翻页.

    Yields:
        单页的解析后响应对象.
    """
    pager = self.pager(limit=limit)
    async for response in pager:
        yield response

async def iter_items(self, limit: int | None = None) -> AsyncGenerator[ItemT_co, None]:
    """跨页展开提取数据项的异步迭代器.

    自动处理网络翻页, 并逐个产出提取的数据项. 达到指定条目数或所有页面拉取完毕时停止.

    Args:
        limit: 最大提取的条目总数限制. 如果为 None, 则提取所有页面的所有条目.

    Yields:
        提取的数据项实体.
    """
    if limit is not None and limit <= 0:
        return
    total_yielded = 0
    async for response in self.paginate():
        items = self.items_extractor(response)
        if items is None:
            continue

        for item in items:
            if limit is not None and total_yielded >= limit:
                return
            yield item
            total_yielded += 1

async def collect_items(self, limit: int | None = None) -> list[ItemT_co]:
    """收集跨页展开的数据项为列表.

    Args:
        limit: 最大提取的条目总数限制. 如果为 None, 则收集所有页面的所有条目.

    Returns:
        包含跨页提取出的所有数据项的列表.
    """
    return [item async for item in self.iter_items(limit=limit)]