AniList API Wrapper
Complete, type-safe Python wrapper for the AniList GraphQL API.
Features
- Zero-config — no API key needed for public data
- Type-safe — Pydantic models for all GraphQL types
- Rate-limited — built-in token bucket (~80 req/min, stays under the 90 cap)
- Rich data — media, characters, staff, studios, airing schedules, trends, user lists
- OAuth2 support — full auth flow for authenticated operations
- CLI tool — query from the terminal
- Well-documented — docstrings on every public method
Installation
pip install anilist-wrapper
Or from source:
git clone https://github.com/enzossatolo/anilist-wrapper.git
cd anilist-wrapper
pip install -e .
Quick Start
from anilist import AniListClient, MediaSeason
client = AniListClient()
# Get an anime by ID
anime = client.get_media(1)
print(anime.title.romaji) # "Cowboy Bebop"
print(anime.average_score) # 86
print(anime.genres) # ["Action", "Adventure", "Drama", "Sci-Fi"]
# Search
results = client.search_media("Attack on Titan")
for m in results.nodes:
print(f"{m.title.english}: {m.average_score}%")
# Seasonal
summer = client.get_seasonal(2026, MediaSeason.SUMMER)
for m in summer.nodes:
print(f"{m.title.romaji} — {m.average_score}%")
# Characters
chars = client.search_characters("Lelouch")
for c in chars.nodes:
print(c.name.full)
# Close when done (or use as context manager)
client.close()
Context manager
with AniListClient() as client:
anime = client.get_media(1)
print(anime.title.romaji)
CLI Usage
# Search
anilist search "Attack on Titan"
anilist search "One Piece" --type MANGA
anilist search "isekai" --format TV --sort POPULARITY_DESC
# Get by ID
anilist get 1
anilist get 1 --json | jq .title.romaji
# Seasonal
anilist seasonal --year 2026 --season SUMMER
anilist seasonal --year 2026 --season WINTER --per-page 5
# Trending
anilist trending
anilist trending --type MANGA
# Characters
anilist character "Spike Spiegel"
anilist character "Mikasa" --json
# Studios
anilist studio "Wit Studio"
# Genres
anilist genres
# Airing schedule
anilist schedule
# User info (requires auth)
anilist user --name "someuser" --token YOUR_OAUTH_TOKEN
API Reference
AniListClient
| Method | Description |
|---|---|
get_media(id) |
Get media by AniList ID |
search_media(query) |
Search by title |
get_seasonal(year, season) |
Get seasonal media |
get_trending() |
Currently trending |
get_media_recommendations(id) |
Similar titles |
get_media_relations(id) |
Sequels, prequels, adaptations |
get_media_trends(id) |
Daily trend stats |
get_media_characters(id) |
Characters in a show |
get_media_staff(id) |
Staff for a show |
get_media_studios(id) |
Studios for a show |
get_media_rankings(id) |
Rankings |
get_character(id) |
Character by ID |
search_characters(query) |
Search characters |
get_staff(id) |
Staff by ID |
search_studios(query) |
Search studios |
get_airing_schedule() |
Upcoming episodes |
get_user(id|name) |
User profile |
get_user_list(user_id) |
User's anime/manga list |
get_genres() |
All media genres |
get_media_tags() |
All media tags |
get_site_statistics() |
Site-wide stats |
Authentication
from anilist.auth import AniListAuth
auth = AniListAuth(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
)
# Get authorization URL
url = auth.get_authorization_url()
# User visits url → redirected back with ?code=...
# Exchange code for token
token = auth.exchange_code("code_from_callback")
# Use with client
client = AniListClient(auth=auth)
user = client.get_user() # Returns the authenticated viewer
# Persist token
auth.save("token.json")
auth = AniListAuth.load("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "token.json")
Rate Limiting
AniList allows ~90 requests per minute. The wrapper defaults to 80 rpm with a token bucket that supports short bursts (up to 10 concurrent requests).
# Stricter limit
client = AniListClient(rate_limit_rpm=60)
# More burst
from anilist.rate_limiter import RateLimiter
# Internal use only — the client handles this automatically
Enums
All AniList enums are available:
from anilist import (
MediaFormat, # TV, MOVIE, OVA, ONA, etc.
MediaStatus, # FINISHED, RELEASING, etc.
MediaSeason, # WINTER, SPRING, SUMMER, FALL
MediaSort, # POPULARITY_DESC, SCORE_DESC, TRENDING_DESC, etc.
MediaSource, # ORIGINAL, MANGA, LIGHT_NOVEL, etc.
MediaListStatus, # CURRENT, PLANNING, COMPLETED, DROPPED, etc.
CharacterSort,
StaffSort,
)
Exceptions
from anilist import (
AniListError, # Base
GraphQLError, # API returned errors
RateLimitError, # HTTP 429
AuthenticationError, # Auth failure
NotFoundError, # Resource not found
ValidationError, # Input validation
)
Requirements
- Python 3.10+
- httpx >= 0.25.0
- pydantic >= 2.0.0
License
MIT
Metadata
Release files for anilist-wrapper 1.1.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| anilist_wrapper-1.1.4.tar.gz | 29.4 kB | With provenance | Details for anilist_wrapper-1.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| anilist_wrapper-1.1.4-py3-none-any.whl | Python 3 | none | any | Details for anilist_wrapper-1.1.4-py3-none-any.whl |
Total release size: 56.9 kB
Release files / anilist_wrapper-1.1.4.tar.gz
| Download URL | anilist_wrapper-1.1.4.tar.gz |
|---|---|
| Size | 29.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f790dcf37202317b30ed7034dab54994ffd103ac137e773c9c7d9242c6201625
|
|
BLAKE2b-256 checksum How to use checksums |
9858105be96e5fe61f78c20c314b8dfc79d417d5a7f4976843e70bd26f2fd9cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logRelease files / anilist_wrapper-1.1.4-py3-none-any.whl
| Download URL | anilist_wrapper-1.1.4-py3-none-any.whl |
|---|---|
| Size | 27.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
40598b59edc1698b0ecac2a2f963209984bce07d89518985de39288d27e073cb
|
|
BLAKE2b-256 checksum How to use checksums |
968b30fdfc98088c0b3587b8f1d558c413517af73da937a1b9a62d2b2abec66b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logSecurity for anilist-wrapper 1.1.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for anilist_wrapper-1.1.4.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.