JikanPy

JikanPy provides two primary wrapper classes depending on your application's concurrency needs:

1. Jikan: A synchronous wrapper class for standard blocking requests.
2. AioJikan: An asynchronous wrapper class designed for asyncio environments.

Every response from the Jikan API via these wrappers includes the standard API data plus two additional fields:

• jikan_url: The requested URL (e.g., https://api.jikan.moe/v4/anime/1).
• headers: The response headers from Jikan.

You can install the current version of JikanPy from PyPI using pip.

Note: This package is jikanpy-v4. If you have the old version (jikanpy) installed, you must uninstall it first to avoid conflicts.

To upgrade or perform a clean install:

pip uninstall jikanpy
pip install --no-cache-dir jikanpy-v4

Alternatively, you can install directly from the source repository:

$ git clone https://github.com/abhinavk99/jikanpy.git 
$ cd jikanpy
$ python setup.py install

Use the AioJikan class for asynchronous applications. It is recommended to use it as an asynchronous context manager to ensure the underlying session is closed correctly.

Using as a context manager (Recommended):

import asyncio
from jikanpy import AioJikan

async def main():
    async with AioJikan() as aio_jikan:
        mushishi = await aio_jikan.anime(457)
        fma = await aio_jikan.manga(25)
        ginko = await aio_jikan.characters(425)
        kana_hanazawa = await aio_jikan.person(185)
        naruto = await aio_jikan.search(search_type='anime', query='naruto')

asyncio.run(main())

Manual instantiation: If you instantiate AioJikan manually, you must call .close() on the object to clean up resources.

aio_jikan_2 = AioJikan()
mushishi = await aio_jikan_2.anime(457)
await aio_jikan_2.close()

Use the Jikan class for standard synchronous Python scripts. It provides bindings for all Jikan API functionality.

Example usage:

from jikanpy import Jikan
jikan = Jikan()

# Get anime details
mushishi = jikan.anime(457)

# Get anime details with specific extension
mushishi_with_eps = jikan.anime(457, extension='episodes')

# Search for anime
search_result = jikan.search('anime', 'Mushishi', page=2)

# Get anime by season and year
winter_2018_anime = jikan.seasons(year=2018, season='winter')

# Get current season
current_season = jikan.seasons(extension='now')

You can override the default Jikan API endpoint or provide your own requests.Session during initialization of the Jikan class.

Custom Base URL: Use selected_base to point to a local instance of jikan-rest.

jikan = Jikan(selected_base='http://localhost:8000/v4')

Custom Requests Session: Pass a requests.Session object to the session argument to use custom persistent headers or connection pooling.

import requests
from jikanpy import Jikan

session = requests.Session()
session.headers.update({'x-test': 'true'})

jikan = Jikan(session=session)

AioJikan supports custom base URLs and aiohttp.ClientSession objects. Note that AioJikan uses aiohttp sessions, not requests sessions.

Custom Base URL and AioHTTP Session:

import aiohttp
import asyncio
from jikanpy import AioJikan

async def main():
    # Create a custom session with persistent headers
    session = aiohttp.ClientSession(headers={'x-test': 'true'})
    
    # Initialize AioJikan with custom base and session
    aio_jikan = AioJikan(selected_base='http://localhost:8000/v4', session=session)
    
    # ... perform requests ...
    
    # IMPORTANT: Close the session manually
    await session.close()

asyncio.run(main())