animedex.backends.nekos.models

Rich nekos.best dataclasses (one per response shape).

nekos.best v2 has a tiny surface — three JSON-emitting endpoints — but each carries enough metadata to make the SFW image collection useful both as a CLI grab-bag and as a Python library lookup.

The two rich shapes pinned here are deliberately per-record, not per-endpoint:

  • NekosImage — one image / GIF record. Comes back from /<category>?amount=N (each row in results) and from /search (each row in results).

  • NekosCategoryFormat — one {format, min, max} entry from /endpoints. The upstream emits a flat {<category>: {format, min, max}, ...} map, so the per-record type is what makes the lossless round-trip contract well-defined.

The NekosImage to_common() projects an upstream record onto the cross-source ArtPost. The projection is deterministic:

  • rating is always "g" (nekos.best v2 has no NSFW tier).

  • id is composed as "nekos:" + filename — nekos.best has no numeric ID column, but every URL ends in a stable filename, so the filename is the canonical identifier.

  • tags carries the upstream’s anime_name (when present) so a cross-source pipeline can match against Anime by show.

NekosImageDimensions

class animedex.backends.nekos.models.NekosImageDimensions(*, width: int | None = None, height: int | None = None, **extra_data: Any)[source]

Bases: BackendRichModel

dimensions sub-block on a NekosImage record.

Variables:

  • width (int or None) – Image width in pixels.

  • height (int or None) – Image height in pixels.

width: int | None
height: int | None

NekosImage

class animedex.backends.nekos.models.NekosImage(*, url: str, dimensions: NekosImageDimensions | None = None, anime_name: str | None = None, artist_name: str | None = None, artist_href: str | None = None, source_url: str | None = None, source_tag: SourceTag | None = None, **extra_data: Any)[source]

Bases: BackendRichModel

A single image / GIF record from nekos.best v2.

Every record exposes url and dimensions; the rest of the fields are best-effort attribution. anime_name is set on anime-derived assets; artist_name / artist_href / source_url are set on fan-art assets where the upstream knows the provenance.

Variables:

  • url (str) – Direct asset URL.

  • dimensions (NekosImageDimensions or None) – {width, height} in pixels.

  • anime_name (str or None) – Show name when the asset is anime-derived.

  • artist_name (str or None) – Artist attribution when the asset is fan art.

  • artist_href (str or None) – Artist’s profile / portfolio URL.

  • source_url (str or None) – Original source URL (pixiv / twitter / official site / etc.).

  • source_tag (SourceTag or None) – Provenance tag stamped by the high-level fetch helper.

url: str
dimensions: NekosImageDimensions | None
anime_name: str | None
artist_name: str | None
artist_href: str | None
source_url: str | None
source_tag: SourceTag | None
to_common() → ArtPost[source]

Project this image record onto the cross-source ArtPost shape.

rating is always "g" (nekos.best v2 is SFW-only). id derives from the URL’s filename, the only stable per-asset identifier nekos.best exposes. The upstream’s anime_name is propagated into tags so cross-source consumers can match on show without an extra round-trip.

Returns:

Cross-source projection.

Return type:

animedex.models.art.ArtPost

NekosCategoryFormat

class animedex.backends.nekos.models.NekosCategoryFormat(*, format: str | None = None, min: str | None = None, max: str | None = None, **extra_data: Any)[source]

Bases: BackendRichModel

Per-category format entry exposed by /endpoints.

Each category advertises a single asset format ("png" or "gif") plus the min / max filename suffix range used by the /<category>/<filename>.<format> direct-asset retrieval. The flat /endpoints payload is a map from category name to one of these entries.

Variables:

  • format (str or None) – Asset format ("png" or "gif").

  • min (str or None) – Smallest filename suffix in the category.

  • max (str or None) – Largest filename suffix in the category.

format: str | None
min: str | None
max: str | None

selftest

animedex.backends.nekos.models.selftest() → bool[source]

Smoke-test the nekos models.

Validates a synthetic NekosImage round-trips through model_dump_json / model_validate_json and projects to a well-formed ArtPost — pinning the SFW-only rating='g' invariant. Also validates a synthetic NekosCategoryFormat.

Returns:

True on success; raises on schema drift.

Return type:

bool