mal package

Submodules

mal.anime module

class mal.anime.Song(data: MusicPayload)

Bases: object

Represents a single song for an anime

id: the id of this song in the MAL database

description: string containing title author and episodes where this theme was used

class mal.anime.Music(data: Sequence[MusicPayload])

Bases: object

Represents opening or ending themes for an anime. Iterate over this to get all songs.

class mal.anime.Statistics(data: StatisticsPayload)

Bases: object

Current statistics for this anime.

watching: number of people who have this title marked as ‘watching’

completed: number of people who have this title marked as ‘completed’

on_hold: number of people who have this title marked as ‘on_hold’

dropped: number of people who have this title marked as ‘dropped’

plan_to_watch: number of people who have this title marked as ‘plan_to_watch’

total_users: total number of people who have this title in their list and it is equal to the sum of all the other attributes

class mal.anime.Anime(payload: AnimePayload)

Bases: Result

Represents a full Anime object with all the possible fields. If some fields were excluded from the query then None or a default value will be returned for those, see description of each field.

status: current publication status, None if not requested

media_type: the type of anime, None if not requested

num_episodes: number of episodes

broadcast_day: day of the week when the episodes are broadcasted

broadcast_time: time of the day of the broadcasting

source: from where the anime was adapted or if it is an original, None if not requested

average_episode_duration: duration of the episodes in seconds

rating: pg rating of the anime

openings: opening themes used for this anime, None if not requested

endings: ending themes used for this anime, None if not requested

statistics: information about how many people have completed this, watching, etc, None if not requested

raw: The raw json data for this object as returned by the API.

property start_season: str: The starting season, for example ‘spring 2016’.

property studios: str: All the studios that were involved in the production.

property is_airing: bool: Returns True if the anime is currently airing, False otherwise.

property is_finished: bool: Returns True if the anime is finished, False otherwise.

property not_aired: bool: Returns True if the anime has not yet aired, False otherwise.

property url: str: URL to the MAL page for this anime.

property api_url: str: URL to request this title from the MAL API.

load_fields(client: Client, *, fields: Sequence[Union[str, Field]] = MISSING) → None

Load additional information for this title.

Note

This operation requires an extra call to the API. If you know from the beginning the fields that you are going to need it’s better to request them all from the start.

Parameters: client – The client used to make requests
Keyword Arguments: fields – The extra fields to request. If some fields are already present they are refreshed. This argument is optional, if not passed it uses the default fields that are set in the client.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was created in the MAL database.

property end_date: Optional[datetime.date]: Returns the ending date as a datetime.date.

property main_picture_url: str: URL to the highest resolution picture available for this title.

property pictures: Optional[List[str]]: List of urls of the available pictures.

property start_date: Optional[Union[datetime.date, int]]: Returns the starting date as a datetime.date.

property title: str: Title of the result. Shorthand for result.titles.title.

property updated_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was last updated in the MAL database.

class mal.anime.AnimeSearchResults(data: AnimeSearchPayload)

Bases: PaginatedObject

Container for anime search results. Iterable and printable.

raw: The raw json data for this object as returned by the API.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.anime.AnimeListEntryStatus(data: AnimeListEntryStatusPayload)

Bases: ListStatus

Represents the status for an entry in a user anime list. Note that since this is marked by the user it can be inconsistent, for example can be marked as completed even if the anime is not yet finished.

status: completed, plan_to_watch, etc

num_episodes_watched: number of episodes that the user has seen so far

is_rewatching: whether the user is rewatching this series

num_times_rewatched: number of times the user has rewatched the series

rewatch_value: integer number quantifying the rewatch value

property completed: bool: True if the user has marked this series as completed.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the user updated the entry.

property end_date: Optional[datetime.date]: The ending date as a datetime.date.

property start_date: Optional[datetime.date]: The ending date as a datetime.date.

class mal.anime.AnimeListEntry(data: AnimeListEntryPayload)

Bases: UserListEntry

Represents a row in the anime list.

entry: the anime of this entry

list_status: all the information about the status

property score: int: Returns the score for this entry.

class mal.anime.AnimeList(data: AnimeListPayload)

Bases: UserList

Iterable object containing the anime list of a user.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.anime.AnimeRanking(data: AnimeRankingPayload, type: Union[str, AnimeRankingType])

Bases: Ranking

Container for anime rankings.

type: the criterion of this ranking

raw: The raw json data for this object as returned by the API.

get(rank: int) → Anime

Returns the entry corresponding to the given rank.

Parameters: rank – the rank of the entry to get
Raises: KeyError – the rank is not present

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.anime.Seasonal(data: SeasonalAnimePayload)

Bases: PaginatedObject

Container for seasonal anime searches.

year: the year of this season

season: which season was requested

raw: The raw json data for this object as returned by the API.

property season_info: str: Information about the season.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

mal.base module

Contains the definitions for the base classes used in other modules.

class mal.base.PaginatedObject(data: PaginatedPayload)

Bases: object

Base class for results that can consist of multiple pages. Implements the method to request the next page.

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.base.BaseResult(payload: BaseResultPayload)

Bases: object

Represents the base for an Anime or Manga objects. This fields are always returned by the API no matter the fields that are requested.

id: the id of the result NOTE: this is not unique for each object only between objects of the same category for example, all anime have different id but an anime and a manga can have same id

titles: Titles object for title information.

raw: The raw json data for this object as returned by the API.

property title: str: Title of the result. Shorthand for result.titles.title.

property main_picture_url: str: URL to the highest resolution picture available for this title.

class mal.base.Related(data: Sequence[RelationPayload])

Bases: object

Represents related anime or manga.

Printing it returns a string with all the pairs relation: title. Can return prequel, sequel and access to all the entries.

property prequel: Optional[mal.base.BaseResult]: Prequel for this title. If there isn’t any returns None.

property sequel: Optional[mal.base.BaseResult]: Sequel for this title. If there isn’t any returns None.

property all: Dict[str, List[mal.base.BaseResult]]: All the available data returned as a dictionary.

class mal.base.Recommendation(data: Sequence[RecommendationPayload])

Bases: object

Recommendation data.

For now it is only used to print the recommendations sorted by the number of users who gave it.

property top_recommendation: Optional[str]: Recommendation with the highest number of users. Returns None if there aren’t any.

class mal.base.Result(payload: ResultPayload)

Bases: BaseResult

Represents the base for search results objects. Both Anime and Manga inherits from this as it contains the common fields between the two.

titles: all the alternative titles, including both english and japanese ones

synopsis: synopsis available on the MAL page

mean: average score given by user rating

rank: position in the ranking by score

popularity: position in the ranking by users who have this title in their list

num_list_users: number of users who have this title in their list

num_scoring_users: number of users who gave a score to this title

nsfw: the level of nsfw, can be white, gray or black

genres: the different genres that this title falls under

background: some background information of the title

related_anime: all the anime related to this title

related_manga: all the manga related to this title

recommendations: similar titles that users have recommended if you liked this one

raw: The raw json data for this object as returned by the API.

property start_date: Optional[Union[datetime.date, int]]: Returns the starting date as a datetime.date.

property end_date: Optional[datetime.date]: Returns the ending date as a datetime.date.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was created in the MAL database.

property updated_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was last updated in the MAL database.

property pictures: Optional[List[str]]: List of urls of the available pictures.

property url: str: Placeholder for the url of the entry.

property api_url: str: Placeholder for the url to request this title from the API.

load_fields(client: Client, *, fields: Sequence[Union[str, Field]] = MISSING) → Any

Load additional information for this title.

Note

This operation requires an extra call to the API. If you know from the beginning the fields that you are going to need it’s better to request them all from the start.

Parameters: client – The client used to make requests
Keyword Arguments: fields – The extra fields to request. If some fields are already present they are refreshed. This argument is optional, if not passed it uses the default fields that are set in the client.

property main_picture_url: str: URL to the highest resolution picture available for this title.

property title: str: Title of the result. Shorthand for result.titles.title.

class mal.base.ListStatus(data: ListStatusPayload)

Bases: object

Information that is associated to an entry in a user list.

score: the score that the user gave to this title

priority: numeric value of the priority given to this title

tags: list of tags that the user categorized this title as

property start_date: Optional[datetime.date]: The ending date as a datetime.date.

property end_date: Optional[datetime.date]: The ending date as a datetime.date.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the user updated the entry.

class mal.base.UserListEntry(data: ListEntryPayload)

Bases: object

Represents an entry in a user list.

property score: int: Returns the score for this entry.

class mal.base.UserList(data: Union[AnimeListPayload, MangaListPayload])

Bases: PaginatedObject

Base for representing a user list.

average_score: The averege score of all rated titles. It’s 0.0f if not computable.

raw: The raw json data for this object as returned by the API.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.base.Ranking(data: RankingPayload, type: Any)

Bases: PaginatedObject

Base for representing ranking results.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

mal.client module

Module in charge of making requests to the API and managing possible errors.

class mal.client.Client(client_id: str)

Bases: object

Offers the interface to make requests.

property search_limit: int: Maximum number of results per page. Defaults to 10. Can be changed with any integer between 1 and 100. If a number outside of this range is given then the value is set to the closest value inside the range.

property anime_fields: List[mal.enums.Field]: Current fields that are requested in a anime query. Change this to change the fields that are requested. To change fields only for one request you should pass them to the search instead.

property manga_fields: List[mal.enums.Field]: Current fields that are requested in a manga query. Change this to change the fields that are requested. To change fields only for one request you should pass them to the search instead.

property include_nsfw: bool: Whether searches and lists include titles marked as nsfw. Defaults to False. Can be also specified for each query using the corresponding keyword, overriding this setting.

anime_search(query: str, *, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING, include_nsfw: bool = MISSING) → AnimeSearchResults

Search anime matching the given query. By default it uses the default parameters or the ones that have been set in limit and fields. If you pass limit and fields to this method they are used for this query only.

Parameters

query – string used to search titles, minimum length 3 characters

Keyword Arguments

limit – maximum number of results, needs to be between 1 and 100
offset – get results at a certain offset from the start, defaults to 0
fields – the fields that are going to be requested, for a complete list see Field enum
include_nsfw – include results marked as nsfw

Returns

iterable object containing the results

Return type

AnimeSearchResults

manga_search(query: str, *, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING, include_nsfw: bool = MISSING) → MangaSearchResults

Search manga matching the given query. By default it uses the default parameters or the ones that have been set in limit and fields. If you pass limit and fields to this method they are used for this query only.

Parameters

query – string used to search titles, minimum length 3 characters

Keyword Arguments

limit – maximum number of results, needs to be between 1 and 100
offset – get results at a certain offset from the start, defaults to 0
fields – the fields that are going to be requested, for a complete list see Field enum
include_nsfw – include results marked as nsfw

Returns

iterable object containing the results

Return type

MangaSearchResults

get_anime(id: Union[int, str], *, fields: Sequence[Union[Field, str]] = MISSING) → Anime

Get the details for a specific anime given the id.

Parameters: id – the id of the anime or the url of its MAL page
Keyword Arguments: fields – list of fields to retrieve for this request
Returns: the anime object with all the details
Return type: Anime

get_manga(id: Union[int, str], *, fields: Sequence[Union[Field, str]] = MISSING) → Manga

Get the details for a specific manga given the id.

Parameters: id – the id of the manga or the url of its MAL page
Keyword Arguments: fields – list of fields to retrieve for this request
Returns: the anime object with all the details
Return type: Manga

get_anime_list(username: str, *, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING, status: Union[AnimeListStatus, str] = MISSING, sort: Union[AnimeListSort, str] = MISSING, include_nsfw: bool = MISSING) → AnimeList

Returns the anime list of a specific user, if public.

Parameters

username – the MAL username of the user, case insensitive

Keyword Arguments

limit – set the number of entries to retrieve, defaults to 10
offset – get results at a certain offset from the start, defaults to 0
fields – set which fields to get for each entry
status – return only a specific category. will return all if omitted
sort – specify the sorting of the list
include_nsfw – include results marked as nsfw

Returns

iterable with all the entries of the list

Return type

AnimeList

get_manga_list(username: str, *, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING, status: Union[MangaListStatus, str] = MISSING, sort: Union[MangaListSort, str] = MISSING, include_nsfw: bool = MISSING) → MangaList

Returns the manga list of a specific user, if public.

Parameters

username – the MAL username of the user, case insensitive

Keyword Arguments

limit – set the number of entries to retrieve, defaults to 10
offset – get results at a certain offset from the start, defaults to 0
fields – set which fields to get for each entry
status – return only a specific category. will return all if omitted
sort – specify the sorting of the list
include_nsfw – include results marked as nsfw

Returns

iterable with all the entries of the list

Return type

MangaList

get_seasonal_anime(year: int, season: Union[str, Season], *, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING, include_nsfw: bool = MISSING) → Seasonal

Returns the list of anime aired during a specific season.

Parameters

year – the desired year
season – the desired season, can be winter, spring, summer or fall. | In particular they correspond to specific months | winter -> January, February, March | spring -> April, May, June | summer -> July, August, September | fall -> October, November, December

Keyword Arguments

limit – set the number of entries to retrieve, defaults to 10
offset – get results at a certain offset from the start, defaults to 0
fields – set which fields to get for each entry
include_nsfw – include results marked as nsfw

Returns

container for the results, sorted by score

Return type

Seasonal

get_anime_ranking(*, ranking_type: Union[str, AnimeRankingType] = AnimeRankingType.all, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING) → AnimeRanking

Returns the top anime in the rankings.

Keyword Arguments

ranking_type – the type of ranking to request, defaults to all. For all possible values see enums.AnimeRanking
limit – numbers of entries to request
offset – get results at a certain offset from the start, defaults to 0
fields – set which fields to get for each entry

Returns

the results

Return type

AnimeRanking

Raises

ValueError – ranking_type is invalid, check AnimeRankingType for all options

get_manga_ranking(*, ranking_type: Union[str, MangaRankingType] = MangaRankingType.all, limit: int = MISSING, offset: int = MISSING, fields: Sequence[Union[Field, str]] = MISSING) → MangaRanking

Returns the top manga in the rankings.

Keyword Arguments

ranking_type – the type of ranking to request, defaults to all. For all possible values see enums.MangaRanking
limit – numbers of entries to request
offset – get results at a certain offset from the start, defaults to 0
fields – set which fields to get for each entry

Returns

the results

Return type

MangaRanking

Raises

ValueError – ranking_type is invalid, check MangaRankingType for all options

get_boards() → Sequence[BoardCategory]: Returns a list of the forum boards divided by category.

get_topics(*, query: str = MISSING, board_id: int = MISSING, subboard_id: int = MISSING, limit: int = MISSING, offset: int = MISSING, topic_user_name: str = MISSING, user_name: str = MISSING) → ForumTopics

Returns all the topics matching the given parameters. At least one of the arguments must be specified.

Keyword Arguments

query – query used to search topics, minimum length 3 characters
board_id – limit the search to a specific board
subboard_id – limit the search to a specific subboard
limit – maximum number of results, between 1 and 100
offset – get results at a certain offset from the start, defaults to 0
topic_user_name – return only topics started by a specific user
user_name – return topics where the user has partecipated NOTE: the difference between topic_user_name and user_name is not clear to get all posts by a user use only topic_user_name

Raises

ValueError – no argument was specified

get_topic_details(topic_id: int, *, limit: int = MISSING, offset: int = MISSING) → Discussion

Returns all the details on a given topic.

Parameters

topic_id – required, the id of the topic to request

Keyword Arguments

limit – the number of posts to retrieve, defaults to 100
offset – get results at a certain offset from the start, defaults to 0

get_url(url: Optional[str]) → Any: Get the raw json data from the given url. Mostly for internal use.

mal.endpoints module

All the available endpoints of the MAL API v2, excluding the ones that require user login to perform actions.

class mal.endpoints.Endpoint(value)

Bases: Enum

Characterize the available endpoints. Each entry has two fields: url and limit.

Attributes: url: contains the url to the endpoint limit: optional, contains the maximum value for the limit parameter for that endpoint.

ANIME = ('https://api.myanimelist.net/v2/anime', 100)

ANIME_RANKING = ('https://api.myanimelist.net/v2/anime/ranking', 500)

ANIME_SEASONAL = ('https://api.myanimelist.net/v2/anime/season', 500)

ANIME_SUGGESTIONS = ('https://api.myanimelist.net/v2/anime/suggestions', 100)

MANGA = ('https://api.myanimelist.net/v2/manga', 100)

MANGA_RANKING = ('https://api.myanimelist.net/v2/manga/ranking', 500)

USER = ('https://api.myanimelist.net/v2/users', None)

USER_ANIMELIST = ('https://api.myanimelist.net/v2/users/{username}/animelist', 1000)

USER_MANGALIST = ('https://api.myanimelist.net/v2/users/{username}/mangalist', 1000)

FORUM_BOARDS = ('https://api.myanimelist.net/v2/forum/boards', None)

FORUM_TOPICS = ('https://api.myanimelist.net/v2/forum/topics', 100)

FORUM_TOPIC_DETAIL = ('https://api.myanimelist.net/v2/forum/topic', 100)

property is_anime: bool

property is_manga: bool

property is_list: bool

mal.enums module

class mal.enums.BaseEnumMeta(cls, bases, classdict)

Bases: EnumMeta

mro(): Return a type’s method resolution order.

class mal.enums.BaseEnum(value)

Bases: Enum

Base class for all the constants used to represent the possible different values some fields. Can be printed directly and can be compared with a string if needed.

Example

print(Field.id) —> id Field.id == ‘id’ —> True

class mal.enums.AnimeStatus(value)

Bases: BaseEnum

An enumeration.

airing = 'currently_airing'

finished = 'finished_airing'

not_aired = 'not_yet_aired'

class mal.enums.AnimeMediaType(value)

Bases: BaseEnum

An enumeration.

movie = 'movie'

music = 'music'

ona = 'ona'

ova = 'ova'

special = 'special'

tv = 'tv'

unknown = 'unknown'

class mal.enums.MangaStatus(value)

Bases: BaseEnum

An enumeration.

finished = 'finished'

not_published = 'not_yet_published'

publishing = 'currently_publishing'

on_hiatus = 'on_hiatus'

discontinued = 'discontinued'

class mal.enums.MangaMediaType(value)

Bases: BaseEnum

An enumeration.

doujinshi = 'doujinshi'

light_novel = 'light_novel'

manga = 'manga'

manhua = 'manhua'

manhwa = 'manhwa'

novel = 'novel'

oel = 'oel'

one_shot = 'one_shot'

unknown = 'unknown'

class mal.enums.NSFWlevel(value)

Bases: BaseEnum

An enumeration.

black = 'black'

gray = 'gray'

white = 'white'

class mal.enums.AdaptationFrom(value)

Bases: BaseEnum

An enumeration.

game = 'game'

light_novel = 'light_novel'

manga = 'manga'

novel = 'novel'

original = 'original'

visual_novel = 'visual_novel'

other = 'other'

koma_manga = '4_koma_manga'

web_manga = 'web_manga'

digital_manga = 'digital_manga'

card_game = 'card_game'

book = 'book'

picture_book = 'picture_book'

radio = 'radio'

music = 'music'

web_novel = 'web_novel'

mixed_media = 'mixed_media'

class mal.enums.AnimeListStatus(value)

Bases: BaseEnum

An enumeration.

completed = 'completed'

dropped = 'dropped'

on_hold = 'on_hold'

plan_to_watch = 'plan_to_watch'

watching = 'watching'

class mal.enums.MangaListStatus(value)

Bases: BaseEnum

An enumeration.

completed = 'completed'

dropped = 'dropped'

on_hold = 'on_hold'

plan_to_read = 'plan_to_read'

reading = 'reading'

class mal.enums.AnimeListSort(value)

Bases: BaseEnum

An enumeration.

score = 'list_score'

updated_at = 'list_updated_at'

title = 'anime_title'

start_date = 'anime_start_date'

id = 'anime_id'

class mal.enums.MangaListSort(value)

Bases: BaseEnum

An enumeration.

score = 'list_score'

updated_at = 'list_updated_at'

title = 'manga_title'

start_date = 'manga_start_date'

id = 'manga_id'

class mal.enums.Season(value)

Bases: BaseEnum

An enumeration.

winter = 'winter'

spring = 'spring'

summer = 'summer'

fall = 'fall'

class mal.enums.AnimeRankingType(value)

Bases: BaseEnum

An enumeration.

all = 'all'

airing = 'airing'

upcoming = 'upcoming'

tv = 'tv'

ova = 'ova'

movie = 'movie'

special = 'special'

by_popularity = 'bypopularity'

favorite = 'favorite'

class mal.enums.MangaRankingType(value)

Bases: BaseEnum

An enumeration.

all = 'all'

manga = 'manga'

novels = 'novels'

oneshots = 'oneshots'

douhin = 'doujin'

manhwa = 'manhwa'

manhua = 'manhua'

by_popularity = 'bypopularity'

favorite = 'favorite'

class mal.enums.Field(value)

Bases: BaseEnum

An enumeration.

id = 'id'

title = 'title'

main_picture = 'main_picture'

alternative_titles = 'alternative_titles'

start_date = 'start_date'

end_date = 'end_date'

synopsis = 'synopsis'

mean = 'mean'

rank = 'rank'

popularity = 'popularity'

num_list_users = 'num_list_users'

num_scoring_users = 'num_scoring_users'

nsfw = 'nsfw'

created_at = 'created_at'

updated_at = 'updated_at'

media_type = 'media_type'

status = 'status'

genres = 'genres'

pictures = 'pictures'

background = 'background'

related_anime = 'related_anime'

related_manga = 'related_manga'

recommendations = 'recommendations'

num_episodes = 'num_episodes'

start_season = 'start_season'

broadcast = 'broadcast'

source = 'source'

average_episode_duration = 'average_episode_duration'

rating = 'rating'

studios = 'studios'

statistics = 'statistics'

opening_themes = 'opening_themes'

ending_themes = 'ending_themes'

authors = 'authors'

num_chapters = 'num_chapters'

num_volumes = 'num_volumes'

serialization = 'serialization'

property anime_fields: List[mal.enums.Field]: Returns all the fields that can be requested for an anime.

property is_anime: bool

property manga_fields: List[mal.enums.Field]: Returns all the fields that can be requested for a manga.

property is_manga: bool

classmethod from_list(fields: Sequence[Union[Field, str]]) → List[Field]

Returns the list of fields from the corresponding string representation.

Parameters: fields – list of fields
Returns: converted fields
Return type: List[Field]
Raises: ValueError – one or more strings are not a valid field

classmethod base() → List[Field]

classmethod default_anime() → List[Field]: Default fields that are requested for an anime.

classmethod default_manga() → List[Field]: Default fields that are requested for a manga.

classmethod all_anime() → List[Field]: All the fields that can be requested for an anime.

classmethod all_manga() → List[Field]: All the fields that can be requested for a manga.

mal.forum module

class mal.forum.SubBoard(data: SubBoardPayload)

Bases: object

Represent a subboard of a forum board.

id: the id of the subboard

title: the title of the subboard

class mal.forum.Board(data: BoardPayload)

Bases: object

Represents a forum board.

id: the id of the board

title: the title of the board

description: the description of the board

subboards: list of all the subboards of the current board

class mal.forum.BoardCategory(data: BoardCategoryPayload)

Bases: object

Boards grouped by category.

title: the name of this cateogry

boards: list of boards belonging to this category

class mal.forum.Topic(data: TopicPayload)

Bases: object

Represent a forum topic.

id: the id of the topic

title: description for this topic

created_by: name of the user who created the topic

number_of_posts: the number of posts under this topic

last_post_created_by: name of the user who created the last post

is_locked: whether the post is locked

property created_at: datetime.datetime: ISO 8061 datetime of when the topic was created.

property last_post_created_at: datetime.datetime: ISO 8061 datetime of when last post in this topic was created

class mal.forum.ForumTopics(data: ForumTopicsPayload, query: str)

Bases: PaginatedObject

Results of a topic query. Contains the resulting topics.

query: query that gave these results

raw: The raw json data for this object as returned by the API.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.forum.ForumUser(data: ForumUserPayload)

Bases: object

Represents a forum user.

id: id of the user

name: nickname of the user

avatar: url to the profile picture used in the forum

class mal.forum.PollOption(data: PollOptionPayload)

Bases: object

Represents an option in a poll.

id: id of this option

text: the text of this option

votes: number of votes for this option

class mal.forum.Poll(data: PollPayload)

Bases: object

Represents a poll posted on the forum.

id: id of the poll

question: the question of the poll

closed: whether the poll is closed or not

options: list of options

property num_options: int: The number of options available.

property total_votes: int: Total number of votes in this poll across all options.

property winner: mal.forum.PollOption: Returns the option that is currently winning. It is the definitive winner if the poll is closed.

class mal.forum.ForumPost(data: ForumPostPayload)

Bases: object

Represents a post on a board.

id: id of the post

number: the post number in the discussion, is assigned in order of reply

created_by: the user who created this post

body: the text of the post

signature: the signature of the author of this post

property created_at: datetime.datetime: ISO 8061 datetime of when the post was created.

class mal.forum.Discussion(data: DiscussionPayload)

Bases: object

Represents a discussion on a board.

title: the title of the discussion

posts: list of all posts under this discussion

poll: optional, poll in this discussio

raw: The raw json data for this object as returned by the API.

property num_posts: int: Shorthand for len(discussion.posts).

class mal.forum.TopicDetail(data: TopicDetailPayload)

Bases: PaginatedObject

Results for a topic detail query. Contains the discussions under this topic.

raw: The raw json data for this object as returned by the API.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

mal.genre module

class mal.genre.Genre(data: GenericPayload)

Bases: object

Represents a specific genre. It has two read only properties that are the id and the name of the genre.

id: The id of the genre.

name: The name of the genre.

mal.manga module

class mal.manga.Author(data: AuthorPayload)

Bases: object

Represents an author for a manga.

id: the id in the MAL database

first_name: the first name of the author

last_name: the last name of the author

role: the role that the author has

property full_name: Returns the full name of the author if available.

class mal.manga.Manga(payload: MangaPayload)

Bases: Result

Represents a full Manga object with all the possible fields. If some fields were excluded from the query then None or a default value will be returned for those, see description of each field.

status: current publication status, None if not requested

media_type: the type of manga, None if not requested

authors: list of authors that created the manga

num_chapters: the number of chapters in total, 0 if not completed

num_volumes: the number of volumes in total, 0 if not completed

raw: The raw json data for this object as returned by the API.

property serialization: Magazines or other formats where the series is published.

property is_publishing: bool: Returns True if the manga is currently publishing, False otherwise.

property is_finished: bool: Returns True if the manga is finished, False otherwise.

property not_published: bool: Returns True if the manga has not yet published, False otherwise.

property is_discontinued: bool: Returns True if the manga is discontinued, False otherwise.

property on_hiatus: bool: Returns True if the manga is on hiatus, False otherwise.

property url: str: URL to the MAL page for this manga.

property api_url: str: URL to request this title from the MAL API.

load_fields(client: Client, *, fields: Sequence[Union[str, Field]] = MISSING) → None

Load additional information for this title.

Note

This operation requires an extra call to the API. If you know from the beginning the fields that you are going to need it’s better to request them all from the start.

Parameters: client – The client used to make requests
Keyword Arguments: fields – The extra fields to request. If some fields are already present they are refreshed. This argument is optional, if not passed it uses the default fields that are set in the client.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was created in the MAL database.

property end_date: Optional[datetime.date]: Returns the ending date as a datetime.date.

property main_picture_url: str: URL to the highest resolution picture available for this title.

property pictures: Optional[List[str]]: List of urls of the available pictures.

property start_date: Optional[Union[datetime.date, int]]: Returns the starting date as a datetime.date.

property title: str: Title of the result. Shorthand for result.titles.title.

property updated_at: Optional[datetime.datetime]: ISO 8061 datetime of when the entry was last updated in the MAL database.

class mal.manga.MangaSearchResults(data: MangaSearchPayload)

Bases: PaginatedObject

Container for manga search results. Iterable and printable.

raw: The raw json data for this object as returned by the API.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.manga.MangaListEntryStatus(data: MangaListEntryStatusPayload)

Bases: ListStatus

Represents the status for an entry in a user manga list. Note that since this is marked by the user it can be inconsistent, for example can be marked as completed even if the manga is not yet finished.

status: completed, plan_to_watch, etc

num_volumes_read: number of volumes that the user has read so far

num_chapters_read: number of chapters that the user has read so far

is_rereading: whether the user is rereading this series

num_times_reread: number of times the user has reread the series

rewatch_value: integer number quantifying the rewatch value

property completed: bool: True if the user has marked this series as completed.

property created_at: Optional[datetime.datetime]: ISO 8061 datetime of when the user updated the entry.

property end_date: Optional[datetime.date]: The ending date as a datetime.date.

property start_date: Optional[datetime.date]: The ending date as a datetime.date.

class mal.manga.MangaListEntry(data: MangaListEntryPayload)

Bases: UserListEntry

Represents a row in the manga list.

entry: the manga of this entry

list_status: all the information about the status

property score: int: Returns the score for this entry.

class mal.manga.MangaList(data: MangaListPayload)

Bases: UserList

Iterable object containing the manga list of a user.

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

class mal.manga.MangaRanking(data: MangaRankingPayload, type: Union[str, MangaRankingType])

Bases: Ranking

Container for manga rankings.

type: the criterion of this ranking

raw: The raw json data for this object as returned by the API.

get(rank: int) → Manga

Returns the entry corresponding to the given rank.

Parameters: rank – the rank of the entry to get
Raises: KeyError – the rank is not present

next_page(client: Client) → Optional[Self]

Returns a new object with the next page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

previous_page(client: Client) → Optional[Self]

Returns a new object with the previous page of results. If not present returns None.

Note

If you don’t want to deal with paginated results consider increasing the ‘limit’ parameter in your queries

Parameters: client – the client used to make requests

mal.titles module

class mal.titles.Titles(title: str, payload: TitlesPayload)

Bases: object

Contains the information about the alternative titles for an anime or a manga, including different languages.

title: The title of the work.

synonyms: A list of alternative titles.

en_title: Official english title.

ja_title: Official japanese title.

Module contents

MyAnimeList API wrapper

Simple wrapper for the MyAnimeList API.

copyright

2022 Skylake-dev

license

MIT, see LICENSE for more details