yuyo.reactions#
Client for higher level callback based reaction menu handling.
CallbackSig module-attribute
#
CallbackSig = collections.Callable[..., collections.Coroutine[typing.Any, typing.Any, None]]
Type-hint of a callback used to handle matching reactions events.
ReactionEventT module-attribute
#
ReactionEventT = typing.Union[hikari.ReactionAddEvent, hikari.ReactionDeleteEvent]
Type hint of the event types CallbackSig takes as its first argument.
AbstractReactionHandler #
Bases: ABC
The interface for a reaction handler used with ReactionClient.
on_reaction_event abstractmethod
async
#
on_reaction_event(event, /, *, alluka=None)
Handle a reaction event.
Parameters:
- event (
ReactionEventT
) –The event to handle.
- alluka (
typing.Optional[alluka.abc.Client]
, default:None
) –The Alluka client to use for callback dependency injection during callback calls.
Raises:
-
HandlerClosed
–If this reaction handler has been closed.
open abstractmethod
async
#
open(message)
Open this handler.
Parameters:
- message (
Message
) –The message to bind this handler to.
ReactionClient #
A class which handles the events for multiple registered reaction handlers.
alluka property
#
alluka: alluka_.abc.Client
The Alluka client being used for callback dependency injection.
__init__ #
__init__(*, rest, event_manager, alluka=None, event_managed=True)
Initialise a reaction client.
This registers ReactionClient as a type dependency when alluka
isn't passed.
Note
For an easier way to initialise the client from a bot see ReactionClient.from_gateway_bot, and ReactionClient.from_tanjun.
Parameters:
- rest (
RESTClient
) –The REST client to register this reaction client with.
- event_manager (
EventManager
) –The event manager client to register this reaction client with.
- alluka (
typing.Optional[alluka.abc.Client]
, default:None
) –The Alluka client to use for callback dependency injection in this client.
If not provided then this will initialise its own Alluka client.
- event_managed (
bool
, default:True
) –Whether the reaction client should be automatically opened and closed based on the lifetime events dispatched by
event_managed
.
from_gateway_bot classmethod
#
from_gateway_bot(bot, /, *, alluka=None, event_managed=True)
Build a ReactionClient
from a gateway bot.
This registers ReactionClient as a type dependency when alluka
isn't passed.
Parameters:
- bot (
EventManagerAware & RESTAware
) –The bot to build a reaction client for.
- alluka (
typing.Optional[alluka.abc.Client]
, default:None
) –The Alluka client to use for callback dependency injection in this client.
If not provided then this will initialise its own Alluka client.
- event_managed (
bool
, default:True
) –Whether the reaction client should be automatically opened and closed based on the lifetime events dispatched by
bot
.
Returns:
-
ReactionClient
–The reaction client for the bot.
from_tanjun classmethod
#
from_tanjun(tanjun_client, /, *, tanjun_managed=True)
Build a ReactionClient
from a gateway bot.
This will use the Tanjun client's alluka client and registers ReactionClient as a type dependency on Tanjun.
Parameters:
- tanjun_client (
Client
) –The tanjun client to build a reaction client for.
- tanjun_managed (
bool
, default:True
) –Whether the reaction client should be automatically opened and closed based on the Tanjun client's lifetime client callback.
Returns:
-
ReactionClient
–The reaction client for the bot.
Raises:
-
ValueError
–If
tanjun_client.events
is None.
get_handler #
get_handler(message)
Get a reference to a handler registered in this reaction client.
Note
This does not call AbstractReactionHandler.close.
Parameters:
Returns:
-
AbstractReactionHandler | None
–The object of the registered handler if found else None.
open async
#
open()
Start this client by registering the required tasks and event listeners for it to function.
remove_handler #
remove_handler(message)
Remove a handler from this reaction client.
Note
This does not call AbstractReactionHandler.close.
Parameters:
Returns:
-
AbstractReactionHandler | None
–The object of the registered handler if found else None.
set_handler #
set_handler(message, handler)
Add a reaction handler to this reaction client.
Note
This does not call AbstractReactionHandler.open.
Parameters:
- message (
hikari.SnowflakeishOr[hikari.Message]
) –The message ID to add register a reaction handler with.
- handler (
AbstractReactionHandler
) –The object of the opened handler to register in this reaction client.
ReactionHandler #
Bases: AbstractReactionHandler
Standard basic implementation of a reaction handler.
authors property
#
authors: collections.Set[hikari.Snowflake]
Set of the authors/owner of a enabled handler.
Note
If this is empty then the handler is considered public and any user will be able to trigger it.
__init__ #
__init__(*, authors=(), timeout=datetime.timedelta(seconds=30))
Initialise a reaction handler.
Parameters:
- authors (
abc.Iterable[hikari.SnowflakeishOr[hikari.User]]
, default:()
) –An iterable of IDs of the users who can call this handler.
If no users are provided then the reactions will be public (meaning that anybody can use it).
- timeout (
typing.Optional[datetime.timedelta]
, default:datetime.timedelta(seconds=30)
) –How long it should take for this handler to timeout.
remove_callback #
remove_callback(emoji_identifier)
set_callback #
set_callback(emoji_identifier, callback)
Add a callback to this reaction handler.
Parameters:
- emoji_identifier (
typing.Union[str, hikari.SnowflakeishOr[hikari.CustomEmoji]]
) –Identifier of the emoji this callback is for.
This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.
- callback (
CallbackSig
) –The callback to add.
This should be a function that accepts a single parameter, which is the event that triggered this reaction.
with_callback #
with_callback(emoji_identifier)
Add a callback to this reaction handler through a decorator call.
Parameters:
- emoji_identifier (
typing.Union[str, hikari.SnowflakeishOr[hikari.CustomEmoji]]
) –Identifier of the emoji this callback is for.
This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.
Returns:
-
abc.abc.Callback[[CallbackSig], CallbackSig]
–A decorator to add a callback to this reaction handler.
ReactionPaginator #
Bases: ReactionHandler
Standard implementation of a reaction handler for pagination.
authors property
#
authors: collections.Set[hikari.Snowflake]
Set of the authors/owner of a enabled handler.
Note
If this is empty then the handler is considered public and any user will be able to trigger it.
__init__ #
__init__(iterator, /, *, authors=(), triggers=(pagination.LEFT_TRIANGLE, pagination.STOP_SQUARE, pagination.RIGHT_TRIANGLE), timeout=datetime.timedelta(seconds=30))
Initialise a reaction paginator.
Parameters:
- iterator (
abc.Iterator[yuyo.pagination.EntryT] | abc.AsyncIterator[yuyo.pagination.EntryT]
) –Either an asynchronous or synchronous iterator of the entries this should paginate through.
This should be an iterator of yuyo.pagination.Pages.
- authors (
abc.Iterable[hikari.SnowflakeishOr[hikari.User]]
, default:()
) –An iterable of IDs of the users who can call this paginator.
If no users are provided then the reactions will be public (meaning that anybody can use it).
- timeout (
typing.Optional[datetime.timedelta]
, default:datetime.timedelta(seconds=30)
) –How long it should take for this paginator to timeout.
add_author #
add_author(user)
add_first_button #
add_first_button(*, emoji=pagination.LEFT_DOUBLE_TRIANGLE, add_reaction=True)
Add the jump to first entry reaction button to this paginator.
You should pass triggers=[]
to ReactionPaginator.__init__ before calling this.
Note
These reactions will appear in the order these methods were called in.
Parameters:
- emoji (
typing.Union[CustomEmoji, str]
, default:LEFT_DOUBLE_TRIANGLE
) –The emoji to react with for this button.
- add_reaction (
bool
, default:True
) –Whether the bot should add this reaction to the message when ReactionPaginator.open is called with
add_reactions=True
.
Returns:
-
Self
–To enable chained calls.
add_last_button #
add_last_button(*, emoji=pagination.RIGHT_DOUBLE_TRIANGLE, add_reaction=True)
Add the jump to last entry reaction button to this paginator.
You should pass triggers=[]
to ReactionPaginator.__init__ before calling this.
Note
These reactions will appear in the order these methods were called in.
Parameters:
- emoji (
typing.Union[CustomEmoji, str]
, default:RIGHT_DOUBLE_TRIANGLE
) –The emoji to react with for this button.
- add_reaction (
bool
, default:True
) –Whether the bot should add this reaction to the message when ReactionPaginator.open is called with
add_reactions=True
.
Returns:
-
Self
–To enable chained calls.
add_next_button #
add_next_button(*, emoji=pagination.RIGHT_TRIANGLE, add_reaction=True)
Add the next entry reaction button to this paginator.
You should pass triggers=[]
to ReactionPaginator.__init__ before calling this.
Note
These reactions will appear in the order these methods were called in.
Parameters:
- emoji (
typing.Union[CustomEmoji, str]
, default:RIGHT_TRIANGLE
) –The emoji to react with for this button.
- add_reaction (
bool
, default:True
) –Whether the bot should add this reaction to the message when ReactionPaginator.open is called with
add_reactions=True
.
Returns:
-
Self
–To enable chained calls.
add_previous_button #
add_previous_button(*, emoji=pagination.LEFT_TRIANGLE, add_reaction=True)
Add the previous entry reaction button to this paginator.
You should pass triggers=[]
to ReactionPaginator.__init__ before calling this.
Note
These reactions will appear in the order these methods were called in.
Parameters:
- emoji (
typing.Union[CustomEmoji, str]
, default:LEFT_TRIANGLE
) –The emoji to react with for this button.
- add_reaction (
bool
, default:True
) –Whether the bot should add this reaction to the message when ReactionPaginator.open is called with
add_reactions=True
.
Returns:
-
Self
–To enable chained calls.
add_stop_button #
add_stop_button(*, emoji=pagination.STOP_SQUARE, add_reaction=True)
Add the stop reaction button to this paginator.
You should pass triggers=[]
to ReactionPaginator.__init__ before calling this.
Note
These reactions will appear in the order these methods were called in.
Parameters:
- emoji (
typing.Union[CustomEmoji, str]
, default:STOP_SQUARE
) –The emoji to react with for this button.
- add_reaction (
bool
, default:True
) –Whether the bot should add this reaction to the message when ReactionPaginator.open is called with
add_reactions=True
.
Returns:
-
Self
–To enable chained calls.
close async
#
close(*, remove_reactions=False)
Close this handler and deregister any previously registered message.
Parameters:
- remove_reactions (
bool
, default:False
) –Whether this should remove the reactions that were being used to paginate through this from the previously registered message.
create_message async
#
create_message(rest, channel_id, /, *, add_reactions=True)
Start this handler and link it to a bot message.
Note
Calling this multiple times will replace the previously registered message.
Parameters:
- rest (
RESTClient
) –Rest client to use to make the response.
- channel_id (
hikari.SnowflakeishOr[hikari.TextableChannel]
) –ID of the channel to respond in.
- add_reactions (
bool
, default:True
) –Whether this should add the paginator's reactions to the message after responding.
Returns:
-
Message
–Object of the message this handler now targets. If
message
was not supplied then this will be the object of a newly created message, otherwise this will be what was supplied asmessage
.
Raises:
-
ValueError
–If the provided iterator didn't yield any content for the first message.
get_next_entry async
#
get_next_entry()
open async
#
open(message, /, *, add_reactions=True)
Start the reaction paginator and start accepting reactions..
Parameters:
- message (
Message
) –The message this paginator should target.
- add_reactions (
bool
, default:True
) –Whether this should add the paginator's reactions to the message.
remove_author #
remove_author(user)
remove_callback #
remove_callback(emoji_identifier)
set_callback #
set_callback(emoji_identifier, callback)
Add a callback to this reaction handler.
Parameters:
- emoji_identifier (
typing.Union[str, hikari.SnowflakeishOr[hikari.CustomEmoji]]
) –Identifier of the emoji this callback is for.
This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.
- callback (
CallbackSig
) –The callback to add.
This should be a function that accepts a single parameter, which is the event that triggered this reaction.
with_callback #
with_callback(emoji_identifier)
Add a callback to this reaction handler through a decorator call.
Parameters:
- emoji_identifier (
typing.Union[str, hikari.SnowflakeishOr[hikari.CustomEmoji]]
) –Identifier of the emoji this callback is for.
This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.
Returns:
-
abc.abc.Callback[[CallbackSig], CallbackSig]
–A decorator to add a callback to this reaction handler.