animedex.backends.waifu

High-level Waifu.im Python API.

Three thin wrappers over the JSON read endpoints on api.waifu.im: tags(), images(), artists().

NSFW posture mirrors the upstream: the /images endpoint defaults to SFW only when isNsfw is omitted; pass is_nsfw=True from Python (--is-nsfw true from the CLI) to opt in to NSFW results. The flag is a transparent passthrough to the upstream’s isNsfw query parameter, not a paternalistic confirmation gate.

• animedex.backends.waifu.models
  • WaifuTag
    • WaifuTag
  • WaifuArtist
    • WaifuArtist
  • WaifuImageDimensions
    • WaifuImageDimensions
  • WaifuImage
    • WaifuImage
  • WaifuUser
    • WaifuUser
  • WaifuStats
    • WaifuStats
  • selftest
    • selftest()

tags

animedex.backends.waifu.tags(*, page_size: int | None = None, config: Config | None = None, **kw) → List[WaifuTag]

List every tag via /tags.

Each tag carries a name / slug / description plus its imageCount so callers can rank tags by popularity. The upstream wraps the response in a paginated envelope; the high-level helper returns just the items list.

Parameters:

page_size (int or None) – Optional pageSize override. None lets the upstream default apply (currently 30).

Returns:

List of typed tags.

Return type:

list[WaifuTag]

artists

animedex.backends.waifu.artists(*, page_number: int | None = None, page_size: int | None = None, config: Config | None = None, **kw) → List[WaifuArtist]

List every artist via /artists.

Parameters:

• page_number (int or None) – 1-indexed page number; None returns page 1 (the upstream default).

• page_size (int or None) – pageSize override.

Returns:

List of typed artists.

Return type:

list[WaifuArtist]

images

animedex.backends.waifu.images(*, included_tags: List[str] | None = None, excluded_tags: List[str] | None = None, is_nsfw: bool | None = None, is_animated: bool | None = None, page_number: int | None = None, page_size: int | None = None, config: Config | None = None, **kw) → List[WaifuImage]

List image records via /images with optional filters.

NSFW posture: when is_nsfw is None (the default), the parameter is omitted from the request and the upstream’s SFW-only default applies. When is_nsfw=True, NSFW images are returned. When is_nsfw=False, SFW images are returned explicitly. The flag is a transparent passthrough; the project’s posture is to inform the user about the upstream’s defaults, not to gate.

Parameters:

• included_tags (list of str or None) – Tag slugs that must be present on returned images (multiple → all-of).

• excluded_tags (list of str or None) – Tag slugs that must not be present.

• is_nsfw (bool or None) – NSFW filter. None (default) honours the upstream’s SFW-only default; True → NSFW only; False → SFW only (explicit).

• is_animated (bool or None) – True → only animated assets; False → only static; None → no filter.

• page_number (int or None) – 1-indexed page number.

• page_size (int or None) – Rows per page.

Returns:

List of typed images.

Return type:

list[WaifuImage]

tag

animedex.backends.waifu.tag(id: int, *, config: Config | None = None, **kw) → WaifuTag

Fetch one tag by numeric ID via /tags/{id}.

Parameters:

id (int) – Numeric Waifu.im tag ID.

Returns:

Typed tag.

Return type:

WaifuTag

tag_by_slug

animedex.backends.waifu.tag_by_slug(slug: str, *, config: Config | None = None, **kw) → WaifuTag

Fetch one tag by URL-safe slug via /tags/by-slug/{slug}.

Parameters:

slug (str) – Lowercased tag slug (e.g. "waifu").

Returns:

Typed tag.

Return type:

WaifuTag

artist

animedex.backends.waifu.artist(id: int, *, config: Config | None = None, **kw) → WaifuArtist

Fetch one artist by numeric ID via /artists/{id}.

Parameters:

id (int) – Numeric Waifu.im artist ID.

Returns:

Typed artist.

Return type:

WaifuArtist

artist_by_name

animedex.backends.waifu.artist_by_name(name: str, *, config: Config | None = None, **kw) → WaifuArtist

Fetch one artist by display name via /artists/by-name/{name}.

The response is the same artist envelope as /artists/{id} but additionally includes the artist’s images list.

Parameters:

name (str) – Artist display name (case-sensitive).

Returns:

Typed artist (with extra images field via extra='allow').

Return type:

WaifuArtist

image

animedex.backends.waifu.image(id: int, *, config: Config | None = None, **kw) → WaifuImage

Fetch one image by numeric ID via /images/{id}.

Parameters:

id (int) – Numeric Waifu.im image ID.

Returns:

Typed image.

Return type:

WaifuImage

stats_public

animedex.backends.waifu.stats_public(*, config: Config | None = None, **kw) → WaifuStats

Fetch the public statistics envelope via /stats/public.

Returns a small object summarising the catalogue size + lifetime request volume; useful as a cheap upstream-liveness probe.

Returns:

Typed statistics envelope.

Return type:

WaifuStats

me

animedex.backends.waifu.me(*, token: str | None = None, config: Config | None = None, **kw) → WaifuUser

Authenticated current user via /users/me.

Returns:

Typed user record (id, Discord identity, role, request counters).

Return type:

WaifuUser

selftest

animedex.backends.waifu.selftest() → bool

Smoke-test the public Waifu.im Python API (signatures only, no network).

Returns:

True on success.

Return type:

bool