animedex.api._paginate

Pagination strategies for the raw API passthrough.

The dispatcher owns HTTP execution, cache lookup, rate limiting, and envelope assembly. This module owns only backend-specific pagination state: how to mutate the next request’s parameters, how to extract items from one decoded page, and when to stop.

PageRequest

class animedex.api._paginate.PageRequest(path: str, params: Dict[str, Any])

Bases: object

Request shape for one paginated page.

Variables:

• path (str) – Path with no query string.

• params (dict) – Query parameters for the page.

path: str

params: Dict[str, Any]

PageResult

class animedex.api._paginate.PageResult(items: List[Any], has_next: bool, reason: str | None = None)

Bases: object

Decoded information from one paginated response.

Variables:

• items (list) – Items extracted from the page.

• has_next (bool) – Whether the upstream indicates that another page may exist.

• reason (str or None) – Termination reason when has_next is False.

items: List[Any]

has_next: bool

reason: str | None = None

PaginationStrategy

class animedex.api._paginate.PaginationStrategy(name: str, initial: Callable[[str, Dict[str, Any]], PageRequest], next_request: Callable[[PageRequest, int, PageResult], PageRequest], decode: Callable[[Any, PageRequest], PageResult])

Bases: object

Backend-specific pagination operations.

Variables:

• name (str) – Strategy/backend name.

• initial (callable) – Build the first request from user input.

• next_request (callable) – Build the next request after a response.

• decode (callable) – Extract page items and upstream termination state.

name: str

initial: Callable[[str, Dict[str, Any]], PageRequest]

next_request: Callable[[PageRequest, int, PageResult], PageRequest]

decode: Callable[[Any, PageRequest], PageResult]

get_strategy

animedex.api._paginate.get_strategy(backend: str) → PaginationStrategy

Return the pagination strategy for backend.

Parameters:

backend (str) – Backend identifier.

Returns:

Pagination strategy.

Return type:

PaginationStrategy

Raises:

ApiError – When the backend is not paginate-aware.

call_paginated

animedex.api._paginate.call_paginated(*, backend: str, path: str, method: str = 'GET', headers: Dict[str, str] | None = None, params: dict | None = None, follow_redirects: bool = True, no_cache: bool = False, cache_ttl: int | None = None, rate: str = 'normal', timeout_seconds: float | None = None, user_agent: str | None = None, base_url: str | None = None, session: 'requests.Session' | None = None, cache: 'SqliteCache' | None = None, rate_limit_registry: 'RateLimitRegistry' | None = None, config: 'Config' | None = None, max_pages: int = 10, max_items: int | None = None) → RawResponse

Issue a raw paginated GET sequence and return an aggregate envelope.

Parameters:

• backend (str) – Backend identifier.

• path (str) – URL path, optionally carrying a query string.

• method (str) – HTTP method. Only GET is currently valid for paginate-aware raw endpoints.

• headers (dict or None) – Caller-supplied headers.

• params (dict or None) – Query parameters merged over any query embedded in path.

• follow_redirects (bool) – Whether to follow redirects.

• no_cache (bool) – Skip cache lookup and writes.

• cache_ttl (int or None) – Override cache TTL in seconds.

• rate (str) – "normal" or "slow".

• timeout_seconds (float or None) – HTTP timeout in seconds.

• user_agent (str or None) – Override default User-Agent.

• base_url (str or None) – Backend base URL override.

• session (requests.Session or None) – Optional requests session.

• cache (SqliteCache or None) – Optional cache.

• rate_limit_registry (RateLimitRegistry or None) – Optional rate-limit registry.

• config (Config or None) – Optional config defaults.

• max_pages (int) – Maximum pages to fetch.

• max_items (int or None) – Maximum items to emit.

Returns:

Aggregate raw envelope whose body is JSON.

Return type:

RawResponse

selftest

animedex.api._paginate.selftest() → bool

Smoke-test strategy registration and representative decoders.