Added docstring for changelog.py

Author: Taaku18

bot.py

@@ -40,7 +40,7 @@
 from emoji import UNICODE_EMOJI
 from motor.motor_asyncio import AsyncIOMotorClient
 
-from core.changelog import ChangeLog
+from core.changelog import Changelog
 from core.clients import ModmailApiClient, SelfHostedClient
 from core.config import ConfigManager
 from core.models import Bot
@@ -657,7 +657,7 @@ async def autoupdate_loop(self):
                 embed.set_footer(text=f"Updating Modmail v{self.version} "
                                       f"-> v{metadata['latest_version']}")
 
-                changelog = await ChangeLog.from_repo(self)
+                changelog = await Changelog.from_url(self)
                 latest = changelog.latest_version
                 embed.description = latest.description
                 for name, value in latest.fields.items():

cogs/utility.py

@@ -13,7 +13,7 @@
 from discord.ext import commands
 
 from core import checks
-from core.changelog import ChangeLog
+from core.changelog import Changelog
 from core.decorators import github_access_token_required, trigger_typing
 from core.models import Bot
 from core.paginator import PaginatorSession
@@ -135,7 +135,7 @@ async def help(self, ctx, *, command: str = None):
     @trigger_typing
     async def changelog(self, ctx):
         """Show a paginated changelog of the bot."""
-        changelog = await ChangeLog.from_repo(self.bot)
+        changelog = await Changelog.from_url(self.bot)
         paginator = PaginatorSession(ctx, *changelog.embeds)
         await paginator.run()
 
@@ -253,7 +253,7 @@ async def update(self, ctx):
                 embed.set_author(name=user['username'] + ' - Updating bot',
                                  icon_url=user['avatar_url'],
                                  url=user['url'])
-                changelog = await ChangeLog.from_repo(self.bot)
+                changelog = await Changelog.from_url(self.bot)
                 latest = changelog.latest_version
                 embed.description = latest.description
                 for name, value in latest.fields.items():

core/changelog.py

@@ -8,6 +8,32 @@
 
 
 class Version:
+    """
+    This class represents a single version of Modmail.
+
+    Parameters
+    ----------
+    bot : Bot
+        The Modmail bot.
+    version : str
+        The version string (ie. "v2.12.0").
+    lines : str
+        The lines of changelog messages for this version.
+
+    Attributes
+    ----------
+    bot : Bot
+        The Modmail bot.
+    version : str
+        The version string (ie. "v2.12.0").
+    lines : List[str]
+        A list of lines of changelog messages for this version.
+    fields : defaultdict[str, str]
+        A dict of fields separated by "Fixed", "Changed", etc sections.
+    description : str
+        General description of the version.
+    """
+
     def __init__(self, bot: Bot, version: str, lines: str):
         self.bot = bot
         self.version = version
@@ -20,6 +46,13 @@ def __repr__(self) -> str:
         return f'Version({self.version}, description="{self.description}")'
 
     def parse(self) -> None:
+        """
+        Parse the lines and split them into `description` and `fields`.
+.
+        Returns
+        -------
+        None
+        """
         curr_action = None
 
         for line in self.lines:
@@ -32,6 +65,9 @@ def parse(self) -> None:
 
     @property
     def embed(self) -> Embed:
+        """
+        Embed: the formatted `Embed` of this `Version`.
+        """
         embed = Embed(color=Color.green(), description=self.description)
         embed.set_author(
             name=f'{self.version} - Changelog',
@@ -46,31 +82,81 @@ def embed(self) -> Embed:
         return embed
 
 
-class ChangeLog:
-    changelog_url = ('https://raw.githubusercontent.com/'
+class Changelog:
+    """
+    This class represents the complete changelog of Modmail.
+
+    Parameters
+    ----------
+    bot : Bot
+        The Modmail bot.
+    text : str
+        The complete changelog text.
+
+    Attributes
+    ----------
+    bot : Bot
+        The Modmail bot.
+    text : str
+        The complete changelog text.
+    versions : List[Version]
+        A list of `Version`'s within the changelog.
+
+    Class Attributes
+    ----------------
+    CHANGELOG_URL : str
+        The URL to Modmail changelog.
+    VERSION_REGEX : re.Pattern
+        The regex used to parse the versions.
+    """
+
+    CHANGELOG_URL = ('https://raw.githubusercontent.com/'
                      'kyb3r/modmail/master/CHANGELOG.md')
-    regex = re.compile(r'# (v\d+\.\d+\.\d+)([\S\s]*?(?=# v|$))')
+    VERSION_REGEX = re.compile(r'# (v\d+\.\d+\.\d+)([\S\s]*?(?=# v|$))')
 
     def __init__(self, bot: Bot, text: str):
         self.bot = bot
         self.text = text
-        self.versions = [Version(bot, *m) for m in self.regex.findall(text)]
+        self.versions = [Version(bot, *m)
+                         for m in self.VERSION_REGEX.findall(text)]
 
     @property
     def latest_version(self) -> Version:
+        """
+        Version: The latest `Version` of the `Changelog`.
+        """
         return self.versions[0]
 
     @property
     def embeds(self) -> List[Embed]:
+        """
+        List[Embed]: A list of `Embed`'s for each of the `Version`.
+        """
         return [v.embed for v in self.versions]
 
     @classmethod
-    async def from_repo(cls, bot, url: str = '') -> 'ChangeLog':
-        url = url or cls.changelog_url
+    async def from_url(cls, bot: Bot, url: str = '') -> 'Changelog':
+        """
+        Create a `Changelog` from a URL.
+
+        Parameters
+        ----------
+        bot : Bot
+            The Modmail bot.
+        url : str, optional
+            Defaults to `CHANGELOG_URL`.
+            The URL to the changelog.
+
+        Returns
+        -------
+        Changelog
+            The newly created `Changelog` parsed from the `url`.
+        """
+        url = url or cls.CHANGELOG_URL
         resp = await bot.session.get(url)
         return cls(bot, await resp.text())
 
 
 if __name__ == '__main__':
     with open('../CHANGELOG.md') as f:
-        print(ChangeLog(..., f.read()).latest_version)
+        print(Changelog(..., f.read()).latest_version)