pagination

def get_has_more_flag(self, response: Any) -> bool | None:
    """提取显式的 has_more 标志."""
    return self._extract(response, self._has_more_flag)

def get_total(self, response: Any) -> int | None:
    """提取数据总数."""
    total = self._extract(response, self._total)
    return total if isinstance(total, int) else None

def get_cursor(self, response: Any) -> Any | None:
    """提取下一页游标或下一批刷新参数."""
    return self._extract(response, self._cursor)

def get_count(self, response: Any) -> int | None:
    """提取当前页实际返回数量."""
    count = self._extract(response, self._count)
    return count if isinstance(count, int) else None

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

    Args:
        params: 当前请求参数.
        response: 当前响应数据.
        adapter: 响应适配器.
    """

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

    Args:
        params: 当前请求参数.
        response: 当前响应数据.
        adapter: 响应适配器.
    """

def has_next(self, params: PaginationParams, response: Any, adapter: ResponseAdapter) -> bool:
    """判断是否还有下一页."""
    explicit_flag = adapter.get_has_more_flag(response)
    if explicit_flag is not None:
        return bool(explicit_flag)

    total = adapter.get_total(response)
    if total is None or self.page_size is None:
        return False

    current_params = cast("dict[Any, Any]", params)
    current_page = current_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

def next_params(
    self,
    params: PaginationParams,
    response: Any,
    adapter: ResponseAdapter,
) -> PaginationParams:
    """计算下一页参数."""
    new_params = cast("dict[Any, Any]", 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: Any, adapter: ResponseAdapter) -> bool:
    """判断是否还有下一页."""
    explicit_flag = adapter.get_has_more_flag(response)
    if explicit_flag is not None:
        return bool(explicit_flag)

    total = adapter.get_total(response)
    if total is None:
        raise ValueError("分页响应未提供 has_more_flag 或 total, 无法判断是否存在下一页")

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

def next_params(
    self,
    params: PaginationParams,
    response: Any,
    adapter: ResponseAdapter,
) -> PaginationParams:
    """计算下一页参数."""
    new_params = cast("dict[Any, Any]", 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, adapter)
    if step <= 0:
        raise ValueError("分页响应未提供有效的当前页数量, 无法计算下一页偏移量")
    new_params[self.offset_key] = current_offset + step
    return new_params

def has_next(self, params: PaginationParams, response: Any, adapter: ResponseAdapter) -> bool:
    """判断是否还能继续换一批."""
    explicit_flag = adapter.get_has_more_flag(response)
    if not explicit_flag:
        return False
    next_refresh_value = self._extract_refresh_value(response, adapter)
    current_params = cast("dict[Any, Any]", params)
    return current_params.get(self.refresh_key) != next_refresh_value

def next_params(
    self,
    params: PaginationParams,
    response: Any,
    adapter: ResponseAdapter,
) -> PaginationParams:
    """计算下一批请求参数."""
    new_params = cast("dict[Any, Any]", copy.deepcopy(params))
    new_params[self.refresh_key] = self._extract_refresh_value(response, adapter)
    return new_params

def has_next(self, params: PaginationParams, response: Any, adapter: ResponseAdapter) -> bool:
    """判断是否还有下一页."""
    explicit_flag = adapter.get_has_more_flag(response)
    if explicit_flag is not None and not bool(explicit_flag):
        return False

    next_cursor = self._extract_cursor(response, adapter)
    current_params = cast("dict[Any, Any]", params)
    return current_params.get(self.cursor_key) != next_cursor

def next_params(
    self,
    params: PaginationParams,
    response: Any,
    adapter: ResponseAdapter,
) -> PaginationParams:
    """计算下一页参数."""
    new_params = cast("dict[Any, Any]", copy.deepcopy(params))
    new_params[self.cursor_key] = self._extract_cursor(response, adapter)
    return new_params

def has_next(self, params: PaginationParams, response: Any, adapter: ResponseAdapter) -> bool:
    """判断是否还有下一页."""
    explicit_flag = adapter.get_has_more_flag(response)
    if explicit_flag is False:
        return False
    return self._build_next_params_candidate(params, response, adapter) is not None

def next_params(
    self,
    params: PaginationParams,
    response: Any,
    adapter: ResponseAdapter,
) -> PaginationParams:
    """计算下一页参数."""
    return self._resolve_next_params(params, response, adapter)

async def next(self) -> RequestResultT:
    """获取并返回下一页响应."""
    return await self.__anext__()

def has_more(self) -> bool:
    """返回当前分页器是否还能继续产出下一页."""
    return self._can_advance()

async def first(self) -> RequestResultT:
    """请求并返回当前批结果."""
    if self._first_response is None:
        self._first_response = await self._advance()
    return self._first_response

async def refresh(self) -> RequestResultT:
    """请求并返回下一批结果."""
    if self._first_response is None:
        await self.first()
    return await self._advance()