Skip to content

Commit

Permalink
docs: add some more info about allow_bots, echo, and unblockable
Browse files Browse the repository at this point in the history
These didn't get any brief mention on the "Anatomy of a plugin" page,
like most of their siblings already had. It seemed only fair.

Also added a gotcha to the `echo` decorator's docs.
  • Loading branch information
dgw committed Jan 27, 2022
1 parent 2f27ab4 commit 82129c2
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 0 deletions.
26 changes: 26 additions & 0 deletions docs/source/plugin/anatomy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,32 @@ Example::
A rule with rate-limiting can return :const:`sopel.plugin.NOLIMIT` to let the
user try again after a failed command, e.g. if a required argument is missing.

Bypassing restrictions
----------------------

By default, a :term:`Rule` will not trigger on messages from Sopel itself,
other users that are flagged as bots, or users who are
:ref:`ignored <Ignore User>` or :ref:`rate-limited <Rate limiting>`. In
certain cases, it might be desirable to bypass these defaults using one or
more of these decorators:

* :func:`~sopel.plugin.allow_bots`: the rule will receive events from other
users flagged as bots (like Sopel itself)
* :func:`~sopel.plugin.echo`: the rule will receive Sopel's own actions (e.g.
the output of any calls to :func:`bot.say <sopel.bot.Sopel.say>`)
* :func:`~sopel.plugin.unblockable`: the rule will ignore rate-limiting or
nick/host blocks and always process the event

For example, Sopel itself uses the :func:`~sopel.plugin.unblockable` decorator
to track joins/parts from everyone, always, so plugins can *always* access
data about any user in any channel.

.. important::

The :func:`~sopel.plugin.echo` decorator will send *anything* Sopel says
(that matches the rule) to the decorated callable, *including output from
the callable itself*. Be careful not to create a feedback loop.

Rule labels
-----------

Expand Down
7 changes: 7 additions & 0 deletions sopel/plugin.py
Original file line number Diff line number Diff line change
Expand Up @@ -493,6 +493,13 @@ def echo(
This decorator can be used to listen in on the messages that Sopel is
sending and react accordingly.
.. important::
The decorated callable will receive *all* matching messages that Sopel
sends, including output from the same callable. Take care to avoid
creating feedback loops when using this feature.
"""
def add_attribute(function):
function.echo = True
Expand Down

0 comments on commit 82129c2

Please sign in to comment.