animedex.backends.waifu.models

Rich Waifu.im dataclasses (one per resource type).

Waifu.im wraps every listing in a {items, pageNumber, totalPages, totalCount, pageSize, hasPreviousPage, hasNextPage} envelope. The high-level API extracts items and validates each row through a typed model; per the project’s lossless contract every model inherits from BackendRichModel (extra='allow', populate_by_name=True, frozen=True) so any field upstream adds round-trips through model_dump.

The WaifuImage.to_common() projection maps image records onto the cross-source ArtPost shape. WaifuTag and WaifuArtist have no cross-source common type and surface as their rich shape only.

WaifuTag

Bases: BackendRichModel

A single tag record (also nested inside WaifuImage).

Variables:

id (int) – Numeric tag ID.
name (str or None) – Display name (capitalised, e.g. "Waifu").
slug (str or None) – URL-safe slug (lowercased, e.g. "waifu").
description (str or None) – Short description.
imageCount (int or None) – Number of images carrying this tag.
reviewStatus (str or None) – Upstream’s review state ("Accepted").

id: int

name: str | None

slug: str | None

description: str | None

imageCount: int | None

reviewStatus: str | None

creatorId: int | None

source_tag: SourceTag | None

WaifuArtist

Bases: BackendRichModel

A single artist record (also nested inside WaifuImage).

Variables:

id (int) – Numeric artist ID.
name (str or None) – Artist display name.
patreon (str or None) – Artist’s Patreon URL.
pixiv (str or None) – Artist’s Pixiv URL.
twitter (str or None) – Artist’s Twitter / X URL.
deviantArt (str or None) – Artist’s DeviantArt URL.
imageCount (int or None) – Number of images by this artist in the catalogue.

id: int

name: str | None

patreon: str | None

pixiv: str | None

twitter: str | None

deviantArt: str | None

reviewStatus: str | None

creatorId: int | None

imageCount: int | None

source_tag: SourceTag | None

WaifuImageDimensions

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

Bases: BackendRichModel

Width / height block on WaifuImage. Note that Waifu.im flattens width / height directly onto the image record rather than nesting them, so this class is here for parity with other backends’ typed access — Waifu.im itself has no nested dimensions object.

width: int | None

height: int | None

WaifuImage

Bases: BackendRichModel

A single image record from Waifu.im.

Returned by /images and /images/{id}. Carries explicit isNsfw / isAnimated flags + nested tags and artists lists.

Variables:

id (int) – Numeric image ID.
url (str) – Direct asset URL.
source (str or None) – Upstream source URL (artist’s pixiv, twitter, etc).
isNsfw (bool or None) – NSFW flag — the canonical signal for the isNsfw= query parameter on /images.
isAnimated (bool or None) – Whether the asset is an animated GIF / WebP.
width (int or None) – Image width in pixels.
height (int or None) – Image height in pixels.
dominantColor (str or None) – Hex colour summarising the image (used for placeholder backgrounds).
tags (list of WaifuTag) – Nested list of typed tag records.
artists (list of WaifuArtist) – Nested list of typed artist records.

id: int

url: str

source: str | None

isNsfw: bool | None

isAnimated: bool | None

width: int | None

height: int | None

perceptualHash: str | None

extension: str | None

dominantColor: str | None

uploaderId: int | None

uploadedAt: str | None

byteSize: int | None

favorites: int | None

likedAt: str | None

addedToAlbumAt: str | None

reviewStatus: str | None

tags: List[WaifuTag]

artists: List[WaifuArtist]

albums: List[dict] | None

source_tag: SourceTag | None

to_common() → ArtPost[source]

Project this image onto the cross-source ArtPost shape.

rating derives from isNsfw: True → "e" (Danbooru’s explicit), False → "g" (general). tags come from the nested tags[].slug list. artist is the first nested artist’s name, when present.

WaifuUser

Bases: BackendRichModel

The authenticated user record from /users/me.

Variables:

id (int) – Numeric Waifu.im user id.
name (str or None) – Display name (typically the user’s Discord username).
discordId (str or None) – Discord snowflake.
avatarUrl (str or None) – Discord-issued avatar URL.
role (str or None) – Role label ("User" / "Moderator" / "Administrator" etc.).

id: int

name: str | None

discordId: str | None

avatarUrl: str | None

role: str | None

isBlacklisted: bool | None

blacklistReason: str | None

requestCount: int | None

apiKeyRequestCount: int | None

jwtRequestCount: int | None

uploadedAt: str | None

source_tag: SourceTag | None

WaifuStats

Bases: BackendRichModel

Public-statistics envelope from /stats/public: counters summarising the upstream’s content + traffic.

Variables:

totalRequests (int or None) – Total request count served by the upstream (lifetime).
totalImages (int or None) – Total image count in the catalogue.
totalTags (int or None) – Total tag count.
totalArtists (int or None) – Total artist count.

totalRequests: int | None

totalImages: int | None

totalTags: int | None

totalArtists: int | None

source_tag: SourceTag | None

selftest

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

Smoke-test the Waifu.im rich models.

Validates a synthetic WaifuImage round-trips through model_dump_json / model_validate_json and projects to a well-formed ArtPost, including the isNsfw → rating mapping.

Returns:: True on success; raises on schema drift.
Return type:: bool