vibrio.lazer#

Module for interacting with osu!lazer functionality (see Lazer, LazerAsync).

class vibrio.lazer.BaseUrlSession(base_url: str)#

Request session with a base URL as used internally in Lazer.

Methods

request(method, url, *args, **kwargs)

Makes a request using the currently stored base URL.

request(method: str | bytes, url: str | bytes, *args: Any, **kwargs: Any) → Response#

Makes a request using the currently stored base URL.

See also

LazerAsync: asynchronous implementation of the same functionality

Notes

This class can be used traditionally instead of as a context manager, in which case the use of start() and stop() are left up to the user. Only do this if you know what you are doing; failing to call stop() appropriately may leave an instance of the server dangling. start() will attempt to create a callback that culls any server instances on program shutdown, but proceed with caution and call stop() as necessary to avoid any possible memory leaks.

Examples

>>> from vibrio import HitStatistics, Lazer, OsuMod
>>> with Lazer() as lazer:
...     attributes = lazer.calculate_performance(
...         beatmap_id=1001682,
...         mods=[OsuMod.HIDDEN, OsuMod.DOUBLE_TIME],
...         hitstats=HitStatistics(
...             count_300=2019, count_100=104, count_50=0, count_miss=3, combo=3141
...         ),
...     )
...     attributes.total
1304.35

Attributes:

connectedbool: Whether the class instance is currently connected to a server.

Methods

`calculate_difficulty`(*[, beatmap_id, ...])	Calculates the difficulty parameters for a beatmap and optional mod combination.
`calculate_performance`(*[, beatmap_id, ...])	Calculates the performance values for a given play on a provided beatmap.
`clear_cache`()	Clears beatmap cache (if applicable).
`get_beatmap`(beatmap_id)	Returns a file stream for the given beatmap.
`has_beatmap`(beatmap_id)	Returns true if the given beatmap is currently stored locally.
`start`()	Launches and connects to vibrio server executable.
`stop`()	Cleans up server executable and related periphery.

calculate_difficulty(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None) → OsuDifficultyAttributes#

Calculates the difficulty parameters for a beatmap and optional mod combination.

beatmap_id and beatmap specify the beatmap to be queried; exactly one of the two must be set during difficulty calculation.

Parameters:

beatmap_idint, optional
beatmapbinary file stream, optional
modslist of OsuMod enums, optional

Returns:

OsuDifficultyAttributes: Dataclass encoding the difficulty attributes of the requested map.

Calculates the performance values for a given play on a provided beatmap.

Each query essentially requires a method of specifying the beatmap the play was made on (through exactly one of beatmap_id, beatmap or difficulty) and a method of describing the play itself (through exactly one of hit_stats and replay). However, processing a replay is not possible with difficulty attributes alone, so using difficulty requires the use of hit_stats.

Parameters:

beatmap_idint, optional
beatmapbinary file stream, optional
modslist of OsuMod enums, optional: For use with either beatmap or beatmap_id.
difficultyOsuDifficultyAttributes, optional: Difficulty attribute instance, as returned by calculate_difficulty().
hit_statsHitStatistics, optional
replaybinary file stream, optional

Returns:

OsuPerformanceAttributes: Dataclass encoding the performance values of the requested play.

clear_cache() → None#: Clears beatmap cache (if applicable).

get_beatmap(beatmap_id: int) → BinaryIO#: Returns a file stream for the given beatmap.

has_beatmap(beatmap_id: int) → bool#: Returns true if the given beatmap is currently stored locally.

property process: Popen[bytes]#: Executable process; errors if unset.

property session: BaseUrlSession#: Request session; errors if unset.

start() → None#: Launches and connects to vibrio server executable.

stop() → None#: Cleans up server executable and related periphery.

class vibrio.lazer.LazerAsync(*, port: int | None = None, self_hosted: bool = False, log_level: logging._Level = 0)#

Context manager for interfacing with osu!lazer functionality asynchronously.

See also

Lazer: synchronous implementation of the same functionality

Notes

Examples

Note: the following example would not execute in a REPL environment as async statements must occur within async functions, but the principle still holds.

>>> from vibrio import HitStatistics, Lazer, OsuMod
>>> async with Lazer() as lazer:
...     attributes = await lazer.calculate_performance(
...         beatmap_id=1001682,
...         mods=[OsuMod.HIDDEN, OsuMod.DOUBLE_TIME],
...         hitstats=HitStatistics(
...             count_300=2019, count_100=104, count_50=0, count_miss=3, combo=3141
...         ),
...     )
...     attributes.total
1304.35

Attributes:

connectedbool: Whether the class instance is currently connected to a server.

Methods

`calculate_difficulty`(*[, beatmap_id, ...])	Calculates the difficulty parameters for a beatmap and optional mod combination.
`calculate_performance`(*[, beatmap_id, ...])	Calculates the performance values for a given play on a provided beatmap.
`clear_cache`()	Clears beatmap cache (if applicable).
`get_beatmap`(beatmap_id)	Returns a file stream for the given beatmap.
`has_beatmap`(beatmap_id)	Returns true if the given beatmap is currently stored locally.
`start`()	Launches and connects to vibrio server executable.
`stop`()	Cleans up server executable and related periphery.

async calculate_difficulty(*, beatmap_id: int | None = None, beatmap: BinaryIO | None = None, mods: list[OsuMod] | None = None) → OsuDifficultyAttributes#

Calculates the difficulty parameters for a beatmap and optional mod combination.

beatmap_id and beatmap specify the beatmap to be queried; exactly one of the two must be set during difficulty calculation.

Parameters:

beatmap_idint, optional
beatmapbinary file stream, optional
modslist of OsuMod enums, optional

Returns:

OsuDifficultyAttributes: Dataclass encoding the difficulty attributes of the requested map.

Calculates the performance values for a given play on a provided beatmap.

Parameters:

beatmap_idint, optional
beatmapbinary file stream, optional
modslist of OsuMod enums, optional: For use with either beatmap or beatmap_id.
difficultyOsuDifficultyAttributes, optional: Difficulty attribute instance, as returned by calculate_difficulty().
hit_statsHitStatistics, optional
replaybinary file stream, optional

Returns:

OsuPerformanceAttributes: Dataclass encoding the performance values of the requested play.

async clear_cache() → None#: Clears beatmap cache (if applicable).

async get_beatmap(beatmap_id: int) → BinaryIO#: Returns a file stream for the given beatmap.

async has_beatmap(beatmap_id: int) → bool#: Returns true if the given beatmap is currently stored locally.

property process: Process#: Executable process; errors if unset.

property session: ClientSession#: Request session; errors if unset.

async start() → None#: Launches and connects to vibrio server executable.

async stop() → None#: Cleans up server executable and related periphery.

class vibrio.lazer.LazerBase(*, port: int | None = None, self_hosted: bool = False, log_level: logging._Level = 0)#

Abstract base class for Lazer and LazerAsync.

Methods

`address`()	Constructs the base URL for the web server.
`args`()	Produces the command line arguments for the server executable.

STARTUP_DELAY = 0.05#: Amount of time (seconds) between requests during startup.

address() → str#: Constructs the base URL for the web server.

args() → list[str]#: Produces the command line arguments for the server executable.

class vibrio.lazer.LogPipe(log_func: Callable[[str], None])#

IO wrapper around a thread for piping output to log function.

Methods

close
fileno

close() → None#

fileno() → int#

exception vibrio.lazer.ServerError#: Unknown/unexpected server-side error.

exception vibrio.lazer.StateError#: Exception due to attempting to induce an invalid state transition e.g. attempting to launch the server when an instance is already tied to the current object.

vibrio.lazer.find_open_port() → int#: Returns a port not currently in use on the system.

vibrio.lazer.get_vibrio_path(platform: str) → Path#: Determines path to server executable on a given platform.

Table of Contents

vibrio.lazer#