sopel.plugins#

Sopel’s plugins interface.

New in version 7.0.

Sopel uses what are called Plugin Handlers as an interface between the bot and its plugins (formerly called “modules”). 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
sopel.plugins entry point group
sopel_modules’s subpackages
sopel.builtins’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:

find_internal_plugins() for internal plugins
find_sopel_modules_plugins() for sopel_modules.* plugins
find_entry_point_plugins() for plugins exposed via packages’ entry points
find_directory_plugins() for plugins in $homedir/plugins, and in extra directories as defined by settings.core.extra

Changed in version 8.0: Looks in $homedir/plugins instead of the $homedir/modules directory, reflecting Sopel’s shift away from calling them “modules”.

sopel.plugins.find_directory_plugins(directory)#

List plugins from a directory.

Parameters:: directory (str) – directory path to search
Returns:: yield instances of PyFilePlugin found in directory

This function looks for single file and folder plugins in a directory.

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

List plugins from an entry point group.

Parameters:: group (str) – entry point group to search in (defaults to sopel.plugins)
Returns:: yield instances of EntryPointPlugin created from each entry point in the group

This function finds plugins declared under an entry point group; by default it looks in the sopel.plugins group.

sopel.plugins.find_internal_plugins()#

List internal plugins.

Returns:: yield instances of PyModulePlugin configured for sopel.builtins.*

Internal plugins can be found under sopel.builtins. This list does not include the coretasks plugin.

sopel.plugins.find_sopel_modules_plugins()#

List plugins from sopel_modules.*.

Returns:: yield instances of PyModulePlugin configured for sopel_modules.*

Before entry point plugins, the only way to package a plugin was to follow PEP 382 by using the sopel_modules namespace. This function is responsible to load such plugins.

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 plugins directory
sopel.plugins entry point group
sopel_modules’s subpackages
sopel.builtins’s core plugins

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