Client v1

Client

This module handles API requests for API v1.

You can read more about it here: https://github.com/ppy/osu-api/wiki

class aiosu.v1.client.Client(token: str, **kwargs: Any)

osu! API v1 Client

Parameters:

• token (str) – The API key

• **kwargs – See below

Keyword Arguments:

• base_url (str) –

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

• limiter (tuple[int, int]) –

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

token: str

base_url: str

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, defaults to standard

• qtype (str) –

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

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

  Optional, max number of days since last event, Min: 1, Max: 31, defaults to 1

Raises:

APIException – Contains status code and error message

Returns:

Requested user

Return type:

list[aiosu.models.user.User]

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

Get a user’s recent scores.

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, defaults to standard

• limit (int) –

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

• qtype (str) –

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

Raises:

• ValueError – If limit is not between 1 and 50

• APIException – Contains status code and error message

Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score]

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

Get a user’s best scores.

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, defaults to standard

• limit (int) –

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

• qtype (str) –

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

Raises:

• ValueError – If limit is not between 1 and 100

• APIException – Contains status code and error message

Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score]

async get_beatmap(**kwargs: Any) → list[Beatmapset]

Get beatmap data.

Parameters:

**kwargs – See below

Keyword Arguments:

• limit (int) –

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

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

  Optional, gamemode to search for, defaults to standard

• converts (bool) –

  Optional, whether to return converts, defaults to False

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

  Optional, mods to apply to the result

• beatmap_id (int) –

  Optional, The ID of the beatmap

• beatmapset_id (int) –

  Optional, The ID of the beatmapset

• since (datetime.datetime) –

  Optional, Return all beatmaps with a leaderboard since this date

• hash (str) –

  Optional, The MD5 hash of the beatmap

• user_query (Union[str, int]) –

  Optional, username or ID to search by

• qtype (str) –

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

Raises:

• ValueError – If limit is not between 1 and 500

• ValueError – If none of hash, since, user_query, beatmap_id or beatmapset_id specified.

• APIException – Contains status code and error message

Returns:

List of beatmapsets each containing one difficulty of the result

Return type:

list[aiosu.models.beatmap.Beatmapset]

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

Get a user’s best scores.

Parameters:

• beatmap_id (int) – The ID of the beatmap

• **kwargs – See below

Keyword Arguments:

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

  Optional, gamemode to search for, defaults to standard

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

  Optional, mods to search for

• limit (int) –

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

• user_query (Union[str, int]) –

  Optional, username or ID to search by

• qtype (str) –

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

Raises:

• ValueError – If limit is not between 1 and 100

• APIException – Contains status code and error message

Returns:

List of requested scores

Return type:

list[aiosu.models.score.Score]

async get_match(match_id: int) → Match

Gets a multiplayer match. (WIP, currently returns raw JSON)

Parameters:

match_id (int) – The ID of the match

Raises:

APIException – Contains status code and error message

Returns:

The requested multiplayer match

Return type:

aiosu.models.legacy.match.Match

async get_replay(**kwargs: Any) → ReplayCompact

Gets data for a replay.

Parameters:

**kwargs – See below

Keyword Arguments:

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

  Optional, gamemode to search for, defaults to standard

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

  Optional, mods to search for

• score_id (int) –

  Optional, the ID of the score

• beatmap_id (int) –

  Optional, the ID of the beatmap, specified together with user_query

• user_query (Union[str, int]) –

  Optional, username or ID to search by, specified together with beatmap_id

• qtype (str) –

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

Raises:

• ValueError – If neither score_id nor beatmap_id + user_id specified

• APIException – Contains status code and error message

Returns:

The data for the requested replay

Return type:

aiosu.models.legacy.replay.Replay

async get_beatmap_osu(beatmap_id: int) → StringIO

Returns the Buffer of the beatmap file requested.

Parameters:

beatmap_id (int) – The ID of the beatmap

Returns:

File-like object of .osu data downloaded from the server.

Return type:

io.StringIO

async close() → None

Closes the client session.