Skip to content

yuyo.reactions#

Client for higher level callback based reaction menu handling.

CallbackSig module-attribute #

CallbackSig = Callable[..., Coroutine[Any, Any, None]]

Type-hint of a callback used to handle matching reactions events.

Client module-attribute #

Client = ReactionClient

Alias of ReactionClient.

Handler module-attribute #

Handler = ReactionHandler

Alias of ReactionHandler.

Paginator module-attribute #

Paginator = ReactionPaginator

Alias of ReactionPaginator.

ReactionEventT module-attribute #

ReactionEventT = Union[ReactionAddEvent, 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.

has_expired abstractmethod property #

has_expired

Whether this handler has ended.

close abstractmethod async #

close()

Close this handler.

on_reaction_event abstractmethod async #

on_reaction_event(event, /, *, alluka=None)

Handle a reaction event.

Parameters:

  • event (ReactionEventT) –

    The event to handle.

  • alluka (Optional[Client], default: None ) –

    The Alluka client to use for callback dependency injection during callback calls.

Raises:

open abstractmethod async #

open(message)

Open this handler.

Parameters:

  • message (Message) –

    The message to bind this handler to.

HandlerClosed #

Bases: Exception

Error raised when a reaction handler has been closed.

ReactionClient #

A class which handles the events for multiple registered reaction handlers.

alluka property #

alluka

The Alluka client being used for callback dependency injection.

is_closed property #

is_closed

Whether this client is closed.

__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 (Optional[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.

close async #

close()

Close this client by unregistering any registered tasks and event listeners.

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 (Optional[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:

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:

Raises:

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:

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:

set_handler #

set_handler(message, handler)

Add a reaction handler to this reaction client.

Note

This does not call AbstractReactionHandler.open.

Parameters:

ReactionHandler #

Bases: AbstractReactionHandler

Standard basic implementation of a reaction handler.

authors property #

authors

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 (Iterable[SnowflakeishOr[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 (Optional[timedelta], default: timedelta(seconds=30) ) –

    How long it should take for this handler to timeout.

remove_callback #

remove_callback(emoji_identifier)

Remove a callback from this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji the callback to remove is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

set_callback #

set_callback(emoji_identifier, callback)

Add a callback to this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[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 (Union[str, SnowflakeishOr[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:

ReactionPaginator #

Bases: ReactionHandler

Standard implementation of a reaction handler for pagination.

authors property #

authors

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 (Iterator[EntryT] | AsyncIterator[EntryT]) –

    Either an asynchronous or synchronous iterator of the entries this should paginate through.

    This should be an iterator of yuyo.pagination.Pages.

  • authors (Iterable[SnowflakeishOr[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 (Optional[timedelta], default: timedelta(seconds=30) ) –

    How long it should take for this paginator to timeout.

add_author #

add_author(user)

Add a author/owner to this handler.

Parameters:

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:

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:

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:

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:

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:

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 (SnowflakeishOr[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 as message.

Raises:

  • ValueError –

    If the provided iterator didn't yield any content for the first message.

get_next_entry async #

get_next_entry()

Get the next entry in this paginator.

Returns:

  • Page | None –

    The next entry in this paginator, or None if there are no more entries.

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 a author/owner from this handler.

Note

If the provided user isn't already a registered owner of this paginator then this should pass silently without raising.

Parameters:

remove_callback #

remove_callback(emoji_identifier)

Remove a callback from this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[CustomEmoji]]) –

    Identifier of the emoji the callback to remove is for.

    This should be a snowfake if this is for a custom emoji or a string if this is for a unicode emoji.

set_callback #

set_callback(emoji_identifier, callback)

Add a callback to this reaction handler.

Parameters:

  • emoji_identifier (Union[str, SnowflakeishOr[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 (Union[str, SnowflakeishOr[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: