Client v2

Repository

This module contains a repository for API v2 token objects.

class aiosu.v2.repository.oauthtoken.BaseTokenRepository

Base token repository. Allows for custom token storage.

abstract async exists(session_id: int) → bool

Check if a token exists.

abstract async add(session_id: int, token: OAuthToken) → OAuthToken

Add a token.

abstract async get(session_id: int) → OAuthToken

Get a token.

abstract async update(session_id: int, token: OAuthToken) → OAuthToken

Update a token.

abstract async delete(session_id: int) → None

Delete a token.

class aiosu.v2.repository.oauthtoken.SimpleTokenRepository

Simple in-memory token repository.

async exists(session_id: int) → bool

Check if a token exists.

async add(session_id: int, token: OAuthToken) → OAuthToken

Add a token.

async get(session_id: int) → OAuthToken

Get a token.

async update(session_id: int, token: OAuthToken) → OAuthToken

Update a token.

async delete(session_id: int) → None

Delete a token.

Client Storage

This module handles multiple API v2 Client sessions.

class aiosu.v2.clientstorage.ClientStorage(**kwargs: Any)

OAuth sessions manager.

Parameters:

**kwargs – See below

Keyword Arguments:
  • token_repository (aiosu.v2.repository.oauthtoken.BaseTokenRepository) –

    Optional, defaults to instance of aiosu.v2.repository.oauthtoken.SimpleTokenRepository

  • client_secret (str)

  • client_id (int)

  • base_url (str) –

    Optional, base API URL, defaults to “https://osu.ppy.sh”

  • create_app_client (bool) –

    Optional, whether to automatically create guest clients, defaults to True

client_secret: str
client_id: int
base_url: str
clients: dict[int, Client]
on_client_add(func: F) → F

A decorator that is called whenever a client is added, to be used as:

@client_storage.on_client_add

async def func(event: ClientAddEvent)

on_client_update(func: F) → F

A decorator that is called whenever any stored client is updated, to be used as:

@client_storage.on_client_update

async def func(event: ClientUpdateEvent)

property app_client: Client

Client credentials app client.

Raises:

ValueError – If no app client is provided and creation is disabled

Returns:

Client credentials app client session

Return type:

aiosu.v2.client.Client

client_exists(client_uid: int) → bool

Checks if a client exists.

Parameters:

client_uid (int) – The owner user ID of the client

Returns:

Whether the client with the given ID exists

Return type:

bool

async add_client(token: OAuthToken, **kwargs: Any) → Client

Adds a client to storage.

Parameters:
Keyword Arguments:
  • id (int) –

    Optional, the ID of the client session

Returns:

The client with the given ID or token

Return type:

aiosu.v2.client.Client

async get_client(**kwargs: Any) → Client

Gets a client from storage.

Parameters:

**kwargs – See below

Keyword Arguments:
  • id (int) –

    Optional, the owner user ID of the client

  • token (OAuthToken) –

    Optional, the token object of the client

Raises:

InvalidClientRequestedError – If no valid ID or token is provided

Returns:

The client with the given ID or token

Return type:

aiosu.v2.client.Client

async revoke_client(client_uid: int) → None

Revokes a client from storage.

Parameters:

client_uid (int) – The owner user ID of the client

Raises:

InvalidClientRequestedError – If no client exists with the given ID

async aclose() → None

Closes all client sessions.

Client

This module handles API requests for API v2 (OAuth).

You can read more about it here: https://osu.ppy.sh/docs/index.html

class aiosu.v2.client.Client(**kwargs: Any)

osu! API v2 Client

Parameters:

**kwargs – See below

Keyword Arguments:
  • token_repository (aiosu.v2.repository.oauthtoken.BaseTokenRepository) –

    Optional, defaults to instance of aiosu.v2.repository.oauthtoken.SimpleTokenRepository

  • session_id (int) –

    Optional, ID of the session to search in the repository, defaults to 0

  • client_id (int) –

    Optional, required to refresh tokens

  • client_secret (str) –

    Optional, required to refresh tokens

  • base_url (str) –

    Optional, base API URL, defaults to “https://osu.ppy.sh”

  • token (aiosu.models.oauthtoken.OAuthToken) –

    Optional, defaults to client credentials if not provided

  • limiter (tuple[int, int]) –

    Optional, rate limit, defaults to (600, 60) (600 requests per minute)

session_id: int
client_id: int
client_secret: str
base_url: str
on_client_update(func: F) → F

A decorator that is called whenever a client is updated, to be used as:

@client.on_client_update

async def func(event: ClientUpdateEvent)

async get_current_token() → OAuthToken

Get the current token

Query tracks from featured artists.

Parameters:

**kwargs – See below

Keyword Arguments:
  • album (str) –

    Optional, the album to filter by.

  • artist (str) –

    Optional, the artist to filter by.

  • genre (int) –

    Optional, the genre ID to filter by.

  • length (tuple[int, int]) –

    Optional, the length range to filter by.

  • bpm (tuple[int, int]) –

    Optional, The BPM range to filter by.

  • query (str) –

    Optional, the search query to filter by.

  • is_default_sort (bool) –

    Optional, whether to sort by the default sort.

  • sort (str) –

    Optional, the sort to use.

  • exclusive_only (bool) –

    Optional, whether to only get osu! exclusive tracks.

Raises:

APIException – Contains status code and error message

Returns:

Featured artist tracks response object

Return type:

aiosu.models.artist.ArtistTracksResponse

async get_seasonal_backgrounds() → SeasonalBackgroundSet

Gets the current seasonal background set.

Raises:

APIException – Contains status code and error message

Returns:

Seasonal background set object

Return type:

aiosu.models.backgrounds.SeasonalBackgroundSet

async get_changelog_listing(**kwargs: Any) → ChangelogListing

Gets the changelog listing.

Parameters:

**kwargs – See below

Keyword Arguments:
  • message_formats (list[aiosu.models.changelog.ChangelogMessageFormat]) –

    Optional, message formats to get, defaults to ["html", "markdown"]

  • from (str) –

    Optional, the start date to return.

  • to (str) –

    Optional, the end date to return.

  • max_id (int) –

    Optional, the maximum ID to return.

  • stream (str) –

    Optional, the stream to return.

  • cursor_string (str) –

    Optional, the cursor string to use.

Raises:

APIException – Contains status code and error message

Returns:

Changelog listing object

Return type:

aiosu.models.changelog.ChangelogListing

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

Gets a specific build from the changelog.

Parameters:

  • stream – The stream to get the build from

  • build – The build to get

Raises:

APIException – Contains status code and error message

Returns:

Build object

Return type:

aiosu.models.changelog.Build

async lookup_changelog_build(changelog_query: str | int, **kwargs: Any) → Build

Looks up a build from the changelog.

Parameters:

  • changelog_query (Union[str, int]) – The query to search for

  • **kwargs – See below

Keyword Arguments:
  • is_id (bool) –

    Optional, whether the query is an ID or not, defaults to True if the query is an int

  • message_formats (list[aiosu.models.changelog.ChangelogMessageFormat]) –

    Optional, message formats to get, defaults to ["html", "markdown"]

Raises:

APIException – Contains status code and error message

Returns:

Build object

Return type:

aiosu.models.changelog.Build

async get_news_listing(**kwargs: Any) → NewsListing

Gets the news listing.

Parameters:

**kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, the number of news posts to return. Min: 1, Max: 21, defaults to 12

  • year (int) –

    Optional, the year to filter by.

  • cursor_string (str) –

    Optional, the cursor string to use for pagination.

Raises:

APIException – Contains status code and error message

Returns:

News listing object

Return type:

aiosu.models.news.NewsListing

async get_news_post(news_query: str | int, **kwargs: Any) → NewsPost

Gets a news post.

Parameters:

  • news_query (Union[str, int]) – The query to search for

  • **kwargs – See below

Keyword Arguments:
  • is_id (bool) –

    Optional, whether the query is an ID or not, defaults to True if the query is an int

Raises:

APIException – Contains status code and error message

Returns:

News post object

Return type:

aiosu.models.news.NewsPost

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

Gets a wiki page.

Parameters:

  • locale (str) – The locale of the wiki page

  • path (str) – The path of the wiki page

Raises:

APIException – Contains status code and error message

Returns:

Wiki page object

Return type:

aiosu.models.wiki.WikiPage

async get_comment(comment_id: int, **kwargs: Any) → CommentBundle

Gets a comment.

Parameters:

  • comment_id (int) – The ID of the comment

  • **kwargs – See below

Keyword Arguments:
  • cursor_string (str) –

    Optional, cursor string to get the next page of comments

Raises:

APIException – Contains status code and error message

Returns:

Comment bundle object

Return type:

aiosu.models.comment.CommentBundle

async get_comments(**kwargs: Any) → CommentBundle

Gets comments.

Parameters:

**kwargs – See below

Keyword Arguments:
  • commentable_type (aiosu.models.comment.CommentableType) –

    Optional, commentable type to get comments from

  • commentable_id (int) –

    Optional, commentable ID to get comments from

  • parent_id (int) –

    Optional, parent ID to get comments from

  • sort (aiosu.models.comment.CommentSortType) –

    Optional, sort order of comments, defaults to "new"

  • cursor_string (str) –

    Optional, cursor string to get the next page of comments

Raises:

APIException – Contains status code and error message

Returns:

Comment bundle object

Return type:

aiosu.models.comment.CommentBundle

async search(query: str, **kwargs: Any) → SearchResponse

Searches for a user, beatmap, beatmapset, or wiki page.

Parameters:

  • query (str) – The query to search for

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.search.SearchMode) –

    Optional, gamemode to search for, defaults to all

  • page (int) –

    Optional, page to get, ignored if mode is all

Raises:
Returns:

Search response object

Return type:

aiosu.models.search.SearchResponse

async get_me(**kwargs: Any) → User

Gets the user who owns the current token

Parameters:

**kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

Raises:
Returns:

Requested user

Return type:

aiosu.models.user.User

async get_own_friends() → list[User]

Gets the token owner’s friend list

Raises:
Returns:

List of friends

Return type:

list[aiosu.models.user.User]

async get_user(user_query: str | int, **kwargs: Any) → User

Gets a user by a query.

Parameters:

  • user_query (Union[str, int]) – Username or ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • qtype (aiosu.models.user.UserQueryType) –

    Optional, “string” or “id”. Type of the user_query

Raises:
Returns:

Requested user

Return type:

aiosu.models.user.User

async get_users(user_ids: list[int]) → list[User]

Get multiple user data.

Parameters:

user_ids (list[int]) – The IDs of the users

Raises:
Returns:

List of user data objects

Return type:

list[aiosu.models.user.User]

async get_user_kudosu(user_id: int, **kwargs: Any) → list[KudosuHistory]

Get a user’s kudosu history.

Parameters:

  • user_id (int) – User ID to search by

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of scores to get

  • offset (int) –

    Optional, offset of the first score to get

Raises:
Returns:

List of kudosu history objects

Return type:

list[aiosu.models.kudosu.KudosuHistory]

async get_user_recents(user_id: int, **kwargs: Any) → list[Score | LazerScore]

Get a user’s recent scores.

Parameters:

  • user_id (int) – User ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 100, defaults to 100

  • include_fails (bool) –

    Optional, whether to include failed scores, defaults to False

  • offset (int) –

    Optional, page offset to start from, defaults to 0

  • new_format (bool) –

    Optional, whether to use the new format, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score] or list[aiosu.models.lazer.LazerScore]

async get_user_bests(user_id: int, **kwargs: Any) → list[Score | LazerScore]

Get a user’s top scores.

Parameters:

  • user_id (int) – User ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 100, defaults to 100

  • offset (int) –

    Optional, page offset to start from, defaults to 0

  • new_format (bool) –

    Optional, whether to use the new format, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score] or list[aiosu.models.lazer.LazerScore]

async get_user_firsts(user_id: int, **kwargs: Any) → list[Score | LazerScore]

Get a user’s first place scores.

Parameters:

  • user_id (int) – User ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 100, defaults to 100

  • offset (int) –

    Optional, page offset to start from, defaults to 0

  • new_format (bool) –

    Optional, whether to use the new format, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score] or list[aiosu.models.lazer.LazerScore]

async get_user_pinned(user_id: int, **kwargs: Any) → list[Score | LazerScore]

Get a user’s pinned scores.

Parameters:

  • user_id (int) – User ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 100, defaults to 100

  • offset (int) –

    Optional, page offset to start from, defaults to 0

  • new_format (bool) –

    Optional, whether to use the new format, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score] or list[aiosu.models.lazer.LazerScore]

async get_user_beatmap_scores(user_id: int, beatmap_id: int, **kwargs: Any) → list[Score]

Get a user’s scores on a specific beatmap.

Parameters:

  • user_id (int) – User ID to search by

  • beatmap_id (int) – Beatmap ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • legacy_only (bool) –

    Optional, whether to only get legacy scores, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score]

async get_user_beatmaps(user_id: int, type: UserBeatmapType, **kwargs: Any) → list[Beatmapset]

Get a user’s beatmaps.

Parameters:

  • user_id (int) – ID of the user

  • type (aiosu.models.beatmap.UserBeatmapType) – Type of beatmaps to get

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of beatmaps to get

  • offset (int) –

    Optional, offset of the first beatmap to get

Raises:
Returns:

List of requested beatmaps

Return type:

list[aiosu.models.beatmap.Beatmap]

async get_user_most_played(user_id: int, **kwargs: Any) → list[BeatmapUserPlaycount]

Get a user’s most played beatmaps.

Parameters:

  • user_id (int) – ID of the user

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of beatmaps to get

  • offset (int) –

    Optional, offset of the first beatmap to get

Raises:
Returns:

List of user playcount objects

Return type:

list[aiosu.models.beatmap.BeatmapUserPlaycount]

async get_user_recent_activity(user_id: int, **kwargs: Any) → list[Event]

Get a user’s recent activity.

Parameters:

  • user_id (int) – ID of the user

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of events to get

  • offset (int) –

    Optional, offset of the first event to get

Raises:
Returns:

List of events

Return type:

list[aiosu.models.event.Event]

async get_events() → EventResponse

Get global events.

Raises:
Returns:

Event response object

Return type:

aiosu.models.event.EventResponse

async get_beatmap_scores(beatmap_id: int, **kwargs: Any) → list[Score]

Get scores submitted on a specific beatmap.

Parameters:

  • beatmap_id (int) – Beatmap ID to search by

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • mods (aiosu.models.mods.Mods) –

    Optional, mods to search for

  • type (aiosu.models.common.BeatmapScoreboardType) –

    Optional, beatmap score ranking type

  • legacy_only (bool) –

    Optional, whether to only get legacy scores, defaults to False

Raises:
Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score]

async get_beatmap(beatmap_id: int) → Beatmap

Get beatmap data.

Parameters:

beatmap_id (int) – The ID of the beatmap

Raises:
Returns:

Beatmap data object

Return type:

aiosu.models.beatmap.Beatmap

async get_beatmaps(beatmap_ids: list[int]) → list[Beatmap]

Get multiple beatmap data.

Parameters:

beatmap_ids (list[int]) – The IDs of the beatmaps

Raises:
Returns:

List of beatmap data objects

Return type:

list[aiosu.models.beatmap.Beatmap]

async lookup_beatmap(**kwargs: Any) → Beatmap

Lookup beatmap data.

Parameters:

**kwargs – See below

Keyword Arguments:
  • checksum (str) –

    Optional, the MD5 checksum of the beatmap

  • filename (str) –

    Optional, the filename of the beatmap

  • id (int) –

    Optional, the ID of the beatmap

Raises:
Returns:

Beatmap data object

Return type:

aiosu.models.beatmap.Beatmap

async get_beatmap_attributes(beatmap_id: int, **kwargs: Any) → BeatmapDifficultyAttributes

Gets difficulty attributes for a beatmap.

Parameters:

  • beatmap_id (int) – The ID of the beatmap

  • **kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • mods (aiosu.models.mods.Mods) –

    Optional, mods to apply to the result

Raises:
Returns:

Difficulty attributes for a beatmap

Return type:

aiosu.models.beatmap.BeatmapDifficultyAttributes

async get_beatmapset(beatmapset_id: int) → Beatmapset

Get beatmapset data.

Parameters:

beatmapset_id (int) – The ID of the beatmapset

Raises:
Returns:

Beatmapset data object

Return type:

aiosu.models.beatmap.Beatmapset

async lookup_beatmapset(beatmap_id: int) → Beatmapset

Lookup beatmap data.

Parameters:

beatmap_id (int) – The ID of a beatmap in the set

Raises:
Returns:

Beatmapset data object

Return type:

aiosu.models.beatmap.Beatmapset

async search_beatmapsets(**kwargs: Any) → BeatmapsetSearchResponse

Search beatmapset by filter.

Parameters:

  • search_filter (str) – The search filter.

  • **kwargs – See below

Keyword Arguments:
  • query (str) –

    Optional, search query

  • mode (aiosu.models.gamemode.Gamemode) –

    Optional, gamemode to search for

  • category (aiosu.models.beatmap.BeatmapsetCategory) –

    Optional, beatmapset category

  • show_explicit (bool) –

    Optional, whether to show explicit content, defaults to False

  • genre (aiosu.models.beatmap.BeatmapsetGenre) –

    Optional, beatmapset genre

  • language (aiosu.models.beatmap.BeatmapsetLanguage) –

    Optional, beatmapset language

  • bundled (aiosu.models.beatmap.BeatmapsetBundleFilterType) –

    Optional, filter by bundled status. Currently not implemented

  • sort (aiosu.models.beatmap.BeatmapsetSortType) –

    Optional, sort order

  • only_video (bool) –

    Optional, whether to only show beatmapsets with video, defaults to False

  • only_storyboard (bool) –

    Optional, whether to only show beatmapsets with storyboard, defaults to False

  • recommended_difficulty (bool) –

    Optional, whether to only show beatmapsets with recommended difficulty, defaults to False

  • only_followed (bool) –

    Optional, whether to only show beatmapsets from followed mappers, defaults to False

  • only_spotlights (bool) –

    Optional, whether to only show beatmapsets were featured in spotlights, defaults to False

  • only_featured_artists (bool) –

    Optional, whether to only show beatmapsets were featured artists, defaults to False

  • include_converts (bool) –

    Optional, whether to include converted beatmapsets, defaults to False

  • cursor_string (str) –

    Optional, cursor string to get the next page of results

Raises:
Returns:

Beatmapset search response

Return type:

list[aiosu.models.beatmap.BeatmapsetSearchResponse]

async get_beatmap_packs(**kwargs: Any) → BeatmapPacksResponse

Get beatmap packs.

Parameters:

**kwargs – See below

Keyword Arguments:
  • type (aiosu.models.beatmap.BeatmapPackType) –

    Optional, beatmap pack type

  • cursor_string (str) –

    Optional, cursor string to get the next page of results

Raises:
Returns:

Beatmap packs response

Return type:

aiosu.models.beatmap.BeatmapPacksResponse

async get_beatmap_pack(pack_tag: str, **kwargs: Any) → BeatmapPack

Get beatmap pack.

Parameters:

  • pack_tag (str) – The tag of the beatmap pack

  • **kwargs – See below

Keyword Arguments:
  • legacy_only (bool) –

    Optional, whether or not to consider lazer scores for completion data, defaults to False

Raises:
Returns:

Beatmap pack object

Return type:

aiosu.models.beatmap.BeatmapPack

async get_beatmapset_events(**kwargs: Any) → list[BeatmapsetEvent]

Get beatmapset events.

Parameters:

**kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of results per page

  • page (int) –

    Optional, page number

  • user_id (int) –

    Optional, user ID

  • beatmapset_id (int) –

    Optional, beatmapset ID

  • min_date (datetime.datetime) –

    Optional, minimum date

  • max_date (datetime.datetime) –

    Optional, maximum date

  • types (list[aiosu.models.beatmap.BeatmapsetEventType]) –

    Optional, event types

Raises:
Returns:

List of beatmapset events

Return type:

list[aiosu.models.event.Event]

async get_beatmapset_discussions(**kwargs: Any) → BeatmapsetDiscussionResponse

Get beatmapset discussions.

Parameters:

**kwargs – See below

Keyword Arguments:
  • beatmap_id (int) –

    Optional, beatmap ID

  • beatmapset_id (int) –

    Optional, beatmapset ID

  • beatmapset_status (aiosu.models.beatmap.BeatmapsetRequestStatus) –

    Optional, beatmapset status

  • limit (int) –

    Optional, number of results per page

  • page (int) –

    Optional, page number

  • message_types (list[aiosu.models.beatmap.BeatmapsetDisscussionType]) –

    Optional, message types

  • only_unresolved (bool) –

    Optional, only unresolved discussions

  • sort (aiosu.models.common.SortType) –

    Optional, sort order, defaults to id_desc

  • user_id (int) –

    Optional, user ID

  • with_deleted (bool) –

    Optional, include deleted discussions

  • cursor_string (str) –

    Optional, cursor string

Raises:
Returns:

Beatmapset discussion response

Return type:

aiosu.models.beatmap.BeatmapsetDiscussionResponse

async get_beatmapset_discussion_posts(**kwargs: Any) → BeatmapsetDiscussionPostResponse

Get beatmapset discussion posts.

Parameters:

**kwargs – See below

Keyword Arguments:
  • beatmapset_discussion_id (int) –

    Optional, beatmapset discussion ID

  • limit (int) –

    Optional, number of results per page

  • page (int) –

    Optional, page number

  • sort (aiosu.models.common.SortType) –

    Optional, sort order, defaults to id_desc

  • types (list[str]) –

    Optional, post types

  • user_id (int) –

    Optional, user ID

  • with_deleted (bool) –

    Optional, include deleted discussions

  • cursor_string (str) –

    Optional, cursor string

Raises:
Returns:

Beatmapset discussion post response

Return type:

aiosu.models.beatmap.BeatmapsetDiscussionPostResponse

async get_beatmapset_discussion_votes(**kwargs: Any) → BeatmapsetDiscussionVoteResponse

Get beatmapset discussion votes.

Parameters:

**kwargs – See below

Keyword Arguments:
  • beatmapset_discussion_id (int) –

    Optional, beatmapset discussion ID

  • limit (int) –

    Optional, number of results per page

  • page (int) –

    Optional, page number

  • receiver_id (int) –

    Optional, receiver ID

  • score (aiosu.models.beatmap.BeatmapsetDiscussionVoteScoreType) –

    Optional, “1” for upvote, “-1” for downvote

  • sort (aiosu.models.common.SortType) –

    Optional, sort order, defaults to id_desc

  • user_id (int) –

    Optional, user ID

  • with_deleted (bool) –

    Optional, include deleted discussions

  • cursor_string (str) –

    Optional, cursor string

Raises:
Returns:

Beatmapset discussion vote response

Return type:

aiosu.models.beatmap.BeatmapsetDiscussionVoteResponse

async get_score(score_id: int, mode: Gamemode, **kwargs: Any) → Score | LazerScore

Gets data about a score.

Parameters:
Keyword Arguments:
  • new_format (bool) –

    Optional, whether to use the new score format, defaults to False

Raises:
Returns:

Score data object

Return type:

aiosu.models.score.Score

async get_score_replay(score_id: int, mode: Gamemode) → BytesIO

Gets the replay file for a score.

Parameters:
Raises:
Returns:

Replay file

Return type:

io.BytesIO

async get_rankings(mode: Gamemode, type: RankingType, **kwargs: Any) → Rankings

Get rankings.

Parameters:

  • mode (aiosu.models.gamemode.Gamemode) – The gamemode to search for

  • type (aiosu.models.rankings.RankingType) – The ranking type to search for

  • **kwargs – See below

Keyword Arguments:
  • country (str) –

    Optional, country code

  • filter (aiosu.models.rankings.RankingFilter) –

    Optional, ranking filter

  • spotlight (int) –

    Optional, spotlight ID

  • variant (aiosu.models.rankings.RankingVariant) –

    Optional, ranking variant

  • cursor_string (str) –

    Optional, cursor string

Raises:
Returns:

Rankings

Return type:

aiosu.models.rankings.Rankings

async get_rankings_kudosu(**kwargs: Any) → Rankings

Get kudosu rankings.

Parameters:

**kwargs – See below

Keyword Arguments:
  • page_id (int) –

    Optional, page ID

Raises:
Returns:

Rankings

Return type:

aiosu.models.rankings.Rankings

async get_spotlights() → list[Spotlight]

Gets the current spotlights.

Raises:
Returns:

List of spotlights

Return type:

list[aiosu.models.spotlight.Spotlight]

async get_forum_topic(topic_id: int, **kwargs: Any) → ForumTopicResponse

Gets a forum topic.

Parameters:

  • topic_id (int) – The ID of the topic

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, the number of posts to return. Min: 1, Max: 50, defaults to 20

  • sort (aiosu.models.common.SortType) –

    Optional, the sort type to use. Defaults to id_asc

  • start (int) –

    Optional, the start post ID to use for pagination.

  • end (int) –

    Optional, the end post ID to use for pagination.

  • cursor_string (str) –

    Optional, the cursor string to use for pagination.

Raises:
Returns:

Forum topic response object

Return type:

aiosu.models.forum.ForumTopicResponse

async create_forum_topic(forum_id: int, title: str, content: str, **kwargs: Any) → ForumCreateTopicResponse

Creates a forum topic.

Parameters:

  • forum_id (int) – The ID of the forum to create the topic in

  • title (str) – The title of the topic

  • content (str) – The content of the topic

  • **kwargs – See below

Keyword Arguments:
  • with_poll (bool) –

    Optional, whether to create a poll with the topic. Defaults to False

  • poll_title (str) –

    Optional, the title of the poll

  • poll_options (list[str]) –

    Optional, the options for the poll

  • poll_length_days (int) –

    Optional, the length of the poll in days. Defaults to 0

  • poll_vote_change (bool) –

    Optional, whether to allow users to change their vote. Defaults to False

  • poll_hide_results (bool) –

    Optional, whether to hide the results of the poll. Defaults to False

  • poll_max_votes (int) –

    Optional, the maximum number of votes a user can make. Defaults to 1

Raises:
Returns:

Forum create topic response object

Return type:

aiosu.models.forum.ForumCreateTopicResponse

async reply_forum_topic(topic_id: int, content: str) → ForumPost

Replies to a forum topic.

Parameters:

  • topic_id (int) – The ID of the topic

  • content (str) – The content of the post

Raises:
Returns:

Forum post object

Return type:

aiosu.models.forum.ForumPost

async edit_forum_topic_title(topic_id: int, new_title: str) → ForumTopic

Edits a forum topic’s title.

Parameters:

  • topic_id (int) – The ID of the topic

  • new_title (str) – The new title of the topic

Raises:
Returns:

Forum topic object

Return type:

aiosu.models.forum.ForumTopic

async edit_forum_post(post_id: int, new_content: str) → ForumPost

Edits a forum post.

Parameters:

  • post_id (int) – The ID of the post

  • new_content (str) – The new content of the post

Raises:
Returns:

Forum post object

Return type:

aiosu.models.forum.ForumPost

async get_chat_ack(**kwargs: Any) → list[ChatUserSilence]

Gets chat acknowledgement.

Parameters:

**kwargs – See below

Keyword Arguments:
  • since (int) –

    Optional, the last message ID received

  • silence_id_since (int) –

    Optional, the last silence ID received

Raises:
Returns:

List of chat user silence objects

Return type:

list[aiosu.models.chat.ChatUserSilence]

async get_chat_updates(since: int, **kwargs: Any) → ChatUpdateResponse

Gets chat updates.

Parameters:

  • since (int) – The last message ID received

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, the maximum number of messages to return. Min: 1, Max: 50. Defaults to 50

  • channel_id (int) –

    Optional, the channel ID to get messages from

  • silence_id_since (int) –

    Optional, the last silence ID received

  • includes (list[aiosu.models.chat.ChatIncludeType]) –

    Optional, the additional information to include. Defaults to all.

Raises:
Returns:

Chat update response object

Return type:

aiosu.models.chat.ChatUpdateResponse

async get_channel(channel_id: int) → ChatChannelResponse

Gets channel.

Parameters:

channel_id (int) – The channel ID to get

Raises:
Returns:

Chat channel object

Return type:

aiosu.models.chat.ChatChannelResponse

async get_channels() → list[ChatChannel]

Gets a list of joinable public channels.

Raises:
Returns:

List of chat channel objects

Return type:

list[aiosu.models.chat.ChatChannel]

async get_channel_messages(channel_id: int, **kwargs: Any) → list[ChatMessage]

Gets channel messages.

Parameters:

  • channel_id (int) – The channel ID to get messages from

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, the maximum number of messages to return. Min: 1, Max: 50. Defaults to 50

  • since (int) –

    Optional, the ID of the oldest message to return

  • until (int) –

    Optional, the ID of the newest message to return

Raises:
Returns:

List of chat message objects

Return type:

list[aiosu.models.chat.ChatMessage]

async create_chat_channel(type: ChatChannelType, **kwargs: Any) → ChatChannel

Creates a chat channel.

Parameters:

  • type (aiosu.models.chat.ChatChannelType) – The type of the channel.

  • **kwargs – See below

Keyword Arguments:
  • message (str) –

    Required if type is ANNOUNCE, the message to send in the PM

  • target_id (int) –

    Only used if if type is PM, the ID of the user to send a PM to

  • target_ids (list[int]) –

    Only used if type is ANNOUNCE, the IDs of the users to send a PM to

  • channel_name (str) –

    Only used if type is ANNOUNCE, the name of the channel

  • channel_description (str) –

    Only used if type is ANNOUNCE, the description of the channel

Raises:
Returns:

Chat channel object

Return type:

aiosu.models.chat.ChatChannel

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

Joins a channel.

Parameters:

  • channel_id (int) – The channel ID to join

  • user_id (int) – The user ID to join as

Raises:
Returns:

Chat channel object

Return type:

aiosu.models.chat.ChatChannel

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

Leaves a channel.

Parameters:

  • channel_id (int) – The channel ID to leave

  • user_id (int) – The user ID to leave as

Raises:
async mark_read(channel_id: int, message_id: int) → None

Marks a channel as read.

Parameters:

  • channel_id (int) – The channel ID to mark as read

  • message_id (int) – The message ID to mark as read up to

Raises:
async send_message(channel_id: int, message: str, is_action: bool) → ChatMessage

Sends a message to a channel.

Parameters:

  • channel_id (int) – The ID of the channel

  • message (str) – The message to send

  • is_action (bool) – Whether the message is an action

Raises:
Returns:

Chat message object

Return type:

aiosu.models.chat.ChatMessage

async send_private_message(user_id: int, message: str, is_action: bool, **kwargs: Any) → ChatMessageCreateResponse

Sends a message to a user.

Parameters:

  • user_id (int) – The ID of the user

  • message (str) – The message to send

  • is_action (bool) – Whether the message is an action

  • **kwargs – See below

Keyword Arguments:
  • uuid (str) –

    Optional, client-side message identifier to be sent back in response and websocket json

Raises:
Returns:

Chat message create response object

Return type:

aiosu.models.chat.ChatMessageCreateResponse

async get_multiplayer_matches(**kwargs: Any) → MultiplayerMatchesResponse

Gets the multiplayer matches.

Parameters:

**kwargs – See below

Keyword Arguments:
  • sort (aiosu.models.common.SortType) –

    Optional, the sort type

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 50, defaults to 50

  • cursor_string (str) –

    Optional, the cursor string to get the next page of results

Raises:
Returns:

Multiplayer matches response object

Return type:

aiosu.models.multiplayer.MultiplayerMatchesResponse

async get_multiplayer_match(match_id: int, **kwargs: Any) → MultiplayerMatchResponse

Gets a multiplayer match.

Parameters:

  • match_id (int) – The ID of the match

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 100, defaults to 100

  • before (int) –

    Optional, the ID of the score to get the scores before

  • after (int) –

    Optional, the ID of the score to get the scores after

Raises:
Returns:

Multiplayer match response object

Return type:

aiosu.models.multiplayer.MultiplayerMatchResponse

async get_multiplayer_rooms(**kwargs: Any) → list[MultiplayerRoom]

Gets the multiplayer rooms.

Parameters:

**kwargs – See below

Keyword Arguments:
  • mode (aiosu.models.multiplayer.MultiplayerRoomMode) –

    Optional, the multiplayer room mode

  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 50, defaults to 50

  • sort (aiosu.models.common.SortType) –

    Optional, the sort type

  • category (aiosu.models.multiplayer.MultiplayerRoomCategory) –

    Optional, the multiplayer room category

  • type (aiosu.models.multiplayer.MultiplayerRoomGroupType) –

    Optional, the multiplayer room group type

Raises:
Returns:

List of multiplayer rooms

Return type:

list[aiosu.models.multiplayer.MultiplayerRoom]

async get_multiplayer_room(room_id: int) → MultiplayerRoom

Gets a multiplayer room.

Parameters:

room_id (int) – The ID of the room

Raises:
Returns:

Multiplayer room object

Return type:

aiosu.models.multiplayer.MultiplayerRoom

async get_multiplayer_leaderboard(room_id: int, **kwargs: Any) → MultiplayerLeaderboardResponse

Gets the multiplayer leaderboard for a room.

Parameters:

  • room_id (int) – The ID of the room

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, number of scores to get. Min: 1, Max: 50, defaults to 50

Raises:
Returns:

Multiplayer leaderboard response object

Return type:

aiosu.models.multiplayer.MultiplayerLeaderboardResponse

async get_multiplayer_scores(room_id: int, playlist_id: int, **kwargs: Any) → MultiplayerScoresResponse

Gets the multiplayer scores for a room.

Parameters:

  • room_id (int) – The ID of the room

  • playlist_id (int) – The ID of the playlist

  • **kwargs – See below

Keyword Arguments:
  • limit (int) –

    Optional, the number of scores to return

  • sort (aiosu.models.multiplayer.MultiplayerScoreSortType) –

    Optional, the sort order of the scores

  • cursor_string (str) –

    Optional, the cursor string to use for pagination

Raises:
Returns:

Multiplayer scores response object

Return type:

aiosu.models.multiplayer.MultiplayerScoresResponse

async revoke_token() → None

Revokes the current token and closes the session.

Raises:
async aclose() → None

Closes the client session.