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)
Parameters

A callable is any function which takes as its arguments a sopel.bot.SopelWrapper 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)
Parameters

bot (sopel.bot.Sopel) – the bot’s instance

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)
Parameters

bot (sopel.bot.Sopel) – the bot’s instance

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)
Parameters

bot (sopel.config.Config) – the bot’s configuration object

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 other tools for creating Sopel plugins.

sopel.module.ADMIN = 8

Privilege level for the +a channel permission

New in version 4.1.

sopel.module.HALFOP = 2

Privilege level for the +h channel permission

New in version 4.1.

sopel.module.NOLIMIT = 1

Return value for callables, which suppresses rate limiting.

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

New in version 4.0.

sopel.module.OP = 4

Privilege level for the +o channel permission

New in version 4.1.

sopel.module.OPER = 32

Privilege level for the +y/+Y channel permissions

Note: Except for these (non-standard) channel modes, Sopel does not monitor or store any user’s OPER status.

New in version 7.0.0.

sopel.module.OWNER = 16

Privilege level for the +q channel permission

New in version 4.1.

sopel.module.VOICE = 1

Privilege level for the +v channel permission

New in version 4.1.

sopel.module.action_commands(*command_list)

Decorate a function to trigger on CTCP ACTION lines.

Parameters

command_list (str) – one or more command name(s) to match (can be regular expressions)

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; the rest of the line, excluding leading whitespace, as the second group; and parameters 1 through 4, separated by whitespace, as groups 3-6.

Example:

@action_commands("hello!")
    # Would trigger on "/me hello!"

New in version 7.0.

Important

This decorator will prevent the other command types from working on the same callable. Normally only one command type is used per function, but if you need to trigger the same command with e.g. both action and nickname commands, use a main function called from decorated wrappers.

Hopefully, a future version of Sopel will remove this limitation.

sopel.module.commands(*command_list)

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

Parameters

command_list (str) – one or more command name(s) to match (can be regular expressions)

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; the rest of the line, excluding leading whitespace, as the second group; and parameters 1 through 4, separated by whitespace, as groups 3-6.

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.echo(function=None)

Decorate a function to specify that it should receive echo messages.

This decorator can be used to listen in on the messages that Sopel is sending and react accordingly.

sopel.module.event(*event_list)

Decorate a function to be triggered on specific IRC events.

Parameters

event_list (str) – one or more event name(s) on which to trigger

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 the default rule() (.*) will match any line of the correct event type(s). If any rule is explicitly specified, it overrides the default.

See also

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, user_help=False, online=False)

Decorate a function with an example, and optionally test output.

Parameters
  • msg (str) – the example command (required; see below)

  • result (str) – the command’s expected output (optional; see below)

  • privmsg (bool) – if True, the example will be tested as if it was received in a private message to the bot; otherwise, in a channel (optional; default False)

  • admin (bool) – whether to treat the test message as having come from a bot admin (optional; default False)

  • owner (bool) – whether to treat the test message as having come from the bot’s owner (optional; default False)

  • repeat (int) – how many times to repeat the test; useful for commands that return random results (optional; default 1)

  • re (bool) – if True, the result is interpreted as a regular expression and used to match the command’s output (optional; see below)

  • ignore (list) – list of regular expression patterns to match ignored output (optional; see below)

  • user_help (bool) – whether this example should be included in user-facing help output such as .help command (optional; default False; see below)

  • online (bool) – if True, pytest will mark this example as “online” (optional; default False; see below)

For compatibility with the built-in help plugin, msg must use the default help_prefix if it is a prefixed command. Other command types should give example invocations that work with Sopel’s default settings, especially if using the “example test” functionality to automatically generate a test(s) for the function.

The presence of a result will generate tests automatically when Sopel’s test suite is run, using msg as input. The exact behavior of the tests depends on the remaining optional example arguments.

Passing re=True, in particular, is useful for matching results that are random and/or dependent on an external API. This way, an example test can check the format of the result without caring about the exact data.

Giving a list of ignore``d patterns is helpful for commands that may return intermittent errors (mostly calls to an external API that isn't necessarily stable), especially when coupled with the ``repeat parameter.

By default, Sopel’s help plugin will display only one example (the one closest to the function’s def statement, due to how decorators work). You can override this choice or include multiple examples by passing user_help=True to one or more example decorator(s).

Finally, passing online=True makes that particular example skippable if Sopel’s test suite is run in offline mode, which is mostly useful to make life easier for other developers working on Sopel without Internet access.

sopel.module.intent(*intent_list)

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

Parameters

intent_list (str) – one or more intent(s) on which to trigger (really, the only useful value is action)

New in version 5.2.0.

Note

This system will be replaced and marked deprecated in or before Sopel 8.0, then removed in Sopel 9.0, as the IRCv3 spec for intents is dead.

sopel.module.interval(*intervals)

Decorate a function to be called by the bot every n seconds.

Parameters

intervals (int) – one or more duration(s), in seconds

This decorator can be used multiple times for multiple intervals, or multiple intervals can be given in multiple arguments. The first time the function will be called is n seconds after the bot was started.

Plugin functions decorated by interval must only take bot 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 in any channels when the function is called, so care must be taken.

Example:

from sopel import module

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

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

Parameters

command_list (str) – one or more command name(s) to match (can be regular expressions)

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; the rest of the line, excluding leading whitespace, as the second group; and parameters 1 through 4, separated by whitespace, as groups 3-6.

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 never have any additional parameters, as the
    # command would match the rest of the line.
sopel.module.output_prefix(prefix)

Decorate a function to add a prefix on its output.

Parameters

prefix (str) – the prefix to add (must include trailing whitespace if desired; Sopel does not assume it should add anything)

Prefix will be added to text sent through:

sopel.module.priority(value)

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

Parameters

value (str) – one of high, medium, or low; defaults to medium

The priority allows you to control the order of callable execution, if your plugin needs it.

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

Decorate a function to be rate-limited.

Parameters
  • user (int) – seconds between permitted calls of this function by the same user

  • channel (int) – seconds between permitted calls of this function in the same channel, regardless of triggering user

  • server (int) – seconds between permitted calls of this function no matter who triggered it or where

How often a function can be triggered on a per-user basis, in a channel, or across the server (bot) can be controlled with this decorator. A value of 0 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_account(message=None, reply=False)

Decorate a function to require services/NickServ authentication.

Parameters
  • message (str) – optional message to say if a user without authentication tries to trigger this function

  • reply (bool) – use reply() instead of say() when True; defaults to False

New in version 7.0.

Note

Only some networks support services authentication, and not all of those implement the standards required for clients like Sopel to determine authentication status. This decorator will block all use of functions it decorates on networks that lack the relevant features.

See also

The value of the trigger’s account property determines whether this requirement is satisfied, and the property’s documentation includes up-to-date details on what features a network must support to allow Sopel to fetch account information.

sopel.module.require_admin(message=None, reply=False)

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

Parameters
  • message (str) – optional message said to non-admin user

  • reply (bool) – use reply() instead of say() when True; defaults to False

When the triggering user is not an admin, the command is not run, and the bot will say the message if given. By default, it uses bot.say(), but when reply is true, then it uses bot.reply() instead.

Changed in version 7.0: Added the reply parameter.

sopel.module.require_chanmsg(message=None, reply=False)

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

Parameters
  • message (str) – optional message said if triggered in private message

  • reply (bool) – use reply() instead of say() when True; defaults to False

If the decorated function is triggered by a private message, message will be said if given. By default, it uses bot.say(), but when reply is true, then it uses bot.reply() instead.

Changed in version 7.0: Added the reply parameter.

sopel.module.require_owner(message=None, reply=False)

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

Parameters
  • message (str) – optional message said to non-owner user

  • reply (bool) – use reply() instead of say() when True; defaults to False

When the triggering user is not the bot’s owner, the command is not run, and the bot will say message if given. By default, it uses bot.say(), but when reply is true, then it uses bot.reply() instead.

Changed in version 7.0: Added the reply parameter.

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

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

Parameters
  • level (int) – required privilege level to use this command

  • message (str) – optional message said to insufficiently privileged user

  • reply (bool) – use reply() instead of say() when True; defaults to False

level can be one of the privilege level constants defined in this module. If the user does not have the privilege, the bot will say message if given. By default, it uses bot.say(), but when reply is true, then it uses bot.reply() instead.

Privilege requirements are ignored in private messages.

Changed in version 7.0: Added the reply parameter.

sopel.module.require_privmsg(message=None, reply=False)

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

Parameters
  • message (str) – optional message said if triggered in a channel

  • reply (bool) – use reply() instead of say() when True; defaults to False

If the decorated function is triggered by a channel message, message will be said if given. By default, it uses bot.say(), but when reply is true, then it uses bot.reply() instead.

Changed in version 7.0: Added the reply parameter.

sopel.module.rule(*patterns)

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

Parameters

patterns (str) – one or more regular expression(s)

Each argument is a regular expression which will trigger the function.

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

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.

Changed in version 7.0: The rule() decorator can be called with multiple positional arguments, each used to add a rule. This is equivalent to decorating the same function multiple times with this decorator.

Note

A regex rule can match only once per line. A future version of Sopel will (hopefully) remove this limitation.

Note

The regex match must start at the beginning of the line. To match anywhere in a line, surround the actual pattern with .*. A future version of Sopel may remove this requirement.

sopel.module.thread(value)

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

Parameters

value (bool) – if True, the function is called in a separate thread; otherwise, from the bot’s main 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.

sopel.module.unblockable(function)

Decorate a function to exempt it from the ignore/blocks system.

For example, this can be used to ensure that important events such as JOIN are always recorded:

from sopel import module

@module.event('JOIN')
@module.unblockable
def on_join_callable(bot, trigger):
    # do something when a user JOIN a channel
    # a blocked nickname or hostname *will* trigger this
    pass

See also

Sopel’s dispatch() and get_triggered_callables() methods.

sopel.module.url(*url_rules)

Decorate a function to handle URLs.

Parameters

url_rules (str) – one or more regex pattern(s) to match 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:

from sopel import module

@module.url(r'https://example.com/bugs/([a-z0-9]+)')
@module.url(r'https://short.com/([a-z0-9]+)')
def handle_example_bugs(bot, trigger, match):
    bot.reply('Found bug ID #%s' % match.group(1))

This should be used rather than the matching in trigger, in order to support e.g. the .title command.

Under the hood, when Sopel collects the decorated handler it uses sopel.bot.Sopel.register_url_callback() to register the handler.

Changed in version 7.0: The same function can be decorated multiple times with url() to register different URL patterns.

Changed in version 7.0: More than one pattern can be provided as positional argument at once.

See also

To detect URLs, Sopel uses a matching pattern built from a list of URL schemes, configured by auto_url_schemes.

sopel.plugins

Sopel’s plugins interface

New in version 7.0.

Sopel uses plugins (also called “modules”) and uses what are called Plugin Handlers as an interface between the bot and its plugins. This interface is defined by the AbstractPluginHandler abstract class.

Plugins that can be used by Sopel are provided by get_usable_plugins() in an ordered dict. This dict contains one and only one plugin per unique name, using a specific order:

  • extra directories defined in the settings

  • homedir’s plugins directory

  • homedir’s modules directory

  • sopel.plugins setuptools entry points

  • sopel_modules’s subpackages

  • sopel.modules’s core plugins

(The coretasks plugin is always the one from sopel.coretasks and cannot be overridden.)

To find all plugins (no matter their sources), the enumerate_plugins() function can be used. For a more fine-grained search, find_* functions exist for each type of plugin.

sopel.plugins.enumerate_plugins(settings)

Yield Sopel’s plugins

Parameters

settings (sopel.config.Config) – Sopel’s configuration

Returns

yield 2-value tuple: an instance of AbstractPluginHandler, and if the plugin is active or not

This function uses the find functions to find all of Sopel’s available plugins. It uses the bot’s settings to determine if the plugin is enabled or disabled.

See also

The find functions used are:

Changed in version 7.0: Previously, plugins were called “modules”, so this would load plugins from the $homedir/modules directory. Now it also loads plugins from the $homedir/plugins directory.

sopel.plugins.find_directory_plugins(directory)

List plugins from a directory

Parameters

directory (str) – Directory path to search

Returns

Yield instance of PyFilePlugin found in directory

sopel.plugins.find_entry_point_plugins(group='sopel.plugins')

List plugins from a setuptools entry point group

Parameters

group (str) – setuptools entry point group to look for (defaults to sopel.plugins)

Returns

Yield instance of EntryPointPlugin created from setuptools entry point given group

sopel.plugins.find_internal_plugins()

List internal plugins

Returns

Yield instance of PyModulePlugin configured for sopel.modules.*

sopel.plugins.find_sopel_modules_plugins()

List plugins from sopel_modules.*

Returns

Yield instance of PyModulePlugin configured for sopel_modules.*

sopel.plugins.get_usable_plugins(settings)

Get usable plugins, unique per name

Parameters

settings (sopel.config.Config) – Sopel’s configuration

Returns

an ordered dict of usable plugins

Return type

collections.OrderedDict

This function provides the plugins Sopel can use to load, enable, or disable, as an ordered dict. This dict contains one and only one plugin per unique name, using a specific order:

  • extra directories defined in the settings

  • homedir’s modules directory

  • sopel.plugins setuptools entry points

  • sopel_modules’s subpackages

  • sopel.modules’s core plugins

(The coretasks plugin is always the one from sopel.coretasks and cannot be overridden.)

See also

The enumerate_plugins() function is used to generate a list of all possible plugins, and its return value is used to populate the ordered dict.

sopel.plugins.handlers

Sopel’s plugin handlers

New in version 7.0.

Between a plugin (or “module”) and Sopel’s core, Plugin Handlers are used. It is an interface (defined by the AbstractPluginHandler abstract class), that acts as a proxy between Sopel and the plugin, making a clear separation between how the bot behaves and how the plugins work.

From the Sopel class, a plugin must be:

Each subclass of AbstractPluginHandler must implement its methods in order to be used in the application.

At the moment, only two types of plugin are handled:

  • PyModulePlugin: manage plugins that can be imported as Python module from a Python package, i.e. where from package import name works

  • PyFilePlugin: manage plugins that are Python files on the filesystem or Python directory (with an __init__.py file inside), that cannot be directly imported and extra steps are necessary

Both expose the same interface and thereby abstract the internal implementation away from the rest of the application.

class sopel.plugins.handlers.AbstractPluginHandler

Base class for plugin handlers.

This abstract class defines the interface Sopel uses to configure, load, shutdown, etc. a Sopel plugin (or “module”).

It is through this interface that Sopel will interact with its plugins, whether internal (from sopel.modules) or external (from the Python files in a directory, to sopel_modules.* subpackages).

Sopel’s loader will create a “Plugin Handler” for each plugin it finds, to which it then delegates loading the plugin, listing its functions (commands, jobs, etc.), configuring it, and running any required actions on shutdown (either upon exiting Sopel or unloading that plugin).

configure(settings)

Configure Sopel’s settings for this plugin

Parameters

settings (sopel.config.Config) – Sopel’s configuration

This method will be called by Sopel’s configuration wizard.

get_label()

Retrieve a display label for the plugin

Returns

A human readable label for display purpose

Return type

str

This method should, at least, return module_name + S + "module".

get_meta_description()

Retrieve a meta description for the plugin

Returns

meta description information

Return type

dict

The expected keys are:

  • name: a short name for the plugin

  • label: a descriptive label for the plugin

  • type: the plugin’s type

  • source: the plugin’s source (filesystem path, python import path, etc.)

has_configure()

Tell if the plugin has a configure action

Returns

True if the plugin has a configure action, False otherwise

Return type

bool

has_setup()

Tell if the plugin has a setup action

Returns

True if the plugin has a setup, False otherwise

Return type

bool

has_shutdown()

Tell if the plugin has a shutdown action

Returns

True if the plugin has a shutdown action, False otherwise

Return type

bool

is_loaded()

Tell if the plugin is loaded or not

Returns

True if the plugin is loaded, False otherwise

Return type

bool

This must return True if the load() method has been called with success.

load()

Load the plugin

This method must be called first, in order to setup, register, shutdown, or configure the plugin later.

register(bot)

Register the plugin with the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

reload()

Reload the plugin

This method can be called once the plugin is already loaded. It will take care of reloading the plugin from its source.

setup(bot)

Setup the plugin with the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

shutdown(bot)

Take action on bot’s shutdown

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

unregister(bot)

Unregister the plugin from the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

class sopel.plugins.handlers.EntryPointPlugin(entry_point)

Sopel plugin loaded from a setuptools entry point

Parameters

entry_point – a setuptools entry point object

This handler loads a Sopel plugin exposed by a setuptools entry point. It expects to be able to load a module object from the entry point, and to work as a PyModulePlugin from that module.

By default, Sopel uses the entry point sopel.plugins. To use that for their plugin, developers must define an entry point either in their setup.py file or their setup.cfg file:

# in setup.py file
setup(
    name='my_plugin',
    version='1.0',
    entry_points={
        'sopel.plugins': [
            'custom = my_plugin.path.to.plugin',
        ],
    }
)

And this plugin can be loaded with:

>>> from pkg_resources import iter_entry_points
>>> from sopel.plugins.handlers import EntryPointPlugin
>>> plugin = [
...     EntryPointPlugin(ep)
...     for ep in iter_entry_points('sopel.plugins', 'custom')
... ][0]
>>> plugin.load()
>>> plugin.name
'custom'

In this example, the plugin custom is loaded from an entry point. Unlike the PyModulePlugin, the name is not derived from the actual python module, but from its entry point’s name.

See also

Sopel uses the find_entry_point_plugins() function internally to search entry points.

Entry point is a standard feature of setuptools for Python, used by other applications (like pytest) for their plugins.

get_meta_description()

Retrieve a meta description for the plugin

Returns

meta description information

Return type

dict

The expected keys are:

  • name: a short name for the plugin

  • label: a descriptive label for the plugin

  • type: the plugin’s type

  • source: the plugin’s source (filesystem path, python import path, etc.)

load()

Load the plugin

This method must be called first, in order to setup, register, shutdown, or configure the plugin later.

class sopel.plugins.handlers.PyFilePlugin(filename)

Sopel plugin loaded from the filesystem outside of the Python path

This plugin handler can be used to load a Sopel plugin from the filesystem, either a Python .py file or a directory containing an __init__.py file, and behaves like a PyModulePlugin:

>>> from sopel.plugins.handlers import PyFilePlugin
>>> plugin = PyFilePlugin('/home/sopel/.sopel/modules/custom.py')
>>> plugin.load()
>>> plugin.name
'custom'

In this example, the plugin custom is loaded from its filename despite not being in the Python path.

get_meta_description()

Retrieve a meta description for the plugin

Returns

meta description information

Return type

dict

The expected keys are:

  • name: a short name for the plugin

  • label: a descriptive label for the plugin

  • type: the plugin’s type

  • source: the plugin’s source (filesystem path, python import path, etc.)

load()

Load the plugin

This method must be called first, in order to setup, register, shutdown, or configure the plugin later.

reload()

Reload the plugin

Unlike PyModulePlugin, it is not possible to use the reload function (either from imp or importlib), because the module might not be available through sys.path.

class sopel.plugins.handlers.PyModulePlugin(name, package=None)

Sopel plugin loaded from a Python module or package

A PyModulePlugin represents a Sopel plugin that is a Python module (or package) that can be imported directly.

This:

>>> import sys
>>> from sopel.plugins.handlers import PyModulePlugin
>>> plugin = PyModulePlugin('xkcd', 'sopel.modules')
>>> plugin.module_name
'sopel.modules.xkcd'
>>> plugin.load()
>>> plugin.module_name in sys.modules
True

Is the same as this:

>>> import sys
>>> from sopel.modules import xkcd
>>> 'sopel.modules.xkcd' in sys.modules
True
configure(settings)

Configure Sopel’s settings for this plugin

Parameters

settings (sopel.config.Config) – Sopel’s configuration

This method will be called by Sopel’s configuration wizard.

get_label()

Retrieve a display label for the plugin

Returns

A human readable label for display purpose

Return type

str

This method should, at least, return module_name + S + "module".

get_meta_description()

Retrieve a meta description for the plugin

Returns

meta description information

Return type

dict

The expected keys are:

  • name: a short name for the plugin

  • label: a descriptive label for the plugin

  • type: the plugin’s type

  • source: the plugin’s source (filesystem path, python import path, etc.)

has_configure()

Tell if the plugin has a configure action

Returns

True if the plugin has a configure action, False otherwise

Return type

bool

has_setup()

Tell if the plugin has a setup action

Returns

True if the plugin has a setup, False otherwise

Return type

bool

has_shutdown()

Tell if the plugin has a shutdown action

Returns

True if the plugin has a shutdown action, False otherwise

Return type

bool

is_loaded()

Tell if the plugin is loaded or not

Returns

True if the plugin is loaded, False otherwise

Return type

bool

This must return True if the load() method has been called with success.

load()

Load the plugin

This method must be called first, in order to setup, register, shutdown, or configure the plugin later.

register(bot)

Register the plugin with the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

reload()

Reload the plugin

This method can be called once the plugin is already loaded. It will take care of reloading the plugin from its source.

setup(bot)

Setup the plugin with the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

shutdown(bot)

Take action on bot’s shutdown

Parameters

bot (sopel.bot.Sopel) – instance of Sopel

unregister(bot)

Unregister the plugin from the bot

Parameters

bot (sopel.bot.Sopel) – instance of Sopel