Plugin structure

A Sopel plugin consists of a Python module containing one or more callables. It may optionally also contain configure, setup, and shutdown hooks.

callable(bot, trigger)

A callable is any function which takes as its arguments a sopel.bot.Sopel object and a sopel.trigger.Trigger object, and is wrapped with appropriate decorators from sopel.module. The bot provides the ability to send messages to the network and check the state of the bot. The trigger provides information about the line which triggered this function to be called.

The return value of these function is ignored, unless it is sopel.module.NOLIMIT, in which case rate limiting will not be applied for that call.

Note that the name can, and should, be anything - it doesn’t need to be called “callable”.

setup(bot)

This is an optional function of a plugin, which will be called while the module is being loaded. The purpose of this function is to perform whatever actions are needed to allow a module to function properly (e.g, ensuring that the appropriate configuration variables exist and are set). Note that this normally occurs prior to connection to the server, so the behavior of the messaging functions on the sopel.bot.Sopel object it’s passed is undefined.

Throwing an exception from this function (such as a sopel.config.ConfigurationError) will prevent any callables in the module from being registered, and provide an error message to the user. This is useful when requiring the presence of configuration values or making other environmental requirements.

The bot will not continue loading modules or connecting during the execution of this function. As such, an infinite loop (such as an unthreaded polling loop) will cause the bot to hang.

shutdown(bot)

This is an optional function of a module, which will be called while the bot is quitting. Note that this normally occurs after closing connection to the server, so the behavior of the messaging functions on the sopel.bot.Sopel object it’s passed is undefined. The purpose of this function is to perform whatever actions are needed to allow a module to properly clean up (e.g, ensuring that any temporary cache files are deleted).

The bot will not continue notifying other modules or continue quitting during the execution of this function. As such, an infinite loop (such as an unthreaded polling loop) will cause the bot to hang.

New in version 4.1.

configure(config)

This is an optional function of a module, which will be called during the user’s setup of the bot. It’s intended purpose is to use the methods of the passed sopel.config.Config object in order to create the configuration variables it needs to function properly.

New in version 3.0.

sopel.module

This contains decorators and tools for creating callable plugin functions.

sopel.module.NOLIMIT = 1

Return value for callables, which supresses rate limiting for the call.

Returning this value means the triggering user will not be prevented from triggering the command again within the rate limit. This can be used, for example, to allow a user to rety a failed command immediately.

New in version 4.0.

sopel.module.commands(*command_list)

Decorate a function to set one or more commands to trigger it.

This decorator can be used to add multiple commands to one callable in a single line. The resulting match object will have the command as the first group, rest of the line, excluding leading whitespace, as the second group. Parameters 1 through 4, seperated by whitespace, will be groups 3-6.

Args:
command: A string, which can be a regular expression.
Returns:
A function with a new command appended to the commands attribute. If there is no commands attribute, it is added.
Example:
@commands(“hello”):
If the command prefix is ”.”, this would trigger on lines starting with ”.hello”.
@commands(‘j’, ‘join’)
If the command prefix is ”.”, this would trigger on lines starting with either ”.j” or ”.join”.
sopel.module.event(*event_list)

Decorate a function to be triggered on specific IRC events.

This is one of a number of events, such as ‘JOIN’, ‘PART’, ‘QUIT’, etc. (More details can be found in RFC 1459.) When the Sopel bot is sent one of these events, the function will execute. Note that functions with an event must also be given a rule to match (though it may be ‘.*’, which will always match) or they will not be triggered.

sopel.tools.events provides human-readable names for many of the numeric events, which may help your code be clearer.

class sopel.module.example(msg, result=None, privmsg=False, admin=False, owner=False, repeat=1, re=False, ignore=None)

Decorate a function with an example.

Add an example attribute into a function and generate a test.

sopel.module.intent(*intent_list)

Decorate a callable trigger on a message with any of the given intents.

New in version 5.2.0.

sopel.module.interval(*args)

Decorates a function to be called by the bot every X seconds.

This decorator can be used multiple times for multiple intervals, or all intervals can be given at once as arguments. The first time the function will be called is X seconds after the bot was started.

Unlike other plugin functions, ones decorated by interval must only take a sopel.bot.Sopel as their argument; they do not get a trigger. The bot argument will not have a context, so functions like bot.say() will not have a default destination.

There is no guarantee that the bot is connected to a server or joined a channel when the function is called, so care must be taken.

Example::

import sopel.module
@sopel.module.interval(5)
def spam_every_5s(bot):
    if "#here" in bot.channels:
        bot.msg("#here", "It has been five seconds!")
sopel.module.nickname_commands(*command_list)

Decorate a function to trigger on lines starting with “$nickname: command”.

This decorator can be used multiple times to add multiple rules. The resulting match object will have the command as the first group, rest of the line, excluding leading whitespace, as the second group. Parameters 1 through 4, seperated by whitespace, will be groups 3-6.

Args:
command: A string, which can be a regular expression.
Returns:
A function with a new regular expression appended to the rule attribute. If there is no rule attribute, it is added.
Example:
@nickname_commands(“hello!”):
Would trigger on “$nickname: hello!”, “$nickname, hello!”, “$nickname hello!”, “$nickname hello! parameter1” and “$nickname hello! p1 p2 p3 p4 p5 p6 p7 p8 p9”.
@nickname_commands(”.*”):
Would trigger on anything starting with “$nickname[:,]? ”, and would have never have any additional parameters, as the command would match the rest of the line.
sopel.module.priority(value)

Decorate a function to be executed with higher or lower priority.

Args:
value: Priority can be one of “high”, “medium”, “low”. Defaults to
medium.

Priority allows you to control the order of callable execution, if your module needs it.

sopel.module.rate(user=0, channel=0, server=0)

Decorate a function to limit how often it can be triggered on a per-user basis, in a channel, or across the server (bot). A value of zero means no limit. If a function is given a rate of 20, that function may only be used once every 20 seconds in the scope corresponding to the parameter. Users on the admin list in Sopel’s configuration are exempted from rate limits.

Rate-limited functions that use scheduled future commands should import threading.Timer() instead of sched, or rate limiting will not work properly.

sopel.module.require_admin(message=None)

Decorate a function to require the triggering user to be a bot admin.

If they are not, message will be said if given.

sopel.module.require_chanmsg(message=None)

Decorate a function to only be triggerable from a channel message.

If it is triggered in a private message, message will be said if given.

sopel.module.require_owner(message=None)

Decorate a function to require the triggering user to be the bot owner.

If they are not, message will be said if given.

sopel.module.require_privilege(level, message=None)

Decorate a function to require at least the given channel permission.

level can be one of the privilege levels defined in this module. If the user does not have the privilege, message will be said if given. If it is a private message, no checking will be done.

sopel.module.require_privmsg(message=None)

Decorate a function to only be triggerable from a private message.

If it is triggered in a channel message, message will be said if given.

sopel.module.rule(value)

Decorate a function to be called when a line matches the given pattern

This decorator can be used multiple times to add more rules.

Args:
value: A regular expression which will trigger the function.

If the Sopel instance is in a channel, or sent a PRIVMSG, where a string matching this expression is said, the function will execute. Note that captured groups here will be retrievable through the Trigger object later.

Inside the regular expression, some special directives can be used. $nick will be replaced with the nick of the bot and , or :, and $nickname will be replaced with the nick of the bot.

sopel.module.thread(value)

Decorate a function to specify if it should be run in a separate thread.

Functions run in a separate thread (as is the default) will not prevent the bot from executing other functions at the same time. Functions not run in a separate thread may be started while other functions are still running, but additional functions will not start until it is completed.

Args:
value: Either True or False. If True the function is called in
a separate thread. If False from the main thread.
sopel.module.unblockable(function)

Decorator which exempts the function from nickname and hostname blocking.

This can be used to ensure events such as JOIN are always recorded.

sopel.module.url(url_rule)

Decorate a function to handle URLs.

This decorator takes a regex string that will be matched against URLs in a message. The function it decorates, in addition to the bot and trigger, must take a third argument match, which is the regular expression match of the url. This should be used rather than the matching in trigger, in order to support e.g. the .title command.