API Reference

This page covers basically everything osu.py is capable of.

Note

Some cross-references in the docs may be broken and certain parts may have inconsistent formatting. I’m working on cleaning it up, but it’s not high priority and takes a while because of the sheer amount of documentation.

Core Classes

Clients

class osu.Client(auth: BaseAuthHandler | None = None, request_wait_time: float = 1.0, limit_per_minute: int = 60, api_version: str | None = None)

Main object for interacting with osu!api, which uses synchronous requests. If you’re looking for asynchronous requests, use AsynchronousClient.

Warning

This class is not thread-safe. If you wish to use with threading, use a threading lock when making requests.

Warning

Regarding the limit_per_minute attribute below: do not change it unless you know what you are doing. The terms of use specify to avoid going over 60 requests per minute.

Parameters:

auth (Optional[osu.auth.BaseAuthHandler]) – Typically will be an osu.auth.AuthHandler or osu.auth.AsynchronousAuthHandler object.
request_wait_time (float) – (Default 1.0) This defines the amount of time that the client should wait before making another request. It can make it easier to stay within the rate limits without using all your requests up quickly and then waiting forever to make another. It’s most applicable in bot-type apps.
limit_per_minute (int) – (Default 60) This sets a cap on the number of requests the client is allowed to make within 1 minute of time. Don’t change this before reading the above warning related to this attribute.
api_version (Optional[str]) – This parameter is here purely to expose the option. You likely don’t need to mess with this. Format is ‘yyyymmdd’ (e.g. 20231030).

classmethod from_credentials(client_id: int, client_secret: str, redirect_url: str | None, scope: Scope | None = None, code: str | None = None, request_wait_time: float = 1.0, limit_per_minute: int = 60, lazily_authenticate: bool = True) → Client

Creates a Client object from client id, client secret, redirect uri, and scope.

Parameters:

client_id: (int) – API client ID
client_secret: (str) – API client secret
redirect_url: (Optional[str]) – API redirect url
scope: (Optional[Scope]) – Scopes to authenticate under. Default is Scope.default(), which is just the public scope.
request_wait_time: (float) – Read Client for details.
limit_per_minute: (int) – Do not change default before reading details in Client.
lazily_authenticate: (bool) – If true, the AuthHandler won’t authenticate with the api until a request is made that requires it.

Return type:

Client

classmethod from_client_credentials(*args, **kwargs): Deprecated since version 2.2.0: Use from_credentials()

set_api_version(version: str) → None

Sets x-api-version header to use when sending requests to the api. You shouldn’t have to change it from the default, but if you need to then the function is available.

Parameters:: version: (str) – x-api-version header value in the format yyyymmdd

set_domain(domain: str) → None

Set domain to use for requests, such as “dev.ppy.sh”

Parameters:: domain: (str) –

lookup_beatmap(checksum: str | None = None, filename: str | None = None, id: int | None = None) → Beatmap

Returns beatmap.

Requires OAuth and scope public

Parameters:

checksum: (Optional[str]) – A beatmap checksum.
filename: (Optional[str]) – A filename to lookup
id: (Optional[int]) – A beatmap ID to lookup

Return type:

Beatmap

get_user_beatmap_score(beatmap: int, user: int, mode: str | GameModeStr | None = None, mods: Sequence[str] | None = None) → BeatmapUserScore

Returns a user’s score on a Beatmap

Requires OAuth and scope public

Parameters:

beatmap: (int) – Id of the beatmap
user: (int) – Id of the user
mode: (Optional[Union[str, GameModeStr]]) – The game mode to get scores for
mods: (Optional[Sequence[str]]) – An array of matching mods, or none. Currently doesn’t do anything.

Return type:

BeatmapUserScore

get_user_beatmap_scores(beatmap: int, user: int, mode: str | GameModeStr | None = None) → List[LegacyScore | SoloScore]

Returns a user’s scores on a Beatmap

Requires OAuth and scope public

Parameters:

beatmap: (int) – Id of the beatmap
user: (int) – Id of the user
mode: (Optional[Union[str, GameModeStr]]) – The game mode to get scores for

Return type:

List[Union[LegacyScore, SoloScore]]

Returns:

Will be SoloScore unless using an older api version

Returns the top scores for a beatmap

Requires OAuth and scope public

Parameters:

beatmap: (int) – Id of the beatmap
mode: (Optional[Union[str, GameModeStr]]) – The game mode to get scores for
mods: (Optional[Union[Mods, Sequence[Union[Mods, Mod, str]]]]) – Must pass one of: a Mods object, a list of string mod abbreviations, a list of Mods objects, a list of :classL`Mod` objects
ranking_type: (Optional[str]) – Beatmap score ranking type. Currently doesn’t do anything.
legacy_only: (Optional[bool]) – Whether or not to exclude lazer scores. Defaults to false.

Return type:

BeatmapScores

Returns:

osu.objects.LegacyScore object inside includes user and the included user includes country and cover.

get_beatmap(beatmap: int) → Beatmap

Gets beatmap data for the specified beatmap ID.

Requires OAuth and scope public

Parameters:: beatmap: (int) – The ID of the beatmap
Return type:: Beatmap
Returns:: Includes attributes beatmapset, beatmapset.ratings, failtimes, max_combo.

get_beatmaps(ids: Sequence[int] | None = None) → List[Beatmap]

Returns list of beatmaps.

Requires OAuth and scope public

Parameters:: ids: (Optional[List[int]]) – Beatmap id to be returned. Specify once for each beatmap id requested. Up to 50 beatmaps can be requested at once.
Return type:: List[Beatmap]
Returns:: Includes attributes beatmapset, beatmapset.ratings, failtimes, max_combo.

Returns difficulty attributes of beatmap with specific mode and mods combination.

Requires OAuth and scope public

Parameters:

beatmap: (int) – Beatmap id.
mods: (Optional[Union[int, Sequence[Union[str, Mods, int]], Mods]]) – Mod combination. Can be either a bitset of mods, a Mods enum, or array of any. Defaults to no mods. Some mods may cause the api to throw an HTTP 422 error depending on the map’s gamemode.
ruleset: (Optional[Union[GameModeStr, str]]) – Ruleset of the difficulty attributes. Only valid if it’s the beatmap ruleset or the beatmap can be converted to the specified ruleset. Defaults to ruleset of the specified beatmap.
ruleset_id: (Optional[Union[GameModeInt, int]]) – The same as ruleset but in integer form.

Return type:

BeatmapDifficultyAttributes

get_beatmapset(beatmapset_id: int) → Beatmapset

Get beatmapset by id.

Requires OAuth and scope public

Parameters:: beatmapset_id: (int) –
Return type:: Beatmapset

Returns the posts of the beatmapset discussions

Requires OAuth and scope public

Parameters:

beatmapset_discussion_id: (Optional[int]) – id of the BeatmapsetDiscussion
limit: (Optional[int]) – Maximum number of results
page: (Optional[int]) – Search results page.
sort: (Optional[str]) – id_desc for newest first; id_asc for oldest first. Defaults to id_desc
type: (Optional[Sequence[str]]) – first, reply, system are the valid values. Defaults to reply.
user: (Optional[int]) – The id of the user
with_deleted: (Optional[str]) – This param has no effect as api calls do not currently receive group permissions.
cursor: (Optional[Dict[str, int]]) – A cursor object received from a previous call to get_beatmapset_discussion_posts (BeatmapsetDiscussionPostsResult.cursor)

Return type:

BeatmapsetDiscussionsPostsResult

Returns the votes given to beatmapset discussions

Requires OAuth and scope public

Parameters:

beatmapset_discussion_id: (Optional[int]) – id of the BeatmapsetDiscussion
limit: (Optional[int]) – Maximum number of results
page: (Optional[int]) – Search results page.
receiver: (Optional[int]) – The id of the User receiving the votes.
score: (Optional[int]) – 1 for upvote, -1 for downvote
sort: (Optional[str]) – id_desc for newest first; id_asc for oldest first. Defaults to id_desc
user: (Optional[int]) – The id of the User giving the votes.
with_deleted: (Optional[str]) – This param has no effect as api calls do not currently receive group permissions
cursor: (Optional[Dict[str, int]]) – A cursor object received from a previous call to get_beatmapset_discussion_votes (BeatmapsetDiscussionVotesResult.cursor)

Return type:

BeatmapsetDiscussionVotesResult

Returns a list of beatmapset discussions

Requires OAuth and scope public

Parameters:

beatmap_id: (Optional[int]) – id of the beatmap
beatmapset_id: (Optional[int]) – id of the beatmapset
beatmapset_status: (Optional[str]) – One of all, ranked, qualified, disqualified, never_qualified. Defaults to all.
limit: (Optional[int]) – Maximum number of results.
message_types: (Optional[Sequence[Union[str, MessageType]]]) – None defaults to all types.
only_unresolved: (Optional[bool]) – true to show only unresolved issues; false, otherwise. Defaults to false.
page: (Optional[int]) – Search result page.
sort: (Optional[str]) – id_desc for newest first; id_asc for oldest first. Defaults to id_desc.
user: (Optional[int]) – The id of the User.
with_deleted: (Optional[str]) – This param has no effect as api calls do not currently receive group permissions.
cursor: (Optional[Dict[str, int]]) – A cursor object received from a previous call to get_beatmapset_discussions (BeatmapsetDiscussionsResult.cursor)

Return type:

BeatmapsetDiscussionsResult

get_changelog_build(stream: str, build: str) → Build

Returns details of the specified build.

Parameters:

stream: (str) – Update stream name.
build: (str) – Build version.

Return type:

A Build with changelog_entries, changelog_entries.github_user, and versions included.

Returns a listing of update streams, builds, and changelog entries.

Parameters:

start: (Optional[str]) – Minimum build version.
max_id: (Optional[int]) – Maximum build ID.
stream: (Optional[str]) – Stream name to return builds from.
end: (Optional[str]) – Maximum build version.
message_formats: (Optional[Sequence[str]]) – html, markdown. Default to both.

Return type:

ChangelogListingResult

lookup_changelog_build(changelog: str, key: str | None = None, message_formats: Sequence[str] | None = None) → Build

Returns details of the specified build.

Parameters:

changelog: (str) – Build version, update stream name, or build ID.
key: (Optional[str]) – Leave blank to query by build version or stream name, or id to query by build ID.
message_formats: (Optional[Sequence[str]]) – html, markdown. Default to both.

Return type:

A Build with changelog_entries, changelog_entries.github_user, and versions included.

Returns a list comments and their replies up to 2 levels deep.

Does not require OAuth

Parameters:

commentable_type: (Optional[Union[ObjectType, str]) – The type of resource to get comments for. Must be of the following types: beatmapset, build, news_post
commentable_id: (Optional[int]) – The id of the resource to get comments for. Id correlates with commentable_type.
cursor: (Optional[dict]) – Pagination option. Returned in CommentSort for next request.
parent_id: (Optional[int]) – Limit to comments which are reply to the specified id. Specify 0 to get top level comments.
sort: (Optional[Union[str, CommentSort]]) – Sort option as defined in CommentSort. Defaults to new for guests and user-specified default when authenticated.

Return type:

CommentBundle

Returns:

pinned_comments is only included when commentable_type and commentable_id are specified.

get_comment(comment: int) → CommentBundle

Gets a comment and its replies up to 2 levels deep.

Does not require OAuth

Parameters:: comment: (int) – Comment id
Return type:: CommentBundle

reply_topic(topic: int, body: str) → ForumPost

Create a post replying to the specified topic.

Requires OAuth, scope forum.write, and a user (authorization code grant or delegate scope)

Parameters:

topic: (int) – Id of the topic to be replied to.
body: (str) – Content of the reply post.

Return type:

ForumPost

Returns:

body attributes included

Create a new topic.

Requires OAuth, scope forum.write, and a user (authorization code grant or delegate scope)

Parameters:

body: (str) – Content of the topic.
forum_id: (int) – Forum to create the topic in.
title: (str) – Title of the topic.
with_poll: (Optional[bool]) – Enable this to also create poll in the topic (default: false).
hide_results: (Optional[bool]) – Enable this to hide result until voting period ends (default: false).
length_days: (Optional[int]) – Number of days for voting period. 0 means the voting will never ends (default: 0). This parameter is required if hide_results option is enabled.
max_options: (Optional[int]) – Maximum number of votes each user can cast (default: 1).
poll_options: (Optional[List[str]]) – List of voting options. BBCode is supported.
poll_title: (Optional[str]) – Title of the poll.
vote_change: (Optional[bool]) – Enable this to allow user to change their votes (default: false).

Return type:

CreateTopicResult

Get topic and its posts.

Requires OAuth and scope public

Parameters:

topic: (int) – Id of the topic.
cursor: (Optional[str]) – Parameter for pagination.
sort: (Optional[str]) – Post sorting option. Valid values are id_asc (default) and id_desc.
limit: (Optional[int]) – Maximum number of posts to be returned (20 default, 50 at most).
start: (Optional[int]) – First post id to be returned with sort set to id_asc. This parameter is ignored if cursor_string is specified.
end: (Optional[int]) – First post id to be returned with sort set to id_desc. This parameter is ignored if cursor_string is specified.

Return type:

GetTopicAndPostsResult

edit_topic(topic: int, topic_title: str) → ForumTopic

Edit topic. Only title can be edited through this endpoint.

Requires OAuth and scope forum.write

Parameters:

topic: (int) – Id of the topic.
topic_title: (str) – New topic title.

Return type:

ForumTopic

edit_post(post: int, body: str) → ForumPost

Edit specified forum post.

Requires OAuth and scope forum.write

post: int: Id of the post.
body: str: New post content in BBCode format.

Return type:: ForumPost

search(mode: str | WikiSearchMode | None = None, query: str | None = None, page: int | None = None) → SearchResult

Searches users and wiki pages.

Requires OAuth and scope public

Parameters:

mode: (Optional[Union[str, WikiSearchMode]]) – Either all, user, or wiki_page. Default is all.
query: (Optional[str]) – Search keyword.
page: (Optional[int]) – Search result page. Ignored for mode all.

Return type:

SearchResult

get_scores(room: int, playlist: int, limit: int | None = None, sort: str | MultiplayerScoresSort | None = None, cursor: str | None = None) → MultiplayerScores

If you’re looking for the endpoint to get a list of 1000 recent scores, check get_all_scores().

Requires OAuth, scope public, and a user (authorization code grant or delegate scope)

Parameters:

room: (int) – Id of the room.
playlist: (int) – Id of the playlist item.
limit: (Optional[int]) – Number of scores to be returned.
sort: (Optional[Union[str, MultiplayerScoresSort]]) –
cursor: (Optional[str]) – MultiplayerScores.cursor value from a previous call to get next page.

Return type:

MultiplayerScores

get_news_listing(limit: int | None = None, year: int | None = None, cursor: dict | None = None) → GetNewsListingResult

Returns a list of news posts and related metadata.

Parameters:

limit: (Optional[int]) – Maximum number of posts (12 default, 1 minimum, 21 maximum).
year: (Optional[int]) – Year to return posts from.
cursor: (Optional[str]) – Cursor for pagination.

Return type:

GetNewsListingResult

get_news_post(news: str, key: str | None = None) → NewsPost

Returns details of the specified news post.

Parameters:

news: (class:str) – News post slug or ID.
key: (Optional[str]) – Unset to query by slug, or id to query by ID.

Return type:

Returns a NewsPost with content and navigation included.

revoke_current_token() → None

Revokes currently authenticated token.

Requires OAuth

Gets the current ranking for the specified type and game mode.

Requires OAuth and scope public

Parameters:

mode: (Union[str, GameModeStr]) –
type: (Union[str, RankingType]) – RankingType
country: (Optional[str]) – Filter ranking by country code. Only available for type of performance.
cursor: (Optional[dict]) –
filter: (Optional[str]) – Either all (default) or friends.
spotlight: (Optional[int]) – The id of the spotlight if type is charts. Ranking for latest spotlight will be returned if not specified.
variant: (Optional[str]) – Filter ranking to specified mode variant. For mode of mania, it’s either 4k or 7k. Only available for type of performance.

Return type:

Union[Rankings[UserStatistics], Rankings[CountryStatistics], Rankings[UserTeamStatistics], SpotlightRankings]

Returns:

Ranking type that depends on type argument

get_spotlights() → Spotlights

Gets the list of spotlights.

Requires OAuth and scope public

Return type:: Spotlights

get_own_data(mode: str | GameModeStr = '') → User

Similar to get_user but with authenticated user (token owner) as user id.

Requires OAuth, scope identify, and a user (authorization code grant or delegate scope)

Parameters:: mode: (Optional[str, GameModeStr]) – GameMode. User default mode will be used if not specified.
Return type:: See return for get_user

get_user_kudosu(user: int, limit: int | None = None, offset: int | None = None)

Returns kudosu history.

Requires OAuth and scope public

Parameters:

user: (int) – Id of the user.
limit: (Optional[int]) – Maximum number of results.
offset: (Optional[int]) – Result offset for pagination.

Return type:

Sequence[KudosuHistory]

This endpoint returns the scores of specified user.

Requires OAuth and scope public

Parameters:

user: (int) – Id of the user.
type: (Union[UserScoreType str]) – Score type. Must be one of best, firsts, recent, pinned
include_fails: (Optional[bool]) – Only for recent scores, include scores of failed plays. Defaults to False.
mode: (Optional[Union[GameModeStr, str]]) – game mode of the scores to be returned. Defaults to the specified user’s mode.
limit: (Optional[int]) – Maximum number of results.
offset: (Optional[int]) – Result offset for pagination.

Return type:

Sequence[Union[LegacyScore, SoloScore]]

Returns:

Includes attributes beatmap, beatmapset. Additionally includes weight if type is best.

get_user_beatmaps(user: int, type: str | UserBeatmapType, limit: int | None = None, offset: int | None = None) → List[BeatmapPlaycount | Beatmapset]

Returns the beatmaps of specified user.

Requires OAuth and scope public

Parameters:

user: (int) – Id of the user.
type: (Union[str, UserBeatmapType]) – Beatmap type. Can be one of favourite, graveyard, guest, loved, most_played, nominated, pending, ranked.
limit: (Optional[int]) – Maximum number of results.
offset: (Optional[int]) – Result offset for pagination.

Return type:

List[Union[BeatmapPlaycount, Beatmapset]]

Returns:

BeatmapPlaycount for type most_played and Beatmapset for any other type.

Returns recent activity.

Requires OAuth and scope public

Parameters:

user: (int) – Id of the user.
limit: (Optional[int]) – Maximum number of results.
offset: (Optional[int]) – Result offset for pagination.

Return type:

List[Event]

Returns:

list of Event objects

get_user(user: int | str, mode: str | GameModeStr | None = '', key: str | None = None) → User

This endpoint returns the detail of specified user.

NOTE: It’s highly recommended to pass key parameter to avoid getting unexpected result (mainly when looking up user with numeric username or nonexistent user id).

Requires OAuth and scope public

Parameters:

user: (Union[int, str]) – Id or username of the user. Id lookup is prioritised unless key parameter is specified. Previous usernames are also checked in some cases.
mode: (Optional[Union[str, GameModeStr]) – User default mode will be used if not specified.
key: (Optional[str]) –
DEPRECATED It’s recommended to prefix usernames with @ instead of setting key

Type of user passed in url parameter. Can be either id or username to limit lookup by their respective type. Passing empty or invalid value will result in id lookup followed by username lookup if not found.

Return type:

User

Returns:

Includes attributes account_history, active_tournament_banner, badges, beatmap_playcounts_count, favourite_beatmapset_count, follower_count, graveyard_beatmapset_count, groups, loved_beatmapset_count, mapping_follower_count, monthly_playcounts, page, pending_beatmapset_count, previous_usernames, rank_highest, rank_history, ranked_beatmapset_count, replays_watched_counts, scores_best_count, scores_first_count, scores_recent_count, statistics, statistics.country_rank, statistics.rank, statistics.variants, support_level, user_achievements.

get_users(ids: Sequence[int], include_variant_statistics: bool | None = None) → List[UserCompact]

Returns list of users. Can get maximum 50 at a time.

Requires OAuth and scope public

Parameters:

ids: (Sequence[int]) – User id to be returned. Specify once for each user id requested. Up to 50 users can be requested at once.
include_variant_statistics: (Optional[bool]) – Whether to additionally include statistics_rulesets.variants. Defaults to false.

Return type:

Sequence[UserCompact]

Returns:

Includes attributes: country, cover, groups, statistics_rulesets.

lookup_users(users: List[str | int], mode: GameModeInt | None = None)

Lookup users by a mix of user ids and usernames. Can lookup maximum 50 at a time.

When mode is specified, global_rank on the UserCompact is returned.

ids: Sequence[Union[int, str]]: Can be a list of user ids and usernames. Usernames should be prefixed with “@” to make sure they’re interpreted as usernames by the api.
mode: Optional[GameModeInt]: Game mode to get data for

Return type:: Sequence[UserCompact]

get_wiki_page(locale: str, path: str) → WikiPage

The wiki article or image data.

No OAuth required.

Parameters:

locale: (str) – Two-letter language code of the wiki page.
path: (str) – The path name of the wiki page.

Return type:

WikiPage

Returns a list of beatmapset events.

Requires OAuth and scope public.

Parameters:

page: (Optional[int]) –
limit: (Optional[int]) –
sort: (Optional[Union[str, BeatmapsetEventSort]]) – Specified a sort order.
type: (Optional[Union[str, BeatmapsetEventType]]) – Specifies for only a certain type of event to be returned.

Return type:

GetBeatmapsetEventsResult

Returns a list of matches.

Requires OAuth and scope public.

Parameters:

limit: (Optional[int]) –
sort: (Optional[Union[str, MatchSort]]) –
cursor: (Optional[Dict]) – Dictionary containing one key: match_id. Can be obtained from a previous call to this function or manually created.
active: (Optional[bool]) – Specifies whether to return only active matches. Default returns active and unactive matches.

Return type:

GetMatchesResult

get_match(match_id: int, before: int | None = None, after: int | None = None, limit: int | None = None) → MatchExtended

Returns a match by id.

Requires OAuth and scope public.

Parameters:

match_id: (int) – The match id.
before: (Optional[int]) – Filter for match events before the specified MatchEvent.id.
after: (Optional[int]) – Filter for match events after the specified MatchEvent.id.
limit: (Optional[int]) – Maximum number of match events to return. 100 default, 101 maximum.

Return type:

Match

Returns a list of rooms.

Requires OAuth, scope public, and a user (authorization code grant or delegate scope).

Parameters:

mode: (Optional[Union[str, GameModeStr]]) – Game mode to filter rooms by.
sort: (Optional[Union[str, RoomSort]]) – Sort rooms by.
limit: (Optional[int]) – max number of rooms to return
room_type: (Optional[Union[RoomType, str]]) – type of room to look for
category: (Optional[Union[RoomCategory, str]]) – type of category of room to look for
filter_mode: (Optional[Union[RoomFilterMode, str]]) –

get_seasonal_backgrounds() → SeasonalBackgrounds

Get the season backgrounds.

Doesn’t require OAuth

Return type:: SeasonalBackgrounds

get_room(room_id: int) → Room

Returns a room by id.

Requires OAuth and scope public.

Parameters:: room_id: (int) – The room id.
Return type:: Room

get_score_by_id(mode: str | GameModeStr, score_id) → LegacyScore | SoloScore

Returns a score by id.

Requires OAuth and scope public.

Parameters:

mode: (Union[str, GameModeStr]) –
score_id: (int) –

Return type:

Union[SoloScore, LegacyScore]

Returns:

Should be a SoloScore, unless for some strange reason it’s not

get_score_by_id_only(score_id: int) → LegacyScore | SoloScore

Returns a score by id, not requiring a mode.

Requires OAuth and scope public.

Parameters:: score_id: (int) –
Return type:: Union[SoloScore, LegacyScore]
Returns:: Should be a SoloScore, unless for some strange reason it’s not

search_beatmapsets(filters: BeatmapsetSearchFilter | None = None, page: int | None = None) → BeatmapsetSearchResult

Search for beatmapsets.

Requires OAuth and scope public.

Parameters:

filters: (Optional[BeatmapsetSearchFilter]) –
page: (Optional[int]) –

Return type:

BeatmapsetSearchResult

get_room_leaderboard(room_id: int) → GetRoomLeaderboardResult

Return a room’s leaderboard. The UserScoreAggregate objects returned under the “leaderboard” key contain the “user” attribute. The UserScoreAggregate object under the “user_score” key contains the “user” and “position” attributes.

Requires OAuth, scope public, and a user (authorization code grant or delegate scope).

Parameters:: room_id: (int) –
Return type:: GetRoomLeaderboard

get_replay_data(mode: str | GameModeStr | None, score_id: int, use_osrparse: bool = True) → Replay | bytes

Returns replay data for a score. Use Client.get_replay_data_by_id_only() for only the id, or specify None to the mode attribute.

Requires OAuth, scope public, and a user (authorization code grant or delegate scope).

Requires osu.py is installed with the ‘replay’ feature if use_osrparse is true.

Parameters:

mode: (Optional[Union[str, GameModeStr]]) –
score_id: (int) –
use_osrparse: (bool) – If true, returns an osrparse.Replay object. Defaults to true.

Return type:

Union[osrparse.Replay, bytes]

get_replay_data_by_id_only(score_id: int, use_osrparse: bool = True) → Replay | bytes

Returns replay data for a score. Use Client.get_replay_data() for score ids that require specifying the game mode too.

Requires OAuth, scope public, and a user (authorization code grant or delegate scope).

Requires osu.py is installed with the ‘replay’ feature if use_osrparse is true.

Parameters:

score_id: (int) –
use_osrparse: (bool) – If true, returns an osrparse.Replay object. Defaults to true.

Return type:

Union[osrparse.Replay, bytes]

get_friends() → List[UserRelation] | List[UserCompact]

Returns a list of friends.

Requires OAuth, scope friends.read, and a user (authorization code grant or delegate scope).

Return type:: Union[List[UserCompact], List[UserRelation]]
Returns:: will be UserRelation objects if using default api version header

chat_keepalive(history_since: int | None = None, since: int | None = None) → List[UserSilence]

Request periodically to reset chat activity timeout. Also returns an updated list of recent silences.

Requires OAuth, scope chat.read, and a user (authorization code grant or delegate scope)

Parameters:

history_since: (Optional[int]) – UserSilence`s after the specified id to return. This field is preferred and takes precedence over `since.
since: (Optional[int]) – UserSilence`s after the specified :class:`ChatMessage.message_id to return.

Return type:

List[UserSilence]

create_new_pm(target_id: int, message: str, is_action: bool, uuid: str | None = None) → CreateNewPmResult

This endpoint allows you to create a new PM channel.

Requires OAuth, scope chat.write, and a user (authorization code grant or delegate scope)

Parameters:

target_id: (int) – user_id of user to start PM with
message: (str) – message to send
is_action: (bool) – whether the message is an action
uuid: (Optional[str]) – client-side message identifier which will be sent back in response and websocket json.

Return type:

CreateNewPmResult

get_channel_messages(channel_id: int, limit: int | None = None, since: int | None = None, until: int | None = None) → List[ChatMessage]

This endpoint returns the chat messages for a specific channel.

Requires OAuth, scope chat.read, and a user (authorization code grant or delegate scope)

Parameters:

channel_id: (int) – The ID of the channel to retrieve messages for
limit: (Optional[int]) – number of messages to return (max of 50)
since: (Optional[int]) – messages after the specified message id will be returned
until: (Optional[int]) – messages up to but not including the specified message id will be returned

Return type:

List[ChatMessage]

send_message_to_channel(channel_id: int, message: str, is_action: bool) → ChatMessage

This endpoint sends and returns a chat messages for a specific channel.

Requires OAuth, scope chat.write, and a user (authorization code grant or delegate scope)

Parameters:

channel_id: (int) – The id of the channel to send message to
message: (class:str) – message to send
is_action: (bool) – whether the message is an action

join_channel(channel_id: int, user_id: int) → ChatChannel

This endpoint allows you to join a public or multiplayer channel.

Requires OAuth, scope chat.write_manage, and a user (authorization code grant or delegate scope)

Parameters:

channel_id: (int) – The id of the channel to join
user_id: (int) – The id of the user to be joined

Return type:

ChatChannel

leave_channel(channel_id: int, user_id: int) → None

This endpoint allows you to leave a public channel.

Requires OAuth, scope chat.write_manage, and a user (authorization code grant or delegate scope)

Parameters:

channel_id: (int) – The id of the channel to join
user_id: (int) – The id of the user to be joined

mark_channel_as_read(channel_id: int, message_id: int) → None

This endpoint marks the channel as having being read up to the given message_id.

Requires OAuth, scope chat.read, and a user (authorization code grant or delegate scope)

Parameters:

channel_id: (int) – id of the channel to mark as read
message_id: (int) – most recent message to mark as read up to

get_channel_list() → List[ChatChannel]

This endpoint returns a list of all joinable public channels.

Requires OAuth, scope chat.read, and a user (authorization code grant or delegate scope)

Return type:: List[ChatChannel]

create_pm_channel(user_id: int) → ChatChannel

Create PM channel with another user. Rejoins if it already exists.

Requires OAuth, scope chat.write_manage, and a user (authorization code grant or delegate scope)

Parameters:: user_id: (int) – id of the user to open a PM channel with
Return type:: ChatChannel with recent_message

create_announcement_channel(user_ids: List[int], message: str, name: str, description: str) → ChatChannel

Creates a new announcement channel.

Requires OAuth, scope chat.write_manage, and a user (authorization code grant or delegate scope)

Parameters:

target_ids: (List[int]) – users to include in the channel
message: (str) – message to send with the announcement
name: (str) – the channel name
description: (str) – the channel description

Return type:

ChatChannel with recent_message

get_channel(channel_id: int) → GetChannelResult

Get a channel by id

Requires OAuth, scope chat.read, and a user (authorization code grant or delegate scope)

Parameters:: channel_id: (int) – id of the channel to get
Return type:: GetChannelResult

get_all_scores(ruleset: str | GameModeStr | None = None, cursor: str | None = None) → GetAllScoresResult

Returns all scores (that are passes), up to 1000. Result is sorted oldest to recent. Can use the cursor in the response in the next call to this function.

Parameters:

ruleset: (Optional[Union[GameModeStr, str]]) –
cursor: (Optional[str]) –

Return type:

List[SoloScore]

get_forums() → GetForumsResult

Returns top-level forums and their sub-forums (max 2 deep).

Return type:: GetForumsResult

get_forum(forum_id: int) → GetForumResult

Get a forum, its recent topics, and pinned topics.

Parameters:: forum_id: (int) –
Return type:: GetForumResult

get_forum_topics(forum_id: int | None = None, cursor: str | None = None, sort: str | None = None, limit: int | None = None) → GetForumTopicsResult

Get a list of topics, optionally under a specified forum.

Parameters:

forum_id: (Optional[int]) – Id of forum to get topics from. Will retrieve topics from all forums if not specified.
cursor: (Optional[str]) – Pass cursor value of last call to continue
sort: (Optional[str]) – ‘new’ (default) or ‘old’
limit: (Optional[int]) – 50 at most and by default

Return type:

GetForumTopicsResult

class osu.AsynchronousClient(auth: BaseAsynchronousAuthHandler | None = None, request_wait_time: float = 1.0, limit_per_minute: int = 60, api_version: str | None = None)

Main object for interacting with osu!api, which uses asynchronous requests. If you’re looking for synchronous requests, use Client.

All the functions of this class are documented under Client and work the same except AsynchronousClient.from_credentials()

async classmethod from_client_credentials(client_id: int, client_secret: str, redirect_url: str | None, scope: ~osu.scope.Scope | None = <osu.scope.Scope object>, code: str | None = None, request_wait_time: float = 1.0, limit_per_minute: int = 60) → AsynchronousClient: Deprecated since version 2.2.0: Use from_credentials()

classmethod from_credentials(client_id: int, client_secret: str, redirect_url: str | None, scope: ~osu.scope.Scope | None = <osu.scope.Scope object>, code: str | None = None, request_wait_time: float = 1.0, limit_per_minute: int = 60, lazily_authenticate: bool = True) → AsynchronousClient | Awaitable

Creates a AsynchronousClient object from client id, client secret, redirect uri, and scope.

Parameters:

client_id: (int) – API client ID
client_secret: (str) – API client secret
redirect_url: (Optional[str]) – API redirect url
scope: (Optional[Scope]) – Scopes to authenticate under. Default is Scope.default(), which is just the public scope.
request_wait_time: (float) – Read Client for details.
limit_per_minute: (int) – Do not change default before reading details in Client.
lazily_authenticate: (bool) – If true, the AuthHandler won’t authenticate with the api until a request is made that requires it.

Return type:

AsynchronousClient

class osu.http.HTTPHandler(auth: BaseAuthHandler | None, request_wait_time: float = 1.0, limit_per_minute: int = 60, api_version: str | None = None): Handles making requests. Used by osu.Client.

class osu.asyncio.http.AsynchronousHTTPHandler(auth: BaseAsynchronousAuthHandler | None, request_wait_time: float = 1.0, limit_per_minute: int = 60, api_version: str | None = None)

Handles making asynchronous requests. Used by osu.AsynchronousClient.

async make_request(path, *args, **kwargs)

Make request to the api.

Parameters:

path (osu.Path) –
data (Optional[Union[dict, list]]) – (Default None) Json body of the request
headers (Optional[Dict[str, str]]) – (Default None) Headers to send in the request
is_download (bool) – (Default False) Returns response object if true
files – (Default None)
kwargs (Dict[str, str]) – All kwargs will be interpreted as query parameters for the request.

class osu.Path(method: str, path: str, scope: str | None, requires_user=False, content_type='application/json', accept='application/json')

An object that defines an endpoint and various attributes of it. Used by Client and passed to osu.http.HTTPHandler or the async equivalent classes.

Attributes and init parameters

method: str: The http method to use (e.g. get, post, put, delete).

path: str: The path to the endpoint (e.g. beatmaps/727/scores)

scope: str | None: The scope required to make this request (e.g. public, forum.write). None if a scope is not required.

requires_user: bool: True if the endpoint requires a form of user authentication. Defaults to false.

content_type: str: Content-Type header to use in the request. Defaults to application/json.

accept: str: Accept header to use in the request. Defaults to application/json.

class osu.http.BaseHTTPHandler(auth: BaseAuthHandler | None, api_version: str | None = None)

Abstract class for handling http requests.

set_api_version(api_version: str | None): Sets x-api-version header. Should be in the format YYYYMMDD. Pass None to set back to default.

set_domain(domain: str) → None: Set the domain to use for requests.

Authentication

class osu.BaseAuthHandler

An abstract class for implementing authentication logic.

get_token() → str | None: Returns the access token. If the token is expired, it will be refreshed before being returned.

osu.FunctionalAuthHandler: alias of AuthUtil

class osu.AuthHandler(client_id: int, client_secret: str, redirect_url: str | None, scope: Scope | None = None)

as_async() → AsynchronousAuthHandler

Returns an asynchronous auth handler. Credentials are shared and updates in one apply to the other. This method primarily exists for running the library’s tests.

NOTE: Using both auth handlers in different threads at the same time is not safe.

get_auth_token(code: str | None = None) → None

code parameter is not required, but without a code the scopes are restricted to public and delegate (more on delegation below). You can obtain a code by having a user authorize themselves under a url which you can get with get_auth_url. Read more about it under that function.

Client Credentials Delegation

Client Credentials Grant tokens may be allowed to act on behalf of the owner of the OAuth client (delegation) by requesting the delegate scope, in addition to other scopes supporting delegation. When using delegation, scopes that support delegation cannot be used together with scopes that do not support delegation. Delegation is only available to Chat Bots. Currently, chat.write is the only other scope that supports delegation.

Parameters:: code: (Optional[str]) – code from user authorizing at a specific url

get_token() → str | None: Returns the access token. If the token is expired, it will be refreshed before being returned.

has_user() → bool: Returns whether this auth has access to endpoints requiring a user

refresh_access_token(refresh_token: str | None = None) → None

This function is usually executed by HTTPHandler, but if you have a refresh token saved from the last session, then you can fill in the refresh_token argument which this function will use to get a valid token.

Parameters:: refresh_token: (Optional[str]) – A refresh token used to get a new access token.

class osu.AsynchronousAuthHandler(client_id: int, client_secret: str, redirect_url: str | None, scope: Scope | None = None)

as_sync() → AuthHandler

Returns a synchronous auth handler. Credentials are shared and updates in one apply to the other. This method primarily exists for running the library’s tests.

NOTE: Using both auth handlers in different threads at the same time is not safe.

async get_auth_token(code: str | None = None)

code parameter is not required, but without a code the scopes are restricted to public and delegate (more on delegation below). You can obtain a code by having a user authorize themselves under a url which you can get with get_auth_url. Read more about it under that function.

Client Credentials Delegation

Client Credentials Grant tokens may be allowed to act on behalf of the owner of the OAuth client (delegation) by requesting the delegate scope, in addition to other scopes supporting delegation. When using delegation, scopes that support delegation cannot be used together with scopes that do not support delegation. Delegation is only available to Chat Bots. Currently, chat.write is the only other scope that supports delegation.

Parameters:: code: (Optional[str]) – code from user authorizing at a specific url

async get_token() → str | None: Returns the access token. If the token is expired, it will be refreshed before being returned.

has_user() → bool: Returns whether this auth has access to endpoints requiring a user

async refresh_access_token(refresh_token: str | None = None)

This function is usually executed by HTTPHandler, but if you have a refresh token saved from the last session, then you can fill in the refresh_token argument which this function will use to get a valid token.

Parameters:: refresh_token: (Optional[str]) – A refresh token used to get a new access token.

class osu.Scope(*scopes)

Scope object for telling the program what scopes you are using

Valid scopes

public: Allows reading of publicly available data on behalf of the user.
identify (default): Allows reading of the public profile of the user (/me).
friends.read: Allows reading of the user’s friend list.
forum.write: Allows creating and editing forum posts on a user’s behalf.
delegate: Allows acting as the owner of a client; only available for Client Credentials Grant.
chat.write: Allows sending chat messages on a user’s behalf.

classmethod default(): Initializes with public scope

classmethod identify(): Initializes with public and identify scopes

Endpoint results

Note

These can be imported directly from osu

Some endpoints return responses that don’t represent any specific objects; that’s what these are for.

class osu.results.BeatmapsetDiscussionPostsResult(beatmapsets: List[BeatmapsetCompact], posts: List[BeatmapsetDiscussionPost], users: List[UserCompact], cursor: str)

Result of osu.Client.get_beatmapset_discussion_posts()

beatmapsets: List[BeatmapsetCompact]

posts: List[BeatmapsetDiscussionPost]

users: List[UserCompact]

cursor: Dict[str, int]

class osu.results.BeatmapsetDiscussionVotesResult(discussions: List[BeatmapsetDiscussion], votes: List[BeatmapsetDiscussionVote], users: List[UserCompact], cursor: str)

Result of osu.Client.get_beatmapset_discussion_votes()

discussions: List[BeatmapsetDiscussion]

votes: List[BeatmapsetDiscussionVote]

users: List[UserCompact]

cursor: Dict[str, int]

class osu.results.BeatmapsetDiscussionsResult(beatmaps: List[Beatmap], discussions: List[BeatmapsetDiscussion], included_discussions: List[BeatmapsetDiscussion], users: List[UserCompact], reviews_config: ReviewsConfig, cursor: str)

Result of osu.Client.get_beatmapset_discussions()

beatmaps: List[Beatmap]

discussions: List[BeatmapsetDiscussion]

included_discussions: List[BeatmapsetDiscussion]

users: List[UserCompact]

reviews_config: ReviewsConfig

cursor: str

class osu.results.BeatmapsetSearchResult(beatmapsets: List[Beatmapset], cursor: Dict, search: SearchInfo, recommended_difficulty: float | None, error: str | None, total: int)

Result of osu.Client.search_beatmapsets()

beatmapsets: List[Beatmapset]

cursor: Dict

search: SearchInfo

recommended_difficulty: int | None

error: str | None

total: int

class osu.results.ChangelogListingResult(builds: List[Build], streams: List[UpdateStream], search: ChangelogListingSearch)

Result of osu.Client.get_changelog_listing()

build: List[Build]

streams: List[Build]

search: ChangelogListingSearch

class osu.results.ChangelogListingSearch(start: str | None, end: str | None, limit: int, max_id: int | None, stream: str | None)

Attribute of ChangelogListingResult

start: str | None: start input

end: str | None: end input

limit: int: Always 21

max_id: int | None: max_id input

stream: str | None: stream input

class osu.results.CreateNewPmResult(channel: ChatChannel, message: ChatMessage, new_channel_id: int)

Result of osu.Client.create_new_pm()

channel: ChatChannel

message: ChatMessage

new_channel_id: int: [DEPRECATED] channel id of newly created ChatChannel

class osu.results.CreateTopicResult(topic: ForumTopic, post: ForumPost)

Result of osu.Client.create_topic()

topic: ForumTopic

post: ForumPost: includes body

class osu.results.GetAllScoresResult(scores: List[SoloScore], cursor: str)

Result of osu.Client.get_all_scores()

scores: List[SoloScore]

cursor: str

class osu.results.GetBeatmapsetEventsResult(events: List[BeatmapsetEvent], reviews_config: Review, users: List[UserCompact])

Result of osu.Client.get_beatmapset_events()

events: List[BeatmapsetEvent]

reviews_config: Review

users: List[UserCompact]: Includes groups attribute

class osu.results.GetChannelResult(channel: ChatChannel, users: List[UserCompact])

Result of osu.Client.get_channel()

channel: ChatChannel

users: List[UserCompact]

class osu.results.GetForumResult(forum: Forum, topics: List[ForumTopic], pinned_topics: List[ForumTopic])

Result of osu.Client.get_forum()

forum: Forum

topics: List[ForumTopic]

pinned_topics: List[ForumTopic]

class osu.results.GetForumTopicsResult(topics: List[ForumTopic], cursor: str | None)

Result of osu.Client.get_forum_topics()

topics: List[ForumTopic]

cursor: str | None

class osu.results.GetForumsResult(forums: List[Forum])

Result of osu.Client.get_forums()

forums: List[Forum]

class osu.results.GetMatchesResult(matches: List[Match], params: Dict, cursor: Dict)

Result of osu.Client.get_matches()

matches: List[Match]

params: Dict

cursor: Dict

class osu.results.GetNewsListingResult(cursor: str, news_posts: List[NewsPost], news_sidebar: NewsSidebar, search: SearchInfo)

Result of osu.Client.get_news_listing()

cursor: str

news_posts: List[NewsPost]

news_sidebar: NewsSidebar

search: SearchInfo

class osu.results.GetRoomLeaderboardResult(leaderboard: List[UserScoreAggregate], user_score: UserScoreAggregate | None)

Result of osu.Client.get_room_leaderboard()

leaderboard: List[UserScoreAggregate]

user_score: UserScoreAggregate | None

class osu.results.GetTopicAndPostsResult(cursor_string: str, search: SearchInfo, topic: ForumTopic, posts: List[ForumPost])

Result of osu.Client.get_topic_and_posts()

cursor_string: str

search: GetTopicAndPostsSearch: Parameters used for current request excluding cursor.

topic: ForumTopic

posts: List[ForumPost]

class osu.results.NewsSidebar(current_year: int, news_post: List[NewsPost], years: List[int])

Attribute of GetNewsListingResult

current_year: int

news_post: List[NewsPost]

years: List[int]

class osu.results.ReviewsConfig(max_blocks: int)

An attribute of BeatmapsetDiscussionsResult

max_blocks: int

class osu.results.SearchInfo(sort: str, limit: int, start: int | None, end: int | None)

A class for search info in several result objects.

sort: str

limit: int

start: str | None

end: str | None

class osu.results.SearchResult(user: List[UserCompact] | None, wiki_page: List[WikiPage] | None)

Result of osu.Client.search()

user: List[UserCompact] | None: For all or user mode. Only first 100 results are accessible

wiki_page: List[WikiPage] | None: For all or wiki_page mode

Objects

Note

These can be imported directly from osu

class osu.objects.Achievement(data)

icon_url: str

id: int

name: str

grouping: str

ordering: int

slug: str

description: str

mode: GameModeStr | None

instructions: str | None

class osu.objects.AchievementEvent(data)

achievement: Achievement

user: EventUser

class osu.objects.BaseNominations(data)

Base attributes for LegacyNominations and Nominations

disqualification: BeatmapsetEvent | None

nominated: bool | None

nomination_reset: BeatmapsetEvent | None

ranking_eta: str | None

ranking_queue_position: int | None

required_hype: int

class osu.objects.Beatmap(data)

Represent a beatmap. This extends BeatmapCompact with additional attributes. Also overrides the type of beatmapset

accuracy: float

ar: float

beatmapset: Beatmapset | None

bpm: float

convert: bool | None

count_circles: int

count_sliders: int

count_spinners: int

cs: float

deleted_at: datetime.datetime | None

drain: float

hit_length: int

is_scoreable: bool

last_updated: datetime.datetime

mode_int: GameModeInt

passcount: int

playcount: int

ranked: RankStatus

url: str

class osu.objects.BeatmapCompact(data)

Represents a beatmap.

beatmapset_id: int

difficulty_rating: float

id: int

mode: GameModeStr

status: RankStatus

total_length: int

user_id: int

version: str

beatmapset: BeatmapsetCompact | None

checksum: str | None

failtimes: Failtimes | None

max_combo: int | None

owners: List[BeatmapOwner] | None: List of owners (mappers) for the Beatmap.

class osu.objects.BeatmapDifficultyAttributes(data, typ: GameModeStr)

Represent beatmap difficulty attributes. Following fields are always present and then there are additional fields for different rulesets.

max_combo: int

star_rating: float

type: GameModeStr

mode_attributes: OsuBeatmapDifficultyAttributes | TaikoBeatmapDifficultyAttributes | None: Other modes have no attributes

class osu.objects.BeatmapOwnerChangeDetails(data)

When ownership of a beatmap is transferred (for guest difficulties).

Extends NotificationsDetailsBase

beatmap_id: int

cover_url: str

title: str

title_unicode: str

version: str

class osu.objects.BeatmapPlaycount(data)

Represent the playcount of a beatmap.

beatmap_id: int

beatmap: BeatmapCompact | None

beatmapset: BeatmapsetCompact | None

count: int

class osu.objects.BeatmapPlaycountEvent(data)

beatmap: EventBeatmap

count: int

class osu.objects.BeatmapScores(data, api_version: str)

Contains a list of scores as well as, possibly, a BeatmapUserScore object.

scores: List[LegacyScore | SoloScore]: The list of top scores for the beatmap in descending order.

user_score: BeatmapUserScore | None: The score of the current user. This is not returned if the current user does not have a score.

class osu.objects.BeatmapUserScore(data, api_version: str)

position: int: The position of the score within the requested beatmap ranking.

score: LegacyScore: The details of the score.

class osu.objects.Beatmapset(data)

Represents a beatmapset. This extends BeatmapsetCompact with additional attributes. Also overrides the type of beatmaps attribute.

availability: BeatmapsetAvailability

beatmaps: List[Beatmap] | None: null when this Beatmapset object comes from a Beatmap object

bpm: float

can_be_hyped: bool

deleted_at: datetime.datetime

discussion_enabled: bool: Deprecated. Is always true.

discussion_locked: bool

is_scoreable: bool

last_updated: datetime.datetime | None

legacy_thread_url: str

nominations_summary: BeatmapsetRequirement

ranked: RankStatus

ranked_date: datetime.datetime | None

storyboard: bool

submitted_date: datetime.datetime | None

tags: str

class osu.objects.BeatmapsetApproveEvent(data)

approval: RankStatus

beatmapset: EventBeatmapset

user: EventUser

class osu.objects.BeatmapsetAvailability(data)

Gives information on the availability of a beatmap for download.

download_disabled: bool

more_information: str | None

class osu.objects.BeatmapsetCompact(data)

Represents a beatmapset.

artist: str

artist_unicode: str

background_url: str: Not given by api but created locally based on beatmapset id.

covers: Covers

creator: str

favourite_count: int

hype: BeatmapsetRequirement | None

id: int

nsfw: bool

offset: int

play_count: int

preview_url: str

source: str

spotlight: bool

status: RankStatus

title: str

title_unicode: str

track_id: int | None

user_id: int

video: bool

availability: BeatmapsetAvailability | None

beatmaps: List[BeatmapCompact] | None: Beatmaps contained in the beatmapset

converts: List[Beatmap] | None

current_nominations: List[CurrentNomination] | None

current_user_attributes: BeatmapsetDiscussionPermissions | None

description: str | None

description_bbcode: str | None

discussions: BeatmapsetDiscussion | None

events: List[BeatmapsetEvent] | None

genre: MetadataAttribute | None

has_favourited: bool | None

language: MetadataAttribute | None

nominations: LegacyNominations | Nominations | None

pack_tags: List[str] | None

ratings: List[int] | None

recent_favourites: List[UserCompact] | None

related_users: List[UserCompact] | None

user: UserCompact | None

version_count: int | None

class osu.objects.BeatmapsetDeleteEvent(data)

beatmapset: EventBeatmapset

class osu.objects.BeatmapsetDiscussion(data)

Represents a Beatmapset modding discussion

beatmap_id: int | None

beatmapset_id: int

can_be_resolved: bool

can_grant_kudosu: bool

created_at: datetime.datetime

deleted_at: datetime.datetime | None

deleted_by_id: int | None

id: int

kudosu_denied: bool

last_post_at: datetime.datetime

message_type: MessageType

parent_id: int | None

resolved: bool

timestamp: int | None

updated_at: datetime.datetime

user_id: int

beatmap: BeatmapCompact | None

beatmapset: BeatmapsetCompact | None

current_user_attributes: BeatmapsetDiscussionPermissions | None

posts: List[BeatmapsetDiscussionPost] | None

starting_post: BeatmapsetDiscussionPost | None

votes: VotesSummary | None

class osu.objects.BeatmapsetDiscussionLockDetails(data)

Beatmapset discussion locked

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetDiscussionPermissions(data)

A user’s permissions in a beatmapset discussion

can_destroy: bool

can_reopen: bool

can_moderate_kudosu: bool

can_resolve: bool

vote_score: int

class osu.objects.BeatmapsetDiscussionPost(data)

Represents a post in a BeatmapsetDiscussion.

beatmapset_discussion_id: int

created_at: datetime.datetime

deleted_at: datetime.datetime | None

deleted_by_id: int | None

id: int

last_editor_id: int | None

updated_at: datetime.datetime

user_id: int

message: str | SystemDiscussionPostMessage: String when system is false and SystemDiscussionPostMessage otherwise.

system: bool

beatmap_discussion: BeatmapsetDiscussion | None

class osu.objects.BeatmapsetDiscussionPostNewDetails(data)

New beatmapset discussion post

Extends BeatmapsetDiscussionPostNotificationDetails

class osu.objects.BeatmapsetDiscussionPostNotificationDetails(data)

Base class for a couple other detail objects.

Extends NotificationsDetailsBase

content: str

title: str

title_unicode: str

post_id: int

discussion_id: int

beatmap_id: int

cover_url: str

class osu.objects.BeatmapsetDiscussionQualifiedProblemDetails(data)

Beatmapset discussion qualified problem

Extends BeatmapsetDiscussionPostNotification

class osu.objects.BeatmapsetDiscussionReviewNewDetails(data)

New beatmapset discussion review.

Extends NotificationsDetailsBase

title: str

title_unicode: str

post_id: int

discussion_id: int

beatmap_id: int

cover_url: str

embeds: ReviewStats

class osu.objects.BeatmapsetDiscussionUnlockDetails(data)

Beatmapset discussion unlocked

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetDiscussionVote(data)

Represents a vote on a BeatmapsetDiscussion.

beatmapset_discussion_id: int

created_at: datetime.datetime

id: int

score: int

updated_at: datetime.datetime

user_id: int

class osu.objects.BeatmapsetDisqualifyDetails(data)

Beatmapset disqualified

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetEvent(data)

Represent a beatmapset event. This object is relevant for the osu.Client.get_beatmapset_events() endpoint.

id: int

type: BeatmapsetEventType

comment: BeatmapsetEventComment | None: Is None for the following types: - BeatmapsetEventType.LOVE - BeatmapsetEventType.QUALIFY - BeatmapsetEventType.APPROVE - BeatmapsetEventType.RANK

created_at: datetime.datetime

user_id: int | None

beatmapset: BeatmapsetCompact | None

discussion: BeatmapsetDiscussion | None

class osu.objects.BeatmapsetEventBeatmapOwnerChange(data)

beatmap_id: int

beatmap_version: str

new_user_id: int

new_user_username: str

class osu.objects.BeatmapsetEventComment(data, type: BeatmapsetEventType)

This object holds some extra information of the event.

beatmap_discussion_id: int | None

beatmap_discussion_post_id: int | None

event_data: BeatmapsetEventNominate | BeatmapsetEventRemoveFromLoved | BeatmapsetEventDisqualify | BeatmapsetEventKudosuGain | BeatmapsetEventKudosuLost | BeatmapsetEventKudosuRecalculate | BeatmapsetEventDiscussionLock | BeatmapsetEventNominationReset | BeatmapsetEventNominationResetReceived | BeatmapsetEventGenreEdit | BeatmapsetEventLanguageEdit | BeatmapsetEventNsfwToggle | BeatmapsetEventOffsetEdit | BeatmapsetEventBeatmapOwnerChange: The type of this attribute depends on the type of the BeatmapsetEvent object.

class osu.objects.BeatmapsetEventDiscussionLock(data)

reason: str

class osu.objects.BeatmapsetEventDisqualify(data)

nominator_ids: List[int]

class osu.objects.BeatmapsetEventEdit(data)

old: str

new: str

class osu.objects.BeatmapsetEventGenreEdit(data)

old: str

new: str

class osu.objects.BeatmapsetEventKudosuChange(data)

new_votes: BeatmapsetEventVote | None

votes: List[BeatmapsetEventVote] | None

class osu.objects.BeatmapsetEventKudosuGain(data)

new_votes: BeatmapsetEventVote | None

votes: List[BeatmapsetEventVote] | None

class osu.objects.BeatmapsetEventKudosuLost(data)

new_votes: BeatmapsetEventVote | None

votes: List[BeatmapsetEventVote] | None

class osu.objects.BeatmapsetEventKudosuRecalculate(data)

new_votes: BeatmapsetEventVote | None

class osu.objects.BeatmapsetEventLanguageEdit(data)

old: str

new: str

class osu.objects.BeatmapsetEventNominate(data)

modes: List[GameModeStr]

class osu.objects.BeatmapsetEventNominationReset(data)

nominator_ids: List[int]

class osu.objects.BeatmapsetEventNominationResetReceived(data)

source_user_id: int

source_user_name: str

class osu.objects.BeatmapsetEventNsfwToggle(data)

old: str

new: str

class osu.objects.BeatmapsetEventOffsetEdit(data)

old: str

new: str

class osu.objects.BeatmapsetEventRemoveFromLoved(data)

reason: str

class osu.objects.BeatmapsetEventVote(data)

user_id: int

score: int

class osu.objects.BeatmapsetLoveDetails(data)

Beatmapset loved

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetNominateDetails(data)

Beatmapset nominated

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetNotificationDetails(data)

Base class for several other detail objects.

Extends NotificationsDetailsBase

title: str

title_unicode: str

cover_url: str

class osu.objects.BeatmapsetPermissions(data)

User permissions on a beatmapset

can_beatmap_update_owner: bool

can_delete: bool

can_edit_metadata: bool

can_edit_offset: bool

can_edit_tags: bool

can_hype: bool

can_hype_reason: str

can_love: bool

can_remove_from_loved: bool

is_watching: bool

new_hype_time: str | None

nomination_modes: Dict[GameModeStr, str]: Values are either “full” or “limited”.

remaining_hype: int

class osu.objects.BeatmapsetQualifyDetails(data)

Beatmapset qualified

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetRankDetails(data)

Beatmapset ranked

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetRemoveFromLovedDetails(data)

Beatmapset removed from love

Extends BeatmapsetNotificationDetails

class osu.objects.BeatmapsetRequiredNominations(data)

Information of required ruleset nominations of a beatmap

main_ruleset: int

non_main_ruleset: int

class osu.objects.BeatmapsetRequirement(data)

Gives information on requirements for a beatmap

current: int

required: int | None: If this is None, then required_meta and eligible_main_rulesets should have values

required_meta: BeatmapsetRequiredNominations | None

eligible_main_rulesets: List[GameModeStr] | None

class osu.objects.BeatmapsetResetNominationsDetails(data)

Beatmapset nominations reset

Extends BeatmapsetNominateDetails

class osu.objects.BeatmapsetReviveEvent(data)

beatmapset: EventBeatmapset

user: EventUser

class osu.objects.BeatmapsetUpdateEvent(data)

beatmapset: EventBeatmapset

user: EventUser

class osu.objects.BeatmapsetUploadEvent(data)

beatmapset: EventBeatmapset

user: EventUser

class osu.objects.Build(data)

created_at: datetime.datetime

display_version: str

id: int

update_stream: UpdateStream | None

users: int

versio: str | None

changelog_entries: List[ChangelogEntry] | None: If the build has no changelog entries, a placeholder is generated.

versions: Versions | None

class osu.objects.ChangelogEntry(data)

category: str

created_at: datetime.datetime | None

github_pull_request_id: int | None

github_url: str | None

id: int | None

major: bool

repository: str | None

title: str | None

type: str

url: str | None

github_user: GithubUser | None: If the changelog entry has no GitHub user, a placeholder is generated.

message: str | None: Entry message in Markdown format. Embedded HTML is allowed.

message_html: str | None: Entry message in HTML format.

class osu.objects.ChannelAnnouncementDetails(data)

Chat channel announcement

Extends NotificationsDetailsBase

channel_id: int

name: str

title: str

type: ChatChannelType

cover_url: str

class osu.objects.ChannelMessageDetails(data)

Chat channel message

Extends NotificationsDetailsBase

title: str

type: ChatChannelType

cover_url: str

class osu.objects.ChatChannel(data)

Represents an individual chat “channel” in the game.

channel_id: int

name: str

description: str | None

icon: str | None: display icon for the channel

type: ChatChannelType

moderated: bool: user can’t send message when the value is True

uuid: str | None: value from requests that is relayed back to the sender.

current_user_attributes: ChatChannelUserAttributes | None: only present on some responses

last_message_id: int | None: message_id of last known message (only returned in presence responses)

recent_messages: List[ChatMessage] | None: [DEPRECATED] up to 50 most recent messages

users: List[int] | None: list of user ids that are in the channel (not included for PUBLIC channels).

class osu.objects.ChatChannelUserAttributes(data)

Data about a user related to a chat channel.

can_message: bool

can_message_error: str | None

last_read_id: int | None

class osu.objects.ChatMessage(data)

Represents an individual Message within a ChatChannel.

channel_id: int: channel_id of where the message was sent

content: str: message content

is_action: bool: was this an action? i.e. /me dances

message_id: int: unique identifier for message

sender_id: int: user_id of the sender

timestamp: datetime.datetime: when the message was sent

type: ChatMessageType

uuid: str | None: message identifier originally sent by client

sender: UserCompact | None: embedded UserCompact object to save additional api lookups

class osu.objects.Comment(data)

Represents a single comment.

commentable_id: int: ID of the object the comment is attached to

commentable_type: str: type of object the comment is attached to

created_at: datetime.datetime

deleted_at: Option[datetime.datetime]

deleted_by_id: int | None: user id of the user that deleted the post; null, otherwise

edited_at: datetime.datetime | None

edited_by_id: int | None: user id of the user that edited the post; null, otherwise

id: int: the ID of the comment

legacy_name: str | None: username displayed on legacy comments

message: str | None: markdown of the comment’s content

message_html: str | None: html version of the comment’s content

parent_id: int | None: ID of the comment’s parent

pinned: bool: Pin status of the comment

replies_count: int: number of replies to the comment

updated_at: datetime.datetime

user: UserCompact | None

user_id: int: user ID of the poster

votes_count: int: number of votes

url: str: URL to the comment

class osu.objects.CommentBundle(data)

Comments and related data.

commentable_meta: List[CommentableMeta]: ID of the object the comment is attached to

comments: List[Comment]: List of comments ordered according to sort

has_more: bool: If there are more comments or replies available

has_more_id: int

included_comments: List[Comment]: Related comments; e.g. parent comments and nested replies

pinned_comments: List[Comment]: Pinned comments

sort: CommentSort

cursor: dict

top_level_count: int | None: Number of comments at the top level. Not returned for replies.

total: int | None: Total number of comments. Not returned for replies.

user_follow: bool: is the current user watching the comment thread?

user_votes: List[int]: IDs of the comments in the bundle the current user has upvoted

users: List[UserCompact]: List of users related to the comments

class osu.objects.CommentNewDetails(data)

New comment

Extends NotificationsDetailsBase

comment_id: int

title: str

content: str

cover_url: str

class osu.objects.CommentableMeta(data)

Metadata of the object that a comment is attached to. If the object is deleted then title is the only attribute with a value.

id: int | None: the ID of the object

owner_id: int | None: the ID of the owner of the object

owner_title: int | None: undocumented

title: str | None: display title

type: str | None: the type of the object

url: str | None: url of the object

current_user_attributes: CommentableMetaAttributes

class osu.objects.CommentableMetaAttributes(data)

User attributes for a CommentableMeta object

can_new_comment_reason: str | None

class osu.objects.Country(data)

Country data

code: str

name: str

display: int | None

class osu.objects.CountryStatistics(data)

code: str

active_users: int

play_count: int

ranked_score: int

performance: int

country: Country

class osu.objects.Covers(data)

cover: str

cover_2x: str

card: str

card_2x: str

list: str

list_2x: str

slimcover: str

slimcover_2x: str

class osu.objects.CurrentNomination(data)

Info about a nomination

beatmapset_id: int

rulesets: List[GameModeStr] | None

reset: bool

user_id: int

class osu.objects.CurrentUserPin(data)

Gives info about a score related to if it’s pinned or not

is_pinned: bool

score_id: int

score_type: ObjectType | None

class osu.objects.DailyChallengeUserStats(data)

Daily challenge stats of a user

daily_streak_best: int

daily_streak_current: int

last_update: datetime.datetime | None

last_weekly_streak: datetime.datetime | None

playcount: int

top_10p_placements: int

top_50p_placements: int

user_id: int

weekly_streak_best: int

weekly_streak_current: int

class osu.objects.Event(data)

Base class of an event

created_at: datetime.datetime

id: int

type: All types and the additional attributes they provide are listed under ‘Event Types’

class osu.objects.EventBeatmap(data)

title: str

url: str

class osu.objects.EventBeatmapset(data)

title: str

url: str

class osu.objects.EventUser(data)

username: str

url: str

previous_username: str | None: Only for UsernameChangeEvent.

class osu.objects.Failtimes(data)

exit: List[int] | None: List of 100 integers.

fail: List[int] | None: List of 100 integers.

class osu.objects.Forum(data)

id: int

name: str

description: str

subforums: List[Forum] | None

class osu.objects.ForumPost(data)

created_at: datetime.datetime

deleted_at: datetime.datetime | None

edited_at: datetime.datetime | None

edited_by_id: int | None

forum_id: int

id: int

topic_id: int

user_id: int

body: TextFormat | None

class osu.objects.ForumTopic(data)

created_at: datetime.datetime

deleted_at: datetime.datetime | None

first_post_id: int

forum_id: int

id: int

is_locked: bool

last_post_id: int

poll: Poll | None

post_count: int

title: str

type: ForumTopicType

updated_at: datetime.datetime

user_id: int

views: int

class osu.objects.ForumTopicReplyDetails(data)

Forum topic reply

Extends NotificationsDetailsBase

title: str

post_id: int

cover_url: str

class osu.objects.GithubUser(data)

display_name: str

github_url: str | None

id: int | None

osu_username: str | None

user_id: int | None

user_url: str | None

class osu.objects.Group(data)

This object isn’t returned by any endpoints yet, it is here purely as a reference for UserGroup

id: int

identifier: str: Unique string to identify the group.

is_probationary: bool: Whether members of this group are considered probationary.

has_playmodes: bool: If this group associates GameModes with a user’s membership, e.g. BN/NAT members

has_listing: bool: Whether this group displays a listing at /groups/{id}

name: str

short_name: str: Short name of the group for display.

colour: str | None

description: TextFormat | None: A dictionary with keys html and markdown.

class osu.objects.KudosuGiver(data)

url: str

username: str

class osu.objects.KudosuHistory(data)

id: int

action: KudosuAction

amount: int

model: ObjectType: Object type which the exchange happened on (forum_post, etc).

created_at: datetime.datetime

giver: KudosuGiver | None: Simple detail of the user who started the exchange.

post: KudosuPost: Simple detail of the object for display.

class osu.objects.KudosuPost(data)

url: str | None: Url of the object.

title: str: Title of the object. It’ll be “[deleted beatmap]” for deleted beatmaps.

class osu.objects.LazerMod(data)

mod: Mod

settings: Dict | None

class osu.objects.LegacyNominations(data)

Shows info about nominations on a beatmapset, extending BaseNominations

is_legacy: bool: True

current: int

required: int

class osu.objects.LegacyScore(data)

Contains information about a score

id: int

best_id: int

user_id: int

accuracy: float

mods: Mods

score: int

max_combo: int

perfect: bool

statistics: ScoreStatistics

passe: bool

pp: float

rank: ScoreRank

created_at: datetime.datetime

mode: GameModeStr

mode_int: GameModeInt

has_replay: bool: is the replay is available

beatmap: BeatmapCompact | None

beatmapset: BeatmapsetCompact | None

rank_country: int | None

rank_global: int | None

weight: PpWeight | None

user: UserCompact | None

match: MatchGameScoreInfo | None

current_user_attributes: ScoreUserAttributes | None

class osu.objects.Match(data)

Info of a match, relevant at osu.Client.get_matches().

id: int

name: str

start_time: datetime.datetime | None

end_time: datetime.datetime | None

class osu.objects.MatchEvent(data, api_version)

An event that occurred in a match.

id: int

timestamp: datetime.datetime

user_id: int

type: MatchEventType

text: str | None: None unless the event type is MatchEventType.OTHER

game: MatchGame | None: None unless the event type is MatchEventType.OTHER

class osu.objects.MatchExtended(data, api_version)

Extended version of Match that is relevant at the osu.Client.get_match() endpoint.

events: List[MatchEvent]: List of events that occurred in the match.

users: List[UserCompact]

first_event_id: int

latest_event_id: int

current_game_id: int

class osu.objects.MatchGame(data, api_version)

Represents a map played in a match and contains all the info about the game

beatmap_id: int

id: int

start_time: datetime.datetime | None

end_time: datetime.datetime | None

mode: GameModeStr

mode_int: GameModeInt

scoring_type: ScoringType

team_type: TeamType

mods: Mods

beatmap: BeatmapCompact | None

scores: List[LegacyScore | SoloScore]

class osu.objects.MatchGameScoreInfo(data)

Says info about a score set in a match. Is an attribute of LegacyScore

slot: int

team: str

passed: bool

class osu.objects.MetadataAttribute(data)

Genre of a beatmapset

id: int | None

name: str

class osu.objects.MultiplayerScore(data)

Score data.

id: int

user_id: int

room_id: int

playlist_item_id: int

beatmap_id: int

rank: str

total_score: int

accuracy: float

max_combo: int

mods: List[LazerMod]

statistics: ScoreDataStatistics

passed: bool

position: int | None

scores_around: MultiplayerScoresAround | None: Scores around the specified score.

user: User

class osu.objects.MultiplayerScores(data)

An object which contains scores and related data for fetching next page of the result.

cursor: str: To be used to fetch the next page.

params: dict: To be used to fetch the next page.

scores: List[MultiplayerScore]

total: int | None: Index only. Total scores of the specified playlist item.

user_score: MultiplayerScore | None: Index only. Score of the accessing user if exists.

class osu.objects.MultiplayerScoresAround(data)

higher: MultiplayerScores

lower: MultiplayerScores

class osu.objects.Navigation(data)

newer: NewsPost | None: null if the next post is not present.

older: NewsPost | None: null if the previous post is not present.

class osu.objects.NewsPost(data)

author: str

edit_url: str: Link to the file view on GitHub.

first_image: str | None: Link to the first image in the document.

first_image_2x: str | None: 2x version of first_image. Will be None if first_image is None and vice-versa.

id: int

published_at: datetime.datetime

slug: str: Filename without the extension, used in URLs.

title: str

updated_at: datetime.datetime

content: str | None: HTML post content.

navigation: Navigation | None: Navigation metadata.

preview: str | None: First paragraph of content with HTML markup stripped.

class osu.objects.Nominations(data)

Shows info about nominations on a beatmapset, extending BaseNominations

is_legacy: bool: False

current: int | Dict[GameModeStr, int]

required: int

class osu.objects.Notification(data)

Represents a notification object. Go to Details object to see details for each event

id: int

name: NotificationType: The type of event

created_at: datetime.datetime

object_type: ObjectType

object_id: int

source_user_id: int | None

is_read: bool

**Documente

beatmapset_discussion_loc: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion

beatmapset_discussion_post_ne: object_id: Beatmapset id object_type: beatmapset source_user_id: Poster of the discussion

beatmapset_discussion_unloc: object_id: Beatmapset id object_type: beatmapset source_user_id: User who unlocked discussion

beatmapset_disqualif: object_id: Beatmapset id object_type: beatmapset source_user_id: User who disqualified beatmapset

beatmapset_lov: object_id: Beatmapset id object_type: beatmapset source_user_id: User who promoted beatmapset to Loved

beatmapset_nominat: object_id: Beatmapset id object_type: beatmapset source_user_id: User who nominated beatmapset

beatmapset_qualif: object_id: Beatmapset id object_type: beatmapset source_user_id: User whom beatmapset nomination triggered qualification

beatmapset_remove_from_love: object_id: Beatmapset id object_type: beatmapset source_user_id: User who removed beatmapset from Loved

beatmapset_reset_nomination: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion

channel_messag: object_id: Channel id object_type: channel source_user_id: User who posted message

forum_topic_repl: object_id: Topic id object_type: forum_topic source_user_id: User who posted message

class osu.objects.NotificationsDetailsBase(data)

Base class for all Detail objects.

username: str

class osu.objects.OsuBeatmapDifficultyAttributes(data)

osu!standard beatmap difficulty attributes. See BeatmapDifficultyAttributes for more information.

aim_difficulty: float

aim_difficult_slider_count: float

speed_difficulty: float

speed_note_count: float

slider_factor: float

aim_difficult_strain_count: float

speed_difficult_strain_count: float

class osu.objects.PlaylistItem(data)

id: int

room_id: int

beatmap_id: int

ruleset_id: GameModeInt

allowed_mods: List[LazerMod]

required_mods: List[LazerMod]

expired: bool

owner_id: int

playlist_order: int | None

played_at: datetime.datetime | None

beatmap: BeatmapCompact | None

class osu.objects.PlaylistItemStats(data)

count_active: int

count_total: int

ruleset_ids: List[GameModeInt]

class osu.objects.Poll(data)

allow_vote_change: bool

ended_at: datetime.datetime | None

hide_incomplete_results: bool

last_vote_at: datetime.datetime | None

max_votes: int

options: List[PollOption]

started_at: datetime.datetime

title: TextFormat

total_vote_count: int

class osu.objects.PollOption(data)

id: int

text: TextFormat

vote_count: int | None: Not present if the poll is incomplete and results are hidden.

class osu.objects.PpWeight(data)

Weighted pp info

percentage: int: number (0-100) that tells percentage weighed

pp: float: amount of pp after being weighted

class osu.objects.ProfileBanner(data)

id: int

tournament_id: int

image: str | None

image2x: str | None

class osu.objects.RankEvent(data)

score_rank: str

rank: int

mode: GameModeStr

beatmap: EventBeatmap

user: EventUser

class osu.objects.RankHighest(data)

Highest rank a player achieved at any point in time.

rank: int

updated_at: datetime.datetime

class osu.objects.RankHistory(data)

Rank history data for a user

mode: GameModeStr

data: List[int]: List of ranks from oldest to newest

class osu.objects.RankLostEvent(data)

mode: GameModeStr

beatmap: EventBeatmap

user: EventUser

class osu.objects.Rankings(data, ranking_cls: Type[_RankingT])

A generic ranking object with statistic type being denoted by _RankingT

cursor: Dict: To be used to query the next page

ranking: List[_RankingT]: Statistics ordered by rank in descending order. Type depends on _RankingT (determined during construction)

total: int: An approximate count of ranks available

class osu.objects.ReadNotification(data)

Represents a read notification.

category: NotificationCategory

id: int

object_id: int

object_type: ObjectType

class osu.objects.Review(data)

max_blocks: int

class osu.objects.ReviewStats(data)

praises: int

suggestions: int

problems: int

class osu.objects.Room(data)

osu.Client.get_rooms() and osu.Client.get_room() endpoints include host, playlist, and recent_participants attributes. In addition, the PlaylistItem objects in playlist include the beatmap attribute and the beatmap attribute has the beatmapset, checksum, and max_combo attributes.

id: int

name: str

category: RoomCategory

status: RoomStatus

type: RoomType

realtime_type: RealTimeType: Only applicable when type is RoomType.REALTIME

user_id: int

starts_at: datetime.datetime | None

ends_at: datetime.datetime | None

max_attempts: int

participant_count: int

channel_id: int

active: bool

has_password: bool

queue_mode: RealTimeQueueMode | PlaylistQueueMode: Type depends on the room type. PlaylistQueueMode for type RoomType.PLAYLIST and RealTimeQueueMode otherwise.

current_playlist_item: PlaylistItem | None

current_user_score: UserScoreAggregate | None

difficulty_range: Dict[str, int] | None: When not none, is a dictionary containing keys “max” and “min”

host: UserCompact | None

playlist: List[PlaylistItem] | None

playlist_item_stats: PlaylistItemStats | None

recent_participants: List[UserCompact] | None

scores: MultiplayerScore | None

class osu.objects.ScoreDataStatistics(data)

ok: int | None

meh: int | None

good: int | None

miss: int | None

none: int | None

great: int | None

perfect: int | None

ignore_hit: int | None

ignore_miss: int | None

large_bonus: int | None

small_bonus: int | None

large_tick_hit: int | None

small_tick_hit: int | None

large_tick_miss: int | None

small_tick_miss: int | None

slider_tail_hit: int | None

combo_break: int | None

legacy_combo_increase: int | None

class osu.objects.ScoreStatistics(data)

count_50: int

count_100: int

count_300: int

count_geki: int

count_katu: int

count_miss: int

class osu.objects.ScoreUserAttributes(data)

Gives info about a score related to the current user

pin: CurrentUserPin | None

class osu.objects.SearchResults(data, data_type)

Represents the results of a search.

results: List[UserCompact | WikiPage]: type depends on search type

total: int

class osu.objects.SeasonalBackground(data)

Represents a seasonal background.

url: str: The url of the background.

user: UserCompact: The artist of the background.

class osu.objects.SeasonalBackgrounds(data)

Contains data on the seasonal backgrounds.

ends_at: datetime.datetime: The date when the seasonal backgrounds will end.

backgrounds: List[SeasonalBackground]: A list of all the seasonal backgrounds.

class osu.objects.SoloScore(data)

Contains information about a score in lazer format (may be scores set on stable).

accuracy: float

beatmap_id: int | None

beatmap: Beatmap | None

beatmapset: BeatmapsetCompact | None

ended_at: datetime.datetime

max_combo: int

maximum_statistics: ScoreDataStatistics

mods: List[LazerMod]

passed: bool

rank: ScoreRank

ruleset_id: int

statistics: ScoreDataStatistics

total_score: int

user_id: int

best_id: int | None

id: int

legacy_perfect: bool | None

pp: float | None

replay: bool

type: ObjectType

user: UserCompact | None

build_id: int | None

legacy_score_id: int | None

legacy_total_score: int | None

started_at: datetime.datetime | None

current_user_attributes: ScoreUserAttributes | None

weight: PpWeight | None

match: MatchGameScoreInfo | None

class osu.objects.Spotlight(data)

The details of a spotlight.

end_date: datetime.datetime: In DateTime format. The end date of the spotlight.

id: int: The ID of this spotlight.

mode_specific: bool: If the spotlight has different modes specific to each game mode.

participant_count: int | None: The number of users participating in this spotlight. This is only shown when viewing a single spotlight.

name: str: The name of the spotlight.

start_date: datetime.datetime: In DatTime format. The starting date of the spotlight.

type: str: The type of spotlight.

class osu.objects.SpotlightRankings(data)

beatmapsets: List[Beatmapset]

ranking: List[UserStatistics]

spotlight: Spotlight

class osu.objects.Spotlights(data)

spotlights: List[Spotlight]

class osu.objects.SystemDiscussionPostMessage(data)

System message of BeatmapsetDiscussionPost

type: str

value: bool

class osu.objects.TaikoBeatmapDifficultyAttributes(data)

osu!taiko beatmap difficulty attributes. See BeatmapDifficultyAttributes for more information.

mono_stamina_factor: float

class osu.objects.TextFormat(data)

A page that has html and raw data

html: str

raw: str

class osu.objects.UpdateStream(data)

display_name: str | None

id: int

is_featured: bool

name: str

latest_build: Build | None

user_count: int | None

class osu.objects.User(data)

Represents a User. Extends UserCompact with additional attributes. Includes country, cover, and is_restricted attributes of UserCompact.

cover_url: str: url of profile cover. Deprecated, use cover.url instead.

discord: str | None

has_supported: bool: Has been a supporter in the past

interests: str | None

join_date: datetime.datetime

kudosu: UserKudosu

location: str | None

max_blocks: int: maximum number of users allowed to be blocked

max_friends: int: maximum number of friends allowed to be added

occupation: str | None

playmode: GameModeStr

playstyle: List[str]: Device choices of the user.

post_count: int: number of forum posts

profile_hue: int | None: Custom color hue in HSL degrees (0-359).

profile_order: List[str]: Ordered list of sections in user profile page. Sections consist of: me, recent_activity, beatmaps, historical, kudosu, top_ranks, medals

title: str | None: user-specific title

title_url: str | None

twitter: str | None

website: str | None

class osu.objects.UserAccountHistory(data)

actor: UserCompact | None

description: str

id: int

length: int

permanent: bool

supporting_url: str | None

timestamp: datetime.datetime

type: UserAccountHistoryType

class osu.objects.UserAchievement(data)

An achievement that a user received

achieved_at: datetime.datetime

achievement_id: int

class osu.objects.UserAchievementUnlockDetails(data)

New achievement unlocked

Extends NotificationsDetailsBase

achievement_id: int

achievement_mode: GameModeStr | None

cover_url: str

slug: str

title: str

user_id: int

class osu.objects.UserBadge(data)

awarded_at: datetime.datetime

description: str

image_url: str

image_2x_url: str

url: str

class osu.objects.UserBeatmapsetNewDetails(data)

New beatmapset

Extends: NotificationsDetailsBase

beatmapset_id: int

title: str

title_unicode: str

cover_url: str

class osu.objects.UserBeatmapsetReviveDetails(data)

User beatmapset revived

Extends UserBeatmapsetNewDetails

class osu.objects.UserCompact(data)

Mainly used for embedding in certain responses to save additional api lookups.

avatar_url: str: url of user’s avatar

country_code: str: two-letter code representing user’s country

default_group: str: Identifier of the default Group the user belongs to.

id: int: unique identifier for user

is_active: bool: has this account been active in the last x months?

is_bot: bool: is this a bot account?

is_deleted: bool

is_online: bool: is the user currently online? (either on lazer or the new website)

is_supporter: bool: does this user have supporter?

last_visit: datetime.datetime | None: null if the user hides online presence

pm_friends_only: bool: whether or not the user allows PM from other than friends

profile_colour: str | None: colour of username/profile highlight, hex code (e.g. #333333)

username: str: user’s display name

account_history: List[UserAccountHistory] | None

active_tournament_banner: ProfileBanner | None: deprecated; use active_tournament_banners

active_tournament_banners: List[ProfileBanner] | None

badges: List[UserBadge] | None

beatmap_playcounts_count: int | None

blocks: List[UserRelations] | None

comments_count: int | None

country: Country | None

cover: UserCover | None

daily_challenge_user_stats: DailyChallengeUserStats | None

favourite_beatmapset_count: int | None

follow_user_mapping: List[int] | None

follower_count: int | None

friends: List[UserRelation] | None

global_rank: UserRank | None

graveyard_beatmapset_count: int | None

groups: List[UserGroup] | None

guest_beatmapset_count: int | None

is_admin: bool | None

is_bng: bool | None

is_gmt: bool | None

is_limited_bn: bool | None

is_moderator: bool | None

is_nat: bool | None

is_restricted: bool | None

is_silenced: bool | None

loved_beatmapset_count: int | None

mapping_follower_count: int | None

monthly_playcounts: List[UserMonthlyPlaycount] | None

nominated_beatmapset_count: int | None

page: TextFormat | None

pending_beatmapset_count: int | None

previous_usernames: List[str] | None

rank_highest: RankHighest | None

rank_history: RankHistory | None

ranked_beatmapset_count: int | None

replays_watched_counts: List[UserReplaysWatchedCount] | None

scores_best_count: int | None

scores_first_count: int | None

scores_pinned_count: int | None

scores_recent_count: int | None

statistics: UserStatistics | None

statistics_rulesets: UserStatisticsRulesets | None

support_level: int | None

team: UserTeam | None

unread_pm_count: int | None

user_achievements: List[UserAchievement] | None

user_preferences: UserPreferences | None

class osu.objects.UserCover(data)

Cover of a user’s profile

custom_url: str | None

url: str | None

id: int | None

class osu.objects.UserGroup(data)

Describes the Group membership of a User. It contains all of the attributes of the Group, in addition to what is listed here.

playmodes: List[GameModeStr] | None: GameModes associated with this membership (None if has_playmodes is false).

class osu.objects.UserKudosu(data)

User kudosu data

total: int

available: int

class osu.objects.UserMonthlyPlaycount(data)

start_date: datetime.date: year-month-day format

count: class:`int`: playcount

class osu.objects.UserPreferences(data)

The settings preferences of a user

audio_autoplay: bool

audio_muted: bool

audio_volume: float

beatmapset_card_size: str: normal or extra
beatmapset_download: str: all, no_video, or direct

beatmapset_show_nsfw: bool

beatmapset_title_show_original: bool

comments_show_deleted: bool

forum_posts_show_deleted: bool

profile_cover_expanded: bool

user_list_filter: str: all, online, or offline
user_list_sort: str: last_visit, rank, or username
user_list_view: str: brick, card, or list

class osu.objects.UserRelation(data)

Info about relationship to a user

target_id: int: zebra id

relation_type: UserRelationType

mutual: bool

target: UserCompact | None

class osu.objects.UserReplaysWatchedCount(data)

The count of replays watched for a month

start_date: datetime.datetime

count: int

class osu.objects.UserScoreAggregate(data)

accuracy: float

attempts: int

completed: int

pp: float

room_id: int

total_score: int

user_id: int

playlist_item_attempts: Dict[str, int] | None: contains keys “attempts” and “id”.

position: int | None: user rank

user: UserCompact | None

class osu.objects.UserSilence(data)

A record indicating a User was silenced.

id: int: id of this object.

user_id: int: id of the User that was silenced

class osu.objects.UserStatisticVariant(data)

A variant ranking system.

country_rank: int | None

global_rank: int | None

mode: GameModeStr

pp: int

variant: str: 4k or 7k

class osu.objects.UserStatistics(data)

A summary of various gameplay statistics for a User. Specific to a GameMode

accuracy: float: Accuracy, as a decimal in [0, 1] range.

count_300: int

count_100: int

count_50: int

count_miss: int

country_rank: int | None: Current country rank according to pp.

global_rank: int | None: Current global rank according to pp.

global_rank_exp: int | None: Current global rank according to experimental pp (not used anymore).

grade_counts: NamedTuple

Below are the attributes and their meanings.

a: int: Number of A ranked scores.
s: int: Number of S ranked scores.
sh: int: Number of Silver S ranked scores.
ss: int: Number of SS ranked scores.
ssh: int: Number of Silver SS ranked scores.

hit_accuracy: float: DEPRECATED: use accuracy. Hit accuracy percentage.

is_ranked: bool: Does the player have a rank

level: NamedTuple: Has attributes ‘current’ (current level) and ‘progress’ (progress to next level).

maximum_combo: int: Highest maximum combo.

play_count: int: Number of maps played.

play_time: int: Cumulative time played.

pp: int: Performance points

pp_exp: int | None: Experimental performance points (not used anymore)

rank_change_since_30_days: int | None

recommended_difficulty: float | None: Recommended difficulty for a player. This value is not received from the api, but locally calculated. The formula is pp^0.4 * 0.195

recommended_difficulty_exp: float | None: Recommended difficulty based on the pp_exp value.

ranked_score: int: Current ranked score.

replays_watched_by_others: int: Number of replays watched by other users.

total_hits: int: Total number of hits.

total_score: int: Total score.

user: UserCompact | None: The associated user.

variants: List[UserStatisticVariant] | None

class osu.objects.UserStatisticsRulesets(data)

Object that contains statistics for each gamemode.

osu: UserStatistics | None: statistics for osu!standard.

taiko: UserStatistics | None: statistics for osu!taiko.

fruits: UserStatistics | None: statistics for osu!catch.

mania: UserStatistics | None: statistics for osu!mania.

class osu.objects.UserSupportAgainEvent(data)

user: EventUser

class osu.objects.UserSupportFirstEvent(data)

user: EventUser

class osu.objects.UserSupportGiftEvent(data)

user: EventUser

class osu.objects.UserTeam(data)

id: int

flag_url: str | None

name: str

short_name: str

class osu.objects.UserTeamStatistics(data)

team_id: int

ruleset: GameModeInt

play_count: int

ranked_score: int

performance: int

class osu.objects.UsernameChangeEvent(data)

user: EventUser

class osu.objects.Versions(data)

Optional Attributes

next: Optional[Build]: May be null if there is not a next build.
previous: Optional[Build]: May be null if there is not a previous build.

class osu.objects.VotersSummary(data)

Gives a summary of players who voted up and down on a discussion

down: List[int]: List of user IDs of users that downvoted

up: List[int]: List of user IDs of users that upvoted

class osu.objects.VotesSummary(data)

Summarizes the votes of a discussion

down: int: Number of downvotes

up: int: Number of upvotes

voters: VotersSummary: summarizes who voted up and down

class osu.objects.WikiPage(data)

Represents a wiki article

available_locales: List[str]: All available locales for the article.

layout: str: The layout type for the page.

locale: str: All lowercase BCP 47 language tag.

markdown: str: Markdown content.

path: str: Path of the article.

subtitle: str | None: The article’s subtitle.

tags: List[str]: Associated tags for the article.

title: str: The article’s title.

Utility

Note

These can be imported directly from osu

class osu.util.BeatmapsetSearchFilter

Util class that helps for filtering in osu.Client.search_beatmapsets().

Read about each filter under its corresponding function.

All set functions return the instance of the class to allow for chaining.

property filters: dict: Dictionary of all filters only including ones that have been set.

set_extra(extras: Sequence[BeatmapsetSearchExtra | str]) → BeatmapsetSearchFilter

Set the extras to filter by.

extras: Sequence[Union[BeatmapsetSearchExtra, str]]

set_generals(generals: Sequence[BeatmapsetSearchGeneral | str]) → BeatmapsetSearchFilter

Set the generals to filter by.

generals: Sequence[Union[BeatmapsetSearchGeneral, str]]

set_genre(genre: BeatmapsetGenre | int) → BeatmapsetSearchFilter

Set the genre to filter by.

genre: str

set_language(language: BeatmapsetLanguage | int) → BeatmapsetSearchFilter

Set the language to filter by.

language: str

set_mode(mode: GameModeInt | int) → BeatmapsetSearchFilter

Set the game mode to filter by.

mode: Union[GameModeInt, str]

set_nsfw(nsfw: bool) → BeatmapsetSearchFilter

Set whether to include NSFW in the search.

nsfw: bool

set_played(played: BeatmapsetSearchPlayed | str) → BeatmapsetSearchFilter

Set whether to include played and unplayed beatmapsets in the search.

played: Union[BeatmapsetSearchPlayed, str]

set_query(query: str) → BeatmapsetSearchFilter

Set the query to search for.

query: str

set_ranked(rank: ScoreRank | str) → BeatmapsetSearchFilter

Filter by rank achieved.

rank: Union[ScoreRank, str]

set_sort(sort: BeatmapsetSearchSort | str, order: str = 'desc') → BeatmapsetSearchFilter

Set the sort order of the search.

sort: Union[BeatmapsetSearchSort, str]

order: str: “desc” or “asc”

set_status(status: BeatmapsetSearchStatus | str) → BeatmapsetSearchFilter

Set the status to filter by.

status: Union[BeatmapsetSearchStatus, str]

Init parameters

category: Optional[Union[str, NotificationCategory]]: Notification category.
object_id: Optional[str]: Id of the object that triggered the notification
object_type: Optional[Union[str, ObjectType]]: Type of the object that triggered the notification

Init parameters

category: Optional[Union[str, NotificationCategory]]: Notification category.
id: Optional[int]: Id of notification to be marked as read
object_id: Optional[str]: Id of the object that triggered the notification
object_type: Optional[Union[str, ObjectType]]: Type of the object that triggered the notification

class osu.util.PlaylistItemUtil(beatmap_id: int, ruleset_id: GameModeInt | int, allowed_mods: Sequence[Mod] | None = None, required_mods: Sequence[Mod] | None = None)

Util class for passing playlist items to endpoints that involve creating a room like create_multiplayer_room and create_playlist.

Init Parameters

beatmap_id: int

ruleset_id: Union[GameModeInt, int]

allowed_mods: Sequence[Mod]

required_mods: Sequence[Mod]

Properties

json: dict: Dictionary format of all the attributes which the client uses when sending a http request

Enums

Note

These can be imported directly from osu

class osu.enums.BeatmapsetEventSort(value, *args, **kwargs)

Sort option for beatmapset events. Relevant to osu.Client.get_beatmapset_events().

Beatmapset event sorts

ASC = ‘id_asc’

DESC = ‘id_desc’

class osu.enums.BeatmapsetEventType(value, *args, **kwargs)

Enum for beatmapset event types. Relevant to osu.Client.get_beatmapset_events().

Beatmapset event types

NOMINATE = ‘nominate’

LOVE = ‘love’

REMOVE_FROM_LOVED = ‘unlove’

QUALIFY = ‘qualify’

DISQUALIFY = ‘disqualify’

APPROVE = ‘approve’

RANK = ‘rank’

KUDOSU_ALLOW = ‘kudosu_allow’

KUDOSU_DENY = ‘kudosu_deny’

KUDOSU_GAIN = ‘kudosu_gain’

KUDOSU_LOST = ‘kudosu_lost’

KUDOSU_RECALCULATE = ‘kudosu_recalculate’

ISSUE_RESOLVE = ‘issue_resolve’

ISSUE_REOPEN = ‘issue_reopen’

DISCUSSION_LOCK = ‘discussion_lock’

DISCUSSION_UNLOCK = ‘discussion_unlock’

DISCUSSION_DELETE = ‘discussion_delete’

DISCUSSION_RESTORE = ‘discussion_restore’

DISCUSSION_POST_DELETE = ‘discussion_post_delete’

DISCUSSION_POST_RESTORE = ‘discussion_post_restore’

NOMINATION_RESET = ‘nomination_reset’

NOMINATION_RESET_RECEIVED = ‘nomination_reset_received’

GENRE_EDIT = ‘genre_edit’

LANGUAGE_EDIT = ‘language_edit’

NSFW_TOGGLE = ‘nsfw_toggle’

OFFSET_EDIT = ‘offset_edit’

BEATMAP_OWNER_CHANGE = ‘beatmap_owner_change’

class osu.enums.BeatmapsetGenre(value, *args, **kwargs)

Genre of a beatmapsets

Genres

UNSPECIFIED = 1

VIDEO_GAME = 2

ANIME = 3

ROCK = 4

POP = 5

OTHER = 6

NOVELTY = 7

HIP_HOP = 9

ELECTRONIC = 10

METAL = 11

CLASSICAL = 12

FOLK = 13

JAZZ = 14

class osu.enums.BeatmapsetLanguage(value, *args, **kwargs)

Language of a beatmapset

Languages

UNSPECIFIED = 1

ENGLISH = 2

JAPANESE = 3

CHINESE = 4

INSTRUMENTAL = 5

KOREAN = 6

FRENCH = 7

GERMAN = 8

SWEDISH = 9

SPANISH = 10

ITALIAN = 11

RUSSIAN = 12

POLISH = 13

OTHER = 14

class osu.enums.BeatmapsetSearchExtra(value, *args, **kwargs)

Extra options for beatmapset filtering. Relevant to osu.Client.search_beatmapsets().

Beatmapset search extra options

VIDEO = ‘video’

STORYBOARD = ‘storyboard’

class osu.enums.BeatmapsetSearchGeneral(value, *args, **kwargs)

General options for beatmapset filtering. Relevant to osu.Client.search_beatmapsets().

Beatmapset search general options

RECOMMENDED = ‘recommended’

CONVERTS = ‘converts’

FOLLOWS = ‘follows’

SPOTLIGHTS = ‘spotlights’

FEATURED_ARTISTS = ‘featured_artists’

class osu.enums.BeatmapsetSearchPlayed(value, *args, **kwargs)

Played options for beatmapset filtering. Relevant to osu.Client.search_beatmapsets().

Beatmapset search played options

ANY = ‘any’

PLAYED = ‘played’

UNPLAYED = ‘unplayed’

class osu.enums.BeatmapsetSearchSort(value, *args, **kwargs)

Sort options for beatmapset searches. Relevant to osu.Client.search_beatmapsets().

Beatmapset search sort options

ARTIST = ‘artist’

CREATOR = ‘creator’

DIFFICULTY = ‘difficulty’

FAVOURITES = ‘favourites’

NOMINATIONS = ‘nominations’

PLAYS = ‘plays’

RANKED = ‘ranked’

RATING = ‘rating’

RELEVANCE = ‘relevance’

TITLE = ‘title’

UPDATED = ‘updated’

class osu.enums.BeatmapsetSearchStatus(value, *args, **kwargs)

Status options for beatmapset filtering. Relevant to osu.Client.search_beatmapsets().

Beatmapset search status options

ANY = ‘any’

HAS_LEADERBOARD = ‘leaderboard’

RANKED = ‘ranked’

QUALIFIED = ‘qualified’

LOVED = ‘loved’

FAVOURITES = ‘favourites’

PENDING = ‘pending’

WIP = ‘wip’

GRAVEYARD = ‘graveyard’

MY_MAPS = ‘mine’

class osu.enums.ChatChannelType(value, *args, **kwargs)

Enum for type of ChatChannel

Chat channel types

PUBLIC = “PUBLIC”

PRIVATE = “PRIVATE”

MULTIPLAYER = “MULTIPLAYER”

SPECTATOR = “SPECTATOR”

TEMPORARY = “TEMPORARY”

PM = “PM”

GROUP = “GROUP”

ANNOUNCE = “ANNOUNCE”

class osu.enums.ChatMessageType(value, *args, **kwargs)

The type of a ChatMessage

Chat message types

ACTION = “action”

MARKDOWN = “markdown”

PLAIN = “plain”

class osu.enums.CommentSort(value, *args, **kwargs)

Type to sort comments by. Relevant to osu.Client.get_comments().

Comment sorts

NEW = ‘new’

OLD = ‘old’

TOP = ‘top’

class osu.enums.ForumTopicType(value, *args, **kwargs)

Enum for ForumTopic type attribute.

Forum topic types

NORMAL = “normal”

STICKY = “sticky”

ANNOUNCEMENT = “announcement”

class osu.enums.GameModeInt(value, *args, **kwargs)

Enums for GameModes using their int values.

GameModes

STANDARD = 0

TAIKO = 1

CATCH = 2

MANIA = 3

class osu.enums.GameModeStr(value, *args, **kwargs)

Enum for GameModes using their string names.

GameModes

STANDARD = ‘osu’

TAIKO = ‘taiko’

CATCH = ‘fruits’

MANIA = ‘mania’

class osu.enums.KudosuAction(value, *args, **kwargs)

A type of action related to kudosu

Kudosu action types

GIVE = “give”

VOTE_GIVE = “vote.give”

RESET = “reset”

VOTE_RESET = “vote.reset”

REVOKE = “revoke”

VOTE_REVOKE = “vote.revoke”

RECALCULATE_RESET = “recalculate.reset”

class osu.enums.MatchEventType(value, *args, **kwargs)

Enum for match event types.

Match event types

PLAYER_LEFT = ‘player-left’

PLAYER_JOINED = ‘player-joined’

PLAYER_KICKED = ‘player-kicked’

MATCH_CREATED = ‘match-created’

MATCH_DISBANDED = ‘match-disbanded’

HOST_CHANGED = ‘host-changed’

OTHER = ‘other’

class osu.enums.MatchSort(value, *args, **kwargs)

Sort options for matches. Relevant to osu.Client.get_matches().

Match sort options

ASCENDING = “id_asc”

DESCENDING = “id_desc”

class osu.enums.MessageType(value, *args, **kwargs)

A type of message in beatmapset discussion

Message types

HYPE = “hype”

MAPPER_NOTE = “mapper_note”

PRAISE = “praise”

PROBLEM = “problem”

REVIEW = “review”

SUGGESTION = “suggestion”

class osu.enums.Mod(value, *args, **kwargs)

Enum of all mods, score submittable or not.

Mods

Easy = ‘EZ’

NoFail = ‘NF’

HalfTime = ‘HT’

Daycore = ‘DC’

HardRock = ‘HR’

SuddenDeath = ‘SD’

Perfect = ‘PF’

DoubleTime = ‘DT’

Nightcore = ‘NC’

Hidden = ‘HD’

Flashlight = ‘FL’

Blinds = ‘BL’

StrictTracking = ‘ST’

Target = ‘TP’

DifficultyAdjust = ‘DA’

Classic = ‘CL’

Random = ‘RD’

Mirror = ‘MR’

Alternate = ‘AL’

SingleTap = ‘SG’

Autoplay = ‘AT’

Cinema = ‘CN’

Relax = ‘RX’

Autopilot = ‘AP’

SpunOut = ‘SO’

Transform = ‘TR’

Wiggle = ‘WG’

SpinIn = ‘SI’

Grow = ‘GR’

Deflate = ‘DF’

WindUp = ‘WU’

WindDown = ‘WD’

Traceable = ‘TC’

BarrelRoll = ‘BR’

ApproachDifferent = ‘AD’

Muted = ‘MU’

NoScope = ‘NS’

Magnetised = ‘MG’

Repel = ‘RP’

AdaptiveSpeed = ‘AS’

FreezeFrame = ‘FR’

TouchDevice = ‘TD’

Swap = ‘SW’

FloatingFruits = ‘FF’

FadeIn = ‘FI’

FourKeys = ‘4K’

FiveKeys = ‘5K’

SixKeys = ‘6K’

SevenKeys = ‘7K’

EightKeys = ‘8K’

NineKeys = ‘9K’

TenKeys = ‘10K’

OneKey = ‘1K’

TwoKeys = ‘2K’

ThreeKeys = ‘3K’

DualStages = ‘DS’

Invert = ‘IN’

ConstantSpeed = ‘CS’

HoldOff = ‘HO’

AccuracyChallenge = ‘AC’

class osu.enums.Mods(value)

IntFlag enum for all score submittable mods. Info gathered from https://github.com/ppy/osu-web/blob/973315aded8a5762fc00a9f245337802c27bd213/app/Libraries/Mods.php and https://github.com/ppy/osu-web/blob/973315aded8a5762fc00a9f245337802c27bd213/database/mods.json

List of mods, their acronyms, and their bitwise representation

NoFail (NF) = 1 << 0

Easy (EZ) = 1 << 1

TouchDevice (TD) = 1 << 2 # Replaces unused NoVideo mod

Hidden (HD) = 1 << 3

HardRock (HR) = 1 << 4

SuddenDeath (SD) = 1 << 5

DoubleTime (DT) = 1 << 6

Relax (RX) = 1 << 7

HalfTime (HT) = 1 << 8

Nightcore (NC) = (1 << 9)

Flashlight (FL) = 1 << 10

SpunOut (SO) = 1 << 12

AutoPilot (AP) = 1 << 13

Perfect (PF) = 1 << 14

FadeIn (FI) = 1 << 20

Mirror (MR) = 1 << 30

Key4 (4K) = 1 << 15

Key5 (5K) = 1 << 16

Key6 (6K) = 1 << 17

Key7 (7K) = 1 << 18

Key8 (8K) = 1 << 19

Key9 (9K) = 1 << 24

classmethod get_from_abbreviation(abbreviation: str) → Mods

Get mod from its abbreviation. Abbreviations are taken from https://osu.ppy.sh/wiki/en/Game_modifier/Summary

Parameters:: abbreviation: (str) – Abbreviation of the mod (must be capitalized)
Return type:: Mods

static get_from_list(mods: Sequence[Mods]) → Mods | None

Get a Mods object from a list of Mods.

Parameters:: mods: (Sequence[Mods]) – Sequence of mods of type Mods
Return type:: Union[Mods, NoneType]

get_incompatible_mods()

Get a list of mods that are incompatible with this mod.

Return type:: Sequence[Mods]

is_compatible_combination()

Check if all the mods in this Mods object are compatible with each other.

Return type:: bool

is_compatible_with(other: Mods)

Check if this mod is compatible with another mod.

Parameters:: other: (Mods) – Mod to check compatibility with.
Return type:: bool

static parse_any_list(mods: Sequence[str | int | Mods]) → Mods

Take a list and return a parsed list. Parsing the list involves converting any object recognizable as a mod to a Mods object. This includes mod names/abbreviations as strings and also their bitset values.

Parameters:: mods: (Sequence[Union[Mods, str, int]]) – Sequence of Mods, str, and/or int objects to be parsed and returned as a Mods object.
Return type:: Union[Mods, NoneType]

to_readable_string()

Get a readable string representation of this mod (sorted by bitset ascending). Example: (Mods.HardRock | Mods.Hidden) -> “HDHR”

Return type:: str

class osu.enums.MultiplayerScoresSort(value, *args, **kwargs)

Sort option for multiplayer scores index. Relevant to osu.Client.get_scores().

Multiplayer scores sorts

ASC = ‘score_asc’

DESC = ‘score_desc’

class osu.enums.NotificationCategory(value, *args, **kwargs)

Enum for notification categories.

Notification Categories

BEATMAP_OWNER_CHANGE = ‘beatmap_owner_change’

BEATMAPSET_DISCUSSION_LOCK = ‘beatmapset_discussion’

BEATMAPSET_DISCUSSION_POST_NEW = ‘beatmapset_discussion’

BEATMAPSET_DISCUSSION_QUALIFIED_PROBLEM = ‘beatmapset_problem’

BEATMAPSET_DISCUSSION_REVIEW_NEW = ‘beatmapset_discussion’

BEATMAPSET_DISCUSSION_UNLOCK = ‘beatmapset_discussion’

BEATMAPSET_DISQUALIFY = ‘beatmapset_state’

BEATMAPSET_LOVE = ‘beatmapset_state’

BEATMAPSET_NOMINATE = ‘beatmapset_state’

BEATMAPSET_QUALIFY = ‘beatmapset_state’

BEATMAPSET_RANK = ‘beatmapset_state’

BEATMAPSET_REMOVE_FROM_LOVED = ‘beatmapset_state’

BEATMAPSET_RESET_NOMINATIONS = ‘beatmapset_state’

CHANNEL_ANNOUNCEMENT = ‘announcement’

CHANNEL_MESSAGE = ‘channel’

COMMENT_NEW = ‘comment’

FORUM_TOPIC_REPLY = ‘forum_topic_reply’

USER_ACHIEVEMENT_UNLOCK = ‘user_achievement_unlock’

USER_BEATMAPSET_NEW = ‘user_beatmapset_new’

USER_BEATMAPSET_REVIVE = ‘user_beatmapset_new’

class osu.enums.NotificationType(value, *args, **kwargs)

Types of notifications that can be received.

Notification types

BEATMAP_OWNER_CHANGE = ‘beatmap_owner_change’

BEATMAPSET_DISCUSSION_LOCK = ‘beatmapset_discussion_lock’

BEATMAPSET_DISCUSSION_POST_NEW = ‘beatmapset_discussion_post_new’

BEATMAPSET_DISCUSSION_QUALIFIED_PROBLEM = ‘beatmapset_discussion_qualified_problem’

BEATMAPSET_DISCUSSION_REVIEW_NEW = ‘beatmapset_discussion_review_new’

BEATMAPSET_DISCUSSION_UNLOCK = ‘beatmapset_discussion_unlock’

BEATMAPSET_DISQUALIFY = ‘beatmapset_disqualify’

BEATMAPSET_LOVE = ‘beatmapset_love’

BEATMAPSET_NOMINATE = ‘beatmapset_nominate’

BEATMAPSET_QUALIFY = ‘beatmapset_qualify’

BEATMAPSET_RANK = ‘beatmapset_rank’

BEATMAPSET_REMOVE_FROM_LOVED = ‘beatmapset_remove_from_loved’

BEATMAPSET_RESET_NOMINATIONS = ‘beatmapset_reset_nominations’

CHANNEL_ANNOUNCEMENT = ‘channel_announcement’

CHANNEL_MESSAGE = ‘channel_message’

COMMENT_NEW = ‘comment_new’

FORUM_TOPIC_REPLY = ‘forum_topic_reply’

USER_ACHIEVEMENT_UNLOCK = ‘user_achievement_unlock’

USER_BEATMAPSET_NEW = ‘user_beatmapset_new’

USER_BEATMAPSET_REVIVE = ‘user_beatmapset_revive’

class osu.enums.ObjectType(value, *args, **kwargs)

Enum for different object types. Score types are most relevant.

Object types

BeatmapDiscussion = “beatmapset_discussion”

BeatmapDiscussionPost = “beatmapset_discussion_post”

Beatmapset = “beatmapset”

Build = “build”

Channel = “channel”

Comment = “comment”

ForumPost = “forum_post”

ForumTopic = “forum_topic”

LegacyMatchScore = “legacy_match_score”

NewsPost = “news_post”

ScoreBestFruits = “score_best_fruits”

ScoreBestMania = “score_best_mania”

ScoreBestOsu = “score_best_osu”

ScoreBestTaiko = “score_best_taiko”

ScoreFruits = “score_fruits”

ScoreMania = “score_mania”

ScoreOsu = “score_osu”

ScoreTaiko = “score_taiko”

SoloScore = “solo_score”

User = “user”

class osu.enums.PlaylistQueueMode(value, *args, **kwargs)

Enum for playlist queue modes.

Playlist queue modes

HOST_ONLY = ‘host_only’

class osu.enums.RankStatus(value, *args, **kwargs)

IntEnum enum for rank status of a beatmap.

Statuses

GRAVEYARD = -2

WIP = -1

PENDING = 0

RANKED = 1

APPROVED = 2

QUALIFIED = 3

LOVED = 4

class osu.enums.RankingType(value, *args, **kwargs)

Ranking types to sort by for osu.Client.get_ranking().

Ranking types

SPOTLIGHT = ‘charts’

COUNTRY = ‘country’

PERFORMANCE = ‘performance’

SCORE = ‘score’

TEAM = ‘team’

class osu.enums.RealTimeQueueMode(value, *args, **kwargs)

Enum for realtime queue modes.

Realtime queue modes

HOST_ONLY = ‘host_only’

ALL_PLAYERS = ‘all_players’

ALL_PLAYERS_ROUND_ROBIN = ‘all_players_round_robin’

class osu.enums.RoomCategory(value, *args, **kwargs)

Enum for room categories.

Room categories

NORMAL = ‘normal’

SPOTLIGHT = ‘spotlight’

FEATURED_ARTIST = ‘featured_artist’

DAILY_CHALLENGE = ‘daily_challenge’

class osu.enums.RoomFilterMode(value, *args, **kwargs)

Enum for different filtering modes of rooms.

Room filter mode types

ENDED = ‘ended’

PARTICIPATED = ‘participated’

OWNED = ‘owned’

ACTIVE = ‘active’

class osu.enums.RoomSort(value, *args, **kwargs)

Sort options for rooms. Relevant to osu.Client.get_rooms().

Room sort options

ENDED = ‘ended’

CREATED = ‘created’

class osu.enums.RoomStatus(value, *args, **kwargs)

Possible statuses for a Room

Room statuses

IDLE = “idle”

PLAYING = “playing”

class osu.enums.RoomType(value, *args, **kwargs)

Enum for room types.

Room types

PLAYLISTS = “playlists”

HEAD_TO_HEAD = “head_to_head”

TEAM_VERSUS = “team_versus”

MATCHMAKING = “matchmaking”

class osu.enums.ScoreRank(value, *args, **kwargs)

Enum for score ranks.

Score ranks

SILVER_SS = ‘XH’

SS = ‘X’

SILVER_S = ‘SH’

S = ‘S’

A = ‘A’

B = ‘B’

C = ‘C’

D = ‘D’

F = ‘F’

class osu.enums.ScoringType(value, *args, **kwargs)

Scoring type used for a legacy multiplayer match

Scoring types

SCORE = “score”

ACCURACY = “accuracy”

COMBO = “combo”

SCOREV2 = “scorev2”

class osu.enums.TeamType(value, *args, **kwargs)

The team type used for a legacy multiplayer match

Team types

HEAD_TO_HEAD = “head-to-head”

TAG_COOP = “tag-coop”

TEAM_VS = “team-vs”

TAG_TEAM_VS = “tag-team-vs”

class osu.enums.UserAccountHistoryType(value, *args, **kwargs)

Type of account history object

User Account History Types

NOTE = “note”

RESTRICTION = “restriction”

SILENCE = “silence”

TOURNAMENT_BAN = “tournament_ban”

class osu.enums.UserBeatmapType(value, *args, **kwargs)

User beatmap types. Relavent to osu.Client.get_user_beatmaps().

User beatmap types

favourite, graveyard, loved, most_played, pending, ranked

FAVOURITE = ‘favourite’

GRAVEYARD = ‘graveyard’

GUEST = ‘guest’

LOVED = ‘loved’

MOST_PLAYED = ‘most_played’

NOMINATED = ‘nominated’

PENDING = ‘pending’

RANKED = ‘ranked’

class osu.enums.UserRelationType(value, *args, **kwargs)

The type of relation to a user

Relation types

FRIEND = “friend”

BLOCK = “block”

class osu.enums.UserScoreType(value, *args, **kwargs)

Enum for the get_user_scores endpoint that specifies score type.

User score types

BEST = “best”

FIRSTS = “firsts”

RECENT = “recent”

PINNED = “pinned”

class osu.enums.WikiSearchMode(value, *args, **kwargs)

Enum for wiki search modes. Relevant to osu.Client.search().

ALL = “all”

USER = “user”

WIKI = “wiki_page”