Add file docstrings to every .py file, improved exception docstrings, helper func typehint

bot/blackjack.py

@@ -1,3 +1,9 @@
+"""
+blackjack.py
+
+Stores classes and functions used for accessing Basic Blackjack Strategy, parsing Embed data and anything else
+related to Blackjack.
+"""
 import logging
 import os
 import re
@@ -14,8 +20,7 @@ logger.setLevel(constants.LOGGING_LEVEL)
 class Card(object):
     _suits = {'H': 'Hearts', 'S': 'Spades', 'C': 'Clubs', 'D': 'Diamonds'}
     _symbols = {'10': 'Ten', '9': 'Nine', '8': 'Eight', '7': 'Seven', '6': 'Six', '5': 'Five', '4': 'Four',
-                '3': 'Three',
-                '2': 'Two', 'k': 'King', 'q': 'Queen', 'j': 'Jack', 'a': 'Ace'}
+                '3': 'Three', '2': 'Two', 'k': 'King', 'q': 'Queen', 'j': 'Jack', 'a': 'Ace'}
 
     EMOTE_REGEX = re.compile(r'<:([A-z0-9]+):\d+>')
     VALUE_PATTERN = re.compile(r'Value: (?:Soft )?(\d+)')
@@ -44,7 +49,7 @@ class Card(object):
         elif self.isNumerical():
             return int(self.symbol)
         elif safe:
-            raise exceptions.IndetermineValue('Could not determine the numeric value of this card.')
+            raise exceptions.IndeterminateValue('Could not determine the numeric value of this card.')
         return unsafe_default
 
     def isAce(self) -> bool:

bot/client.py

@@ -1,3 +1,9 @@
+"""
+client.py
+
+Stores the primary client class, which accesses the Discord API and processes messages automatically.
+"""
+
 import ctypes
 import logging
 from typing import Optional

bot/constants.py

@@ -1,3 +1,9 @@
+"""
+constants.py
+
+Stores constants like paths to various locations, integers/strings or simple generated classes.
+"""
+
 import logging
 import os
 

bot/exceptions.py

@@ -1,22 +1,35 @@
+"""
+exceptions.py
+
+Stores exceptions in a single file for the rest of the project to use.
+"""
+
+
 class UnbelievableException(BaseException):
+    """Base project-wide exception"""
     pass
 
 
 class BlackjackException(UnbelievableException):
+    """Blackjack related exceptions inherit from this"""
     pass
 
 
 class NoAceValue(BlackjackException):
+    """The card was an ace and the program tried to acquire it's value - this should have been handled differently."""
     pass
 
 
-class IndetermineValue(BlackjackException):
+class IndeterminateValue(BlackjackException):
+    """The card's value could not be determined (likely a invalid card, or case sensitivity was ignored)."""
     pass
 
 
 class InvalidCard(BlackjackException):
+    """The card was fundamentally impossible in it's identifier."""
     pass
 
 
 class CooldownRequired(UnbelievableException):
+    """The program tried to activate/use a cooldown before it had ended."""
     pass

bot/helpers.py

@@ -1,3 +1,10 @@
+"""
+helpers.py
+
+Stores helper functions to assist the developer with common or complex operations in a separate file.
+Miscellaneous random (perhaps development-only) functions will be found here.
+"""
+
 from pprint import pprint
 from typing import Union
 
@@ -9,6 +16,6 @@ def print_embed(embed: discord.Embed) -> None:
     pprint((embed.title, embed.description, embed.footer, embed.color, embed.fields, embed.author, embed.timestamp))
 
 
-def embed_author_matches(embed: discord.Embed, user: Union[discord.User, discord.ClientUser]):
+def embed_author_matches(embed: discord.Embed, user: Union[discord.User, discord.ClientUser]) -> bool:
     """Returns if the Unbelievabot Embed relates to the given user."""
     return embed.author != discord.embeds.EmptyEmbed and embed.author.name == f'{user.name}#{user.discriminator}'

bot/parsers.py

@@ -1,3 +1,9 @@
+"""
+parsers.py
+
+Stores classes related to parsing and extracting information from different messages returned by UnbelievaBot.
+"""
+
 import logging
 import re
 from abc import ABC

bot/stats.py

@@ -1,3 +1,9 @@
+"""
+stats.py
+
+Holds classes and functions related to working with the database, i.e. storing statistics collected by the client.
+"""
+
 import asyncio
 import logging
 import sqlite3

bot/timings.py

@@ -1,6 +1,11 @@
+"""
+timings.py
+
+Holds classes related to maintaining consistent cooldowns for various commands and API operations.
+"""
+
 import asyncio
 import logging
-import time
 from datetime import datetime
 from typing import Union, Optional
 
@@ -60,8 +65,3 @@ class Cooldown(object):
         if self.hot_until:
             return now or datetime.utcnow().timestamp() >= self.hot_until
         return True
-
-
-class TimingHandler(object):
-    """A class for easily managing and working with cooldown timers."""
-    pass

main.py

@@ -1,3 +1,10 @@
+"""
+main.py
+
+The main launcher file for running the bot. Run python against the file, and specify the channel ID and the bot ID
+to be checked against. Also sets up logging for the rest of the project, and runs the client.
+"""
+
 import argparse
 import logging
 

stat_analysis.py

@@ -1,3 +1,9 @@
+"""
+stat_analysis.py
+
+A simple script for viewing income data from raw log data provided by the bot.
+"""
+
 import re
 
 import matplotlib.pyplot as plt