quality: Docstring cleanup for pydocstyle prep

dev-requirements.txt

@@ -3,9 +3,12 @@ coveralls>=2.0; python_version >= '3.5'
 flake8<3.6.0; python_version == '3.3'
 flake8>=3.7.0,<3.8.0; python_version != '3.3'
 flake8-coding
+flake8-docstrings
 flake8-future-import<0.4.6
 flake8-import-order; python_version > '3.3'
 flake8-import-order<=1.18.1; python_version <= '3.3'
+# required by flake8-docstrings, 3+ drop py2
+pydocstyle<3.0
 pytest<3.3; python_version == '3.3'
 pytest>=4.6,<4.7; python_version != '3.3'
 pytest-vcr==1.0.2; python_version != '3.3'

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.

setup.cfg

@@ -59,10 +59,20 @@ ignore =
     # support for Python older than 3.5)
     FI15,
     # Ignore "annotations" future import, since it's not available before 3.7
-    FI18
+    FI18,
+    # Ignore missing docstrings we don't care about (magic method, __init__)
+    D105, D107,
+    # Ignore missing docstrings for now, TODO
+    #  public module, public class, public method, public function, public package
+    D100, D101, D102, D103, D104,
+    # Ignore some that the module config convention breaks for now, TODO
+    D205, D212, D400, D415,
+    # Docstring style and option choices
+    D203, D213, D407, D413
 exclude =
     docs/*,
     env/*,
     contrib/*,
     conftest.py
 accept-encodings = utf-8
+docstring-convention = all

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.')
@@ -1096,6 +1096,7 @@ class SopelWrapper(object):
     to the sender (either a channel or in a private message) and even to
     :meth:`reply to someone<reply>` in a channel.
     """
+
     def __init__(self, sopel, trigger, output_prefix=''):
         if not output_prefix:
             # Just in case someone passes in False, None, etc.
@@ -1200,7 +1201,7 @@ def reply(self, message, destination=None, reply_to=None, notice=False):
         self._bot.reply(message, destination, reply_to, notice)
 
     def kick(self, nick, channel=None, message=None):
-        """Override ``Sopel.kick`` to kick in a channel
+        """Override ``Sopel.kick`` to kick in a channel.
 
         :param str nick: nick to kick out of the ``channel``
         :param str channel: optional channel to kick ``nick`` from

sopel/cli/config.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""Sopel Config Command Line Interface (CLI): ``sopel-config``"""
+"""Sopel Config Command Line Interface (CLI): ``sopel-config``."""
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 import argparse

sopel/cli/plugins.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""Sopel Plugins Command Line Interface (CLI): ``sopel-plugins``"""
+"""Sopel Plugins Command Line Interface (CLI): ``sopel-plugins``."""
 from __future__ import absolute_import, division, print_function, unicode_literals
 
 import argparse

sopel/cli/run.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python2.7
 # coding=utf-8
-"""
-Sopel - An IRC Bot
+"""Sopel - An IRC Bot.
+
 Copyright 2008, Sean B. Palmer, inamidst.com
 Copyright © 2012-2014, Elad Alfassa <elad@fedoraproject.org>
 Licensed under the Eiffel Forum License 2.

sopel/config/__init__.py

@@ -80,6 +80,7 @@ class ConfigurationError(Exception):
 
     :param str value: a description of the error that has occurred
     """
+
     def __init__(self, value):
         self.value = value
 
@@ -92,6 +93,7 @@ class ConfigurationNotFound(ConfigurationError):
 
     :param str filename: file path that could not be found
     """
+
     def __init__(self, filename):
         super(ConfigurationNotFound, self).__init__(None)
         self.filename = filename
@@ -118,6 +120,7 @@ class Config(object):
     Sopel to run. All other sections must be defined later, by the code that
     needs them, using :meth:`define_section`.
     """
+
     def __init__(self, filename, validate=True):
         self.filename = filename
         """The config object's associated file."""
@@ -145,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
@@ -215,11 +218,11 @@ def add_section(self, name):
             return False
 
     def define_section(self, name, cls_, validate=True):
-        """Define the available settings in a section.
+        r"""Define the available settings in a section.
 
         :param str name: name of the new section
-        :param cls\\_: :term:`class` defining the settings within the section
-        :type cls\\_: subclass of :class:`~.types.StaticSection`
+        :param cls\_: :term:`class` defining the settings within the section
+        :type cls\_: subclass of :class:`~.types.StaticSection`
         :param bool validate: whether to validate the section's values
                               (optional; defaults to ``True``)
         :raise ValueError: if the section ``name`` has been defined already with
@@ -260,16 +263,17 @@ def define_section(self, name, cls_, validate=True):
         setattr(self, name, cls_(self, name, validate=validate))
 
     class ConfigSection(object):
-        """Represents a section of the config file.
+        r"""Represents a section of the config file.
 
         :param str name: name of this section
         :param items: key-value pairs
-        :type items: :term:`iterable` of two-item :class:`tuple`\\s
+        :type items: :term:`iterable` of two-item :class:`tuple`\s
         :param parent: this section's containing object
         :type parent: :class:`Config`
 
         Contains all keys in the section as attributes.
         """
+
         def __init__(self, name, items, parent):
             object.__setattr__(self, '_name', name)
             object.__setattr__(self, '_parent', parent)

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

@@ -60,6 +60,7 @@ class StaticSection(object):
         Python will work just fine.
 
     """
+
     def __init__(self, config, section_name, validate=True):
         if not config.parser.has_section(section_name):
             config.parser.add_section(section_name)
@@ -149,6 +150,7 @@ class BaseValidated(object):
             settings>` using environment variables
 
     """
+
     def __init__(self, name, default=None, is_secret=False):
         self.name = name
         """Name of the attribute."""
@@ -209,7 +211,8 @@ def serialize(self, value, *args, **kwargs):
     def parse(self, value, *args, **kwargs):
         """Take a string from the file, and return the appropriate object.
 
-        Must be implemented in subclasses."""
+        Must be implemented in subclasses.
+        """
         raise NotImplementedError("Parse method must be implemented in subclass")
 
     def __get__(self, instance, owner=None):
@@ -288,6 +291,7 @@ class ValidatedAttribute(BaseValidated):
     :param bool is_secret: ``True`` when the attribute should be considered
                            a secret, like a password (default to ``False``)
     """
+
     def __init__(self,
                  name,
                  parse=None,
@@ -332,6 +336,7 @@ class SecretAttribute(ValidatedAttribute):
     This attribute is always considered to be secret/sensitive data, but
     otherwise behaves like other any option.
     """
+
     def __init__(self, name, parse=None, serialize=None, default=None):
         super(SecretAttribute, self).__init__(
             name,
@@ -403,6 +408,7 @@ class SpamSection(StaticSection):
         The comma delimiter fallback does not support commas within items in
         the list.
     """
+
     DELIMITER = ','
     QUOTE_REGEX = re.compile(r'^"(?P<value>#.*)"$')
     """Regex pattern to match value that requires quotation marks.
@@ -536,6 +542,7 @@ class ChoiceAttribute(BaseValidated):
                     :const:`sopel.config.types.NO_DEFAULT` (optional)
     :type default: str
     """
+
     def __init__(self, name, choices, default=None):
         super(ChoiceAttribute, self).__init__(name, default=default)
         self.choices = choices
@@ -583,6 +590,7 @@ class FilenameAttribute(BaseValidated):
                     :const:`sopel.config.types.NO_DEFAULT` (optional)
     :type default: str
     """
+
     def __init__(self, name, relative=True, directory=False, default=None):
         super(FilenameAttribute, self).__init__(name, default=default)
         self.relative = relative
@@ -610,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/coretasks.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""Tasks that allow the bot to run, but aren't user-facing functionality
+"""Tasks that allow the bot to run, but aren't user-facing functionality.
 
 This is written as a module to make it easier to extend to support more
 responses to standard IRC codes without having to shove them all into the
@@ -84,7 +84,7 @@ def _join_event_processing(bot):
 
 
 def auth_after_register(bot):
-    """Do NickServ/AuthServ auth"""
+    """Do NickServ/AuthServ auth."""
     if bot.config.core.auth_method:
         auth_method = bot.config.core.auth_method
         auth_username = bot.config.core.auth_username
@@ -900,8 +900,8 @@ def _get_sasl_pass_and_mech(bot):
 @module.unblockable
 @module.require_admin
 def blocks(bot, trigger):
-    """
-    Manage Sopel's blocking features.\
+    """Manage Sopel's blocking features.
+
     See [ignore system documentation]({% link _usage/ignoring-people.md %}).
     """
     STRINGS = {
@@ -1088,7 +1088,7 @@ def track_topic(bot, trigger):
 
 @module.rule(r'(?u).*(.+://\S+).*')
 def handle_url_callbacks(bot, trigger):
-    """Dispatch callbacks on URLs
+    """Dispatch callbacks on URLs.
 
     For each URL found in the trigger, trigger the URL callback registered by
     the ``@url`` decorator.