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.
discord.Client
for discord.py.nextcord.Client
for nextcord.disnake.Client
for disnake.discord.Client
for py-cord.
This is used in
NodePool
to type hint the client used to createNode
s andPlayer
s.Node.client
will be of this type.
- clsNodePool.get_node
- clsNodePool.get_random_node
- asyncadd_node
- asyncclose
- asynccreate_node
- asyncremove_node
- class mafic.NodePool(client, default_strategies=None)#
-
A class that manages nodes and chooses them based on strategies.
- Parameters:
client (
ClientT
) – The client to use to connect to the nodes.default_strategies (
Optional
[StrategyList
]) – The default strategies to use when selecting a node. Defaults to [Strategy.SHARD
,Strategy.LOCATION
,Strategy.USAGE
].
- 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 runningremove_node()
to re-add the node if it has been restarted.New in version 2.7.
- 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.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()
withsession_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:
- 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:
- Returns:
The node to use.
- Return type:
- Raises:
RuntimeError – If the node pool has not been initialized.
- classmethod get_random_node()#
Get a random node.
- Returns:
The random node.
- Return type:
- Raises:
ValueError – If there are no nodes.
- mafic.pool.StrategyList#
A type hint for a list of strategies to select the best node.
This can either be:
A single
StrategyCallable
.A sequence of
Strategy
s.A sequence of
StrategyCallable
s.A sequence of
Strategy
s andStrategyCallable
s.
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
andendpoint
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>)#