animedex.backends.mangadex

High-level MangaDex Python API.

Wraps the five anonymous JSON read endpoints listed in the project’s mid-tier roadmap: search / show / feed / chapter / cover. The pages (At-Home reader) endpoint is intentionally not wrapped here — it carries short-lived base URLs and HTTP/2 concurrency caps that warrant their own module in a later phase.

MangaDex’s catalogue is scanlation-driven, which means legal posture varies per series. The project’s posture is to surface upstream metadata as-is; downstream consumers decide what to do with it.

show

animedex.backends.mangadex.show(id: str, *, config: Config | None = None, **kw) → MangaDexManga[source]

Fetch one manga by its MangaDex UUID via /manga/{id}.

Parameters:: id (str) – MangaDex UUID (string; not numeric).
Returns:: Typed manga resource, lossless against the upstream JSON:API data block.
Return type:: MangaDexManga

search

animedex.backends.mangadex.search(title: str, *, limit: int = 10, offset: int = 0, config: Config | None = None, **kw) → List[MangaDexManga][source]

Search manga by free-text title via /manga?title=<title>.

Parameters:

title (str) – Search phrase.
limit (int) – Max rows per page (defaults to 10).
offset (int) – Pagination offset.

Returns:

List of typed manga resources.

Return type:

list[MangaDexManga]

feed

animedex.backends.mangadex.feed(id: str, *, limit: int = 20, offset: int = 0, lang: str | None = None, config: Config | None = None, **kw) → List[MangaDexChapter][source]

List chapters for one manga via /manga/{id}/feed.

Parameters:

id (str) – MangaDex manga UUID.
limit (int) – Max rows per page (defaults to 20).
offset (int) – Pagination offset.
lang (str or None) – Optional ISO-639 language filter (e.g. "en"). When set, filters via translatedLanguage[]=<lang>.

Returns:

List of typed chapter resources.

Return type:

list[MangaDexChapter]

chapter

animedex.backends.mangadex.chapter(id: str, *, config: Config | None = None, **kw) → MangaDexChapter[source]

Fetch one chapter by its UUID via /chapter/{id}.

Parameters:: id (str) – MangaDex chapter UUID.
Returns:: Typed chapter resource.
Return type:: MangaDexChapter

cover

animedex.backends.mangadex.cover(id: str, *, config: Config | None = None, **kw) → MangaDexCover[source]

Fetch one cover by its UUID via /cover/{id}.

The returned resource carries a fileName attribute; the public cover URL is composed as https://uploads.mangadex.org/covers/<manga-id>/<fileName>.

Parameters:: id (str) – MangaDex cover UUID.
Returns:: Typed cover resource.
Return type:: MangaDexCover

aggregate

animedex.backends.mangadex.aggregate(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]

Volume + chapter aggregation tree via /manga/{id}/aggregate.

Returns the manga’s chapters grouped by volume, structured as volumes -> chapters -> count. The shape is upstream-specific (not a JSON:API resource); surfaces as MangaDexResource with attributes carrying the aggregation tree.

recommendation

animedex.backends.mangadex.recommendation(id: str, *, config: Config | None = None, **kw) → List[MangaDexResource][source]: Manga recommendations for one manga via /manga/{id}/recommendation.

random_manga

animedex.backends.mangadex.random_manga(*, config: Config | None = None, **kw) → MangaDexManga[source]: Random manga via /manga/random.

manga_tag

animedex.backends.mangadex.manga_tag(*, config: Config | None = None, **kw) → List[MangaDexResource][source]: The full tag taxonomy via /manga/tag.

chapter_search

animedex.backends.mangadex.chapter_search(*, limit: int = 10, offset: int = 0, config: Config | None = None, **kw) → List[MangaDexChapter][source]: Search chapters via /chapter.

cover_search

animedex.backends.mangadex.cover_search(*, limit: int = 10, offset: int = 0, config: Config | None = None, **kw) → List[MangaDexCover][source]: Search covers via /cover.

author_search

animedex.backends.mangadex.author_search(*, limit: int = 10, offset: int = 0, name: str | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: Search authors via /author.

author

animedex.backends.mangadex.author(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: One author by UUID via /author/{id}.

group_search

animedex.backends.mangadex.group_search(*, limit: int = 10, offset: int = 0, name: str | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: Search scanlation groups via /group.

group

animedex.backends.mangadex.group(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: One scanlation group by UUID via /group/{id}.

list_show

animedex.backends.mangadex.list_show(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]

One custom list by UUID via /list/{id}.

Public custom lists are anonymous-readable; private ones return 403 / 404 without a token.

list_feed

animedex.backends.mangadex.list_feed(id: str, *, limit: int = 10, offset: int = 0, config: Config | None = None, **kw) → List[MangaDexChapter][source]: Chapter feed for one custom list via /list/{id}/feed.

user

animedex.backends.mangadex.user(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: One user by UUID via /user/{id} (public profile).

user_lists

animedex.backends.mangadex.user_lists(id: str, *, limit: int = 10, offset: int = 0, config: Config | None = None, **kw) → List[MangaDexResource][source]: One user’s public custom lists via /user/{id}/list.

statistics_manga

animedex.backends.mangadex.statistics_manga(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: Read / follow / rating stats for one manga via /statistics/manga/{id}.

statistics_manga_batch

animedex.backends.mangadex.statistics_manga_batch(*, manga: List[str] | None = None, config: Config | None = None, **kw) → MangaDexResource[source]: Stats for many manga at once via /statistics/manga?manga[]=<id>&manga[]=....

statistics_chapter

animedex.backends.mangadex.statistics_chapter(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: Read stats for one chapter via /statistics/chapter/{id}.

statistics_chapter_batch

animedex.backends.mangadex.statistics_chapter_batch(*, chapter: List[str] | None = None, config: Config | None = None, **kw) → MangaDexResource[source]: Stats for many chapters at once via /statistics/chapter?chapter[]=<id>&chapter[]=....

statistics_group

animedex.backends.mangadex.statistics_group(id: str, *, config: Config | None = None, **kw) → MangaDexResource[source]: Stats for one scanlation group via /statistics/group/{id}.

report_reasons

animedex.backends.mangadex.report_reasons(category: str, *, config: Config | None = None, **kw) → List[MangaDexResource][source]

Available report reasons for a category via /report/reasons/{category}.

Categories: manga / chapter / scanlation_group / user / author.

me

animedex.backends.mangadex.me(*, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → MangaDexUser[source]

Authenticated current user via /user/me.

Returns:: Typed user resource.
Return type:: MangaDexUser

my_follows_manga

animedex.backends.mangadex.my_follows_manga(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexManga][source]: Manga the authenticated user is following via /user/follows/manga.

is_following_manga

animedex.backends.mangadex.is_following_manga(id: str, *, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → bool[source]: Whether the authenticated user follows manga id via /user/follows/manga/{id} (200 → True; 404 → False).

my_follows_group

animedex.backends.mangadex.my_follows_group(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: Scanlation groups the authenticated user is following via /user/follows/group.

is_following_group

animedex.backends.mangadex.is_following_group(id: str, *, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → bool[source]: Whether the authenticated user follows scanlation group id via /user/follows/group/{id}.

my_follows_user

animedex.backends.mangadex.my_follows_user(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: Users the authenticated user is following via /user/follows/user.

is_following_user

animedex.backends.mangadex.is_following_user(id: str, *, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → bool[source]: Whether the authenticated user follows user id via /user/follows/user/{id}.

my_follows_list

animedex.backends.mangadex.my_follows_list(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: Custom lists the authenticated user is following via /user/follows/list.

my_follows_manga_feed

animedex.backends.mangadex.my_follows_manga_feed(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexChapter][source]: Chapter feed for the manga the authenticated user follows via /user/follows/manga/feed.

my_lists

animedex.backends.mangadex.my_lists(*, limit: int = 20, offset: int = 0, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]: The authenticated user’s own custom lists via /user/list.

my_history

animedex.backends.mangadex.my_history(*, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[MangaDexResource][source]

The authenticated user’s reading history via /user/history.

The upstream returns a list of {chapterId, readDate} entries wrapped in the standard envelope; the rich shape round-trips them via MangaDexResource’s catch-all attributes.

my_manga_status

animedex.backends.mangadex.my_manga_status(*, status: str | None = None, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → Dict[str, str][source]

Reading-status map for every manga the authenticated user has interacted with, via /manga/status.

The upstream returns {result, statuses: {manga-uuid: status}}; this helper returns the inner statuses map directly. Pass status="reading" (or "on_hold" / "plan_to_read" / "dropped" / "re_reading" / "completed") to filter.

Returns:: Dict mapping manga UUID → reading-status label.
Return type:: dict[str, str]

my_manga_status_by_id

animedex.backends.mangadex.my_manga_status_by_id(id: str, *, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → str | None[source]

Reading status for one manga via /manga/{id}/status.

Returns:: The status string, or None when the user has never interacted with this manga.
Return type:: str or None

my_manga_read_markers

animedex.backends.mangadex.my_manga_read_markers(id: str, *, creds: MangaDexCredentials | None = None, config: Config | None = None, **kw) → List[str][source]

Chapter-IDs the authenticated user has marked read for one manga, via /manga/{id}/read.

Returns:: List of chapter UUIDs.
Return type:: list[str]

ping

animedex.backends.mangadex.ping(*, config: Config | None = None, **kw) → str[source]: Liveness probe via /ping. Returns the upstream’s plain text body (typically "pong") so callers can confirm the upstream is reachable cheaply.

selftest

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

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

Returns:: True on success.
Return type:: bool