Event Hooks¶

The Lazbot framework handles the inter workings of connecting to and streaming the events from the Slack servers. In order to connect to the event stream that the framework manages, you have to register event hooks with the main bot instance. The bot has a number of event hooks that work with either the internal event sequence or from the slack event stream.

General Style¶

For all slack event hooks, the decorator will take a channel keyword argument that will define a whitelist for which channels the event will be triggered from.

Messages¶

The main event hook you will be using is the chat message hook. This is the bot.listen decorator and provides some powerful parsing and filtering to control the scope in which the actions of the hook are triggered. The only required argument for the decoration is a filter string. The filter string can be a literal string that will be matched against, a literal "*" that will match all strings, or a regex string. If using a regex string, you must also set the regex flag to True.

Advanced Regex¶

The regex variant of the filter strings uses the built in re module to compile the string into a regex object and match against it. It will attempt to extract the matched groups in the provided string.

Also provided are a number of built in custom groups and parsers in the Filter class. The syntax for them is like the flask style: <username:them>. This will then provide a User object under the them keyword in the event call. The names for these should not collide with the already passed in arguments used (or they will define over them).

To see the various provided types, see the Filter documentation. If you want to add your own, you just need to:

from lazbot import Filter
from datetime import time

Filter.translations["time"] = {
   "regex": "[0-9]{1,2}:[0-5][0-9]",
   "handler: lambda _, s: time(*map(int, s.split(':')))
}

This would let you add a <time:when> regex and it will return a rich datetime.time object (rather than a string).

Setup¶

If you want to perform actions after the bot has connected to Slack, you can use the setup decorator. This registers the decorated function to be called after the bot has connected to slack. It will provide the initial rtm.start response and the internal slacker object as arguments.

Scheduled Tasks¶

There is a built in scheduling system for creating time delayed actions either once or on a recurring schedule. The decorator for this can also be called as a regular function. The scheduling can use either a relative timedelta object with the after keyword or use an absolute value with the when keyword. If the recurring flag is set to true, the creator will attempt to extrapolate the interval in which to call the task again until the end of the execution or it is called to be stopped. The decorated function is actually a rich Scheduled Tasks object with various methods to control the execution of the task.

Generic Events¶

There is a generic on decorator that will trigger on the defined events in the decorator. This can be any of the events defined in the Slack RTM documentation.

Navigation