Plugins: Developer Overview

• What is a Plugin?
• Tutorials
  • Your first plugin
  • Playing with commands
  • Configuration and plugin setup
• Anatomy of a plugin
• Interact with the bot
  • Make it talk
  • Do it with style
  • Channels & users
• About time
• User privileges
• Callable decorators
• Automated tests
• Advanced Tips & Tricks

Plugin glossary

Action command

An action command is a Named rule that reacts to a name in a message sent with the ACTION CTCP command.

Command

A command is a Named rule that reacts to a Command prefix and a name.

Command prefix

The command prefix is a regular expression joined to a Command’s name as its prefix. It is defined by configuration using core.prefix.

Entry point plugin

A plugin that is an installed Python package and exposed through the sopel.plugins entry point group.

Find rule

A find rule is a Generic rule that triggers for every time the regex matches a part of the message.

Folder plugin

A plugin composed of a directory that contains a __init__.py file. It is not considered as a proper Python package unless its parent directory is in sys.path. As they can create problems, they are not recommended, and either Single file plugin or Entry point plugin should be used instead.

Generic rule

A generic rule matches any message using a regular expression. It doesn’t use any specific format, unlike a Named rule. It can match the whole message (Match rule), or any part of it (Search rule), or it may trigger for every match in the message (Find rule).

Match rule

A match rule is a Generic rule that triggers when the regex matches the whole message.

Named rule

A named rule is a rule that uses a regular expression with a specific format: with a name, and usually with a prefix, or a set of specific conditions. See Command, Action command, and Nick command. A named rule always matches the message from its start, and it accepts any number of arguments:

[nick] <prefix><name> [<arg1> <arg2> <...> <argN>]

A named rule can have aliases, i.e. alternative names used to trigger the rule.

Namespace package plugin

A plugin that is a Python namespace package, i.e. a package within a specific namespace (sopel_modules.<name>, where sopel_modules is the namespace, and <name> is the plugin’s name). This is the old way to distribute plugins and is not recommended; Entry point plugin should be used instead.

Nick command

A nick command (or nickname command) is a Named rule that reacts to a name prefixed by the bot’s nickname in a message.

Plugin callable

A plugin callable is a Python callable, that handles a specific message from the IRC server matching a Rule. See also the Plugin Anatomy: callables section for the plugin callable signature.

Plugin job

A plugin job is a Python callable, that executes periodically on a schedule. See also the Plugin Anatomy: jobs section for the plugin job signature.

Rate limiting

How often a rule can be triggered on a per-user basis, in a channel, or across the IRC network.

Rule

A rule defines how to match a specific message from the IRC server, usually with a regular expression. It also defines how to react to these messages. For that it can execute a callable.

Rule system

The rule system is how Sopel manages and handles rules.

Search rule

A search rule is a Generic rule that triggers when the regex matches any part of the message.

Single file plugin

A Sopel plugin composed of a single Python file. Can be loaded by Sopel even when it’s not available from sys.path.

Sopel plugin

A Sopel plugin is a plugin made for Sopel. It contains rules, it has a setup/shutdown cycle, and it can extend the bot’s configuration with its own section.

It is of one of the possible plugin types, preferably a Single file plugin, or an Entry point plugin. The other two types are Folder plugin and Namespace package plugin.

Sopelunker

A person who does Sopelunking.

Sopelunking

Action performed by a Sopelunker.

URL callback

A URL callback is a rule that triggers for every URL in a message.