Utilities#

Authorization#

This module contains authorization functions.

aiosu.utils.auth.generate_url(client_id: int, redirect_uri: str, base_url: str = 'https://osu.ppy.sh', scopes: ~aiosu.models.scopes.Scopes = Scopes.None, state: str | None = None) → str#

Generates an OAuth URL.

Parameters:

  • client_id (int) – The ID of the client

  • redirect_uri (str) – The URL to redirect to

  • base_url (Optional[str]) – The base URL of the API, defaults to “https://osu.ppy.sh”

  • scopes (Optional[Scopes]) – The scopes to request, defaults to Scopes.PUBLIC | Scopes.IDENTIFY

  • state (Optional[str]) – The state to pass to the API, defaults to None

Returns:

The OAuth URL

Return type:

str

async aiosu.utils.auth.process_code(client_id: int, client_secret: str, redirect_uri: str, code: str, base_url: str = 'https://osu.ppy.sh') → OAuthToken#

Creates an OAuth Token from an authorization code.

Parameters:

  • client_id (int) – The ID of the client

  • client_secret (str) – The client secret

  • redirect_uri (str) – The URL to redirect to

  • code (str) – Code returned from the API

  • base_url (Optional[str]) – The base URL of the API, defaults to “https://osu.ppy.sh”

Returns:

The OAuth token

Return type:

aiosu.models.oauthtoken.OAuthToken

Replay#

This module contains functions to parse replay files.

aiosu.utils.replay.parse_file(file: BinaryIO) → ReplayFile#

Parse a replay file and return a dictionary with the replay data.

Parameters:

file (BinaryIO) – The replay file.

Returns:

The replay data.

Return type:

Replay

aiosu.utils.replay.parse_path(path: str) → ReplayFile#

Parse a replay file and return a dictionary with the replay data.

Parameters:

path (str) – The path to the replay file.

Returns:

The replay data.

Return type:

Replay

aiosu.utils.replay.write_path(path: str, replay: ReplayFile) → None#

Write a replay to a file.

Parameters:

  • path (str) – The path to the file to write to.

  • replay (Replay) – The replay to write.

aiosu.utils.replay.write_replay(file: BinaryIO, replay: ReplayFile) → None#

Write a replay to a file.

Parameters:

  • file (BinaryIO) – The file to write to.

  • replay (Replay) – The replay to write.

Accuracy#

This module contains accuracy calculators for osu! gamemodes.

class aiosu.utils.accuracy.CatchAccuracyCalculator#
static calculate(score: Score) → float#

Calculates accuracy for an osu!catch score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Accuracy for the given score

Return type:

float

classmethod calculate_weighted(score: Score) → float#

Calculates weighted accuracy for an osu!catch score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Weighted accuracy to be used in pp calculation

Return type:

float

class aiosu.utils.accuracy.ManiaAccuracyCalculator#
static calculate(score: Score) → float#

Calculates accuracy for an osu!mania score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Accuracy for the given score

Return type:

float

static calculate_weighted(score: Score) → float#

Calculates weighted accuracy for an osu!mania score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Weighted accuracy to be used in pp calculation

Return type:

float

class aiosu.utils.accuracy.OsuAccuracyCalculator#
static calculate(score: Score) → float#

Calculates accuracy for an osu!std score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Accuracy for the given score

Return type:

float

static calculate_weighted(score: Score) → float#

Calculates weighted accuracy for an osu!std score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Raises:

ValueError – If score does not have an associated beatmap

Returns:

Weighted accuracy to be used in pp calculation

Return type:

float

class aiosu.utils.accuracy.TaikoAccuracyCalculator#
static calculate(score: Score) → float#

Calculates accuracy for an osu!taiko score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Accuracy for the given score

Return type:

float

classmethod calculate_weighted(score: Score) → float#

Calculates weighted accuracy for an osu!taiko score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate accuracy for

Returns:

Weighted accuracy to be used in pp calculation

Return type:

float

Performance#

This module contains performance point calculators for osu! gamemodes.

class aiosu.utils.performance.CatchPerformanceCalculator(difficulty_attributes: BeatmapDifficultyAttributes)#

osu!catch performance point calculator.

Parameters:

difficulty_attributes (BeatmapDifficultyAttributes) – API difficulty attributes for a beatmap

calculate(score: Score) → CatchPerformanceAttributes#

Calculates performance points for a score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate pp for

Returns:

Performance attributes for the score

Return type:

aiosu.models.performance.CatchPerformanceAttributes

difficulty_attributes#
class aiosu.utils.performance.ManiaPerformanceCalculator(difficulty_attributes: BeatmapDifficultyAttributes)#

osu!mania performance point calculator.

Parameters:

difficulty_attributes (BeatmapDifficultyAttributes) – API difficulty attributes for a beatmap

calculate(score: Score) → ManiaPerformanceAttributes#

Calculates performance points for a score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate pp for

Returns:

Performance attributes for the score

Return type:

aiosu.models.performance.ManiaPerformanceAttributes

difficulty_attributes#
class aiosu.utils.performance.OsuPerformanceCalculator(difficulty_attributes: BeatmapDifficultyAttributes)#

osu!std performance point calculator. Only compatible with scores from API v2.

Parameters:

difficulty_attributes (BeatmapDifficultyAttributes) – API difficulty attributes for a beatmap

calculate(score: Score) → OsuPerformanceAttributes#

Calculates performance points for a score.

Parameters:

score (aiosu.models.score.Score) – The score to calculate pp for

Raises:

ValueError – If score does not have an associated beatmap

Returns:

Performance attributes for the score

Return type:

aiosu.models.performance.OsuPerformanceAttributes

difficulty_attributes#
class aiosu.utils.performance.TaikoPerformanceCalculator(difficulty_attributes: BeatmapDifficultyAttributes)#

osu!taiko performance point calculator.

Parameters:

difficulty_attributes (BeatmapDifficultyAttributes) – API difficulty attributes for a beatmap

calculate(score: Score) → TaikoPerformanceAttributes#

Calculates performance points for a score

Parameters:

score (aiosu.models.score.Score) – The score to calculate pp for

Returns:

Performance attributes for the score

Return type:

aiosu.models.performance.TaikoPerformanceAttributes

difficulty_attributes#

Binary#

This module contains functions for reading and writing binary data.

aiosu.utils.binary.pack(file: BinaryIO, fmt: str, value: object) → None#

Pack a value into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • fmt (str) – The format to pack with.

  • value (object) – The value to pack.

aiosu.utils.binary.pack_byte(file: BinaryIO, value: int) → None#

Pack a byte into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (int) – The value to pack.

aiosu.utils.binary.pack_float16(file: BinaryIO, value: float) → None#

Pack a float16 into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (float) – The value to pack.

aiosu.utils.binary.pack_float32(file: BinaryIO, value: float) → None#

Pack a float32 into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (float) – The value to pack.

aiosu.utils.binary.pack_float64(file: BinaryIO, value: float) → None#

Pack a float64 into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (float) – The value to pack.

aiosu.utils.binary.pack_int(file: BinaryIO, value: int) → None#

Pack an integer into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (int) – The value to pack.

aiosu.utils.binary.pack_long(file: BinaryIO, value: int) → None#

Pack a long into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (int) – The value to pack.

aiosu.utils.binary.pack_replay_data(file: BinaryIO, data: str) → None#

Pack the replay data into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • data (str) – The data to pack.

aiosu.utils.binary.pack_short(file: BinaryIO, value: int) → None#

Pack a short into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (int) – The value to pack.

aiosu.utils.binary.pack_string(file: BinaryIO, value: str) → None#

Pack a string into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (str) – The value to pack.

aiosu.utils.binary.pack_timestamp(file: BinaryIO, value: datetime) → None#

Pack a timestamp into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (datetime) – The value to pack.

aiosu.utils.binary.pack_uleb128(file: BinaryIO, value: int) → None#

Pack a ULEB128 into a file.

Parameters:

  • file (BinaryIO) – The file to pack into.

  • value (int) – The value to pack.

aiosu.utils.binary.unpack(file: BinaryIO, fmt: str) → int#

Unpack a value from a file.

Parameters:

  • file (BinaryIO) – The file to unpack from.

  • fmt (str) – The format to unpack.

Returns:

The unpacked value.

Return type:

int

aiosu.utils.binary.unpack_byte(file: BinaryIO) → int#

Unpack a byte from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked byte.

Return type:

int

aiosu.utils.binary.unpack_float16(file: BinaryIO) → float#

Unpack a float16 from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked float16.

Return type:

float

aiosu.utils.binary.unpack_float32(file: BinaryIO) → float#

Unpack a float32 from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked float32.

Return type:

float

aiosu.utils.binary.unpack_float64(file: BinaryIO) → float#

Unpack a float64 from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked float64.

Return type:

float

aiosu.utils.binary.unpack_int(file: BinaryIO) → int#

Unpack an integer from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked integer.

Return type:

int

aiosu.utils.binary.unpack_long(file: BinaryIO) → int#

Unpack a long from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked long.

Return type:

int

aiosu.utils.binary.unpack_replay_data(file: BinaryIO) → str#

Unpack the replay data from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The replay event data.

Return type:

str

aiosu.utils.binary.unpack_short(file: BinaryIO) → int#

Unpack a short from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked short.

Return type:

int

aiosu.utils.binary.unpack_string(file: BinaryIO) → str#

Unpack a string from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked string.

Return type:

str

aiosu.utils.binary.unpack_timestamp(file: BinaryIO) → datetime#

Unpack a timestamp from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked timestamp.

Return type:

datetime

aiosu.utils.binary.unpack_uleb128(file: BinaryIO) → int#

Unpack a ULEB128 from a file.

Parameters:

file (BinaryIO) – The file to unpack from.

Returns:

The unpacked ULEB128.

Return type:

int