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: bytes | str) → None#

Pack a string into a file.

Parameters:

file (BinaryIO) – The file to pack into.
value (Union[bytes, 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