Node Management#

This file is about managing nodes and selecting the best node for a player.

mafic.type_variables.ClientT = ~ClientT#

A type hint for a client that is (optionally a subclass of) your library’s client.

This is used in NodePool to type hint the client used to create Nodes and Players. Node.client will be of this type.

Methods
class mafic.NodePool(client, default_strategies=None)#

Bases: Generic[ClientT]

A class that manages nodes and chooses them based on strategies.

Parameters:
await add_node(node, *, player_cls=None)#

Add an existing node to this pool.

Note

You generally do not want this, use create_node() instead. This is used for after running remove_node() to re-add the node if it has been restarted.

New in version 2.7.

Parameters:

  • node (Node[ClientT]) – The node to add.

  • player –

    The player class to use for this node when resuming.

    New in version 2.8.

Return type:

None

await close()#

Close all nodes in the pool. :rtype: None

New in version 2.6.

await create_node(*, host, port, label, password, secure=False, heartbeat=30, timeout=10, session=None, resume_key=None, regions=None, shard_ids=None, resuming_session_id=None, player_cls=None)#

Create a node and connect it.

The parameters here relate to Node.

Parameters:

  • host (str) – The host of the node to connect to.

  • port (int) – The port of the node to connect to.

  • label (str) – The label of the node used to identify it.

  • password (str) – The password of the node to authenticate.

  • secure (bool) – Whether to use SSL (TLS) or not.

  • heartbeat (int) – The interval to send heartbeats to the node websocket connection.

  • timeout (float) – The timeout to use for the node websocket connection.

  • session (Optional[aiohttp.ClientSession]) – The session to use for the node websocket connection.

  • resume_key (Optional[str]) –

    The key to use when resuming the node. If not provided, the key will be generated from the host, port and label.

    Warning

    This is ignored in lavalink V4, use resuming_session_id instead.

  • regions (Optional[Sequence[Group | Region | VoiceRegion]]) – The voice regions that the node can be used in. This is used to determine when to use this node.

  • shard_ids (Optional[Sequence[int]]) – The shard IDs that the node can be used in. This is used to determine when to use this node.

  • resuming_session_id (Optional[str]) –

    The session ID to use when resuming the node. If not provided, the node will not resume.

    This should be stored from on_node_ready() with session_id to resume the session and gain control of the players. If the node is not resuming, players will be destroyed if Lavalink loses connection to us.

    New in version 2.2.

  • player_cls (Optional[type[Player[ClientT]]]) –

    The player class to use for this node when resuming.

    New in version 2.8.

Returns:

The created node.

Return type:

Node

Raises:

RuntimeError – If the node pool has not been initialized.

classmethod get_node(*, guild_id, endpoint, strategies=None)#

Get a node based on the given strategies.

Parameters:

  • guild_id (str | int) – The guild ID to get a node for.

  • endpoint (Optional[str]) – The endpoint to get a node for.

  • strategies (Optional[StrategyList]) – The strategies to use to get a node. If not provided, the default strategies will be used.

Returns:

The node to use.

Return type:

Node

Raises:

RuntimeError – If the node pool has not been initialized.

classmethod get_random_node()#

Get a random node.

Returns:

The random node.

Return type:

Node

Raises:

ValueError – If there are no nodes.

await remove_node(node, *, transfer_players=True)#

Remove a node from the pool.

New in version 2.6.

Parameters:

  • node (Union[Node[ClientT], str]) – The node to remove.

  • transfer_players (bool) – Whether to transfer players to other nodes or destroy them.

Return type:

None

mafic.pool.StrategyList#

A type hint for a list of strategies to select the best node.

This can either be:

alias of Union[Callable[List[Node[ClientT]], int, Optional[int], Optional[str], List[Node[ClientT]]], Sequence[Strategy], Sequence[Callable[List[Node[ClientT]], int, Optional[int], Optional[str], List[Node[ClientT]]]], Sequence[Union[Strategy, Callable[List[Node[ClientT]], int, Optional[int], Optional[str], List[Node[ClientT]]]]]]

mafic.strategy.StrategyCallable#

Represents a strategy callable.

This accepts nodes, guild_id, shard_count and endpoint and returns a list of nodes.

alias of Callable[List[Node[ClientT]], int, Optional[int], Optional[str], List[Node[ClientT]]]

class mafic.Strategy(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Represents a strategy for selecting a node.

LOCATION = 1#

Selects a node based on the region the guild is in.

RANDOM = 2#

Selects a random node.

SHARD = 3#

Selects a node based on the shard ID of the guild.

USAGE = 4#

Selects a node based on the least used node.

class mafic.VoiceRegion(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Represents a Discord voice region.

All the attributes here are best effort but may not be complete. The value is what you find in region[number].discord.media endpoints.

AMSTERDAM = 'amsterdam'#
ATLANTA = 'atlanta'#
BRAZIL = 'brazil'#
BUCHAREST = 'bucharest'#
BUENOS_AIRES = 'buenos-aires'#
DUBAI = 'dubai'#
EUROPE = 'europe'#
FINLAND = 'finland'#
FRANKFURT = 'frankfurt'#
HONG_KONG = 'hongkong'#
INDIA = 'india'#
JAPAN = 'japan'#
LONDON = 'london'#
MADRID = 'madrid'#
MILAN = 'milan'#
MONTREAL = 'montreal'#
NEWARK = 'newark'#
OREGON = 'oregon'#
ROTTERDAM = 'rotterdam'#
RUSSIA = 'russia'#
SANTA_CLARA = 'santa-clara'#
SANTIAGO = 'santiago'#
SEATTLE = 'seattle'#
SINGAPORE = 'singapore'#
SOUTH_AFRICA = 'southafrica'#
SOUTH_KOREA = 'south-korea'#
STOCKHOLM = 'stockholm'#
ST_PETE = 'st-pete'#
SYDNEY = 'sydney'#
US_CENTRAL = 'us-central'#
US_EAST = 'us-east'#
US_SOUTH = 'us-south'#
US_WEST = 'us-west'#
class mafic.Region(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Represents a region of voice regions.

This groups voice regions by geographical location.

CENTRAL_EUROPE = (VoiceRegion.FRANKFURT, VoiceRegion.EUROPE)#
CENTRAL_NA = (VoiceRegion.US_CENTRAL,)#
EAST_ASIA = (VoiceRegion.JAPAN, VoiceRegion.HONG_KONG)#
EAST_EUROPE = (VoiceRegion.BUCHAREST,)#
EAST_NA = (VoiceRegion.MONTREAL, VoiceRegion.US_EAST, VoiceRegion.ATLANTA)#
NORTH_ASIA = (VoiceRegion.RUSSIA,)#
NORTH_EUROPE = (VoiceRegion.FINLAND, VoiceRegion.ST_PETE, VoiceRegion.STOCKHOLM)#
OCEANIA = (VoiceRegion.SYDNEY,)#
SOUTH_AFRICA = (VoiceRegion.SOUTH_AFRICA,)#
SOUTH_AMERICA = (VoiceRegion.SANTIAGO, VoiceRegion.BUENOS_AIRES, VoiceRegion.BRAZIL)#
SOUTH_ASIA = (VoiceRegion.INDIA, VoiceRegion.SINGAPORE)#
SOUTH_EUROPE = (VoiceRegion.MILAN,)#
SOUTH_NA = (VoiceRegion.US_SOUTH,)#
WEST_ASIA = (VoiceRegion.DUBAI,)#
WEST_EUROPE = (VoiceRegion.MADRID, VoiceRegion.NEWARK, VoiceRegion.ROTTERDAM, VoiceRegion.LONDON, VoiceRegion.AMSTERDAM)#
WEST_NA = (VoiceRegion.OREGON, VoiceRegion.SANTA_CLARA, VoiceRegion.SEATTLE, VoiceRegion.US_WEST)#
class mafic.Group(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Represents a group of regions.

This groups regions by geographical location. These are very generic and should be used rarely.

CENTRAL = (<Region.NORTH_EUROPE>, <Region.WEST_EUROPE>, <Region.SOUTH_EUROPE>, <Region.EAST_EUROPE>, <Region.CENTRAL_EUROPE>, <Region.SOUTH_AFRICA>)#
EAST = (<Region.NORTH_ASIA>, <Region.EAST_ASIA>, <Region.SOUTH_ASIA>, <Region.WEST_ASIA>, <Region.OCEANIA>)#
WEST = (<Region.EAST_NA>, <Region.WEST_NA>, <Region.SOUTH_NA>, <Region.CENTRAL_NA>, <Region.SOUTH_AMERICA>)#