animedex.api._dispatch

Universal animedex api dispatcher.

call() is the single entry point: it composes the URL, waits on the per-backend rate-limit bucket, looks up the local SQLite cache, issues the HTTP request when needed, and assembles a RawResponse envelope containing everything a CLI render mode needs (body, status, response headers, redirect chain, request snapshot with credentials redacted, timing breakdown, cache provenance).

Per-backend modules under animedex/api/<backend>.py are thin shims that pre-fill the backend argument; this module owns the shared envelope assembly.

resolve_base_url

animedex.api._dispatch.resolve_base_url(backend: str) → str[source]

Return the canonical base URL for backend.

Parameters:

backend (str) – Backend identifier.

Returns:

Base URL with no trailing slash.

Return type:

str

Raises:

KeyError – When the backend is not registered.

call

animedex.api._dispatch.call(*, backend: str, path: str, method: str = 'GET', headers: Dict[str, str] | None = None, params: dict | None = None, json_body: Any | None = None, raw_body: bytes | 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) → RawResponse[source]

Issue one request and return its complete envelope.

Parameters:

  • backend (str) – Backend identifier (e.g. "anilist"); determines base URL and rate-limit bucket.

  • path (str) – URL path (relative to base) or absolute URL.

  • method (str) – HTTP method.

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

  • params (dict or None) – Query parameters.

  • json_body (Any or None) – JSON body for POST.

  • raw_body (bytes or None) – Raw byte body (mutually exclusive with json_body).

  • follow_redirects (bool) – Whether to follow 3xx automatically.

  • no_cache (bool) – When True, skip cache lookup and write.

  • cache_ttl (int or None) – Override TTL in seconds; defaults to the metadata category default.

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

  • timeout_seconds (float or None) – HTTP timeout in seconds. None falls back to the project-default 30 s.

  • user_agent (str or None) – Override for the project default UA.

  • base_url (str or None) – Override for the backend’s canonical base URL.

  • session (requests.Session or None) – Reuse a requests.Session; one is created when not given.

  • cache (SqliteCache or None) – SqliteCache instance; None skips cache regardless of no_cache.

  • rate_limit_registry (RateLimitRegistry or None) – Rate-limit registry; defaults to animedex.transport.ratelimit.default_registry().

  • config (Config or None) – Optional Config whose user_agent, timeout_seconds, and cache_ttl_seconds fields supply defaults when the matching kwarg is not given (or is None). Explicit kwargs always win. Per plans/05 §4 every public API function honours this kwarg.

Returns:

Full envelope.

Return type:

RawResponse

selftest_backend_shim

animedex.api._dispatch.selftest_backend_shim(backend: str, call_fn: Any, *, extra_params: tuple = ()) → bool[source]

Shared offline smoke check for every per-backend shim.

Per-backend selftest functions should prove that the backend’s own call was not renamed, removed, or narrowed. This helper checks that call_fn is callable, targets a registered raw backend, has a Pythonic keyword surface, and exposes the cross-cutting kwargs every shim must thread (no_cache, cache_ttl, rate, timeout_seconds, user_agent, cache). A rename that drops one of these is a regression.

Parameters:

  • backend (str) – Backend identifier.

  • call_fn (Callable) – The shim’s public call function.

  • extra_params (tuple of str) – Backend-specific kwargs that must also be present (e.g. ("query", "variables") for anilist, ("path",) for the REST shims). Generic kwargs are checked unconditionally.

Returns:

True on success; raises on failure so the runner prints a useful traceback.

Return type:

bool

selftest

animedex.api._dispatch.selftest() → bool[source]

Smoke-test the dispatcher against an in-memory mock.

Returns:

True on success.

Return type:

bool