Docstring pass for Valentine's cogs

9 files changed, 73 insertions, 57 deletions

diff --git a/bot/seasons/valentines/__init__.py b/bot/seasons/valentines/__init__.py
index f1489cf9..e3e04421 100644
--- a/bot/seasons/valentines/__init__.py
+++ b/bot/seasons/valentines/__init__.py
@@ -8,6 +8,7 @@ class Valentines(SeasonBase):
 
     Get yourself into the bot-commands channel and check out the new features!
     """
+
     name = "valentines"
     bot_name = "Tenderbot"
     greeting = "Get loved-up!"
diff --git a/bot/seasons/valentines/be_my_valentine.py b/bot/seasons/valentines/be_my_valentine.py
index 0046ceb4..6abccceb 100644
--- a/bot/seasons/valentines/be_my_valentine.py
+++ b/bot/seasons/valentines/be_my_valentine.py
@@ -16,9 +16,7 @@ HEART_EMOJIS = [":heart:", ":gift_heart:", ":revolving_hearts:", ":sparkling_hea
 
 
 class BeMyValentine:
-    """
-    A cog that sends valentines to other users !
-    """
+    """A cog that sends Valentines to other users."""
 
     def __init__(self, bot):
         self.bot = bot
@@ -26,6 +24,8 @@ class BeMyValentine:
 
     @staticmethod
     def load_json():
+        """Load Valentines messages from the static resources."""
+
         p = Path('bot', 'resources', 'valentines', 'bemyvalentine_valentines.json')
         with p.open() as json_data:
             valentines = load(json_data)
@@ -34,19 +34,20 @@ class BeMyValentine:
     @commands.group(name="lovefest", invoke_without_command=True)
     async def lovefest_role(self, ctx):
         """
-        You can have yourself the lovefest role or remove it.
+        Subscribe or unsubscribe from the lovefest role.
+
         The lovefest role makes you eligible to receive anonymous valentines from other users.
 
         1) use the command \".lovefest sub\" to get the lovefest role.
         2) use the command \".lovefest unsub\" to get rid of the lovefest role.
         """
+
         await ctx.invoke(self.bot.get_command("help"), "lovefest")
 
     @lovefest_role.command(name="sub")
     async def add_role(self, ctx):
-        """
-        This command adds the lovefest role.
-        """
+        """Adds the lovefest role."""
+
         user = ctx.author
         role = discord.utils.get(ctx.guild.roles, id=Lovefest.role_id)
         if Lovefest.role_id not in [role.id for role in ctx.message.author.roles]:
@@ -57,9 +58,8 @@ class BeMyValentine:
 
     @lovefest_role.command(name="unsub")
     async def remove_role(self, ctx):
-        """
-        This command removes the lovefest role.
-        """
+        """Removes the lovefest role."""
+
         user = ctx.author
         role = discord.utils.get(ctx.guild.roles, id=Lovefest.role_id)
         if Lovefest.role_id not in [role.id for role in ctx.message.author.roles]:
@@ -72,7 +72,7 @@ class BeMyValentine:
     @commands.group(name='bemyvalentine', invoke_without_command=True)
     async def send_valentine(self, ctx, user: typing.Optional[discord.Member] = None, *, valentine_type=None):
         """
-        This command sends valentine to user if specified or a random user having lovefest role.
+        Send a valentine to user, if specified, or to a random user with the lovefest role.
 
         syntax: .bemyvalentine [user](optional) [p/poem/c/compliment/or you can type your own valentine message]
         (optional)
@@ -119,7 +119,7 @@ class BeMyValentine:
     @send_valentine.command(name='secret')
     async def anonymous(self, ctx, user: typing.Optional[discord.Member] = None, *, valentine_type=None):
         """
-        This command DMs a valentine to be given anonymous to a user if specified or a random user having lovefest role.
+        Send an anonymous Valentine via DM to to a user, if specified, or to a random with the lovefest role.
 
         **This command should be DMed to the bot.**
 
@@ -171,6 +171,8 @@ class BeMyValentine:
             await ctx.author.send(f"Your message has been sent to {user}")
 
     def valentine_check(self, valentine_type):
+        """Return the appropriate Valentine type & title based on the invoking user's input."""
+
         if valentine_type is None:
             valentine, title = self.random_valentine()
 
@@ -191,12 +193,14 @@ class BeMyValentine:
     @staticmethod
     def random_user(author, members):
         """
-        Picks a random member from the list provided in `members`, ensuring
-        the author is not one of the options.
+        Picks a random member from the list provided in `members`.
+
+        The invoking author is ignored.
 
         :param author: member who invoked the command
         :param members: list of discord.Member objects
         """
+
         if author in members:
             members.remove(author)
 
@@ -204,14 +208,15 @@ class BeMyValentine:
 
     @staticmethod
     def random_emoji():
+        """Return two random emoji from the module-defined constants."""
+
         EMOJI_1 = random.choice(HEART_EMOJIS)
         EMOJI_2 = random.choice(HEART_EMOJIS)
         return EMOJI_1, EMOJI_2
 
     def random_valentine(self):
-        """
-        Grabs a random poem or a compliment (any message).
-        """
+        """Grabs a random poem or a compliment (any message)."""
+
         valentine_poem = random.choice(self.valentines['valentine_poems'])
         valentine_compliment = random.choice(self.valentines['valentine_compliments'])
         random_valentine = random.choice([valentine_compliment, valentine_poem])
@@ -222,20 +227,20 @@ class BeMyValentine:
         return random_valentine, title
 
     def valentine_poem(self):
-        """
-        Grabs a random poem.
-        """
+        """Grabs a random poem."""
+
         valentine_poem = random.choice(self.valentines['valentine_poems'])
         return valentine_poem
 
     def valentine_compliment(self):
-        """
-        Grabs a random compliment.
-        """
+        """Grabs a random compliment."""
+
         valentine_compliment = random.choice(self.valentines['valentine_compliments'])
         return valentine_compliment
 
 
 def setup(bot):
+    """Be my Valentine Cog load."""
+
     bot.add_cog(BeMyValentine(bot))
     log.debug("Be My Valentine cog loaded")
diff --git a/bot/seasons/valentines/lovecalculator.py b/bot/seasons/valentines/lovecalculator.py
index 4df33b93..56cb551d 100644
--- a/bot/seasons/valentines/lovecalculator.py
+++ b/bot/seasons/valentines/lovecalculator.py
@@ -21,9 +21,7 @@ with Path('bot', 'resources', 'valentines', 'love_matches.json').open() as file:
 
 
 class LoveCalculator:
-    """
-    A cog for calculating the love between two people
-    """
+    """A cog for calculating the love between two people."""
 
     def __init__(self, bot):
         self.bot = bot
@@ -103,4 +101,6 @@ class LoveCalculator:
 
 
 def setup(bot):
+    """Love calculator Cog load."""
+
     bot.add_cog(LoveCalculator(bot))
diff --git a/bot/seasons/valentines/movie_generator.py b/bot/seasons/valentines/movie_generator.py
index b52eba7f..19fbf25e 100644
--- a/bot/seasons/valentines/movie_generator.py
+++ b/bot/seasons/valentines/movie_generator.py
@@ -12,18 +12,15 @@ log = logging.getLogger(__name__)
 
 
 class RomanceMovieFinder:
-    """
-    A cog that returns a random romance movie suggestion to a user
-    """
+    """A cog that returns a random romance movie suggestion to a user."""
 
     def __init__(self, bot):
         self.bot = bot
 
     @commands.command(name="romancemovie")
     async def romance_movie(self, ctx):
-        """
-        Randomly selects a romance movie and displays information about it
-        """
+        """Randomly selects a romance movie and displays information about it."""
+
         # selecting a random int to parse it to the page parameter
         random_page = random.randint(0, 20)
         # TMDB api params
@@ -62,5 +59,7 @@ class RomanceMovieFinder:
 
 
 def setup(bot):
+    """Romance movie Cog load."""
+
     bot.add_cog(RomanceMovieFinder(bot))
     log.debug("Random romance movie cog loaded!")
diff --git a/bot/seasons/valentines/myvalenstate.py b/bot/seasons/valentines/myvalenstate.py
index 9f06553d..46fdebbc 100644
--- a/bot/seasons/valentines/myvalenstate.py
+++ b/bot/seasons/valentines/myvalenstate.py
@@ -16,13 +16,14 @@ with open(Path('bot', 'resources', 'valentines', 'valenstates.json'), 'r') as fi
 
 
 class MyValenstate:
+    """A Cog to find your most likely Valentine's vacation destination."""
+
     def __init__(self, bot):
         self.bot = bot
 
     def levenshtein(self, source, goal):
-        """
-        Calculates the Levenshtein Distance between source and goal.
-        """
+        """Calculates the Levenshtein Distance between source and goal."""
+
         if len(source) < len(goal):
             return self.levenshtein(goal, source)
         if len(source) == 0:
@@ -43,6 +44,8 @@ class MyValenstate:
 
     @commands.command()
     async def myvalenstate(self, ctx, *, name=None):
+        """Find the vacation spot(s) with the most matching characters to the invoking user."""
+
         eq_chars = collections.defaultdict(int)
         if name is None:
             author = ctx.message.author.name.lower().replace(' ', '')
@@ -81,5 +84,7 @@ class MyValenstate:
 
 
 def setup(bot):
+    """Valenstate Cog load."""
+
     bot.add_cog(MyValenstate(bot))
     log.debug("MyValenstate cog loaded")
diff --git a/bot/seasons/valentines/pickuplines.py b/bot/seasons/valentines/pickuplines.py
index 4462478f..bce5cdcc 100644
--- a/bot/seasons/valentines/pickuplines.py
+++ b/bot/seasons/valentines/pickuplines.py
@@ -15,9 +15,7 @@ with open(Path('bot', 'resources', 'valentines', 'pickup_lines.json'), 'r', enco
 
 
 class PickupLine:
-    """
-    A cog that gives random cheesy pickup lines.
-    """
+    """A cog that gives random cheesy pickup lines."""
 
     def __init__(self, bot):
         self.bot = bot
@@ -25,8 +23,11 @@ class PickupLine:
     @commands.command()
     async def pickupline(self, ctx):
         """
-        Gives you a random pickup line. Note that most of them are very cheesy!
+        Gives you a random pickup line.
+
+        Note that most of them are very cheesy.
         """
+
         random_line = random.choice(pickup_lines['lines'])
         embed = discord.Embed(
             title=':cheese: Your pickup line :cheese:',
@@ -40,5 +41,7 @@ class PickupLine:
 
 
 def setup(bot):
+    """Pickup lines Cog load."""
+
     bot.add_cog(PickupLine(bot))
     log.info('Pickup line cog loaded')
diff --git a/bot/seasons/valentines/savethedate.py b/bot/seasons/valentines/savethedate.py
index b9484be9..d296a23e 100644
--- a/bot/seasons/valentines/savethedate.py
+++ b/bot/seasons/valentines/savethedate.py
@@ -14,18 +14,15 @@ HEART_EMOJIS = [":heart:", ":gift_heart:", ":revolving_hearts:", ":sparkling_hea
 
 
 class SaveTheDate:
-    """
-    A cog that gives random suggestion, for a valentines date !
-    """
+    """A cog that gives random suggestion for a Valentine's date."""
 
     def __init__(self, bot):
         self.bot = bot
 
     @commands.command()
     async def savethedate(self, ctx):
-        """
-        Gives you ideas for what to do on a date with your valentine.
-        """
+        """Gives you ideas for what to do on a date with your valentine."""
+
         with open(Path('bot', 'resources', 'valentines', 'date_ideas.json'), 'r', encoding="utf8") as f:
             valentine_dates = load(f)
             random_date = random.choice(valentine_dates['ideas'])
@@ -40,5 +37,7 @@ class SaveTheDate:
 
 
 def setup(bot):
+    """Save the date Cog Load."""
+
     bot.add_cog(SaveTheDate(bot))
     log.debug("Save the date cog loaded")
diff --git a/bot/seasons/valentines/valentine_zodiac.py b/bot/seasons/valentines/valentine_zodiac.py
index 06c0237d..e18196fc 100644
--- a/bot/seasons/valentines/valentine_zodiac.py
+++ b/bot/seasons/valentines/valentine_zodiac.py
@@ -15,15 +15,16 @@ HEART_EMOJIS = [":heart:", ":gift_heart:", ":revolving_hearts:", ":sparkling_hea
 
 
 class ValentineZodiac:
-    """
-    A cog that returns a counter compatible zodiac sign to the given user's zodiac sign.
-    """
+    """A cog that returns a counter compatible zodiac sign to the given user's zodiac sign."""
+
     def __init__(self, bot):
         self.bot = bot
         self.zodiacs = self.load_json()
 
     @staticmethod
     def load_json():
+        """Load Zodiac compatibility from static JSON resource."""
+
         p = Path('bot', 'resources', 'valentines', 'zodiac_compatibility.json')
         with p.open() as json_data:
             zodiacs = load(json_data)
@@ -31,9 +32,8 @@ class ValentineZodiac:
 
     @commands.command(name="partnerzodiac")
     async def counter_zodiac(self, ctx, zodiac_sign):
-        """
-        Provides a counter compatible zodiac sign to the given user's zodiac sign.
-        """
+        """Provides a counter compatible zodiac sign to the given user's zodiac sign."""
+
         try:
             compatible_zodiac = random.choice(self.zodiacs[zodiac_sign.lower()])
         except KeyError:
@@ -55,5 +55,7 @@ class ValentineZodiac:
 
 
 def setup(bot):
+    """Valentine Zodiac Cog load."""
+
     bot.add_cog(ValentineZodiac(bot))
     log.debug("Valentine Zodiac cog loaded")
diff --git a/bot/seasons/valentines/whoisvalentine.py b/bot/seasons/valentines/whoisvalentine.py
index 2fe07aba..9ac2ee94 100644
--- a/bot/seasons/valentines/whoisvalentine.py
+++ b/bot/seasons/valentines/whoisvalentine.py
@@ -15,14 +15,15 @@ with open(Path("bot", "resources", "valentines", "valentine_facts.json"), "r") a
 
 
 class ValentineFacts:
+    """A Cog for displaying facts about Saint Valentine."""
+
     def __init__(self, bot):
         self.bot = bot
 
     @commands.command(aliases=('whoisvalentine', 'saint_valentine'))
     async def who_is_valentine(self, ctx):
-        """
-        Displays info about Saint Valentine.
-        """
+        """Displays info about Saint Valentine."""
+
         embed = discord.Embed(
             title="Who is Saint Valentine?",
             description=FACTS['whois'],
@@ -37,9 +38,8 @@ class ValentineFacts:
 
     @commands.command()
     async def valentine_fact(self, ctx):
-        """
-        Shows a random fact about Valentine's Day.
-        """
+        """Shows a random fact about Valentine's Day."""
+
         embed = discord.Embed(
             title=choice(FACTS['titles']),
             description=choice(FACTS['text']),
@@ -50,4 +50,6 @@ class ValentineFacts:
 
 
 def setup(bot):
+    """Who is Valentine Cog load."""
+
     bot.add_cog(ValentineFacts(bot))