From b0ce68cb5a4c5d805d7bbd7389e2f18889d96a7a Mon Sep 17 00:00:00 2001 From: mal Date: Sat, 31 Oct 2020 22:10:04 +0000 Subject: [PATCH] quality: docstring tense, mood, tweaks --- sopel/modules/admin.py | 12 ++++++------ sopel/modules/choose.py | 2 +- sopel/modules/clock.py | 12 ++++++------ sopel/modules/countdown.py | 2 +- sopel/modules/currency.py | 6 ++++-- sopel/modules/dice.py | 4 ++-- sopel/modules/help.py | 4 ++-- sopel/modules/rand.py | 2 +- sopel/modules/reddit.py | 6 +++--- sopel/modules/reload.py | 6 +++--- sopel/modules/remind.py | 4 ++-- sopel/modules/safety.py | 4 ++-- sopel/modules/search.py | 8 ++++---- sopel/modules/seen.py | 2 +- sopel/modules/translate.py | 4 ++-- sopel/modules/url.py | 2 +- sopel/modules/wikipedia.py | 4 ++-- sopel/modules/xkcd.py | 2 +- sopel/plugin.py | 2 +- sopel/test_tools.py | 2 +- sopel/tools/web.py | 8 ++++---- test/cli/test_cli_utils.py | 2 +- test/test_tools.py | 2 +- 23 files changed, 52 insertions(+), 50 deletions(-) diff --git a/sopel/modules/admin.py b/sopel/modules/admin.py index 77191163fe..909d0fe643 100644 --- a/sopel/modules/admin.py +++ b/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 diff --git a/sopel/modules/choose.py b/sopel/modules/choose.py index 95e251db00..04a6334504 100644 --- a/sopel/modules/choose.py +++ b/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 diff --git a/sopel/modules/clock.py b/sopel/modules/clock.py index 493f5e0d45..abcd141866 100644 --- a/sopel/modules/clock.py +++ b/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 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 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. """ diff --git a/sopel/modules/countdown.py b/sopel/modules/countdown.py index 2b06f391fc..468edcfbb7 100644 --- a/sopel/modules/countdown.py +++ b/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" diff --git a/sopel/modules/currency.py b/sopel/modules/currency.py index d4a7aaf9e1..50b93830b4 100644 --- a/sopel/modules/currency.py +++ b/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) diff --git a/sopel/modules/dice.py b/sopel/modules/dice.py index 5f571c6144..338738ec03 100644 --- a/sopel/modules/dice.py +++ b/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] diff --git a/sopel/modules/help.py b/sopel/modules/help.py index ee6b6a2fca..e9ceb2c1b9 100644 --- a/sopel/modules/help.py +++ b/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. """ diff --git a/sopel/modules/rand.py b/sopel/modules/rand.py index d7f8d8aba1..995c848f80 100644 --- a/sopel/modules/rand.py +++ b/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) diff --git a/sopel/modules/reddit.py b/sopel/modules/reddit.py index 84f7a27fc6..3d6b38544f 100644 --- a/sopel/modules/reddit.py +++ b/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 diff --git a/sopel/modules/reload.py b/sopel/modules/reload.py index 893372d40f..88b7244d7c 100644 --- a/sopel/modules/reload.py +++ b/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?') diff --git a/sopel/modules/remind.py b/sopel/modules/remind.py index ef74594752..14cdcaa7a7 100644 --- a/sopel/modules/remind.py +++ b/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. diff --git a/sopel/modules/safety.py b/sopel/modules/safety.py index 0c439c00cb..907f7ee2fb 100644 --- a/sopel/modules/safety.py +++ b/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: diff --git a/sopel/modules/search.py b/sopel/modules/search.py index 09ab4d8263..23c0683264 100644 --- a/sopel/modules/search.py +++ b/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 diff --git a/sopel/modules/seen.py b/sopel/modules/seen.py index 02eeb6bd4a..6cae52a88c 100644 --- a/sopel/modules/seen.py +++ b/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 ` to know when was last seen." diff --git a/sopel/modules/translate.py b/sopel/modules/translate.py index ce769a25c4..982b473549 100644 --- a/sopel/modules/translate.py +++ b/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: diff --git a/sopel/modules/url.py b/sopel/modules/url.py index 515cb1c25b..26fc114a22 100644 --- a/sopel/modules/url.py +++ b/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: diff --git a/sopel/modules/wikipedia.py b/sopel/modules/wikipedia.py index 1e017d42e0..47c6aa1b8b 100644 --- a/sopel/modules/wikipedia.py +++ b/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) diff --git a/sopel/modules/xkcd.py b/sopel/modules/xkcd.py index 804292c8b5..a747afe97e 100644 --- a/sopel/modules/xkcd.py +++ b/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: diff --git a/sopel/plugin.py b/sopel/plugin.py index 8c08846845..5ae82743d2 100644 --- a/sopel/plugin.py +++ b/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, # Copyright © 2013, Elad Alfassa # Copyright 2013, Lior Ramati diff --git a/sopel/test_tools.py b/sopel/test_tools.py index 9ddad1c9a1..cf939bd8bc 100644 --- a/sopel/test_tools.py +++ b/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:: diff --git a/sopel/tools/web.py b/sopel/tools/web.py index 70d7b63147..cabea001b5 100644 --- a/sopel/tools/web.py +++ b/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 diff --git a/test/cli/test_cli_utils.py b/test/cli/test_cli_utils.py index 37eda9929e..151f2adf33 100644 --- a/test/cli/test_cli_utils.py +++ b/test/cli/test_cli_utils.py @@ -1,5 +1,5 @@ # coding=utf-8 -"""Tests for sopel.cli.utils""" +"""Tests for ``sopel.cli.utils``.""" from __future__ import absolute_import, division, print_function, unicode_literals import argparse diff --git a/test/test_tools.py b/test/test_tools.py index fb13992021..9786d6ef65 100644 --- a/test/test_tools.py +++ b/test/test_tools.py @@ -1,5 +1,5 @@ # coding=utf-8 -"""Tests sopel.tools""" +"""Tests for ``sopel.tools``.""" from __future__ import absolute_import, division, print_function, unicode_literals from datetime import timedelta