API Reference ¶

chat_acknowledge(history_since: int | None = None, since: int | None = None) → Sequence[UserSilence]¶

Send a chat ack.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

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 ChatMessage.message_id to return.

Returns

List[UserSilence]

check_download_quota() → int¶

Get the amount of quota you’ve used.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Returns

int

[This description may be outdated]

This endpoint creates a new channel if doesn’t exist and joins it. Currently only for rejoining existing PM channels which the user has left.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameter

channel_type: Union[ChatChannelType, str]

channel type (currently only supports PM and ANNOUNCE)

target_id: Optional[int]

target user id; required if type is PM; ignored, otherwise.

target_ids: Optional[Sequence[int]]

target user ids; required if type is ANNOUNCE; ignored, otherwise.

message: Optional[str]

message to send with the announcement; required if type is ANNOUNCE.

channel: Optional[Dict[str, str]]

channel details; required if type is ANNOUNCE.

name: str: the channel name
description: str: the channel description

Returns

ChatChannel: contains recent_messages attribute (which is deprecated).

Create a multiplayer (realtime) room.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

name: str: Name of the room

starting_map: Union[PlaylistItemUtil, dict]

password: Optional[str]: Password to enter the room which is optional.
queue_mode: Optional[Union[RealTimeQueueMode, str]]: The mode for queuing maps.

auto_start_duration: Optional[int]

room_type: Optional[Union[RoomType, str]]

auto_skip: Optional[bool]: Whether to automatically skip intro or not.

Returns

Room

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, delegate scope, or password auth)

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.

Returns

CreateNewPmResult

Create a playlist

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

name: str: Name of the playlist
playlist_items: Sequence[Union[PlaylistItemUtil, dict]]: List of beatmaps to put on the playlist
duration: Optional[int]: Duration for the playlist to last in minutes. If not specified then an end time must be specified. The playlist must have a duration of at least 30 minutes.
ends_at: Optional[Union[datetime.datetime, str]]: Time for the playlist to end at. If not specified then a duration must be specified. Must amount to a duration of at least 30 minutes.
max_attempts: Optional[int]: Null means infinite attempts.
queue_mode: Optional[Union[PlaylistQueueMode, str]]: PlaylistQueueMode.HOST_ONLY is the only option

auto_start_duration: Optional[int]

Returns

Room

Create a new topic.

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

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[str]: Newline-separated 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).

Returns

CreateTopicResult

delete_comment(comment: int) → CommentBundle¶

Deletes the specified comment.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

comment: int: Comment id

Returns

download_beatmapset(beatmapset_id: int, path: str, chunk_write_size: int = 4096) → None¶

Download a beatmapset

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

beatmapset_id: int: Id of the beatmapset
path: str: Path to write the beatmapset to
chunk_write_size: int: File is written in chunks and this defines chunk size in bytes. Defaults to 4096.

edit_comment(comment: int, message: str | None = None) → CommentBundle¶

Edit an existing comment.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

comment: int: Comment id
message: Optional[str]: New text of the comment

Returns

BeatmapDifficultyAttributes

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.

Returns

ForumPost

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.

Returns

ForumTopic

favourite_beatmapset(beatmapset_id: int, favourite: bool) → int¶

Add or remove a favourite beatmapset

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

beatmapset_id: int

favourite: bool: whether to favourite (true) or unfavourite (false)

Returns

int: The number of favourites on the beatmapsets

classmethod from_client_credentials(client_id: int, client_secret: str, redirect_url: str | None, scope: ~osu.objects.scope.Scope | None = <osu.objects.scope.Scope object>, code: str | None = None, request_wait_time: float | None = 1.0, limit_per_minute: float | None = 60.0) → Client¶

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

Parameters

client_id: int

API Client id

client_secret: int

API Client secret

redirect_uri: Optional[str]

API redirect uri

scope: Optional[Scope]

Scopes to use. Default is Scope.default() which is just the public scope.

code: Optional[str]

If provided, is used to authorize. Read more about this under AuthHandler.get_auth_token

request_wait_time: Optional[float]

Default is 1.

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: Optional[float]

Default is 60 because that’s the limit peppy requests that we stay under.

This sets a cap on the number of requests the client is allowed to make within 1 minute of time.

Returns

Client

classmethod from_osu_credentials(username: str, password: str, request_wait_time: float | None = 1.0, limit_per_minute: float | None = 60.0) → Client¶

Returns a Client object which will make authorize and make requests to lazer.ppy.sh

username: str: osu! username login
password: str: osu! password login
request_wait_time: Optional[float]: Read under Client init parameters.
limit_per_minute: Optional[float]: Read under Client init parameters.

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

Returns

Beatmap: 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.

Returns

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.

Returns

BeatmapScores: LegacyScore object inside includes “user” and the included user includes “country” and “cover”.

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.

Returns

List[Beatmap]: Includes attributes beatmapset, beatmapset.ratings, failtimes, max_combo.

get_beatmapset(beatmapset_id: int) → Beatmapset¶

Get beatmapset by id.

Requires OAuth and scope public

Parameters

beatmapset_id: int

Returns

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)

Returns

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)

Returns

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)

Returns

BeatmapsetDiscussionsResult

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.

Returns

GetBeatmapsetEventsResult

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

Returns details of the specified build.

Parameters

stream: str: Update stream name.
build: str: Build version.

Returns

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.

Returns

ChangelogListingResult

get_channel(channel_id: int) → GetChannelResult¶

Gets details of a chat channel.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameter

channel_id: int

Returns

GetChannelResult

get_channel_list() → List[ChatChannel]¶

This endpoint returns a list of all joinable public channels.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Returns

Sequence[ChatChannel]

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. You may need to first join the channel with osu.Client.join_channel().

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameter

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

Returns

List[ChatMessage]

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

Returns

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

Does not require OAuth

Parameter

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. See CommentSort for detail. The format follows Cursor except it’s not currently included in the response.
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.

Returns

CommentBundle: pinned_comments is only included when commentable_type and commentable_id are specified.

get_friends() → List[UserCompact]¶

Returns a list of friends.

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

Returns

List[UserCompact]

get_lazer_beatmap_scores(beatmap: int, mode: str | GameModeStr | None = None, mods: str | None = None, type: str | None = None) → BeatmapScores¶

Returns the top scores for a beatmap on the lazer client.

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[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
type: Optional[str]: Beatmap score ranking type. Currently doesn’t do anything.

Returns

BeatmapScores: SoloScore object inside includes “user” and the included user includes “country” and “cover”.

get_match(match_id: int) → MatchExtended¶

Returns a match by id.

Requires OAuth and scope public.

Parameters

match_id: int: The match id.

Returns

Match

get_matches(limit: int | None = None, sort: str | MatchSort | None = None, cursor: Dict | None = None) → GetMatchesResult¶

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.

Returns

GetMatchesResult

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.

Returns

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.

Returns

Returns a NewsPost with content and navigation included.

get_notifications(max_id: int | None = None) → GetNotificationsResult¶

This endpoint returns a list of the user’s unread notifications. Sorted descending by id with limit of 50.

Requires OAuth, scope lazer, a user (authorization code grant, delegate scope, or password auth)

Parameters

max_id: Optional[int]: Maximum id fetched. Can be used to load earlier notifications. Defaults to no limit (fetch latest notifications)

Returns

GetNotificationsResult

get_open_chat_channels() → List[ChatChannel]¶

Get a list of chat channels that you have open. Includes recent DMs and public chat channels.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Returns

List[ChatChannel]

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, delegate scope, or password auth)

Parameters

mode: Optional[str, GameModeStr]: GameMode. User default mode will be used if not specified.

Returns

See return for get_user

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

Requires OAuth and scope public

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.

Returns

Rankings

get_replay_data(mode, score_id) → Replay¶

Returns replay data for a score.

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

Parameters

mode: Union[str, GameModeStr]

score_id: int

Returns

osrparse.Replay

get_room(room_id: int) → Room¶

Returns a room by id.

Requires OAuth and scope public.

Parameters

room_id: int: The room id.

Returns

Room

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, delegate scope, or password auth).

Parameters

room_id: int

Returns

GetRoomLeaderboard

Returns a list of rooms.

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

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_score_by_id(mode, score_id) → LegacyScore | SoloScore¶

Returns a score by id.

Requires OAuth and scope public.

Parameters

mode: Union[str, GameModeStr]

score_id: int

Returns

Union[SoloScore, LegacyScore]

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

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

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.

Returns

MultiplayerScores

get_seasonal_backgrounds() → SeasonalBackgrounds¶

Get the season backgrounds.

Doesn’t require OAuth

Returns

SeasonalBackgrounds

get_spotlights() → Spotlights¶

Gets the list of spotlights.

Requires OAuth and scope public

Returns

Spotlights

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.

Returns

GetTopicAndPostsResult

get_updates(since: int = 0, includes: Sequence[str] | None = None, history_since: int | None = None) → GetUpdatesResult¶

This endpoint returns new messages since the given message_id along with updated channel ‘presence’ data.

Requires OAuth, scope lazer, a user (authorization code grant, delegate scope, or password auth)

Parameters

since: int: Defaults to 0. UserSilence`s after the specified `ChatMessage.message_id to return.
includes: Optional[Sequence[str]]: List of fields from presence, silences to include in the response. Uses presences if not specified.
history_since: Optional[int]: UserSilence`s after the specified id to return. This field is preferred and takes precedence over `since.

Returns

GetUpdatesResult

get_user(user: int, 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]: 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.

Returns

User: 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_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.

Returns

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

Returns

List[Union[LegacyScore, SoloScore]]

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, loved, most_played, pending, ranked.
limit: Optional[int]: Maximum number of results.
offset: Optional[int]: Result offset for pagination.

Returns

List[Union[BeatmapPlaycount, Beatmapset]]: BeatmapPlaycount for type most_played and Beatmapset for any other type.

get_user_highscore(room: int, playlist: int, user: int) → MultiplayerScore¶

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

room: int: Id of the room.
playlist: int: Id of the playlist item.
user: int: User id.

Returns

MultiplayerScores

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.

Returns

Sequence[KudosuHistory]

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.

Returns

List[Event]: list of Event objects

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
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.

Returns

Sequence[Union[LegacyScore, SoloScore]]: Includes attributes beatmap, beatmapset. Additionally includes weight if type is best.

get_users(ids: Sequence[int]) → List[UserCompact]¶

Returns list of users.

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.

Returns

Sequence[UserCompact]: Includes attributes: country, cover, groups, statistics_rulesets.

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.

Returns

WikiPage

join_channel(channel: int, user: int) → ChatChannel¶

This endpoint allows you (or someone else) to join a public channel.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

channel: int: channel id of channel to join
user: int: user id of user joining

Returns

ChatChannel

join_user_to_room(room: int, user: int, password: str | None = None) → None¶

Join a user to a room.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

room: int

user: int

password: Optional[str]

kick_user_from_room(room: int, user: int) → None¶

Kick a user from a room.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

room: int

user: int

leave_channel(channel: int, user: int) → None¶

This endpoint allows you (or someone else) to leave a public channel.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

channel: int: channel id of channel to leave
user: int: user id of user leaving

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

Returns

Beatmap

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.

Returns

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

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 lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

channel_id: int: The channel_id of the channel to mark as read
message_id: int: The message_id of the message to mark as read up to

This endpoint allows you to mark notifications read. Should only supply one of the arguments.

Requires OAuth, scope lazer, a user (authorization code grant, delegate scope, or password auth)

Parameters

identities: Optional[Sequence[Union[IdentitiesUtil, Dict[str, str]]]]

notifications: Optional[Sequence[Union[NotificationsUtil, Dict[str, str]]]]

Posts a new comment to a comment thread.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameter

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.
message: Optional[str]: Text of the comment
parent_id: Optional[int]: The id of the comment to reply to, null if not a reply

Returns

remove_comment_vote(comment: int) → CommentBundle¶

Un-upvotes a comment.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

comment: int: Comment id

Returns

event_data: Union[BeatmapsetEventNominate, BeatmapsetEventRemoveFromLoved, BeatmapsetEventDisqualify, BeatmapsetEventKudosuGain, BeatmapsetEventKudosuLost, BeatmapsetEventKudosuRecalculate, BeatmapsetEventDiscussionLock, BeatmapsetEventNominationReset, BeatmapsetEventNominationResetReceived, BeatmapsetEventGenreEdit, BeatmapsetEventLanguageEdit, BeatmapsetEventNsfwToggle, BeatmapsetEventOffsetEdit, BeatmapsetEventBeatmapOwnerChange]

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, delegate scope, or password auth)

Parameters

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

Returns

ForumPost: body attributes included

report(comments: str, reason: str, reportable_id: int, reportable_type: ObjectType | str) → None¶

Send a report.

Requires OAuth, lazer scope, and a user (authorization code grant, delegate scope, or password auth).

Parameters

comments: str

reason: str

reportable_id: id

reportable_type: Union[str, ObjectType]

revoke_current_token() → None¶

Revokes currently authenticated token.

Requires OAuth

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.

Returns

SearchResult

search_beatmapsets(filters=None, page=None) → BeatmapsetSearchResult¶

Search for beatmapsets.

Requires OAuth and scope public.

Attributes

filters: Optional[BeatmapsetSearchFilter]

page: Optional[int]

Returns

BeatmapsetSearchResult

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

This endpoint sends a message to the specified channel.

Requires OAuth, scope lazer, and a user (authorization code grant, delegate scope, or password auth)

Parameters

channel: int: The channel_id of the channel to send message to
message: str: message to send
is_action: bool: whether the message is an action

Returns

ChatMessage

class osu.AuthHandler(client_id: int, client_secret: str, redirect_url: str, scope: ~osu.objects.scope.Scope | None = <osu.objects.scope.Scope object>)¶

Helps to go through the oauth process easily, as well as refresh tokens without the user needing to worry about it.

Note: If you’re not authorizing a user with a url for a code, this does not apply to you. AuthHandler does not save refresh tokens past the program finishing. AuthHandler will save the refresh token to refresh the access token while the program is running, so make sure to save the refresh token before shutting down the program so you can use it to get a valid access token without having the user reauthorize.

Init Parameters

client_id: int: Client id
client_secret: str: Client secret
redirect_uri: str: Redirect uri
scope: Optional[Scope]: Scope object helps the program identify what requests you can and can’t make with your scope. Default is ‘public’ (Scope.default())

classmethod from_save_data(save_data: dict)¶: Create a new AuthHandler object from save data.

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

get_auth_url(state: str | None = '')¶

Returns a url that a user can authorize their account at. They’ll then be returned to the redirect_uri with a code that can be used under get_auth_token.

Parameters

state: Optional[str]: Will be returned to the redirect_uri along with the code.

get_save_data()¶

Get save data in json format. Can be used to easily initiate a new AuthHandler object in a new session.

Returns

{

‘save_version’: int,

‘client_id’: int,

‘client_secret’: str,

‘redirect_url’: str,

‘scope’: str,

‘refresh_token’: str,

}

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.

set_refresh_callback(callback: Callable[[AuthHandler], None])¶

Set a callback to be called everytime the access token is refreshed.

Parameters

callback: Callable[['AuthHandler'], None]

property token¶: Returns the access token. If the token is expired, it will be refreshed before being returned.

class osu.LazerAuthHandler(username: str, password: str)¶

class osu.NotificationWebsocket(notification_uri, auth, loop=None)¶

This class allows you to receive notifications without constantly polling the server. To utilize it you should do either of: - Make a class inheriting this one and redefine the event functions (on_logout, on_new, …). - Use the event function as a decorator, read more on its use under its docs.

Event types

on_ready

Fired when the websocket establishes connection.

on_logout

Server will disconnect session after sending this event so don’t try to reconnect.

on_new

New notification. See Notification object for notification types.

Arguments

notification: Notification

on_read

Notification has been read.

Arguments

notifications: Sequence[ReadNotification]: list of notifications that were read
timestamp: datetime.datetime: time at which the notifications were read

on_chat_channel_join

Broadcast to the user when the user joins a chat channel.

Arguments

channel: ChatChannel: Has the current_user_attributes, last_message_id, and users attributes.

on_chat_channel_part

Broadcast to the user when the user leaves a chat channel.

Arguments

channel: ChatChannel: Has the current_user_attributes, last_message_id, and users attributes.

on_chat_message_new

Sent to the user when the user receives a chat message.

Messages intented for a user are always sent even if the user does not currently have the channel open. Such messages include PM and Announcement messages.

Other messages, e.g. public channel messages are not sent if the user is no longer present in the channel.

Arguments

messages: Sequence[ChatMessage]: The message received
users: Sequence[UserCompact]: The related uesrs who sent the messages.

on_unplanned_disconnect

Event fired by NotificationWebsocket object when there’s a disconnection without having been sent a logout event.

connect()¶: Connect to the uri and start receiving events. This function does not return until the websocket disconnects.

event(func)¶

Decorator for adding event functions. Example:

notification_websocket = NotificationWebsocket(notif_uri, auth)

@notification_websocket.event()
def new(notification):
    print(notification.name)

Endpoint results¶

Some endpoints return specific responses that don’t represent any specific objects.

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

Result of osu.Client.get_beatmapset_discussion_posts()

Attributes

beatmapsets: List[BeatmapsetCompact]

posts: List[BeatmapsetDiscussionPost]

users: List[UserCompact]

cursor: Dict[str, int]

class osu.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()

Attributes

beatmaps: List[Beatmap]

discussions: List[BeatmapsetDiscussion]

included_discussions: List[BeatmapsetDiscussion]

users: List[UserCompact]

reviews_config: ReviewsConfig

cursor: str

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

Result of osu.Client.get_beatmapset_discussion_votes()

Attributes

discussions: List[BeatmapsetDiscussion]

votes: List[BeatmapsetDiscussionVote]

users: List[UserCompact]

cursor: Dict[str, int]

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

Result of osu.client.search_beatmapsets()

Attributes

beatmapsets: List[Beatmapset]

cursor: Dict

search: SearchInfo

recommended_difficulty: Optional[int]

error: Optional[str]

total: int

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

Result of osu.Client.get_changelog_listing()

Attributes

build: List[Build]

streams: List[Build]

search: ChangelogListingSearch

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

Attribute of ChangelogListingResult

Attributes

start: Optional[str]: start input
end: Optional[str]: end input
limit: int: Always 21
max_id: Optional[int]: max_id input
stream: Optional[str]: stream input

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

Result of osu.Client.create_new_pm()

Attributes

channel: ChatChannel

message: ChatMessage

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

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

Result of osu.Client.create_topic()

Attributes

topic: ForumTopic

post: ForumPost: includes body

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

Result of osu.Client.get_beatmapset_events()

Attributes

events: List[BeatmapsetEvent]

reviews_config: Review

users: List[UserCompact]: Includes groups attribute

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

Result of osu.Client.get_channel()

Attributes

channel: ChatChannel

users: List[UserCompact]: Users are only visible for PM channels.

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

Result of osu.Client.get_matches()

Attributes

matches: List[Match]

params: Dict

cursor: Dict

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

Result of osu.Client.get_news_listing()

Attributes

cursor: str

news_posts: List[NewsPost]

news_sidebar: NewsSidebar

search: SearchInfo

class osu.GetNotificationsResult(notifications: List[Notification], stacks: List[NotificationStackResult], timestamp: datetime, types: List[NotificationTypeResult], unread_count: int | None, notification_endpoint: str)¶

Result of osu.Client.get_notifications()

Attributes

notifications: List[Notification]

stacks: List[NotificationStackResult]

timestamp: datetime.datetime

types: List[NotificationTypeResult]

unread_count: Optional[int]

notification_endpoint: str

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

Result of osu.client.get_room_leaderboard()

Attributes

leaderboard: List[UserScoreAggregate]

user_score: Optional[UserScoreAggregate]

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

Result of osu.Client.get_topic_and_posts()

Attributes

cursor_string: str

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

topic: ForumTopic

posts: List[ForumPost]

class osu.GetUpdatesResult(presence: List[ChatChannel] | None, silences: List[UserSilence] | None)¶

Result of osu.Client.get_updates()

Attributes

presence: Optional[List[ChatChannel]]

silences: Optional[List[UserSilence]]

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

Attribute of GetNewsListingResult

Attributes

current_year: int

news_post: List[NewsPost]

years: List[int]

class osu.NotificationStackResult(category: NotificationType | ObjectType, cursor: Dict[str, int] | None, object_type: ObjectType, object_id: int, total: int)¶

Attribute of GetNotificationsResult

Attributes

category: NotificationType

cursor: Optional[Dict[str, int]]: dict with one key id if not null

object_type: ObjectType

object_id: int

total: int

class osu.NotificationTypeResult(cursor: Dict[str, int] | None, name: ObjectType | None, total: int)¶

Attribute of GetNotificationsResult

Attributes

cursor: Optional[Dict[str, int]]: dict that contains one key id if not null

total: int

class osu.ReviewsConfig(max_blocks: int)¶

An attribute of BeatmapsetDiscussionsResult

Attributes

max_blocks: int

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

A class for search info in several result objects.

Attributes

sort: str

limit: int

start: Optional[str]

end: Optional[str]

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

Result of osu.Client.search()

Attributes

user: Optional[List[UserCompact]]: For all or user mode. Only first 100 results are accessible
wiki_page: Optional[List[WikiPage]]: For all or wiki_page mode

Objects¶

class osu.Achievement(data)¶

Attributes

icon_url: str

id: int

grouping: str

ordering: int

slug: str

description: str

mode: Optional[GameModeStr]

instructions: Optional[str]

class osu.AchievementEvent(data)¶

Attributes

achievement: Achievement

user: EventUser

class osu.BaseNominations(data)¶

Base attributes for LegacyNominations and Nominations

Attributes

disqualification: Optional[BeatmapsetEvent]

nominated: Optional[bool]

nomination_reset: Optional[BeatmapsetEvent]

ranking_eta: Optional[str]

ranking_queue_position: Optional[int]

required_hype: int

class osu.Beatmap(data)¶

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

Attributes

accuracy: float

ar: float

beatmapset: Optional[Beatmapset]

bpm: float

convert: Optional[bool]

count_circles: int

count_sliders: int

count_spinners: int

cs: float

deleted_at: Optional[datetime.datetime]

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.BeatmapCompact(data)¶

Represents a beatmap.

Attributes

beatmapset_id: int

difficulty_rating: float

id: int

mode: GameModeStr

status: RankStatus

total_length: int

user_id: int

version: str

beatmapset: Optional[BeatmapsetCompact]

checksum: Optional[str]

failtimes: Optional[Failtimes]

max_combo: Optional[int]

user: Optional[UserCompact]

class osu.BeatmapDifficultyAttributes(data)¶

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

Attributes

The parameters depend on the ruleset, but the following two attributes are present in all rulesets.

max_combo: int

star_rating: float

mode_attributes: Optional[Union[OsuBeatmapDifficultyAttributes, TaikoBeatmapDifficultyAttributes, FruitsBeatmapDifficultyAttributes, ManiaBeatmapDifficultyAttributes]]

Can be none for some beatmaps that are bugged and have no difficulty attributes.

type: Optional[GameModeStr]

class osu.BeatmapPlaycount(data)¶

Represent the playcount of a beatmap.

Attributes

beatmap_id: int

beatmap: Optional[BeatmapCompact]

beatmapset: Optional[BeatmapsetCompact]

class osu.BeatmapPlaycountEvent(data)¶

Attributes

beatmap: EventBeatmap

class osu.BeatmapScores(data)¶

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

Attributes

scores: List[Union[LegacyScore, SoloScore]]: The list of top scores for the beatmap in descending order.
user_score: Optional[BeatmapUserScore]: The score of the current user. This is not returned if the current user does not have a score.

class osu.Beatmapset(data)¶

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

Attributes

availability: BeatmapsetAvailability

beatmaps: Optional[List[Beatmap]]: 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: Optional[datetime.datetime]

legacy_thread_url: str

nominations_summary: NominationsSummary

ranked: RankStatus

ranked_date: Optional[datetime.datetime]

storyboard: bool

submitted_date: Optional[datetime.datetime]

tags: str

class osu.BeatmapsetApproveEvent(data)¶

Attributes

approval: RankStatus

beatmapset: EventBeatmapset

user: EventUser

class osu.BeatmapsetAvailability(data)¶

Gives information on the availability of a beatmap for download.

Attributes

download_disabled: bool

more_information: Optional[str]

class osu.BeatmapsetCompact(data)¶

Represents a beatmapset.

Attributes

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: Optional[BeatmapsetRequirement]

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: Optional[int]

user_id: int

video: bool

availability: Optional[BeatmapsetAvailability]

beatmaps: Optional[List[BeatmapCompact]]: Beatmaps contained in the beatmapset

converts: Optional[List[Beatmap]]

current_nominations: Optional[List[CurrentNomination]]

current_user_attributes: Optional[BeatmapsetDiscussionPermissions]

description: Optional[str]

description_bbcode: Optional[str]

discussions: Optional[BeatmapsetDiscussion]

events: Optional[List[BeatmapsetEvent]]

genre: Optional[MetadataAttribute]

has_favourited: Optional[bool]

language: Optional[MetadataAttribute]

nominations: Optional[Union[LegacyNominations, Nominations]]

ratings: Optional[List[int]]

recent_favourites: Optional[List[UserCompact]]

related_users: Optional[List[UserCompact]]

user: Optional[UserCompact]

class osu.BeatmapsetDeleteEvent(data)¶

Attributes

beatmapset: EventBeatmapset

class osu.BeatmapsetDiscussion(data)¶

Represents a Beatmapset modding discussion

Attributes

beatmap_id: Optional[int]

beatmapset_id: int

can_be_resolved: bool

can_grant_kudosu: bool

created_at: datetime.datetime

deleted_at: Optional[datetime.datetime]

deleted_by_id: Optional[int]

id: int

kudosu_denied: bool

last_post_at: datetime.datetime

message_type: MessageType

parent_id: Optional[int]

resolved: bool

timestamp: Optional[int]

updated_at: datetime.datetime

user_id: int

beatmap: Optional[BeatmapCompact]

beatmapset: Optional[BeatmapsetCompact]

current_user_attributes: Optional[BeatmapsetDiscussionPermissions]

posts: Optional[List[BeatmapsetDiscussionPost]]

starting_post: Optional[BeatmapsetDiscussionPost]

votes: Optional[VotesSummary]

class osu.BeatmapsetDiscussionPermissions(data)¶

A user’s permissions in a beatmapset discussion

Attributes

can_destroy: bool

can_reopen: bool

can_moderate_kudosu: bool

can_resolve: bool

vote_score: int

class osu.BeatmapsetDiscussionPost(data)¶

Represents a post in a BeatmapsetDiscussion.

Attributes

beatmapset_discussion_id: int

created_at: datetime.datetime

deleted_at: Optional[datetime.datetime]

deleted_by_id: Optional[int]

id: int

last_editor_id: Optional[int]

updated_at: datetime.datetime

user_id: int

message: Union[str, SystemDiscussionPostMessage]: String when system is false and SystemDiscussionPostMessage otherwise.

system: bool

beatmap_discussion: Optional[BeatmapsetDiscussion]

class osu.BeatmapsetDiscussionVote(data)¶

Represents a vote on a BeatmapsetDiscussion.

Attributes

beatmapset_discussion_id: int

created_at: datetime.datetime

id: int

score: int

updated_at: datetime.datetime

user_id: int

class osu.BeatmapsetEvent(data)¶

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

Attributes

id: int

type: BeatmapsetEventType

comment: Optional[BeatmapsetEventComment]: Is None for the following types: - BeatmapsetEventType.LOVE - BeatmapsetEventType.QUALIFY - BeatmapsetEventType.APPROVE - BeatmapsetEventType.RANK

created_at: datetime.datetime

user_id: Optional[int]

beatmapset: Optional[BeatmapsetCompact]

discussion: Optional[BeatmapsetDiscussion]

class osu.BeatmapsetEventComment(data, type: BeatmapsetEventType)¶

This object holds some extra information of the event.

Attributes

beatmap_discussion_id: Optional[int]

beatmap_discussion_post_id: Optional[int]

The type of this attribute depends on the type of the BeatmapsetEvent object.

class osu.BeatmapsetEventNominate(data)¶

Attributes

modes: List[GameModeStr]

class osu.BeatmapsetEventRemoveFromLoved(data)¶

Attributes

reason: str

class osu.BeatmapsetEventDisqualify(data)¶

Attributes

nominator_ids: List[int]

class osu.BeatmapsetEventVote(data)¶

Attributes

user_id: int

score: int

class osu.BeatmapsetEventKudosuGain(data)¶

Attributes

new_votes: Optional[BeatmapsetEventVote]

votes: Optional[List[BeatmapsetEventVote]]

class osu.BeatmapsetEventKudosuLost(data)¶

Attributes

new_votes: Optional[BeatmapsetEventVote]

votes: Optional[List[BeatmapsetEventVote]]

class osu.BeatmapsetEventKudosuRecalculate(data)¶

Attributes

new_votes: Optional[BeatmapsetEventVote]

class osu.BeatmapsetEventDiscussionLock(data)¶

Attributes

reason: str

class osu.BeatmapsetEventNominationReset(data)¶

Attributes

nominator_ids: List[int]

class osu.BeatmapsetEventNominationResetReceived(data)¶

Attributes

source_user_id: int

source_user_name: str

class osu.BeatmapsetEventGenreEdit(data)¶

Attributes

old: str

new: str

class osu.BeatmapsetEventLanguageEdit(data)¶

Attributes

old: str

new: str

class osu.BeatmapsetEventNsfwToggle(data)¶

Attributes

old: str

new: str

class osu.BeatmapsetEventOffsetEdit(data)¶

Attributes

old: str

new: str

class osu.BeatmapsetEventBeatmapOwnerChange(data)¶

Attributes

beatmap_id: int

beatmap_version: str

new_user_id: int

new_user_username: str

class osu.BeatmapsetPermissions(data)¶

User permissions on a beatmapset

Attributes

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: Optional[str]

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

remaining_hype: int

class osu.BeatmapsetRequirement(data)¶

Gives information on requirements for a beatmap

Attributes

current: int

required: int

class osu.BeatmapsetReviveEvent(data)¶

Attributes

beatmapset: EventBeatmapset

user: EventUser

class osu.BeatmapsetUpdateEvent(data)¶

Attributes

beatmapset: EventBeatmapset

user: EventUser

class osu.BeatmapsetUploadEvent(data)¶

Attributes

beatmapset: EventBeatmapset

user: EventUser

class osu.BeatmapUserScore(data)¶

Attributes

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

class osu.Build(data)¶

Attributes

created_at: datetime.datetime

display_version: str

id: int

update_stream: Optional[UpdateStream]

users: int

version Optional[str]

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

versions: Optional[Versions]

class osu.ChangelogEntry(data)¶

Attributes

category: str

created_at: Optional[datetime.datetime]

github_pull_request_id: Optional[int]

github_url: Optional[str]

id: Optional[int]

major: bool

repository: Optional[str]

title: Optional[str]

type: str

url: Optional[str]

github_user: Optional[GithubUser]: If the changelog entry has no GitHub user, a placeholder is generated.
message: Optional[str]: Entry message in Markdown format. Embedded HTML is allowed.
message_html: Optional[str]: Entry message in HTML format.

class osu.ChatChannel(data)¶

Represents an individual chat “channel” in the game.

Attributes

channel_id: int

description: Optional[str]

icon: Optional[str]

display icon for the channel

type: ChatChannelType

Below are the channel types and their permission checks for joining/messaging: PUBLIC

None

PRIVATE: is player in the allowed groups? (channel.allowed_groups)
MULTIPLAYER: is player currently in the mp game?
SPECTATOR: None
TEMPORARY: deprecated
PM: For PMs, two factors are taken into account: Is either user blocking the other? If so, deny. Does the target only accept PMs from friends? Is the current user a friend? If not, deny.
GROUP: is player in channel? (user_channels)
ANNOUNCE: is user in the announce group?

moderated: bool

user can’t send message when the value is True

uuid: Optional[str]

value from requests that is relayed back to the sender.

current_user_attributes: Optional[ChatChannelUserAttributes]

only present on some responses

last_message_id: Optional[int]

message_id of last known message (only returned in presence responses)

recent_messages: Optional[List[ChatMessage]]

[DEPRECATED] up to 50 most recent messages

users: Optional[List[int]]

list of user ids that are in the channel (not included for PUBLIC channels).

class osu.ChatChannelUserAttributes(data)¶

Data about a user related to a chat channel.

Attributes

can_message: bool

can_message_error: Optional[str]

last_read_id: Optional[int]

class osu.ChatMessage(data)¶

Represents an individual Message within a ChatChannel.

Attributes

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: Optional[str]: message identifier originally sent by client
sender: Optional[UserCompact]: embedded UserCompact object to save additional api lookups

class osu.Comment(data)¶

Represents a single comment.

Attributes

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: Optional[int]: user id of the user that deleted the post; null, otherwise

edited_at: Optional[datetime.datetime]

edited_by_id: Optional[int]: user id of the user that edited the post; null, otherwise
id: int: the ID of the comment
legacy_name: Optional[str]: username displayed on legacy comments
message: Optional[str]: markdown of the comment’s content
message_html: Optional[str]: html version of the comment’s content
parent_id: Optional[int]: 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: Optional[UserCompact]

user_id: int: user ID of the poster
votes_count: int: number of votes
url: str: URL to the comment

class osu.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.

Attributes

id: Optional[int]: the ID of the object
owner_id: Optional[int]: the ID of the owner of the object
owner_title: Optional[int]: undocumented
title: Optional[str]: display title
type: Optional[str]: the type of the object
url: Optional[str]: url of the object

current_user_attributes: CommentableMetaAttributes

class osu.CommentableMetaAttributes(data)¶

User attributes for a CommentableMeta object

Attributes

can_new_comment_reason: Optional[str]

class osu.CommentBundle(data)¶

Comments and related data.

Attributes

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

top_level_count: Optional[int]: Number of comments at the top level. Not returned for replies.
total: Optional[int]: 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.Country(data)¶

Country data

Attributes

code: str

display: Optional[int]

class osu.Covers(data)¶

Attributes

cover: str

cover_2x: str

card: str

card_2x: str

list: str

list_2x: str

slimcover: str

slimcover_2x: str

class osu.CurrentNomination(data)¶

Info about a nomination

Attributes

beatmapset_id: int

rulesets: Optional[List[GameModeStr]]

reset: bool

user_id: int

class osu.CurrentUserPin(data)¶

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

Attributes

is_pinned: bool

score_id: int

score_type: ObjectType

class osu.Event(data)¶

Base class of an event

Attributes

created_at: datetime.datetime

id: int

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

class osu.EventUser(data)¶

Attributes

username: str

url: str

previous_username: Optional[str]: Only for UsernameChangeEvent.

class osu.EventBeatmap(data)¶

Attributes

title: str

url: str

class osu.EventBeatmapset(data)¶

Attributes

title: str

url: str

class osu.Failtimes(data)¶

Attributes

exit: Optional[List[int]]: List of 100 integers.
fail: Optional[List[int]]: List of 100 integers.

class osu.ForumPost(data)¶

Attributes

created_at: datetime.datetime

deleted_at: Optional[datetime.datetime]

edited_at: Optional[datetime.datetime]

edited_by_id: Optional[int]

forum_id: int

id: int

topic_id: int

user_id: int

body: Optional[TextFormat]

class osu.ForumTopic(data)¶

Attributes

created_at: datetime.datetime

deleted_at: Optional[datetime.datetime]

first_post_id: int

forum_id: int

id: int

is_locked: bool

last_post_id: int

poll: Optional[Poll]

post_count: int

title: str

type: ForumTopicType

updated_at: datetime.datetime

user_id: int

class osu.FruitsBeatmapDifficultyAttributes(data)¶

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

Attributes

approach_rate: float

class osu.GithubUser(data)¶

Attributes

display_name: str

github_url: Optional[str]

id: Optional[int]

osu_username: Optional[str]

user_id: Optional[int]

user_url: Optional[str]

class osu.Group(data)¶

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

Attributes

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}

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

colour: Optional[str]

description: Optional[TextFormat]: A dictionary with keys html and markdown.

class osu.KudosuHistory(data)¶

Attributes

id: int

action: KudosuAction

amount: int

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

created_at: datetime.datetime

giver: Optional[KudosuGiver]: Simple detail of the user who started the exchange.
post: KudosuPost: Simple detail of the object for display.

class osu.LegacyNominations(data)¶

Shows info about nominations on a beatmapset, extending BaseNominations

Attributes

is_legacy: bool: True

current: int

required: int

class osu.LegacyScore(data)¶

Contains information about a score

Attributes

id: int

best_id: int

user_id: int

accuracy: float

mods: Mods

score: int

max_combo: int

perfect: bool

statistics: ScoreStatistics

passed bool

pp: float

rank: ScoreRank

created_at: datetime.datetime

mode: GameModeStr

mode_int: GameModeInt

has_replay: bool: is the replay is available

beatmap: Optional[BeatmapCompact]

beatmapset: Optional[BeatmapsetCompact]

rank_country: Optional[int]

rank_global: Optional[int]

weight: Optional[PpWeight]

user: Optional[UserCompact]

match: Optional[MatchGameScoreInfo]

current_user_attributes: Optional[ScoreUserAttributes]

class osu.ManiaBeatmapDifficultyAttributes(data)¶

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

Attributes

great_hit_window: float

score_multiplier: float

class osu.Match(data)¶

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

Attributes

id: int

start_time: Optional[datetime.datetime]

end_time: Optional[datetime.datetime]

class osu.MatchEvent(data)¶

An event that occurred in a match.

Attributes

id: int

timestamp: datetime.datetime

user_id: int

type: MatchEventType

text: Optional[str]: None unless the event type is MatchEventType.OTHER
game: Optional[MatchGame]: None unless the event type is MatchEventType.OTHER

class osu.MatchExtended(data)¶

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

Attributes

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.MatchGame(data)¶

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

Attributes

beatmap_id: int

id: int

start_time: Optional[datetime.datetime]

end_time: Optional[datetime.datetime]

mode: GameModeStr

mode_int: GameModeInt

scoring_type: ScoringType

team_type: TeamType

mods: Mods

beatmap: Optional[BeatmapCompact]

scores: List[LegacyScore]

class osu.MatchGameScoreInfo(data)¶

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

Attributes

slot: int

team: str

passed: bool

class osu.MetadataAttribute(data)¶

Genre of a beatmapset

Attributes

id: Optional[int]

class osu.MultiplayerScores(data)¶

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

Attributes

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

scores: List[MultiplayerScore]

total: Optional[int]: Index only. Total scores of the specified playlist item.
user_score: Optional[MultiplayerScore]: Index only. Score of the accessing user if exists.

class osu.MultiplayerScoresAround(data)¶

Attributes

higher: MultiplayerScores

lower: MultiplayerScores

class osu.NewsPost(data)¶

Attributes

author: str

edit_url: str: Link to the file view on GitHub.
first_image: Optional[str]: Link to the first image in the document.

id: int

published_at: datetime.datetime

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

title: str

updated_at: datetime.datetime

content: Optional[str]: HTML post content.
navigation: Optional[Navigation]: Navigation metadata.
preview: Optional[str]: First paragraph of content with HTML markup stripped.

class osu.Navigation(data)¶

Attributes

newer: Optional[NewsPost]: null if the next post is not present.
older: Optional[NewsPost]: null if the previous post is not present.

class osu.Nominations(data)¶

Shows info about nominations on a beatmapset, extending BaseNominations

Attributes

is_legacy: bool: False

current: Union[int, Dict[GameModeStr, int]]

required: int

class osu.Notification(data)¶

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

Attributes

id: int

name: NotificationType: The type of event

created_at: datetime.datetime

object_type: ObjectType

object_id: int

source_user_id: Optional[int]

is_read: bool

Details of the notification.

Documented event names and their attribute meanings

beatmapset_discussion_lock: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion
beatmapset_discussion_post_new: object_id: Beatmapset id object_type: beatmapset source_user_id: Poster of the discussion
beatmapset_discussion_unlock: object_id: Beatmapset id object_type: beatmapset source_user_id: User who unlocked discussion
beatmapset_disqualify: object_id: Beatmapset id object_type: beatmapset source_user_id: User who disqualified beatmapset
beatmapset_love: object_id: Beatmapset id object_type: beatmapset source_user_id: User who promoted beatmapset to Loved
beatmapset_nominate: object_id: Beatmapset id object_type: beatmapset source_user_id: User who nominated beatmapset
beatmapset_qualify: object_id: Beatmapset id object_type: beatmapset source_user_id: User whom beatmapset nomination triggered qualification
beatmapset_remove_from_loved: object_id: Beatmapset id object_type: beatmapset source_user_id: User who removed beatmapset from Loved
beatmapset_reset_nominations: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion
channel_message: object_id: Channel id object_type: channel source_user_id: User who posted message
forum_topic_reply: object_id: Topic id object_type: forum_topic source_user_id: User who posted message

class osu.OsuBeatmapDifficultyAttributes(data)¶

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

Attributes

aim_difficulty: float

approach_rate: float

flashlight_difficulty: float

overall_difficulty: float

slider_factor: float

speed_difficulty: float

speed_note_count: float

class osu.PlaylistItem(data)¶

Attributes

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: Optional[int]

played_at: Optional[datetime.datetime]

beatmap: Optional[BeatmapCompact]

class osu.PlaylistItemStats(data)¶

Attributes

count_active: int

count_total: int

ruleset_ids: List[GameModeInt]

class osu.Poll(data)¶

Attributes

allow_vote_change: bool

ended_at: Optional[datetime.datetime]

hide_incomplete_results: bool

last_vote_at: Optional[datetime.datetime]

max_votes: int

options: List[PollOption]

started_at: datetime.datetime

title: TextFormat

total_vote_count: int

class osu.PollOption(data)¶

Attributes

id: int

text: TextFormat

vote_count: Optional[int]: Not present if the poll is incomplete and results are hidden.

class osu.PpWeight(data)¶

Weighted pp info

Attributes

percentage: int: number (0-100) that tells percentage weighed
pp: float: amount of pp after being weighted

class osu.ProfileBanner(data)¶

Attributes

id: int

tournament_id: int

image: Optional[str]

image2x: Optional[str]

class osu.RankEvent(data)¶

Attributes

score_rank: str

rank: int

mode: GameModeStr

beatmap: EventBeatmap

user: EventUser

class osu.RankHighest(data)¶

Highest rank a player achieved at any point in time.

Attributes

rank: int

updated_at: datetime.datetime

class osu.RankHistory(data)¶

Rank history data for a user

Attributes

mode: GameModeStr

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

class osu.Rankings(data)¶

Attributes

beatmapsets: Optional[List[Beatmapset]]: The list of beatmaps in the requested spotlight for the given mode; only available if type is charts
cursor: Dict: To be used to query the next page
ranking: List[UserStatistics]: Score details ordered by rank in descending order.
spotlight: Optional[Spotlight]: Spotlight details; only available if type is charts
total: int: An approximate count of ranks available

class osu.RankLostEvent(data)¶

Attributes

mode: GameModeStr

beatmap: EventBeatmap

user: EventUser

class osu.ReadNotification(data)¶

Represents a read notification.

Attributes

category: NotificationCategory

id: int

object_id: int

object_type: ObjectType

class osu.Review(data)¶

Attributes

max_blocks: int

class osu.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.

Attributes

id: int

category: RoomCategory

type: RoomType

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

user_id: int

starts_at: Optional[datetime.datetime]

ends_at: Optional[datetime.datetime]

max_attempts: int

participant_count: int

channel_id: int

active: bool

has_password: bool

queue_mode: Union[RealTimeQueueMode, PlaylistQueueMode]: Type depends on the room type. PlaylistQueueMode for type RoomType.PLAYLIST and RealTimeQueueMode otherwise.

current_playlist_item: Optional[PlaylistItem]

current_user_score: Optional[UserScoreAggregate]

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

host: Optional[UserCompact]

playlist: Optional[List[PlaylistItem]]

playlist_item_stats: Optional[PlaylistItemStats]

recent_participants: Optional[List[UserCompact]]

scores: Optional[MultiplayerScore]

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.

class osu.ScoreDataStatistics(data)¶

Attributes

ok: Optional[int]

meh: Optional[int]

good: Optional[int]

miss: Optional[int]

none: Optional[int]

great: Optional[int]

perfect: Optional[int]

ignore_hit: Optional[int]

ignore_miss: Optional[int]

large_bonus: Optional[int]

small_bonus: Optional[int]

large_tick_hit: Optional[int]

small_tick_hit: Optional[int]

large_tick_miss: Optional[int]

small_tick_miss: Optional[int]

class osu.ScoreStatistics(data)¶

Attributes

count_50: int

count_100: int

count_300: int

count_geki: int

count_katu: int

count_miss: int

class osu.ScoreUserAttributes(data)¶

Gives info about a score related to the current user

Attributes

Optional[CurrentUserPin]

class osu.SearchResults(data, data_type)¶

Represents the results of a search.

Attributes

results: List[Union[UserCompact, WikiPage]]: type depends on search type

total: int

class osu.SoloScore(data)¶

Contains information about a lazer score.

Attributes

accuracy: float

beatmap_id: Optional[int]

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: Optional[int]

id: int

legacy_perfect: Optional[bool]

pp: Optional[float]

replay: bool

type: ObjectType

user: Optional[UserCompact]

build_id: Optional[int]

legacy_score_id: Optional[int]

legacy_total_score: Optional[int]

started_at: Optional[datetime.datetime]

current_user_attributes: Optional[ScoreUserAttributes]

weight: Optional[PpWeight]

class osu.Spotlight(data)¶

The details of a spotlight.

Attributes

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: Optional[int]: 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.Spotlights(data)¶

Attributes

spotlights: List[Spotlight]

class osu.SystemDiscussionPostMessage(data)¶

System message of BeatmapsetDiscussionPost

Attributes

type: str

value: bool

class osu.TaikoBeatmapDifficultyAttributes(data)¶

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

Attributes

stamina_difficulty: float

rhythm_difficulty: float

colour_difficulty: float

great_hit_window: float

peak_difficulty: float

class osu.TextFormat(data)¶

A page that has html and raw data

Attributes

html: str

raw: str

class osu.UpdateStream(data)¶

Attributes

display_name: Optional[str]

id: int

is_featured: bool

latest_build: Optional[Build]

user_count: Optional[int]

class osu.User(data)¶

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

Attributes

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

discord: Optional[str]

has_supported: bool: Has been a supporter in the past

interests: Optional[str]

join_date: datetime.datetime

kudosu: UserKudosu

location: Optional[str]

max_blocks: int: maximum number of users allowed to be blocked
max_friends: int: maximum number of friends allowed to be added

occupation: Optional[str]

playmode: GameModeStr

playstyle: List[str]: Device choices of the user.
post_count: int: number of forum posts
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: Optional[str]: user-specific title

title_url: Optional[str]

twitter: Optional[str]

website: Optional[str]

class osu.UserCompact(data)¶

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

Attributes

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: Optional[datetime.datetime]: null if the user hides online presence
pm_friends_only: bool: whether or not the user allows PM from other than friends
profile_colour: Optional[str]: colour of username/profile highlight, hex code (e.g. #333333)
username: str: user’s display name

account_history: Optional[List[UserAccountHistory]]

active_tournament_banner: Optional[ProfileBanner]

badges: Optional[List[UserBadge]]

beatmap_playcounts_count: Optional[int]

blocks: Optional[List[UserRelations]]

comments_count: Optional[int]

country: Optional[Country]

cover: Optional[UserCover]

favourite_beatmapset_count: Optional[int]

follow_user_mapping: Optional[List[int]]

follower_count: Optional[int]

friends: Optional[List[UserRelations]]

graveyard_beatmapset_count: Optional[int]

groups: Optional[List[UserGroup]]

guest_beatmapset_count: Optional[int]

is_admin: Optional[bool]

is_bng: Optional[bool]

is_gmt: Optional[bool]

is_limited_bn: Optional[bool]

is_moderator: Optional[bool]

is_nat: Optional[bool]

is_restricted: Optional[bool]

is_silenced: Optional[bool]

loved_beatmapset_count: Optional[int]

mapping_follower_count: Optional[int]

monthly_playcounts: Optional[List[UserMonthlyPlaycount]]

nominated_beatmapset_count: Optional[int]

page: Optional[TextFormat]

pending_beatmapset_count: Optional[int]

previous_usernames: Optional[List[str]]

rank_highest: Optional[RankHighest]

rank_history: Optional[RankHistory]

ranked_beatmapset_count: Optional[int]

replays_watched_counts: Optional[List[UserReplaysWatchedCount]]

scores_best_count: Optional[int]

scores_first_count: Optional[int]

scores_pinned_count: Optional[int]

scores_recent_count: Optional[int]

statistics: Optional[UserStatistics]

statistics_rulesets: Optional[UserStatisticsRulesets]

support_level: Optional[int]

unread_pm_count: Optional[int]

user_achievements: Optional[List[UserAchievement]]

user_preferences: Optional[UserPreferences]

class osu.UserCover(data)¶

Cover of a user’s profile

Attributes

custom_url: Optional[str]

url: Optional[str]

id: Optional[int]

class osu.UserAccountHistory(data)¶

Attributes

actor: Optional[UserCompact]

description: str

id: int

length: int

permanent: bool

supporting_url: Optional[str]

timestamp: datetime.datetime

type: UserAccountHistoryType

class osu.UserAchievement(data)¶

An achievement that a user received

Attributes

achieved_at: datetime.datetime

achievement_id: int

class osu.UserBadge(data)¶

Attributes

awarded_at: datetime.datetime

description: str

image_url: str

image_2x_url: str

url: str

class osu.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.

Attributes

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

class osu.UserKudosu(data)¶

User kudosu data

Attributes

total: int

available: int

class osu.UserMonthlyPlaycount(data)¶

Attributes

start_date: datetime.date: year-month-day format
count: class:int: playcount

class osu.UsernameChangeEvent(data)¶

Attributes

user: EventUser

class osu.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.UserRelations(data)¶

Info about relationship to a user

Attributes

target_id: int: zebra id

relation_type: UserRelationType

mutual: bool

class osu.UserReplaysWatchedCount(data)¶

The count of replays watched for a month

Attributes

start_date: datetime.datetime

class osu.UserStatistics(data)¶

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

Attributes

count_300: int

count_100: int

count_50: int

count_miss: int

country_rank: Optional[int]

Current country rank according to pp.

global_rank: Optional[int]: Current global rank according to pp.

global_rank_exp: Optional[int]

Current global rank according to experimental pp.

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

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

Experimental performance points (on lazer.ppy.sh)

recommended_difficulty: float

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

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: Optional[UserCompact]

The associated user.

variants: Optional[List[UserStatisticVariant]]

class osu.UserStatisticsRulesets(data)¶

Object that contains statistics for each gamemode.

Attributes

osu: Optional[UserStatistics]: statistics for osu!standard.
taiko: Optional[UserStatistics]: statistics for osu!taiko.
fruits: Optional[UserStatistics]: statistics for osu!catch.
mania: Optional[UserStatistics]: statistics for osu!mania.

class osu.UserStatisticVariant(data)¶

A variant ranking system.

Attributes

country_rank: Optional[int]

global_rank: Optional[int]

mode: GameModeStr

pp: int

variant: str: 4k or 7k

class osu.UserSupportAgain(data)¶

Attributes

user: EventUser

class osu.UserSupportFirst(data)¶

Attributes

user: EventUser

class osu.UserSupportGift(data)¶

Attributes

user: EventUser

class osu.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.VotersSummary(data)¶

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

Attributes

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

class osu.VotesSummary(data)¶

Summarizes the votes of a discussion

Attributes

down: int: Number of downvotes
up: int: Number of upvotes
voters: VotersSummary: summarizes who voted up and down

class osu.WikiPage(data)¶

Represents a wiki article

Attributes

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: Optional[str]: The article’s subtitle.
tags: List[str]: Associated tags for the article.
title: str: The article’s title.

Utility¶

class osu.BeatmapsetSearchFilter¶

Util class that helps for filtering in 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[GameModeStr, 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) → BeatmapsetSearchFilter¶

Set the sort order of the search.

sort: Union[BeatmapsetSearchSort, str]

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[id]: 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.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

Notifications¶

class osu.BeatmapOwnerChangeDetails(data)¶

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

Attributes

beatmap_id: int

cover_url: str

title: str

title_unicode: str

version: str

class osu.BeatmapsetDiscussionLockDetails(data)¶

Beatmapset discussion locked

class osu.BeatmapsetDiscussionPostNewDetails(data)¶

New beatmapset discussion post

Extends BeatmapsetDiscussionPostNotificationDetails

class osu.BeatmapsetDiscussionPostNotificationDetails(data)¶

Base class for a couple other detail objects.

Attributes

content: str

title: str

title_unicode: str

post_id: int

discussion_id: int

beatmap_id: int

cover_url: str

class osu.BeatmapsetDiscussionQualifiedProblemDetails(data)¶

Beatmapset discussion qualified problem

Extends BeatmapsetDiscussionPostNotification

class osu.BeatmapsetDiscussionReviewNewDetails(data)¶

New beatmapset discussion review.

Attributes

title: str

title_unicode: str

post_id: int

discussion_id: int

beatmap_id: int

cover_url: str

embeds: ReviewStats

class osu.BeatmapsetDiscussionUnlockDetails(data)¶

Beatmapset discussion unlocked

class osu.BeatmapsetDisqualifyDetails(data)¶

Beatmapset disqualified

class osu.BeatmapsetLoveDetails(data)¶

Beatmapset loved

class osu.BeatmapsetNominateDetails(data)¶

Beatmapset nominated

class osu.BeatmapsetNotificationDetails(data)¶

Base class for several other detail objects.

Attributes

title: str

title_unicode: str

cover_url: str

class osu.BeatmapsetQualifyDetails(data)¶

Beatmapset qualified

class osu.BeatmapsetRankDetails(data)¶

Beatmapset ranked

class osu.BeatmapsetRemoveFromLovedDetails(data)¶

Beatmapset removed from love

class osu.BeatmapsetResetNominationsDetails(data)¶

Beatmapset nominations reset

Extends BeatmapsetNominateDetails

class osu.ChannelAnnouncementDetails(data)¶

Chat channel announcement

Attributes

channel_id: int

title: str

type: ChatChannelType

cover_url: str

class osu.ChannelMessageDetails(data)¶

Chat channel message

Attributes

title: str

type: ChatChannelType

cover_url: str

class osu.CommentNewDetails(data)¶

New comment

Attributes

comment_id: int

title: str

content: str

cover_url: str

class osu.ForumTopicReplyDetails(data)¶

Forum topic reply

Attributes

title: str

post_id: int

cover_url: str

class osu.Notification(data)¶

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

Attributes

id: int

name: NotificationType: The type of event

created_at: datetime.datetime

object_type: ObjectType

object_id: int

source_user_id: Optional[int]

is_read: bool

Details of the notification.

Documented event names and their attribute meanings

beatmapset_discussion_lock: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion
beatmapset_discussion_post_new: object_id: Beatmapset id object_type: beatmapset source_user_id: Poster of the discussion
beatmapset_discussion_unlock: object_id: Beatmapset id object_type: beatmapset source_user_id: User who unlocked discussion
beatmapset_disqualify: object_id: Beatmapset id object_type: beatmapset source_user_id: User who disqualified beatmapset
beatmapset_love: object_id: Beatmapset id object_type: beatmapset source_user_id: User who promoted beatmapset to Loved
beatmapset_nominate: object_id: Beatmapset id object_type: beatmapset source_user_id: User who nominated beatmapset
beatmapset_qualify: object_id: Beatmapset id object_type: beatmapset source_user_id: User whom beatmapset nomination triggered qualification
beatmapset_remove_from_loved: object_id: Beatmapset id object_type: beatmapset source_user_id: User who removed beatmapset from Loved
beatmapset_reset_nominations: object_id: Beatmapset id object_type: beatmapset source_user_id: User who locked discussion
channel_message: object_id: Channel id object_type: channel source_user_id: User who posted message
forum_topic_reply: object_id: Topic id object_type: forum_topic source_user_id: User who posted message

class osu.NotificationsDetailsBase(data)¶

Base class for all Detail objects.

Attributes

username: str

class osu.ReadNotification(data)¶

Represents a read notification.

Attributes

category: NotificationCategory

id: int

object_id: int

object_type: ObjectType

class osu.ReviewStats(data)¶

Attributes

praises: int

suggestions: int

problems: int

class osu.UserAchievementUnlockDetails(data)¶

New achievement unlocked