animedex.entry.api

animedex api Click group + shared helpers.

The group itself lives here. Each backend subcommand is registered from its own sibling module (animedex/entry/api/<backend>.py) which imports and decorates onto api_group. Keeping each subcommand in its own file keeps any one file readable and lets contributors edit one backend’s CLI without touching the others.

Shared utilities used by every subcommand:

_default_cache() - lazy singleton SqliteCache at the platform-default path.
_output_mode_from_flags() - mutual-exclusion check on -i / -I / --debug.
_render_output() - dispatch to the four renderers.
_exit_code_for() - status-class-aware exit code.
_emit() - print + ctx.exit one-shot.
_parse_extra_headers() - turn -H "Name: Value" into a dict.
_common_request_options(), _common_output_options() - decorator factories.

all

animedex.entry.api.__all__ = ['api_group']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

ApiFieldOption

class animedex.entry.api.ApiFieldOption(*args, expose_kind: str, **kwargs)[source]

Bases: Option

Click option that preserves mixed -f / -F order.

Click normally collects values per option declaration, which loses order when two flags write to the same parameter. The raw passthrough needs gh-style last-write-wins across both flags, so each parsed value carries its kind before landing in api_fields.

__init__(*args, expose_kind: str, **kwargs)[source]

add_to_parser(parser, ctx) → None[source]

handle_parse_result(ctx, opts, args)[source]

Process the value produced by the parser from user input.

Always process the value through the Parameter’s type, wherever it comes from.

If the parameter is deprecated, this method warn the user about it. But only if the value has been explicitly set by the user (and as such, is not coming from a default).

type_cast_value(ctx, value)[source]: Convert and validate a value against the parameter’s type, multiple, and nargs.

api_group

animedex.entry.api.api_group(*args: t.Any, **kwargs: t.Any) → t.Any

Raw HTTP / GraphQL passthrough to one of the 12 upstream backends.

Each subcommand wraps one backend’s raw API surface. The dispatcher injects the project User-Agent, applies a per-backend rate-limit token bucket, and consults the local SQLite cache before issuing the request.

Output modes (mutually exclusive):
  (default)         response body only (gh-api equivalent)
  -i, --include     status line + response headers + body
  -I, --head        status line + response headers (no body)
  --debug           full RawResponse envelope as indented JSON
                    (request snapshot, redirect chain, timing,
                    cache provenance; credentials redacted)

Other behaviour:
  -X, --method METHOD     set the HTTP method on raw requests
  -f, --field K=V        add a typed field (repeatable)
  -F, --raw-field K=V    add a string field (repeatable)
  --paginate             auto-paginate supported GET endpoints
  --max-pages N          page ceiling for --paginate (default 10)
  --max-items N          item ceiling for --paginate
  --no-follow             disable 3xx auto-following
  --debug-full-body       opt out of the 64 KiB body cap in --debug
  --no-cache              skip cache lookup/write for eligible requests
  --cache TTL_SECONDS     override default cache TTL
  --rate {normal,slow}    voluntary slowdown (slow halves refill)
  -H, --header K:V        add request header (repeatable)

A caller-supplied User-Agent via --header overrides the project default verbatim.

.. rubric:: Examples

animedex api jikan /anime/52991 animedex api anilist ‘{ Media(id:154587){ title{romaji} } }’ animedex api kitsu ‘/anime?filter[text]=Frieren&page[limit]=2’ -i animedex api shikimori /api/graphql –graphql ‘{ animes(ids:”52991”){ id name }}’ animedex api jikan /anime –paginate –field q=Naruto –field limit=2 –max-pages 3 animedex api jikan /anime/52991 –method DELETE animedex api jikan /anime/52991 –debug | jq ‘{cache, timing}’

Per-backend docs (each subcommand's --help has more detail):
  anilist    https://docs.anilist.co/
  jikan      https://docs.api.jikan.moe/
  kitsu      https://kitsu.docs.apiary.io/
  mangadex   https://api.mangadex.org/docs/
  trace      https://soruly.github.io/trace.moe-api/
  danbooru   https://danbooru.donmai.us/wiki_pages/help:api
  shikimori  https://shikimori.io/api/doc
  ann        https://www.animenewsnetwork.com/encyclopedia/api.php
  ghibli     https://ghibliapi.vercel.app/
  nekos      https://docs.nekos.best/
  quote      https://animechan.io/docs
  waifu      https://docs.waifu.im/

Backend: animedex (local; routes to one of 12 upstream backends).

Rate limit: not applicable at this level (each backend’s bucket applies inside the call).

— LLM Agent Guidance — The api group is the project’s escape hatch for endpoints not covered by the higher-level commands. Each subcommand wraps one backend’s raw HTTP/GraphQL surface; the dispatcher injects the project User-Agent, applies rate limiting, and consults the local cache. Method/path choices are forwarded verbatim; unsupported –paginate combinations fall back to a single raw request rather than blocking the call. The caller owns the upstream result. The output flags (-i / -I / –debug) are shared and mutually exclusive. Use –debug when you need to inspect the full envelope (redirect chain, timing, cache provenance, fingerprint-redacted request headers) - this is the “data + debug” mode.

Caller-supplied User-Agent via –header overrides the project default verbatim. — End —

animedex.entry.api

__all__

ApiFieldOption

api_group

all