quality: docstring rephrasing and restructuring

pytest_run.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 # coding=utf-8
-"""This is a script for running pytest from the command line.
+"""A script for running pytest from the command line.
 
 This script exists so that the project directory gets added to sys.path, which
 prevents us from accidentally testing the globally installed sopel version.

sopel/bot.py

@@ -131,7 +131,7 @@ def scheduler(self):
 
     @property
     def command_groups(self):
-        """A mapping of plugin names to lists of their commands.
+        """Map of plugin names to lists of their commands.
 
         .. versionchanged:: 7.1
             This attribute is now generated on the fly from the registered list
@@ -156,7 +156,7 @@ def command_groups(self):
 
     @property
     def doc(self):
-        """A dictionary of command names to their documentation.
+        """Map of command names to their documentation.
 
         Each command is mapped to its docstring and any available examples, if
         declared in the plugin's code.
@@ -188,7 +188,7 @@ def doc(self):
 
     @property
     def hostmask(self):
-        """The current hostmask for the bot :class:`sopel.tools.target.User`.
+        """Get current hostmask for the bot :class:`sopel.tools.target.User`.
 
         :return: the bot's current hostmask
         :rtype: str
@@ -823,7 +823,7 @@ def dispatch(self, pretrigger):
 
     @property
     def running_triggers(self):
-        """Current active threads for triggers.
+        """Get current active threads for triggers.
 
         :return: the running thread(s) currently processing trigger(s)
         :rtype: :term:`iterable`
@@ -853,7 +853,7 @@ def _update_running_triggers(self, running_triggers):
                 t for t in running_triggers if t.is_alive()]
 
     def on_scheduler_error(self, scheduler, exc):
-        """Called when the Job Scheduler fails.
+        """Handle failed Job Scheduler.
 
         :param scheduler: the job scheduler that errored
         :type scheduler: :class:`sopel.plugins.jobs.Scheduler`
@@ -866,7 +866,7 @@ def on_scheduler_error(self, scheduler, exc):
         self.error(exception=exc)
 
     def on_job_error(self, scheduler, job, exc):
-        """Called when a job from the Job Scheduler fails.
+        """Handle failed job from the Job Scheduler.
 
         :param scheduler: the job scheduler responsible for the errored ``job``
         :type scheduler: :class:`sopel.plugins.jobs.Scheduler`
@@ -881,9 +881,9 @@ def on_job_error(self, scheduler, job, exc):
         self.error(exception=exc)
 
     def error(self, trigger=None, exception=None):
-        """Called internally when a plugin causes an error.
+        r"""Handle uncaught plugin errors.
 
-        :param trigger: the ``Trigger``\\ing line (if available)
+        :param trigger: the ``Trigger``\ing line (if available)
         :type trigger: :class:`sopel.trigger.Trigger`
         :param Exception exception: the exception raised by the error (if
                                     available)
@@ -933,7 +933,7 @@ def _nick_blocked(self, nick):
         return False
 
     def _shutdown(self):
-        """Internal bot shutdown method."""
+        """Shut down the bot."""
         LOGGER.info('Shutting down')
         # Stop Job Scheduler
         LOGGER.info('Stopping the Job Scheduler.')

sopel/config/__init__.py

@@ -148,7 +148,7 @@ def __init__(self, filename, validate=True):
 
     @property
     def homedir(self):
-        """The config file's home directory.
+        """Home directory for config file.
 
         If the :attr:`core.homedir <.core_section.CoreSection.homedir>` setting
         is available, that value is used. Otherwise, the default ``homedir`` is

sopel/config/core_section.py

@@ -637,7 +637,7 @@ class CoreSection(StaticSection):
 
     @property
     def homedir(self):
-        """The directory in which various files are stored at runtime.
+        """Directory where Sopel's data is stored.
 
         By default, this is the same directory as the config file. It cannot be
         changed at runtime.

sopel/config/types.py

@@ -618,7 +618,7 @@ def _parse(self, value, settings, section):
         return self.parse(result)
 
     def _serialize(self, value, settings, section):
-        """Used to validate ``value`` when it is changed at runtime.
+        """Validate ``value`` when it is changed at runtime.
 
         :param settings: the config object which contains this attribute
         :type settings: :class:`~sopel.config.Config`

sopel/irc/__init__.py

@@ -108,7 +108,7 @@ def name(self):
 
     @property
     def config(self):
-        """The :class:`sopel.config.Config` for the current Sopel instance."""
+        """Get the :class:`sopel.config.Config` for the current Sopel instance."""
         # TODO: Deprecate config, replaced by settings
         return self.settings
 

sopel/irc/abstract_backends.py

@@ -28,7 +28,7 @@ def is_connected(self):
         raise NotImplementedError
 
     def on_irc_error(self, pretrigger):
-        """Action to perform when the server sends an error event.
+        """Perform action when the server sends an error event.
 
         :param pretrigger: PreTrigger object with the error event
         :type pretrigger: :class:`sopel.trigger.PreTrigger`

sopel/irc/backends.py

@@ -152,21 +152,21 @@ def initiate_connect(self, host, port, source_address):
             self.handle_close()
 
     def handle_connect(self):
-        """Called when the active opener's socket actually makes a connection."""
+        """Handle active opener's new accepted connection."""
         LOGGER.info('Connection accepted by the server...')
         self.timeout_scheduler.start()
         self.bot.on_connect()
 
     def handle_close(self):
-        """Called when the socket is closed."""
+        """Handle closed socket."""
         LOGGER.debug('Stopping timeout watchdog')
         self.timeout_scheduler.stop()
         LOGGER.info('Closing connection')
         self.close()
         self.bot.on_close()
 
     def handle_error(self):
-        """Called when an exception is raised and not otherwise handled.
+        """Handle unhandled exceptions.
 
         This method is an override of :meth:`asyncore.dispatcher.handle_error`,
         the :class:`asynchat.async_chat` being a subclass of
@@ -211,12 +211,12 @@ def found_terminator(self):
         self.bot.on_message(line)
 
     def on_scheduler_error(self, scheduler, exc):
-        """Called when the Job Scheduler fails."""
+        """Handle Job Scheduler failures."""
         LOGGER.exception('Error with the timeout scheduler: %s', exc)
         self.handle_close()
 
     def on_job_error(self, scheduler, job, exc):
-        """Called when a job from the Job Scheduler fails."""
+        """Handle failures of a job from the Job Scheduler."""
         LOGGER.exception('Error with the timeout scheduler: %s', exc)
         self.handle_close()
 

sopel/modules/admin.py

@@ -232,9 +232,7 @@ def invite_join(bot, trigger):
 @plugin.event('KICK')
 @plugin.priority('low')
 def hold_ground(bot, trigger):
-    """
-    This function monitors all kicks across all channels Sopel is in. If it
-    detects that it is the one kicked it'll automatically join that channel.
+    """Monitor KICK messages to rejoin if kicked.
 
     WARNING: This may not be needed and could cause problems if Sopel becomes
     annoying. Please use this with caution.

sopel/modules/adminchannel.py

@@ -32,9 +32,9 @@ def default_mask(trigger):
 @plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
 @plugin.command('op')
 def op(bot, trigger):
-    """
-    Command to op users in a room. If no nick is given,
-    Sopel will op the nick who sent the command
+    """Op users in a room.
+
+    If no nick is given, Sopel will op the nick who sent the command.
     """
     if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
         bot.reply(ERROR_MESSAGE_NOT_OP)
@@ -50,9 +50,9 @@ def op(bot, trigger):
 @plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
 @plugin.command('deop')
 def deop(bot, trigger):
-    """
-    Command to deop users in a room. If no nick is given,
-    Sopel will deop the nick who sent the command
+    """Deop users in a room.
+
+    If no nick is given, Sopel will deop the nick who sent the command.
     """
     if bot.channels[trigger.sender].privileges[bot.nick] < plugin.OP:
         bot.reply(ERROR_MESSAGE_NOT_OP)
@@ -68,9 +68,9 @@ def deop(bot, trigger):
 @plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
 @plugin.command('voice')
 def voice(bot, trigger):
-    """
-    Command to voice users in a room. If no nick is given,
-    Sopel will voice the nick who sent the command
+    """Voice users in a room.
+
+    If no nick is given, Sopel will voice the nick who sent the command.
     """
     if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
         bot.reply(ERROR_MESSAGE_NOT_OP)
@@ -86,9 +86,9 @@ def voice(bot, trigger):
 @plugin.require_privilege(plugin.OP, ERROR_MESSAGE_NO_PRIV)
 @plugin.command('devoice')
 def devoice(bot, trigger):
-    """
-    Command to devoice users in a room. If no nick is given,
-    Sopel will devoice the nick who sent the command
+    """Devoice users in a room.
+
+    If no nick is given, Sopel will devoice the nick who sent the command
     """
     if bot.channels[trigger.sender].privileges[bot.nick] < plugin.HALFOP:
         bot.reply(ERROR_MESSAGE_NOT_OP)

sopel/modules/invite.py

@@ -16,7 +16,7 @@
 
 
 def invite_handler(bot, sender, user, channel):
-    """Common control logic for invite commands received from anywhere."""
+    """Check common requirements for invite commands."""
     sender = tools.Identifier(sender)
     user = tools.Identifier(user)
     channel = tools.Identifier(channel)
@@ -60,10 +60,7 @@ def invite_handler(bot, sender, user, channel):
 @plugin.example('.invite jenny', user_help=True)
 @plugin.example('.invite converge #sopel', user_help=True)
 def invite(bot, trigger):
-    """
-    Invite the given user to the current channel, or (with optional
-    second argument) another channel that Sopel is in.
-    """
+    """Invite the given user to the current or given channel."""
     if not trigger.group(3):
         return bot.reply("Whom should I invite?")
     user = trigger.group(3)

sopel/modules/meetbot.py

@@ -504,8 +504,9 @@ def log_meeting(bot, trigger):
 @plugin.command("comment")
 @plugin.require_privmsg()
 def take_comment(bot, trigger):
-    """
-    Log a comment, to be shown with other comments when a chair uses .comments.
+    """Log a comment.
+
+    Comments will be shown with others when a chair uses .comments.
     Intended to allow commentary from those outside the primary group of people
     in the meeting.
 

sopel/modules/reddit.py

@@ -361,9 +361,9 @@ def auto_subreddit_info(bot, trigger, match):
 @plugin.example('.setsfw false')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def set_channel_sfw(bot, trigger):
-    """
-    Sets the Safe for Work status (true or false) for the current
-    channel. Defaults to false.
+    """Set the Safe for Work status for the current channel.
+
+    Defaults to false.
     """
     param = 'true'
     if trigger.group(2) and trigger.group(3):
@@ -380,9 +380,9 @@ def set_channel_sfw(bot, trigger):
 @plugin.example('.getsfw [channel]')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_channel_sfw(bot, trigger):
-    """
-    Gets the preferred channel's Safe for Work status, or the current
-    channel's status if no channel given.
+    """Get the preferred channel's Safe for Work status.
+
+    Checks current channel if none is specified.
     """
     channel = trigger.group(2)
     if not channel:
@@ -408,8 +408,8 @@ def get_channel_sfw(bot, trigger):
 @plugin.example('.setspoilfree false')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def set_channel_spoiler_free(bot, trigger):
-    """
-    Sets the Spoiler-Free status (true or false) for the current channel.
+    """Set the Spoiler-Free status for the current channel.
+
     Defaults to false.
     """
     param = 'true'
@@ -427,9 +427,9 @@ def set_channel_spoiler_free(bot, trigger):
 @plugin.example('.getspoilfree [channel]')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_channel_spoiler_free(bot, trigger):
-    """
-    Gets the channel's Spoiler-Free status, or the current channel's
-    status if no channel given.
+    """Get a channel's Spoiler-Free status.
+
+    Checks current channel if none is specified.
     """
     channel = trigger.group(2)
     if not channel:

sopel/modules/reload.py

@@ -116,15 +116,15 @@ def f_load(bot, trigger):
 @plugin.require_privmsg
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def pm_f_reload(bot, trigger):
-    """Wrapper for allowing delivery of .reload command via PM"""
+    """Allow .reload command via PM."""
     f_reload(bot, trigger)
 
 
 @plugin.command('update')
 @plugin.require_privmsg
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def pm_f_update(bot, trigger):
-    """Wrapper for allowing delivery of .update command via PM"""
+    """Allow .update command via PM."""
     f_update(bot, trigger)
 
 
@@ -134,5 +134,5 @@ def pm_f_update(bot, trigger):
 @plugin.require_privmsg
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def pm_f_load(bot, trigger):
-    """Wrapper for allowing delivery of .load command via PM"""
+    """Allow .load command via PM."""
     f_load(bot, trigger)

sopel/modules/url.py

@@ -159,10 +159,7 @@ def shutdown(bot):
     online=True, vcr=True)
 @plugin.output_prefix('[url] ')
 def title_command(bot, trigger):
-    """
-    Show the title or URL information for the given URL, or the last URL seen
-    in this channel.
-    """
+    """Show title or URL info for a given URL or the last URL in the channel."""
     if not trigger.group(2):
         if trigger.sender not in bot.memory['last_seen_url']:
             return
@@ -188,10 +185,10 @@ def title_command(bot, trigger):
 @plugin.rule(r'(?u).*(https?://\S+).*')
 @plugin.output_prefix('[url] ')
 def title_auto(bot, trigger):
-    """
-    Automatically show titles for URLs. For shortened URLs/redirects, find
-    where the URL redirects to and show the title for that (or call a function
-    from another plugin to give more information).
+    """Automatically show titles for URLs.
+
+    For shortened URLs/redirects, find where the URL redirects to and show the title
+    for that (or call a function from another plugin to give more information).
     """
     # Enabled or disabled by feature flag
     if not bot.settings.url.enable_auto_title:

sopel/modules/wikipedia.py

@@ -197,10 +197,7 @@ def say_section(bot, trigger, server, query, section):
 
 
 def mw_section(server, query, section):
-    """
-    Retrieves a snippet from the specified section from the given page
-    on the given server.
-    """
+    """Retrieve a snippet of a section section of a page."""
     sections_url = ('https://{0}/w/api.php?format=json&redirects'
                     '&action=parse&prop=sections&page={1}'
                     .format(server, query))

sopel/tests/mocks.py

@@ -50,7 +50,7 @@ def __init__(self, bot):
 
     @property
     def chanserv(self):
-        """ChanServ's message prefix."""
+        """Message prefix for ChanServ."""
         return 'ChanServ!ChanServ@services.'
 
     def channel_joined(self, channel, users=None):

sopel/tools/__init__.py

@@ -55,7 +55,7 @@ def deprecated(
     warning_in=None,
     func=None,
 ):
-    """Decorator to mark deprecated functions in Sopel's API
+    """Mark deprecated functions in Sopel's API. Decorator.
 
     :param str reason: optional text added to the deprecation warning
     :param str version: optional version number when the decorated function