Info#

Async Kitsu API Wrapper#

Simple & asynchronus wrapper for the Kitsu API Written in python

copyright

2022-present ShomyKohai

license

MIT, see LICENSE

Core#

Client#

class askitsu.Client(token=None, *, session=None, cache_expiration=300)#

Represents a client connection to get data from Kitsu.io API

Parameters

token (str) –
Access token to make authenticated requests.

Useful when you need to fetch NSFW content, interact with users or post something.

New in version 0.4.1.
session (Optional[aiohttp.ClientSession]) – An object that represents the effective connection

token#

Token passed to the session.

Type: str

async check_user(slug)#

This function is a coroutine.

Check if the user exists on Kitsu

New in version 0.5.0.

Parameters: slug (str) – Nickname of the user
Return type: bool

async close()#

Close client connection

Return type: None

async get_anime_entry(id)#

This function is a coroutine.

Shortcut for get_entry(); returns only Anime object

Parameters: id (int) – ID of the anime
Return type: Anime

async get_characters(entry)#

This function is a coroutine.

Return a Character | List[Character]

Parameters

entry (Union[Anime, Manga]) – A valid entry to get characters (Can also be Object)
limit (int) – Number of characters to fetch

Return type

Optional[List[Character]]

async get_entry(type, id)#

This function is a coroutine.

Get an entry object (Anime | Manga | Character) by an id

Parameters

type (Entries) – The type of media to fetch
id (int) – ID of the media

Return type

Union[Anime, Manga, Character, None]

async get_manga_entry(id)#

This function is a coroutine.

Shortcut for get_entry(); returns only Manga object

New in version 0.3.0.

Parameters: id (int) – ID of the manga
Return type: Manga

async get_reviews(entry, limit=1)#

This function is a coroutine.

Get reviews of a given entry

New in version 0.3.0.

Parameters

entry (Union[Anime, Manga]) – A valid entry to get reviews (Can also be Object)
limit (int) – Limit to reviews to fetch

Return type

Optional[List[Review]]

async get_trending_entry(type, limit=10)#

This function is a coroutine.

Return a list of anime or manga (max of 10)

New in version 0.2.1.

Parameters: entry (Union[Anime, Manga]) – Entry to fetch its trending
Return type: Union[List[Anime], List[Manga], None]

async get_user(id)#

This function is a coroutine.

Get a user by their id

New in version 0.5.0.

Parameters: id (int) – The id of the user to fetch
Return type: Optional[User]

async search(type, query, limit=1)#

This function is a coroutine.

Search trough Kitsu API with the providen query and fetch the found data

Parameters

type (Entries) – The type of entry to search
query (str) – Represents the search query
limit (int) – Limit the search to a specific number of results

Return type

Union[Anime, List[Anime], Manga, List[Manga], Character, List[Character], None]

async search_anime(query, limit=1)#

This function is a coroutine.

Shortcut function to search() with the type parameter populated by the “anime” keyword

Parameters

query (str) – Represents the search query
limit (int) – Limit the search to a specific number of results

Return type

Union[Anime, List[Anime], None]

async search_manga(query, limit=1)#

This function is a coroutine.

Shortcut function to search() with the type parameter populated by the “manga” keyword

Parameters

query (str) – Represents the search query
limit (int) – Limit the search to a specific number of results

Return type

Union[Manga, List[Manga], None]

async search_user(name)#

Fetch a user by their username

name: str: Nickname of the user to fetch

Return type: Optional[User]

Anime#

class askitsu.Anime(attributes, http, cache)#

Bases: askitsu.models.core.Entry

Represents an Anime instance

id#

ID of the anime

Type: int

status#

Actual status of the given anime (E.g. “finished”)

Type: str

started_at#

Date when the anime started

Type: Optional[datetime]

ended_at#

Date when the anime ended

Type: Optional[datetime]

slug#

String identifier. Work as id to fetch data

Type: str

title#

Return canon title of the given anime

Changed in version 0.4.1.

Now it returns an instance of askitsu.Title

Type: str

canonical_title#

Returns canonical title of the given anime

New in version 0.4.1.

Type: str

episode_count#

Episode number

Type: int

episode_lenght#

Lenght of a single episode of the anime

Type: int

total_lenght#

Total lenght of all episodes (minutes)

Type: int

nsfw#

Check if the anime is NSFW or SFW Return True | False

Type: bool

yt_id#

Return id of the YouTube trailer

Type: str

cover_image#

Return cover image dict with all sizes

Changed in version 0.4.1.

Now it returns a cover image object

Type: CoverImage

poster_image#

Return poster image dict with all sizes

Changed in version 0.4.1.

Now it returns a poster image object

Type: PosterImage

rating_rank#

Return rating rank (Position on the leaderboard based on rating)

Type: int

popularity_rank#

Return popularity rank (Position on the leaderboard based on user preferences)

Type: int

youtube_url#

Return full url of YouTube trailer

Type: Optional[str]

url#

Returns url to Kitsu.io website

New in version 0.4.0.

Type: str

stream_links#

Return a list of :class:StreamLink

New in version 0.4.0.

Type: List[StreamLink]

rating#

The rating received from the community in a scale from 1 to 100

New in version 0.4.0.

Type: float

age_rating#

Age rating of the anime

New in version 0.4.0.

Type: Literal[‘G’, ‘PG’, ‘R’, ‘R18’]

categories#

Categories of the anime

New in version 0.4.0.

Type: List[Category]

subtype#

The subtype of the show

New in version 0.4.1.

Type: Literal[‘ONA’, ‘OVA’, ‘TV’, ‘movie’, ‘music’, ‘special’]

characters#

Get all characters (Max 20)

New in version 0.4.1.

Note

Use askitsu.Client.get_characters() if you want to set a limit

The limit with this property is automatically set to 20 (The highest)

Type: Union[Character, List[Character]

async episodes(limit=12)#

Returns a list of episodes

New in version 0.4.0.

limit: int: Limit of episodes to fetch. Defaults to 12.

Return type: List[Episode]

Episode#

class askitsu.Episode(attributes)#

Represent an Anime episode

New in version 0.4.0.

id#

ID of the episode

Type: int

synopsis#

Synopsis of the episode

Type: str

description#

Full description of the episode

Type: str

title#

Title of the episode

Type: str

season#

Season which the episode belong to

Type: int

number#

Episode’s number

Type: int

lenght#

Lenght of the episode (in minutes)

Type: int

thumbnail#

Url of the thumbnail

Type: str

StreamingLinks#

class askitsu.StreamLink(attributes)#

Represent an Anime stream link

id#

ID of Anime Stream links

Type: int

url#

URL of streaming service

Type: str

subs#

Avaiable subs

Type: list

dub#

Avaiable dub in streaming service

Type: list

name#

Name of the stream service

Type: str

Manga#

class askitsu.Manga(attributes, http, cache)#

Bases: askitsu.models.core.Entry

Represents a Manga instance

id#

ID of the manga

Type: int

status#

Actual status of the given manga (Ex. “finished”)

Type: str

started_at#

Date when the manga started

Type: Optional[datetime]

ended_at#

Date when the manga ended

Type: Optional[datetime]

slug#

String identifier. Work as id to fetch data

Type: str

title#

Return canon title of the given manga

Changed in version 0.4.1.

Now it returns an instance of askitsu.Title

Type: str

canonical_title#

Returns canonical title of the given manga

New in version 0.4.1.

Type: str

chapter_count#

Number of chapters

Type: int

volume_count#

Number of volumes

Type: int

cover_image#

Return cover image dict with all sizes

Changed in version 0.4.1.

Now it returns a cover image object

Type: CoverImage

poster_image#

Return poster image dict with all sizes

Changed in version 0.4.1.

Now it returns a poster image object

Type: PosterImage

rating_rank#

Return rating rank

Type: int

popularity_rank#

Return popularity rank position

Type: int

url#

Returns url to Kitsu.io website

New in version 0.4.0.

Type: str

rating#

The rating received from the community in a scale from 1 to 100

New in version 0.4.0.

Type: float

age_rating#

Age rating of the manga

New in version 0.4.0.

Type: Literal[‘G’, ‘PG’, ‘R’, ‘R18’]

categories#

Categories of the manga

New in version 0.4.0.

Type: List[Category]

subtype#

The subtype of the manga

New in version 0.4.1.

Type: Literal[‘doujin’, ‘manga’, ‘manhua’, ‘manhwa’, ‘novel’, ‘oel’, ‘oneshot’]

characters#

Get all characters (Max 20)

New in version 0.4.1.

Note

Use askitsu.Client.get_characters() if you want to set a limit

The limit with this property is automatically set to 20 (The highest)

Type: Union[Character, List[Character]

async chapters(limit=12)#

Returns a chapter list of chapters

New in version 0.4.0.

limit: int: Limit of chapters to fetch. Defaults to 12.

Return type: List[Chapter]

Chapter#

class askitsu.Chapter(attributes)#

Represent a Manga chapter

id#

ID of the chapter

Type: int

description#

Full description of the chapter

Type: str

title#

Title of the chapter

Type: str

volume_number#

Which volume the chapter belong to

Type: int

chapter#

Chapter number

Type: int

property thumbnail#

Url of the thumbnail

Return type: Optional[str]

Users#

User#

class askitsu.User(attributes, http, cache)#

Represents a user of Kitsu

New in version 0.5.0.

id#

The id of the user

Type: int

name#

Name of the user

Type: str

slug#

String identifier of the user (nickname)

Type: str

about#

About section of the user (description)

Type: str

location#

Location of the user (if set)

Type: Optional[str]

waifu_husbando#

Return the choice of the user if they have a waifu or an husbando

Type: str

followers#

Followers count of the users

Type: int

following#

Number of users that the user is following

Type: int

gender#

Gender of the user (if set)

Type: Optional[str]

comments_count#

Number of comment posted by the user

Type: int

favorites_count#

Number of favorites media of the user

Type: int

posts_count#

Number of posts

Type: int

media_reaction#

Number of interaction with medias

Type: int

pro#

Return if the user has pro tier

Type: bool

pro_tier#

Return the typology of pro

Type: Optional[str]

property avatar#

Avatar of the user

Return type: Optional[Image]

property banner#

Same as cover_image()

Return type: Optional[CoverImage]

property birthday#

Birthday of the user (if set)

Return type: Optional[datetime]

property cover_image#

Background of the user profile

Return type: Optional[CoverImage]

property created_at#

When the user registered to Kitsu

Return type: Optional[datetime]

property profile_links#

Social linked to the profile

Return type: Optional[List[UserProfile]]

UserProfile#

class askitsu.UserProfile(attributes, user)#

A profile linked to a User

id#

The id of the profile link

Type: int

name#

Name of the linked profile

Type: str

user#

Name of the user whom the profile belong to

Type: str

url#

The url to the profile of the user

Type: str

Post#

class askitsu.Post(attributes, author)#

A post made by a User

id#

ID of the post

Type: int

content#

Formatted content of the post

Type: str

nsfw#

If the post is marked as NSFW by the author

Type: bool

likes_count#

Number of likes in the post

Type: int

spoiler#

If the post is marked as spoiler by the author

Type: bool

author#

The author of the Post

Type: User

property created_at#

When the user registered to Kitsu

Return type: Optional[datetime]

LibraryEntry#

class askitsu.LibraryEntry(attributes, user, http)#

A library entry that belongs to a User

id#

ID of the LibraryEntry

Type: int

status#

Status of the Media in the library entry

Type: LibraryEntryStatus

user#

User which the library entry belongs to

Type: User

reconsume_count#

Number of reconsume of a media (E.g. Rewatch in Anime)

Type: int

reconsuming#

If the user is currently reconsuming the Media

Type: bool

rating#

Rating of the Media given by the user

Type: Optional[int]

private#

If the library entry is private

Type: bool

progress#

Progress of the user in the linked media

Type: int

media_type#

The type of the linked media: Anime or Manga

Type: str

media_id#

The ID of the linked media

Type: int

nsfw#

If the library entry is NSFW or not

Type: bool

notes#

Additional notes made by the user

Type: Optional[str]

property created_at#

When the library entry got created

Return type: Optional[datetime]

property finished_at#

When the library entry got finished

Return type: Optional[datetime]

property media#

The linked media

Return type: Union[Anime, Manga]

property progressed_at#

When the library entry got a progress update

Return type: Optional[datetime]

Misc#

Categories#

class askitsu.Category(attributes)#

Represent a category of a media.

New in version 0.4.0.

title#

Title of the category

Type: str

description#

Description of the category

Type: str

slug#

Identifier string of the category

Type: str

nsfw#

If the category is NSFW or not

Type: bool

property created_at#

When a category got added in Kitu DB

Return type: Optional[datetime]

property updated_at#

Last time a category got updated

Return type: Optional[datetime]

Character#

class askitsu.Character(attributes, entry_id=None, **kwargs)#

Represents a Character istance

New in version 0.2.0.

media_id#

ID of the character’s origin media

Type: int

id#

ID of the character

Type: int

name#

Return characters canonical name

Type: str

slug#

String identifier. Work as id to fetch data

Type: str

description#

The character’s description

Type: str

role#

Role of the character (“main” or “supporting”)

Type: Literal[str]

image#

Return character’s image

Type: str

Reviews#

class askitsu.Review(entry_id, entry_type, attributes)#

Represents a Review instance. Reviews belong to a media (Anime, Manga)

New in version 0.3.0.

id#

ID of the review

Type: int

content#

Content of the review

Type: str

progress#

User’s progress of the media at the time of the review

Type: str

Titles#

class askitsu.Title(data, entry_id=None, entry_type=None)#

Represent the various titles that a entry can have

entry_id#

The id of the media which the title belong to

Type: int

entry_type#

The type of the media (anime, manga)

Type: str

en#

The title of the media in English

Type: str

en_jp#

The title of the media in romanized Japanese

Type: str

romaji#

Same as en_jp

Type: str

ja_jp#

The title of the media in Japanese

Type: str

Assets#

Image#

class askitsu.Image(data)#

Represent a general image

tiny#

Poster image – size: tiny

Type: str

small#

Poster image – size: small

Type: str

medium#

Poster image – size: medium

Type: str

large#

Poster image – size: large

Type: str

original#

Poster image with original size

Type: str

CoverImage#

class askitsu.CoverImage(data, entry_id=None, entry_type=None)#

Cover image of a media

entry_id#

The id which the cover image belongs to

Type: int

entry_type#

The type of the media

Type: str

tiny#

Cover image – size: tiny

Type: str

small#

Cover image – size: small

Type: str

large#

Cover image – size: large

Type: str

original#

Cover image with original size

Type: str

PosterImage#

class askitsu.PosterImage(data, entry_id=None, entry_type=None)#

Poster image of a media

entry_id#

The id which the poster image belongs to

Type: int

entry_type#

The type of the media

Type: str

tiny#

Poster image – size: tiny

Type: str

small#

Poster image – size: small

Type: str

medium#

Poster image – size: medium

Type: str

large#

Poster image – size: large

Type: str

original#

Poster image with original size

Type: str

Enums#

Entries#

class askitsu.Entries(value)#

An enumeration.

ANIME = 'anime'#

CHARACTER = 'character'#

MANGA = 'manga'#

MediaType#

class askitsu.MediaType(value)#

An enumeration.

ANIME = 'ANIME'#

MANGA = 'MANGA'#

LibraryEntryStatus#

class askitsu.LibraryEntryStatus(value)#

An enumeration.

COMPLETED = 'COMPLETED'#

CURRENT = 'CURRENT'#

DROPPED = 'DROPPED'#

ON_HOLD = 'ON_HOLD'#

PLANNED = 'PLANNED'#

Errors#

AskitsuException#

HTTPError#

exception askitsu.HTTPError(msg, status)#

Represents a generic HTTP error.

Parameters

msg (str) – Error message
status (int) – Code of the HTTP response

InvalidArgument#

exception askitsu.InvalidArgument(msg=None)#

Raises when an invalid entry gets passed

Parameters: msg (str) – Error message to pass

NotAuthenticated#

exception askitsu.NotAuthenticated#: Raises when an Authenticated API request get place without being authenticated

New in version 0.3.0.

BadApiRequest#

exception askitsu.BadApiRequest(response)#: Raises when a 400 error code takes place

New in version 0.4.0.