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 (aiosu.models.user.UserQueryType) –

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

  • event_days (int) –

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

Raises:

  • ValueError – If event_days is not between 1 and 31

  • 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 (aiosu.models.user.UserQueryType) –

    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 (aiosu.models.user.UserQueryType) –

    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 (aiosu.models.user.UserQueryType) –

    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 (aiosu.models.user.UserQueryType) –

    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 (aiosu.models.user.UserQueryType) –

    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 aclose() → None#

Closes the client session.