animedex.backends.danbooru.models

Rich Danbooru dataclasses (one per resource type).

Danbooru’s REST surface is conventional: every record returns as a flat JSON object whose keys map directly onto the rich type. The high-level helpers project image-post records onto the cross-source ArtPost shape; artists / tags / pools have no cross-source common type today and surface as their rich shape only.

Per the project’s lossless rich-model contract every class inherits from BackendRichModel (extra='allow', populate_by_name=True, frozen=True). Only the fields the high-level API touches are spelled out as typed attributes; upstream may add more (Danbooru is actively maintained), and they round-trip through model_dump losslessly via extra='allow'.

DanbooruPost

class animedex.backends.danbooru.models.DanbooruPost(*, id: int, rating: str | None = None, score: int | None = None, md5: str | None = None, file_url: str | None = None, large_file_url: str | None = None, preview_file_url: str | None = None, tag_string: str | None = None, tag_string_artist: str | None = None, source: str | None = None, image_width: int | None = None, image_height: int | None = None, fav_count: int | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

A single post (image + metadata) on Danbooru.

Variables:

• id (int) – Numeric post ID.

• rating (str or None) – Content rating, one of g / s / q / e (general / sensitive / questionable / explicit).

• score (int or None) – Net upvote score.

• md5 (str or None) – MD5 hash of the image file.

• file_url (str or None) – Full-resolution image URL.

• large_file_url (str or None) – Reduced-resolution preview URL (1280-wide).

• preview_file_url (str or None) – Thumbnail URL.

• tag_string (str or None) – Space-separated tag list (the canonical form).

• tag_string_artist (str or None) – Space-separated artist tags.

• source (str or None) – External provenance URL.

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

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

• fav_count (int or None) – Favourite count.

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

id: int

rating: str | None

score: int | None

md5: str | None

file_url: str | None

large_file_url: str | None

preview_file_url: str | None

tag_string: str | None

tag_string_artist: str | None

source: str | None

image_width: int | None

image_height: int | None

fav_count: int | None

source_tag: SourceTag | None

to_common() → ArtPost

Project this post onto the cross-source ArtPost shape.

rating round-trips directly (Danbooru’s vocabulary is the project’s normalised one). tags come from tag_string (whitespace-split). artist is the first non-empty entry in tag_string_artist. The lossless rich shape carries the rest.

DanbooruArtist

class animedex.backends.danbooru.models.DanbooruArtist(*, id: int, name: str | None = None, group_name: str | None = None, other_names: List[str] | None = None, is_deleted: bool | None = None, is_banned: bool | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

A single artist record.

id: int

name: str | None

group_name: str | None

other_names: List[str] | None

is_deleted: bool | None

is_banned: bool | None

source_tag: SourceTag | None

DanbooruTag

class animedex.backends.danbooru.models.DanbooruTag(*, id: int, name: str | None = None, post_count: int | None = None, category: int | None = None, is_deprecated: bool | None = None, words: List[str] | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

A single tag record (with usage statistics).

id: int

name: str | None

post_count: int | None

category: int | None

is_deprecated: bool | None

words: List[str] | None

source_tag: SourceTag | None

DanbooruPool

class animedex.backends.danbooru.models.DanbooruPool(*, id: int, name: str | None = None, description: str | None = None, post_ids: List[int] | None = None, post_count: int | None = None, category: str | None = None, is_active: bool | None = None, is_deleted: bool | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

A single pool record (an ordered collection of posts).

id: int

name: str | None

description: str | None

post_ids: List[int] | None

post_count: int | None

category: str | None

is_active: bool | None

is_deleted: bool | None

source_tag: SourceTag | None

DanbooruProfile

class animedex.backends.danbooru.models.DanbooruProfile(*, id: int, name: str | None = None, level: int | None = None, inviter_id: int | None = None, created_at: str | None = None, updated_at: str | None = None, last_logged_in_at: str | None = None, last_forum_read_at: str | None = None, post_upload_count: int | None = None, post_update_count: int | None = None, note_update_count: int | None = None, is_deleted: bool | None = None, favorite_tags: str | None = None, blacklisted_tags: str | None = None, comment_threshold: int | None = None, default_image_size: str | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

The authenticated user’s own profile envelope from /profile.json. Carries account-scoped fields the anonymous /users/{id}.json view omits (last_logged_in_at, blacklisted_tags, favorite_tags, comment_threshold, etc.).

id: int

name: str | None

level: int | None

inviter_id: int | None

created_at: str | None

updated_at: str | None

last_logged_in_at: str | None

last_forum_read_at: str | None

post_upload_count: int | None

post_update_count: int | None

note_update_count: int | None

is_deleted: bool | None

favorite_tags: str | None

blacklisted_tags: str | None

comment_threshold: int | None

default_image_size: str | None

source_tag: SourceTag | None

DanbooruSavedSearch

class animedex.backends.danbooru.models.DanbooruSavedSearch(*, id: int, user_id: int | None = None, query: str | None = None, labels: List[Any] | None = None, created_at: str | None = None, updated_at: str | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

One /saved_searches.json row: a user-saved tag-DSL query plus the labels the user has organised it under.

id: int

user_id: int | None

query: str | None

labels: List[Any] | None

created_at: str | None

updated_at: str | None

source_tag: SourceTag | None

DanbooruRecord

class animedex.backends.danbooru.models.DanbooruRecord(*, id: Any | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

Catch-all Danbooru record shape used by the long-tail of anonymous-readable endpoints (versions / votes / events / operational metrics / etc.) where typing every field per endpoint would multiply the model count without much benefit to a downstream caller. id is the only universal field and is typed as Any because the upstream’s primary keys vary by resource family (numeric for the typical rows; UUID string for /jobs, /metrics, and similar operational queues). Everything else round-trips via extra='allow'.

id: Any | None

source_tag: SourceTag | None

DanbooruRelatedTag

class animedex.backends.danbooru.models.DanbooruRelatedTag(*, query: str | None = None, category: str | None = None, related_tags: List[Any] | None = None, tag: Any | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

Response shape for /related_tag.json: a query echo + a ranked list of related tags. The shape is upstream-specific and not a uniform list-of-records.

query: str | None

category: str | None

related_tags: List[Any] | None

tag: Any | None

source_tag: SourceTag | None

DanbooruIQDBQuery

class animedex.backends.danbooru.models.DanbooruIQDBQuery(*, post: Any | None = None, post_id: int | None = None, score: float | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

Response shape for /iqdb_queries.json: a list of similarity-scored matches against a candidate image URL or upload.

post: Any | None

post_id: int | None

score: float | None

source_tag: SourceTag | None

DanbooruCount

class animedex.backends.danbooru.models.DanbooruCount(*, counts: dict | None = None, source_tag: SourceTag | None = None, **extra_data: Any)

Bases: BackendRichModel

The /counts/posts.json?tags=... envelope: {counts: {posts: N}}.

Wraps the upstream’s already-wrapped count so callers get a typed counts.posts access.

counts: dict | None

source_tag: SourceTag | None

total() → int | None

Return the post count, when present.

Returns:

Number of posts matching the tag query, or None if the upstream omitted the count.

Return type:

int or None

selftest

animedex.backends.danbooru.models.selftest() → bool

Smoke-test the Danbooru rich models.

Validates a synthetic DanbooruPost round-trips through model_dump_json / model_validate_json and projects to a well-formed ArtPost.

Returns:

True on success; raises on schema drift.

Return type:

bool