State

State handler for Andesite clients.

If you want to store your state externally for example in a database, there are two approaches you can use. You can either implement the AbstractState and use the default AndesitePlayerState (which can be easily converted to and from JSON), or you can use the default State with a custom AbstractPlayerState implementation. Both approaches have their advantages, but you should always consider that while the get operations are often performed together (especially during state migration), the set operations are not.

StateArgumentType

(Type alias) types which can be passed as a state handler to a client.

Type

Union[AbstractState, bool, None]

player_to_raw(player)

Convert the given player to a JSON-serialisable dict.

Parameters

player (Player) – Player to convert.

Return type

Dict[str, Any]

Returns

A JSON-Serialisable dict containing all the data of the player. This data can be passed to player_from_raw which creates a Player instance again.

player_from_raw(data)

Recreate a player from the converted dict.

Parameters

data (Dict[str, Any]) – Data returned by player_to_raw to convert to a Player.

Raises

Exception – If the data can’t be used to create a Player.

Return type

Player

Returns

Created Player instance.

voice_server_update_to_raw(update)

Convert the given voice server update to a JSON-serialisable dict.

Parameters

update (VoiceServerUpdate) – Voice server update to convert.

Return type

Dict[str, Any]

Returns

A JSON-Serialisable dict containing all the data of the voice server update. This data can be passed to voice_server_update_from_raw which creates a VoiceServerUpdate instance again.

voice_server_update_from_raw(data)

Recreate a voice server update from the converted dict.

Parameters

data (Dict[str, Any]) – Data returned by voice_server_update_to_raw to convert.

Raises

Exception – If the data can’t be used to create a voice server update.

Return type

VoiceServerUpdate

Returns

Created VoiceServerUpdate instance.

class AbstractPlayerState

State of a single Andesite player.

Notes

Unless you’re doing something weird you don’t need to call the setter functions. If the player state is managed by an AbstractState which is connected to a client then everything is done for you.

See also

AndesitePlayerState for an in-memory implementation.

abstract property guild_id

ID of the guild the player is for.

Return type

int

abstract async get_player()

Get the player information.

Return type

Optional[Player]

Returns

Player information or None if no player information is present.

abstract async set_player(player)

Set the current player.

Parameters

player (Optional[Player]) – Player data to set. May be None to remove the player information.

Return type

None

abstract async get_voice_server_update()

Get the last voice server update that was sent to the player.

Return type

Optional[VoiceServerUpdate]

Returns

The last voice server update or None if none exists.

abstract async set_voice_server_update(update)

Set the last voice server update.

Parameters

update (Optional[VoiceServerUpdate]) – Voice server update to set.

Return type

None

abstract async get_track()

Get the currently playing track.

Return type

Optional[str]

abstract async set_track(track)

Set the currently playing track.

Return type

None

class PlayerState(guild_id)

Default player state storing the state in memory.

The player state can be converted to a JSON-serialisable dict using to_raw. A state can also be created from said dict using the classmethod from_raw. These methods exist to make it easy to implement a custom AbstractState which loads and stores serialised player states.

property guild_id

ID of the guild the player is for.

Return type

int

async get_player()

Get the player information.

Return type

Optional[Player]

Returns

Player information or None if no player information is present.

async set_player(player)

Set the current player.

Parameters

player (Optional[Player]) – Player data to set. May be None to remove the player information.

Return type

None

async get_track()

Get the currently playing track.

Return type

Optional[str]

async set_track(track)

Set the currently playing track.

Return type

None

async get_voice_server_update()

Get the last voice server update that was sent to the player.

Return type

Optional[VoiceServerUpdate]

Returns

The last voice server update or None if none exists.

async set_voice_server_update(update)

Set the last voice server update.

Parameters

update (Optional[VoiceServerUpdate]) – Voice server update to set.

Return type

None

classmethod from_raw(data)

Create an AbstractPlayerState from the raw data.

Parameters

data (Dict[str, Any]) – Raw player state data as returned by to_raw

Return type

AbstractPlayerState

Returns

A new instance of PlayerState describing the same state as the data.

to_raw()

Convert the player state into a JSON-serialisable dict.

Use the classmethod from_raw to re-create a PlayerState using the returned data.

Return type

Dict[str, Any]

class AbstractState

Andesite state handler.

Keeps track of the state of an Andesite node.

abstract async handle_player_update(update)

Handle a player update.

Parameters

update (PlayerUpdate) – Update that was received.

Return type

None

abstract async handle_andesite_event(event)

Handle an Andesite event.

Parameters

event (AndesiteEvent) – Andesite event that was received.

Return type

None

abstract async handle_voice_server_update(guild_id, update)

Handle a voice server update.

Parameters

• guild_id (int) – Guild the update applies to.

• update (VoiceServerUpdate) – Voice server update.

Return type

None

async on_handle_message_error(message, exc)

Called when an error occurs during message handling.

Parameters

• message (ReceiveOperation) – Message that caused the error

• exc (Exception) – Exception that was raised.

Return type

None

async on_handle_sent_message_error(guild_id, op, payload, exc)

Called when an error occurs during sent message handling.

Parameters

• guild_id (int) – Guild the message was sent for.

• op (str) – Operation code.

• payload (Dict[str, Any]) – Raw payload which was sent.

• exc (Exception) – Exception that was raised.

Return type

None

abstract async get(guild_id)

Get the player state of a guild.

Parameters

guild_id (int) – Guild to get player state for.

Return type

AbstractPlayerState

Returns

Player state for the given guild.

class State(*, state_factory=<class 'andesite.state.PlayerState'>, keep_states=True)

Default implementation of AbstractState.

Stores the player states in memory, unless explicitly suppressed.

Parameters

• state_factory (Callable[[int], ~PST]) – Callable which when called with a guild id, creates an AbstractPlayerState. The default is PlayerState.

• keep_states (bool) – Whether or not the player states should be stored when they’re created. This is required for in-memory storage as otherwise the data would be lost.

player_states

Mapping from

Type

Optional[Dict[int, AbstractPlayerState]]

guild id to the corresponding player state. `None` if `keep_states`

was `False`.

player_states

async handle_player_update(update)

Handle a player update.

Parameters

update (PlayerUpdate) – Update that was received.

Return type

None

async on_handle_message_error(message, exc)

Called when an error occurs during message handling.

Parameters

• message (ReceiveOperation) – Message that caused the error

• exc (Exception) – Exception that was raised.

Return type

None

async on_handle_sent_message_error(guild_id, op, payload, exc)

Called when an error occurs during sent message handling.

Parameters

• guild_id (int) – Guild the message was sent for.

• op (str) – Operation code.

• payload (Dict[str, Any]) – Raw payload which was sent.

• exc (Exception) – Exception that was raised.

Return type

None

async handle_andesite_event(event)

Handle an Andesite event.

Parameters

event (AndesiteEvent) – Andesite event that was received.

Return type

None

async handle_voice_server_update(guild_id, update)

Handle a voice server update.

Parameters

• guild_id (int) – Guild the update applies to.

• update (VoiceServerUpdate) – Voice server update.

Return type

None

async get(guild_id)

Get the player state of a guild.

Parameters

guild_id (int) – Guild to get player state for.

Return type

~PST

Returns

Player state for the given guild.