plugin: rename sopel.module into sopel.plugin

contrib/sopel.cfg

@@ -1,7 +1,7 @@
 # Default sopel configuration file for Fedora
 # For information related to possible configuration values see
 # https://sopel.chat/docs/config.html#the-core-configuration-section
-# https://sopel.chat/usage/module-configuration/
+# https://sopel.chat/usage/plugin-configuration/
 #
 # IMPORTANT NOTE!
 # You must delete the not_configured line in order for the bot to work,

docs/source/plugin.rst

@@ -43,20 +43,20 @@ However, sometimes multiple words are needed for clarity or disambiguation;
     A callable is any function which takes as its arguments a
     :class:`sopel.bot.SopelWrapper` object and a :class:`sopel.trigger.Trigger`
     object, and is wrapped with appropriate decorators from
-    :mod:`sopel.module`. The ``bot`` provides the ability to send messages to
+    :mod:`sopel.plugin`. 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
-    :const:`sopel.module.NOLIMIT`, in which case rate limiting will not be
+    :const:`sopel.plugin.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"::
 
-        from sopel import module
+        from sopel import plugin
 
-        @module.commands('hello')
+        @plugin.commands('hello')
         def say_hello(bot, trigger):
             """Reply hello to you."""
             bot.reply('Hello!')
@@ -68,20 +68,20 @@ However, sometimes multiple words are needed for clarity or disambiguation;
     :type bot: :class:`sopel.bot.Sopel`
 
     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
+    plugin is being loaded. The purpose of this function is to perform whatever
+    actions are needed to allow a plugin 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 :class:`sopel.bot.Sopel` object it's passed
     is undefined.
 
     Throwing an exception from this function (such as a
     :exc:`sopel.config.ConfigurationError`) will prevent any callables in the
-    module from being registered, and provide an error message to the user.
+    plugin 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
+    The bot will not continue loading plugins 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.
 
@@ -90,15 +90,15 @@ However, sometimes multiple words are needed for clarity or disambiguation;
     :param bot: the bot's instance
     :type bot: :class:`sopel.bot.Sopel`
 
-    This is an optional function of a module, which will be called while the
+    This is an optional function of a plugin, 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
     :class:`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
+    this function is to perform whatever actions are needed to allow a plugin
     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
+    The bot will not continue notifying other plugins 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.
 
@@ -109,7 +109,7 @@ However, sometimes multiple words are needed for clarity or disambiguation;
     :param bot: the bot's configuration object
     :type bot: :class:`sopel.config.Config`
 
-    This is an optional function of a module, which will be called during the
+    This is an optional function of a plugin, which will be called during the
     user's setup of the bot. It's intended purpose is to use the methods of the
     passed :class:`sopel.config.Config` object in order to create the
     configuration variables it needs to function properly.
@@ -120,6 +120,17 @@ However, sometimes multiple words are needed for clarity or disambiguation;
 Callable decorators
 ===================
 
+.. automodule:: sopel.plugin
+   :members:
+
+About ``sopel.module``
+----------------------
+
+Before Sopel 7.1, ``sopel.module`` was the preferred and only way to decorate
+callables for plugins. However, since the term ``module`` can be confusing
+(mostly because it already has a special meaning in Python), it has been
+replaced by ``plugin`` in most cases related to add-ons for Sopel.
+
 .. automodule:: sopel.module
    :members:
 

sopel/__init__.py

@@ -27,7 +27,8 @@
     'irc',
     'loader',
     'logger',
-    'module',
+    'module',  # deprecated in 7.1, removed in 9.0
+    'plugin',
     'tools',
     'trigger',
     'version_info',

sopel/bot.py

@@ -85,7 +85,7 @@ def __init__(self, config, daemon=False):
         The value associated with each channel is a dictionary of
         :class:`sopel.tools.Identifier`\\s to a bitwise integer value,
         determined by combining the appropriate constants from
-        :mod:`sopel.module`.
+        :mod:`sopel.plugin`.
 
         .. deprecated:: 6.2.0
             Use :attr:`channels` instead. Will be removed in Sopel 8.
@@ -126,7 +126,7 @@ def rules(self):
 
     @property
     def scheduler(self):
-        """Job Scheduler. See :func:`sopel.module.interval`."""
+        """Job Scheduler. See :func:`sopel.plugin.interval`."""
         return self._scheduler
 
     @property
@@ -992,7 +992,7 @@ def register_url_callback(self, pattern, callback):
                 bot.register_url_callback(regex, callback)
 
         It's recommended you completely avoid manual management of URL
-        callbacks through the use of :func:`sopel.module.url`.
+        callbacks through the use of :func:`sopel.plugin.url`.
         """
         if 'url_callbacks' not in self.memory:
             self.memory['url_callbacks'] = tools.SopelMemory()
@@ -1027,7 +1027,7 @@ def unregister_url_callback(self, pattern, callback):
                 bot.unregister_url_callback(regex, callback)
 
         It's recommended you completely avoid manual management of URL
-        callbacks through the use of :func:`sopel.module.url`.
+        callbacks through the use of :func:`sopel.plugin.url`.
         """
         if 'url_callbacks' not in self.memory:
             # nothing to unregister

sopel/config/core_section.py

@@ -138,7 +138,7 @@ class CoreSection(StaticSection):
             Liam
 
     This would then allow both "William: Hi!" and "Bill: Hi!" to work with
-    :func:`~sopel.module.nickname_commands`.
+    :func:`~sopel.plugin.nickname_commands`.
     """
 
     auth_method = ChoiceAttribute('auth_method', choices=[
@@ -194,7 +194,7 @@ class CoreSection(StaticSection):
     :default: ``['http', 'https', 'ftp']``
 
     Used by the URL callbacks feature to call plugins when links are posted in
-    chat; see the :func:`sopel.module.url` decorator.
+    chat; see the :func:`sopel.plugin.url` decorator.
 
     The default value allows ``http``, ``https``, and ``ftp``. It is equivalent
     to this configuration example:

sopel/coretasks.py

@@ -656,9 +656,9 @@ def receive_cap_list(bot, trigger):
 
 def receive_cap_ls_reply(bot, trigger):
     if bot.server_capabilities:
-        # We've already seen the results, so someone sent CAP LS from a module.
+        # We've already seen the results, so someone sent CAP LS from a plugin.
         # We're too late to do SASL, and we don't want to send CAP END before
-        # the module has done what it needs to, so just return
+        # the plugin has done what it needs to, so just return
         return
 
     for cap in trigger.split():
@@ -674,8 +674,8 @@ def receive_cap_ls_reply(bot, trigger):
 
     bot.server_capabilities = batched_caps
 
-    # If some other module requests it, we don't need to add another request.
-    # If some other module prohibits it, we shouldn't request it.
+    # If some other plugin requests it, we don't need to add another request.
+    # If some other plugin prohibits it, we shouldn't request it.
     core_caps = [
         'echo-message',
         'multi-prefix',
@@ -689,7 +689,7 @@ def receive_cap_ls_reply(bot, trigger):
 
     def acct_warn(bot, cap):
         LOGGER.info('Server does not support %s, or it conflicts with a custom '
-                    'module. User account validation unavailable or limited.',
+                    'plugin. User account validation unavailable or limited.',
                     cap[1:])
         if bot.config.core.owner_account or bot.config.core.admin_accounts:
             LOGGER.warning(
@@ -905,7 +905,7 @@ def account_notify(bot, trigger):
 @module.unblockable
 def recv_whox(bot, trigger):
     if len(trigger.args) < 2 or trigger.args[1] not in who_reqs:
-        # Ignored, some module probably called WHO
+        # Ignored, some plugin probably called WHO
         return
     if len(trigger.args) != 8:
         return LOGGER.warning('While populating `bot.accounts` a WHO response was malformed.')

sopel/irc/backends.py

@@ -16,7 +16,7 @@
 import sys
 import threading
 
-from sopel import loader, module
+from sopel import loader, plugin
 from sopel.tools import jobs
 from .abstract_backends import AbstractIRCBackend
 from .utils import get_cnames
@@ -41,7 +41,7 @@
 LOGGER = logging.getLogger(__name__)
 
 
-@module.thread(False)
+@plugin.thread(False)
 def _send_ping(backend):
     if not backend.is_connected():
         return
@@ -53,7 +53,7 @@ def _send_ping(backend):
             LOGGER.exception('Socket error on PING')
 
 
-@module.thread(False)
+@plugin.thread(False)
 def _check_timeout(backend):
     if not backend.is_connected():
         return
@@ -87,8 +87,8 @@ def __init__(self, bot, server_timeout=None, ping_timeout=None, **kwargs):
         self.timeout_scheduler = jobs.Scheduler(self)
 
         # prepare interval decorator
-        ping_interval = module.interval(self.ping_timeout)
-        timeout_interval = module.interval(self.server_timeout)
+        ping_interval = plugin.interval(self.ping_timeout)
+        timeout_interval = plugin.interval(self.server_timeout)
 
         # register timeout jobs
         self.register_timeout_jobs([

sopel/loader.py

@@ -171,7 +171,7 @@ def is_triggerable(obj):
 
     .. seealso::
 
-        Many of the decorators defined in :mod:`sopel.module` make the
+        Many of the decorators defined in :mod:`sopel.plugin` make the
         decorated function a triggerable object.
     """
     forbidden_attrs = (