quality: docstring tense, mood, tweaks

sopel/modules/admin.py

@@ -185,9 +185,9 @@ def quit(bot, trigger):
 @plugin.priority('low')
 @plugin.example('.say #YourPants Does anyone else smell neurotoxin?')
 def say(bot, trigger):
-    """
-    Send a message to a given channel or nick. Can only be done in privmsg by
-    an admin.
+    """Send a message to a given channel or nick.
+
+    Can only be done in privmsg by an admin.
     """
     if trigger.group(2) is None:
         return
@@ -205,9 +205,9 @@ def say(bot, trigger):
 @plugin.command('me')
 @plugin.priority('low')
 def me(bot, trigger):
-    """
-    Send an ACTION (/me) to a given channel or nick. Can only be done in
-    privmsg by an admin.
+    """Send an ACTION (/me) to a given channel or nick.
+
+    Can only be done in privmsg by an admin.
     """
     if trigger.group(2) is None:
         return

sopel/modules/choose.py

@@ -30,7 +30,7 @@
 @plugin.example(".choose a | b | c", user_help=True)
 @plugin.example(".choose a, b, c", user_help=True)
 def choose(bot, trigger):
-    """Makes a difficult choice easy."""
+    """Make a difficult choice easy."""
     if not trigger.group(2):
         bot.reply("I'd choose an option, but you didn't give me any.")
         return

sopel/modules/clock.py

@@ -165,7 +165,7 @@ def update_user(bot, trigger):
 @plugin.example('.gettz', user_help=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_user_tz(bot, trigger):
-    """Gets a user's preferred time zone.
+    """Get a user's preferred time zone.
 
     It will show yours if no user specified.
     """
@@ -185,7 +185,7 @@ def get_user_tz(bot, trigger):
 @plugin.command('settimeformat', 'settf')
 @plugin.example('.settf %Y-%m-%dT%T%z')
 def update_user_format(bot, trigger):
-    """Sets your preferred format for time.
+    """Set your preferred format for time.
 
     Uses the standard strftime format. You can use <http://strftime.net> or
     your favorite search engine to learn more.
@@ -222,7 +222,7 @@ def update_user_format(bot, trigger):
 @plugin.example('.gettf', user_help=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_user_format(bot, trigger):
-    """Gets a user's preferred time format.
+    """Get a user's preferred time format.
 
     It will show yours if no user specified.
     """
@@ -274,7 +274,7 @@ def update_channel(bot, trigger):
 @plugin.example('.getctz', user_help=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_channel_tz(bot, trigger):
-    """Gets the channel's preferred timezone.
+    """Get the channel's preferred timezone.
 
     It returns the current channel's if no channel name is given.
     """
@@ -297,7 +297,7 @@ def get_channel_tz(bot, trigger):
 @plugin.require_privilege(plugin.OP)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def update_channel_format(bot, trigger):
-    """Sets your preferred format for time.
+    """Set your preferred format for time.
 
     Uses the standard strftime format. You can use <http://strftime.net> or
     your favorite search engine to learn more.
@@ -338,7 +338,7 @@ def update_channel_format(bot, trigger):
 @plugin.example('.getctf', user_help=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def get_channel_format(bot, trigger):
-    """Gets the channel's preferred time format
+    """Get the channel's preferred time format.
 
     It returns the current channel's if no channel name is given.
     """

sopel/modules/countdown.py

@@ -17,7 +17,7 @@
 @plugin.example('.countdown 2078 09 14')
 @plugin.output_prefix('[countdown] ')
 def generic_countdown(bot, trigger):
-    """Displays a countdown to a given date."""
+    """Display a countdown to a given date."""
     text = trigger.group(2)
     if not text:
         bot.reply("Please use correct format: {}countdown 2012 12 21"

sopel/modules/currency.py

@@ -63,13 +63,15 @@ def setup(bot):
 
 
 class FixerError(Exception):
-    """A Fixer.io API Error Exception"""
+    """Fixer.io API Error Exception."""
+
     def __init__(self, status):
         super(FixerError, self).__init__("FixerError: {}".format(status))
 
 
 class UnsupportedCurrencyError(Exception):
-    """A currency is currently not supported by the API"""
+    """Currency is currently not supported by the API."""
+
     def __init__(self, currency):
         super(UnsupportedCurrencyError, self).__init__(currency)
 

sopel/modules/dice.py

@@ -113,7 +113,7 @@ def get_sum(self):
         return result
 
     def get_number_of_faces(self):
-        """Returns sum of different faces for dropped and not dropped dice
+        """Return sum of different faces for dropped and not dropped dice.
 
         This can be used to estimate, whether the result can be shown in
         compressed form in a reasonable amount of space.
@@ -179,7 +179,7 @@ def _roll_dice(bot, dice_expression):
 @plugin.example(".roll 1d6", user_help=True)
 @plugin.output_prefix('[dice] ')
 def roll(bot, trigger):
-    """Rolls dice and reports the result.
+    """Roll dice and reports the result.
 
     The dice roll follows this format: XdY[vZ][+N][#COMMENT]
 

sopel/modules/help.py

@@ -251,7 +251,7 @@ def is_cache_valid(bot):
 @plugin.command('help', 'commands')
 @plugin.priority('low')
 def help(bot, trigger):
-    """Shows a command's documentation, and an example if available. With no arguments, lists all commands."""
+    """Show a command's documentation, and an example if available. With no arguments, lists all commands."""
     if bot.config.help.reply_method == 'query':
         def respond(text):
             bot.say(text, trigger.nick)
@@ -325,7 +325,7 @@ def msgfun(l):
 
 
 def create_list(bot, msg):
-    """Creates & uploads the command list.
+    """Create and upload the command list.
 
     Returns the URL from the chosen pastebin provider.
     """

sopel/modules/rand.py

@@ -22,7 +22,7 @@
 @plugin.example('.rand 10 99', r'random\(10, 99\): \d\d', re=True, repeat=10)
 @plugin.output_prefix('[rand] ')
 def rand(bot, trigger):
-    """Replies with a random number between first and second argument."""
+    """Reply with a random number between first and second argument."""
     arg1 = trigger.group(3)
     arg2 = trigger.group(4)
 

sopel/modules/reddit.py

@@ -217,7 +217,7 @@ def say_post_info(bot, trigger, id_, show_link=True, show_comments_link=False):
 @plugin.url(comment_url)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def comment_info(bot, trigger, match):
-    """Shows information about the linked comment"""
+    """Show information about the linked comment."""
     try:
         c = bot.memory['reddit_praw'].comment(match.group(1))
     except prawcore.exceptions.NotFound:
@@ -250,7 +250,7 @@ def comment_info(bot, trigger, match):
 
 
 def subreddit_info(bot, trigger, match, commanded=False):
-    """Shows information about the given subreddit"""
+    """Show information about the given subreddit."""
     match_lower = match.lower()
     if match_lower in ['all', 'popular']:
         message = ('[REDDIT] {link}{nsfw} | {public_description}')
@@ -313,7 +313,7 @@ def subreddit_info(bot, trigger, match, commanded=False):
 
 
 def redditor_info(bot, trigger, match, commanded=False):
-    """Shows information about the given Redditor"""
+    """Show information about the given Redditor."""
     try:
         u = bot.memory['reddit_praw'].redditor(match)
         u.id  # shortcut to check if the user exists or not

sopel/modules/reload.py

@@ -36,7 +36,7 @@ def _load(bot, plugin):
 @plugin.require_admin
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def f_reload(bot, trigger):
-    """Reloads a plugin (for use by admins only)."""
+    """Reload a plugin (for use by admins only)."""
     name = trigger.group(2)
 
     if not name or name == '*' or name.upper() == 'ALL THE THINGS':
@@ -61,7 +61,7 @@ def f_reload(bot, trigger):
 @plugin.require_admin
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def f_update(bot, trigger):
-    """Pulls the latest versions of all plugins from Git (for use by admins only)."""
+    """Pull the latest versions of all plugins from Git (for use by admins only)."""
     proc = subprocess.Popen('/usr/bin/git pull',
                             stdout=subprocess.PIPE,
                             stderr=subprocess.PIPE, shell=True)
@@ -76,7 +76,7 @@ def f_update(bot, trigger):
 @plugin.require_admin
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def f_load(bot, trigger):
-    """Loads a plugin (for use by admins only)."""
+    """Load a plugin (for use by admins only)."""
     name = trigger.group(2)
     if not name:
         bot.reply('Load what?')

sopel/modules/remind.py

@@ -220,7 +220,7 @@ def remind_monitoring(bot):
 @plugin.command('in')
 @plugin.example('.in 3h45m Go to class')
 def remind_in(bot, trigger):
-    """Gives you a reminder in the given amount of time."""
+    """Give you a reminder in the given amount of time."""
     if not trigger.group(2):
         bot.reply("Missing arguments for reminder command.")
         return plugin.NOLIMIT
@@ -454,7 +454,7 @@ def parse_regex_match(match, default_timezone=None):
                 user_help=True)
 @plugin.example('.at 00:01 25/12 Open your gift!', user_help=True)
 def remind_at(bot, trigger):
-    """Gives you a reminder at the given time.
+    """Give you a reminder at the given time.
 
     Takes ``hh:mm:ssTimezone Date message`` where seconds, Timezone, and Date
     are optional.

sopel/modules/safety.py

@@ -120,7 +120,7 @@ def _download_malwaredomains_db(path):
 @plugin.priority('high')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def url_handler(bot, trigger):
-    """Checks for malicious URLs"""
+    """Check for malicious URLs."""
     check = True    # Enable URL checking
     strict = False  # Strict mode: kick on malicious URL
     positives = 0   # Number of engines saying it's malicious
@@ -228,7 +228,7 @@ def toggle_safety(bot, trigger):
 # Code above also calls this if there are too many cache entries
 @plugin.interval(24 * 60 * 60)
 def _clean_cache(bot):
-    """Cleans up old entries in URL safety cache."""
+    """Clean up old entries in URL safety cache."""
     if bot.memory['safety_cache_lock'].acquire(False):
         LOGGER.info('Starting safety cache cleanup...')
         try:

sopel/modules/search.py

@@ -91,7 +91,7 @@ def duck_api(query):
     vcr=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def duck(bot, trigger):
-    """Queries DuckDuckGo for the specified input."""
+    """Query DuckDuckGo for the specified input."""
     query = trigger.group(2)
     if not query:
         bot.reply('{prefix}{command} what?'.format(
@@ -126,7 +126,7 @@ def duck(bot, trigger):
 @plugin.example('.bing sopel.chat irc bot')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def bing(bot, trigger):
-    """Queries Bing for the specified input."""
+    """Query Bing for the specified input."""
     if not trigger.group(2):
         bot.reply('{}bing what?'.format(bot.settings.core.help_prefix))
         return
@@ -142,7 +142,7 @@ def bing(bot, trigger):
 @plugin.example('.search sopel irc bot')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def search(bot, trigger):
-    """Searches both Bing and DuckDuckGo."""
+    """Search both Bing and DuckDuckGo."""
     if not trigger.group(2):
         bot.reply('{}search for what?'.format(bot.settings.core.help_prefix))
         return
@@ -168,7 +168,7 @@ def search(bot, trigger):
 @plugin.example('.suggest lkashdfiauwgaef', 'Sorry, no result.', online=True, vcr=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def suggest(bot, trigger):
-    """Suggests terms starting with given input"""
+    """Suggest terms starting with given input."""
     if not trigger.group(2):
         bot.reply('{}suggest what?'.format(bot.settings.core.help_prefix))
         return

sopel/modules/seen.py

@@ -20,7 +20,7 @@
 @plugin.command('seen')
 @plugin.output_prefix('[seen] ')
 def seen(bot, trigger):
-    """Reports when and where the user was last seen."""
+    """Report when and where the user was last seen."""
     if not trigger.group(2):
         bot.reply(
             "Use `%sseen <nick>` to know when <nick> was last seen."

sopel/modules/translate.py

@@ -86,7 +86,7 @@ def translate(text, in_lang='auto', out_lang='en'):
 @plugin.priority('low')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def tr(bot, trigger):
-    """Translates a phrase, with an optional language hint."""
+    """Translate a phrase, with an optional language hint."""
     in_lang, out_lang, phrase = trigger.groups()
 
     if (len(phrase) > 350) and (not trigger.admin):
@@ -136,7 +136,7 @@ def tr(bot, trigger):
                 online=True, vcr=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def tr2(bot, trigger):
-    """Translates a phrase, with an optional language hint."""
+    """Translate a phrase, with an optional language hint."""
     command = trigger.group(2)
 
     if not command:

sopel/modules/url.py

@@ -386,7 +386,7 @@ def get_or_create_shorturl(bot, url):
 
 
 def get_tinyurl(url):
-    """Returns a shortened tinyURL link of the URL."""
+    """Return a shortened tinyURL link of the URL."""
     base_url = "https://tinyurl.com/api-create.php"
     tinyurl = "%s?%s" % (base_url, web.urlencode({'url': url}))
     try:

sopel/modules/wikipedia.py

@@ -168,7 +168,7 @@ def say_snippet(bot, trigger, server, query, show_url=True):
 
 
 def mw_snippet(server, query):
-    """Retrieves a snippet of the given page from the given MediaWiki server."""
+    """Retrieve a snippet of the given page from the given MediaWiki server."""
     snippet_url = ('https://' + server + '/w/api.php?format=json'
                    '&action=query&prop=extracts&exintro&explaintext'
                    '&exchars=300&redirects&titles=')
@@ -242,7 +242,7 @@ def mw_section(server, query, section):
 @plugin.url(r'https?:\/\/([a-z]+\.wikipedia\.org)\/wiki\/((?!File\:)[^ #]+)#?([^ ]*)')
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def mw_info(bot, trigger, match=None):
-    """Retrieves and outputs a snippet of the linked page."""
+    """Retrieve and outputs a snippet of the linked page."""
     if match.group(3):
         if match.group(3).startswith('cite_note-'):  # Don't bother trying to retrieve a snippet when cite-note is linked
             say_snippet(bot, trigger, match.group(1), unquote(match.group(2)), show_url=False)

sopel/modules/xkcd.py

@@ -59,7 +59,7 @@ def web_search(query):
 @plugin.example(".xkcd", user_help=True)
 @plugin.output_prefix(PLUGIN_OUTPUT_PREFIX)
 def xkcd(bot, trigger):
-    """Finds an xkcd comic strip.
+    """Find an xkcd comic strip.
 
     Takes one of 3 inputs:
 

sopel/plugin.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""This contains decorators and other tools for creating Sopel plugins."""
+"""Decorators and other tools for creating Sopel plugins."""
 # Copyright 2013, Ari Koivula, <ari@koivu.la>
 # Copyright © 2013, Elad Alfassa <elad@fedoraproject.org>
 # Copyright 2013, Lior Ramati <firerogue517@gmail.com>

sopel/test_tools.py

@@ -1,5 +1,5 @@
 # coding=utf-8
-"""This module has classes and functions that can help in writing tests.
+"""Classes and functions that can help in writing tests.
 
 .. note::
 

sopel/tools/web.py

@@ -148,7 +148,7 @@ def quote(string, safe='/'):
 
 # six-like shim for Unicode safety
 def unquote(string):
-    """Decodes a URL-encoded string.
+    """Decode a URL-encoded string.
 
     :param str string: the string to decode
     :return str: the decoded ``string``
@@ -185,7 +185,7 @@ def urlencode_non_ascii(b):
 
 
 def iri_to_uri(iri):
-    """Decodes an internationalized domain name (IDN)."""
+    """Decode an internationalized domain name (IDN)."""
     parts = urlparse(iri)
     parts_seq = (part.encode('idna') if parti == 1 else urlencode_non_ascii(part.encode('utf-8')) for parti, part in enumerate(parts))
     if sys.version_info.major > 2:
@@ -207,7 +207,7 @@ def iri_to_uri(iri):
 # Functions for URL detection
 
 def trim_url(url):
-    """Removes extra punctuation from URLs found in text.
+    """Remove extra punctuation from URLs found in text.
 
     :param str url: the raw URL match
     :return str: the cleaned URL
@@ -234,7 +234,7 @@ def trim_url(url):
 
 
 def search_urls(text, exclusion_char=None, clean=False, schemes=None):
-    """Extracts all URLs in ``text``.
+    """Extract all URLs in ``text``.
 
     :param str text: the text to search for URLs
     :param str exclusion_char: optional character that, if placed before a URL