Listeners

Reactions

The Reaction listeners allow for listening for reaction changes on a specific message.

Registering a reaction listener

bot.reaction_listener.register(message, coro, data=None) registers the message message for reaction listening. If a reaction event occurs, coro(event) is called with event being a BaseReactionEvent (see below). coro is expected to be a coroutine.

The ReactionEvent objects

The callback coroutine is called with an event object as its argument that carries information about the reaction event.

If a reaction was added, it is of the type subsystems.reactions.ReactionAddedEvent. If a reaction was removed, it is of the type subsystems.reactions.ReactionRemovedEvent.

The event object has the following fields:

• callback: A reference to the callback coroutine.
• data: Opaque object that the user specified in the registration process.
• user: User that did the reaction.
• member: Member that did the reaction. If the user is not a member, this is None.
• message: Message that the reaction was added or removed on.
• emoji: The reaction emoji.

Timers

The timer subsystem allows for a periodic or singular coroutine to be scheduled based on a time distance or a calendar-oriented schedule.

Timers do not survive bot restarts.

Timedict

The central data structure when scheduling a job coroutine is the timedict. For every time or calendar unit, it contains a list of elements. It is of the following form:

{
    "year": [int],
    "month": [int],
    "monthday": [int],
    "weekday": [int],
    "hour": [hour],
    "minute": [int]
}

Not every value has to be set. The empty dict specifies every single minute. Its granularity ends at minutely intervals. For example,

{
    "year": [2055, 2056],
    "monthday": [13],
    "weekday": [5]
}

specifies every Friday 13th in the years 2055 and 2056.

The Job object

When scheduling a job, the registering function returns a Job object. It has the following attributes and methods:

• Job.timedict is a copy of the timedict you passed to the registering function.
• Job.cancel() removes the job from the schedule, effectively cancelling it.
• Job.next_execution() returns a datetime.datetime object specifying the next execution of the job coroutine. Returns None if there is no future execution.
• Job.data is an opaque value guaranteed to never be overwritten. It can be used to store arbitrary information to be used by the coroutine.

Scheduling a job

bot.timers.schedule(coro, timedict, repeat=True) schedules the coroutine coro to be executed according to the specification in timedict. coro is expected to be a coroutine with the signature coro(job). It will be called with job being the Job object that led to its execution.

Helper functions

subsystems.timers.timedict(year=[int], month=[int], monthday=[int], weekday=[int], hour=[int], minute=[int]) returns a timedict with the values you passed to it.

Direct Messages (DMs)

The DM listener allows for listening to DMs from a specific user. It works very similar to the reaction listener.

Registering a DM listener

To register a DM listener, call python bot.dm_listener.register(user, coro, data=None, blocking=False). The arguments are as follows:

• user is the User whose DM channel you want to listen to.
• coro is the coroutine that is called when a DM is received. It is expected to have the signature coro(callback, message). callback is a Callback object (see below), message is a Message object.
• data is an omittable opaque object that is passed to the callback coroutine within the Callback object.
• blocking is a switch that allows you to register an exclusive listener. If this is set to True, no other DM listener can be registered on this user's DM channel until you free the channel. On the other hand, if a listener is already registered, this registration fails.

The method returns a Callback object that is used to identify the listener. In error cases, the following exceptions are raised:

• RuntimeError is raised if there already exists a blocking listener for this user's DMs.
• KeyError is raised if a blocking listener is to be registered but there already is a (blocking or non-blocking) listener for user.

Unregistering / freeing a DM listener

callback.unregister()