animedex.backends.nekos

High-level nekos.best v2 Python API.

Three thin wrappers over the v2 endpoints:

• categories() — list every available category name (sugar over GET /endpoints).

• image() — fetch one or more random images / GIFs from a named category.

• search() — best-effort metadata search across all categories.

Every function accepts config and forwards transport-level keyword arguments to the underlying passthrough call.

• animedex.backends.nekos.models
  • NekosImageDimensions
    • NekosImageDimensions
  • NekosImage
    • NekosImage
  • NekosCategoryFormat
    • NekosCategoryFormat
  • selftest
    • selftest()

categories

animedex.backends.nekos.categories(*, config: Config | None = None, **kw) → List[str]

List every nekos.best v2 category name.

Calls GET /endpoints and returns just the category names, alphabetically. The richer per-category format data is available via categories_full() for callers that want the asset format and filename range.

Returns:

Alphabetised list of category names.

Return type:

list[str]

categories_full

animedex.backends.nekos.categories_full(*, config: Config | None = None, **kw) → Dict[str, NekosCategoryFormat]

List every category along with its per-category format metadata.

Calls GET /endpoints and validates each entry through NekosCategoryFormat so downstream callers get typed access to format / min / max.

Returns:

Mapping from category name to format metadata.

Return type:

dict[str, NekosCategoryFormat]

image

animedex.backends.nekos.image(category: str, *, amount: int = 1, config: Config | None = None, **kw) → List[NekosImage]

Fetch one or more random images / GIFs from a category.

Calls GET /<category>?amount=<N>. The upstream’s response body is {"results": [<NekosImage>, ...]}; each row is validated through NekosImage.

Parameters:

• category (str) – Category name (e.g. "husbando", "neko", "waifu"). Must be one of those returned by categories().

• amount (int) – Number of images to return, 1..20. Defaults to 1.

Returns:

List of images. The list is always at least one entry long when the category is valid.

Return type:

list[NekosImage]

Raises:

ApiError – bad-args for amount out of range, not-found when the category is unknown.

search

animedex.backends.nekos.search(query: str, *, type: int = 1, category: str | None = None, amount: int = 1, config: Config | None = None, **kw) → List[NekosImage]

Search nekos.best v2 by metadata.

Calls GET /search?query=<query>&type=<type>&amount=<amount> (plus optional &category=<name>). The upstream matches query against anime_name / artist_name / source_url fuzzily and always returns up to amount results — a query that nothing closely matches falls through to a near-random ranking rather than an empty list.

Parameters:

• query (str) – Search phrase.

• type (int) – Asset type filter — 1 for images (default), 2 for GIFs.

• category (str or None) – Restrict the search to one category.

• amount (int) – Maximum number of results, 1..20. Defaults to 1. The upstream returns exactly amount results in practice — there is no empty-result signal for non-matching queries.

Returns:

List of matching images.

Return type:

list[NekosImage]

Raises:

ApiError – bad-args for amount or type out of range, upstream-shape for malformed responses.

selftest

animedex.backends.nekos.selftest() → bool

Smoke-test the public nekos.best Python API (signatures only).

Confirms each public callable accepts a config keyword so the Click factory’s keyword-injection pattern works, and that the callables list matches the documented surface.

Returns:

True on success.

Return type:

bool