quality: docstring whitespace, punctuation

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'

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

@@ -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."""
@@ -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/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

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.

sopel/db.py

@@ -47,12 +47,14 @@ def _deserialize(value):
 
 class NickIDs(BASE):
     """Nick IDs table SQLAlchemy class."""
+
     __tablename__ = 'nick_ids'
     nick_id = Column(Integer, primary_key=True)
 
 
 class Nicknames(BASE):
     """Nicknames table SQLAlchemy class."""
+
     __tablename__ = 'nicknames'
     __table_args__ = MYSQL_TABLE_ARGS
     nick_id = Column(Integer, ForeignKey('nick_ids.nick_id'), primary_key=True)
@@ -62,6 +64,7 @@ class Nicknames(BASE):
 
 class NickValues(BASE):
     """Nick values table SQLAlchemy class."""
+
     __tablename__ = 'nick_values'
     __table_args__ = MYSQL_TABLE_ARGS
     nick_id = Column(Integer, ForeignKey('nick_ids.nick_id'), primary_key=True)
@@ -71,6 +74,7 @@ class NickValues(BASE):
 
 class ChannelValues(BASE):
     """Channel values table SQLAlchemy class."""
+
     __tablename__ = 'channel_values'
     __table_args__ = MYSQL_TABLE_ARGS
     channel = Column(String(255), primary_key=True)
@@ -80,6 +84,7 @@ class ChannelValues(BASE):
 
 class PluginValues(BASE):
     """Plugin values table SQLAlchemy class."""
+
     __tablename__ = 'plugin_values'
     __table_args__ = MYSQL_TABLE_ARGS
     plugin = Column(String(255), primary_key=True)
@@ -862,7 +867,7 @@ def get_nick_or_channel_value(self, name, key, default=None):
             return self.get_channel_value(name, key, default)
 
     def get_preferred_value(self, names, key):
-        """Get a value for the first name which has it set.
+        r"""Get a value for the first name which has it set.
 
         :param list names: a list of channel names and/or nicknames
         :param str key: the name by which the desired value was saved
@@ -878,7 +883,7 @@ def get_preferred_value(self, names, key):
         .. note::
 
             This is the only ``get_*_value()`` method that does not support
-            passing a ``default``. Try to avoid using it on ``key``\\s which
+            passing a ``default``. Try to avoid using it on ``key``\s which
             might have ``None`` as a valid value, to avoid ambiguous logic.
 
         """

sopel/irc/__init__.py

@@ -60,6 +60,7 @@
 
 class AbstractBot(object):
     """Abstract definition of Sopel's interface."""
+
     def __init__(self, settings):
         # private properties: access as read-only properties
         self._nick = tools.Identifier(settings.core.nick)
@@ -414,7 +415,7 @@ def cap_req(self, module_name, capability, arg=None, failure_callback=None,
             self._cap_reqs[cap] = entry
 
     def write(self, args, text=None):
-        """Send a command to the server.
+        r"""Send a command to the server.
 
         :param args: an iterable of strings, which will be joined by spaces
         :type args: :term:`iterable`
@@ -431,7 +432,7 @@ def write(self, args, text=None):
         and ``sopel.write(('PRIVMSG', ':Hello, world!'))`` will send
         ``PRIVMSG :Hello, world!`` to the server.
 
-        Newlines and carriage returns (``'\\n'`` and ``'\\r'``) are removed
+        Newlines and carriage returns (``'\n'`` and ``'\r'``) are removed
         before sending. Additionally, if the message (after joining) is longer
         than than 510 characters, any remaining characters will not be sent.
 

sopel/irc/abstract_backends.py

@@ -16,6 +16,7 @@ class AbstractIRCBackend(object):
     Some methods of this class **MUST** be overridden by a subclass, or the
     backend implementation will not function correctly.
     """
+
     def __init__(self, bot):
         self.bot = bot
 

sopel/irc/backends.py

@@ -72,6 +72,7 @@ class AsynchatBackend(AbstractIRCBackend, asynchat.async_chat):
     :param int server_timeout: connection timeout in seconds
     :param int ping_timeout: ping timeout in seconds
     """
+
     def __init__(self, bot, server_timeout=None, ping_timeout=None, **kwargs):
         AbstractIRCBackend.__init__(self, bot)
         asynchat.async_chat.__init__(self)
@@ -230,6 +231,7 @@ class SSLAsynchatBackend(AsynchatBackend):
     :param str ca_certs: filesystem path to a CA Certs file containing trusted
                          root certificates
     """
+
     def __init__(self, bot, verify_ssl=True, ca_certs=None, **kwargs):
         AsynchatBackend.__init__(self, bot, **kwargs)
         self.verify_ssl = verify_ssl

sopel/irc/isupport.py

@@ -172,6 +172,7 @@ class ISupport(object):
 
     .. __: https://modern.ircdocs.horse/#rplisupport-parameters
     """
+
     def __init__(self, **kwargs):
         self.__isupport = dict(
             (key.upper(), value)

sopel/irc/utils.py

@@ -67,6 +67,7 @@ class CapReq(object):
         For more information on how capability requests work, see the
         documentation for :meth:`sopel.irc.AbstractBot.cap_req`.
     """
+
     def __init__(self, prefix, module, failure=None, arg=None, success=None):
         def nop(bot, cap):
             pass

sopel/loader.py

@@ -13,7 +13,7 @@
 
 
 def trim_docstring(doc):
-    """Get the docstring as a series of lines that can be sent"""
+    """Get the docstring as a series of lines that can be sent."""
     if not doc:
         return []
     lines = doc.expandtabs().splitlines()
@@ -34,7 +34,7 @@ def trim_docstring(doc):
 
 
 def clean_callable(func, config):
-    """Clean the callable. (compile regexes, fix docs, set defaults)
+    """Clean the callable. (compile regexes, fix docs, set defaults).
 
     :param func: the callable to clean
     :type func: callable

sopel/logger.py

@@ -18,6 +18,7 @@ class IrcLoggingHandler(logging.Handler):
 
     Implementation of a :class:`logging.Handler`.
     """
+
     def __init__(self, bot, level):
         super(IrcLoggingHandler, self).__init__(level)
         self._bot = bot
@@ -52,6 +53,7 @@ class ChannelOutputFormatter(logging.Formatter):
 
     Implementation of a :class:`logging.Formatter`.
     """
+
     def __init__(self, fmt='[%(filename)s] %(message)s', datefmt=None):
         super(ChannelOutputFormatter, self).__init__(fmt=fmt, datefmt=datefmt)