From d41a4fff9b75ad842df1b7f758899bd6843439be Mon Sep 17 00:00:00 2001 From: andrei Date: Mon, 2 Apr 2018 14:58:24 -0700 Subject: [PATCH] [docs] Update listeners docs --- docs/bot_tutorial/building_block_listeners.md | 99 +++++++++---------- 1 file changed, 48 insertions(+), 51 deletions(-) diff --git a/docs/bot_tutorial/building_block_listeners.md b/docs/bot_tutorial/building_block_listeners.md index 37f985c..3a664e5 100644 --- a/docs/bot_tutorial/building_block_listeners.md +++ b/docs/bot_tutorial/building_block_listeners.md @@ -1,51 +1,48 @@ -# Listeners -Listeners are a way to execute custom actions when a certain Discord event happens. For example, on message creation, when a member joins or leaves a guild, or when someone changes their username or nickname. - -## Listeners in disco -Listeners are easy to use and implement in Disco. First of all, we'll create a [Plugin](https://b1naryth1ef.github.io/disco/bot_tutorial/building_block_plugins.html) like so: -```py -class MyPlugin(Plugin): -``` -Now, inside this plugin, we'll create our first listener. A listener is built up following this syntax: -```py -@Plugin.listen('EventName') -def on_event_name(self, event): - # Do something with the event -``` -Change the `'EventName'` in the `.listen()` method to the event name you want to listen to, and give the `on_event_name` method a more descriptive name. - -This listener will listen for a new message and will reply with the exact same message every time. -```py -@Plugin.listen('MesageCreate') -def on_message_create(self, event): - event.reply(event.message.content) -``` -Let's create another listener, this time one that listens for a member that's added to the guild, when this happens, it will send a welcome message in a welcome channel: -```py -WELCOME_CHANNEL = 381890676654080001 - -@Plugin.listen('GuildMemberAdd') -def on_member_add(self, event): - self.bot.client.state.channels.get(WELCOME_CHANNEL).send_message( - 'Welcome to the server {}'.format(event.member.user.mention()) - ) -``` - -A list of all Discord events supported by disco can be found [here](https://b1naryth1ef.github.io/disco/api/disco_gateway_events.html) including event attributes and functions you can use on the event property. - -These are all the listeners we created in this tutorial: - -```py -class MyPlugin(Plugin): - @Plugin.listen('MesageCreate') - def on_message_create(self, event): - event.reply(event.message.content) - - WELCOME_CHANNEL = 381890676654080001 - - @Plugin.listen('GuildMemberAdd') - def on_member_add(self, event): - self.bot.client.state.channels.get(WELCOME_CHANNEL).send_message( - 'Welcome to the server {}'.format(event.member.user.mention()) - ) -``` +# Listeners + +Listeners provide an API to listen to and execute code upon the occurance of specified Discord events. + +## Listener Basics + +To start off with, lets create a listener attached to our plugin that fires whenever a message is created. + +```py +@Plugin.listen('MessageCreate') +def on_message_create(self, event): + self.log.debug('Got message: %s', event.message) +``` + +Ok, but what if we want to make a listener which welcomes new users to our server? Well thats also easy: + +```py +@Plugin.listen('GuildMemberAdd') +def on_guild_member_add(self, event): + self.state.channels.get(MY_WELCOME_CHANNEL_ID).send_message( + 'Hey there {}, welcome to the server!'.format(event.member.mention) + ) +``` + +## Listener Events + +To see all the events you can subscribe too, checkout the [gateway events list](https://b1naryth1ef.github.io/disco/api/disco_gateway_events.html). + +## Listener Priority + +Each listener thats registered comes with a priority. This priority describes how the builtin event emitter will distribute events to your listener. To set a priority you can simply pass the priority kwarg: + +```py +from holster.emitter import Priority + +@Plugin.listen('GuildMemberAdd', priority=Priority.BEFORE) +def on_guild_member_add(self, event): + # This would be very bad, don't do this... + time.sleep(10) +``` + +#### Priorities + +| Name | Description | +|------|-------------| +| BEFORE | Recieves all events sequentially alongside the emitter. This is the most dangerous priority level, as any executed code will block other events in the emitter from flowing. Blocking within a BEFORE handler can be lethal. | +| SEQUENTIAL | Recieves all events sequentially, but within a seperate greenlet. This priority level can be used for plugins that require sequential events but may block or take a long time to execute their event handler. | +| NONE | This priority provides no guarentees about the ordering of events. Similar to SEQUENTIAL all event handlers are called within a seperate greenlet. |