Added docstring for clients.py

Author: Taaku18

bot.py

@@ -636,7 +636,7 @@ async def autoupdate_loop(self):
             return
 
         if self.self_hosted and not self.config.get('github_access_token'):
-            print('Github access token not found.')
+            print('GitHub access token not found.')
             print('Autoupdates disabled.')
             print(LINE)
             return

cogs/utility.py

@@ -183,7 +183,7 @@ async def about(self, ctx):
             else:
                 footer = 'You are up to date with the latest version.'
 
-        embed.add_field(name='Github',
+        embed.add_field(name='GitHub',
                         value='https://github.com/kyb3r/modmail',
                         inline=False)
 
@@ -202,7 +202,7 @@ async def github(self, ctx):
         data = await self.bot.api.get_user_info()
 
         embed = Embed(
-            title='Github',
+            title='GitHub',
             description='Current User',
             color=Color.blurple()
         )

core/changelog.py

@@ -48,10 +48,6 @@ def __repr__(self) -> str:
     def parse(self) -> None:
         """
         Parse the lines and split them into `description` and `fields`.
-.
-        Returns
-        -------
-        None
         """
         curr_action = None
 

core/checks.py

@@ -7,6 +7,7 @@ def has_permissions(**perms):
 
     Examples
     --------
+    ::
         @has_permissions(administrator=True)
         async def setup(ctx):
             print("Success")
@@ -21,8 +22,8 @@ async def predicate(ctx):
 
         Returns
         -------
-        True
-            If the author is a bot owner, or
+        bool
+            `True` if the author is a bot owner, or
             has the ``administrator`` permission.
             Or if the author has all of the required permissions.
             Otherwise, `False`.
@@ -55,8 +56,8 @@ async def predicate(ctx):
 
         Returns
         -------
-        True
-            if the current `Context` is within a Modmail thread.
+        Bool
+            `True` if the current `Context` is within a Modmail thread.
             Otherwise, `False`.
         """
         return ctx.thread is not None

core/clients.py

@@ -5,11 +5,30 @@
 
 from aiohttp import ClientResponseError, ClientResponse
 from discord import Member, DMChannel
+from discord.ext import commands
 
 from core.models import Bot, UserClient
 
 
 class ApiClient:
+    """
+    This class represents the general request class for all type of clients.
+
+    Parameters
+    ----------
+    bot : Bot
+        The Modmail bot.
+
+    Attributes
+    ----------
+    bot : Bot
+        The Modmail bot.
+    session : ClientSession
+        The bot's current running `ClientSession`.
+    headers : Dict[str, str]
+        The HTTP headers that will be sent along with the requiest.
+    """
+
     def __init__(self, bot: Bot):
         self.bot = bot
         self.session = bot.session
@@ -21,6 +40,31 @@ async def request(self, url: str,
                       return_response: bool = False,
                       headers: dict = None) -> Union[ClientResponse,
                                                      dict, str]:
+        """
+        Makes a HTTP request.
+
+        Parameters
+        ----------
+        url : str
+            The destination URL of the request.
+        method : str
+            The HTTP method (POST, GET, PUT, DELETE, FETCH, etc.).
+        payload : Dict[str, Any]
+            The json payload to be sent along the request.
+        return_response : bool
+            Whether the `ClientResponse` object should be returned.
+        headers : Dict[str, str]
+            Additional headers to `headers`.
+
+        Returns
+        -------
+        ClientResponse or Dict[str, Any] or List[Any] or str
+            `ClientResponse` if `return_response` is `True`.
+            `dict` if the returned data is a json object.
+            `list` if the returned data is a json list.
+            `str` if the returned data is not a valid json data,
+            the raw response.
+        """
         if headers is not None:
             headers.update(self.headers)
         else:
@@ -35,16 +79,74 @@ async def request(self, url: str,
                 return await resp.text()
 
     def filter_valid(self, data):
+        """
+        Filters configuration keys that are accepted.
+
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            The data that needs to be cleaned.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Filtered `data` to keep only the accepted pairs.
+        """
         valid_keys = self.bot.config.valid_keys.difference(
             self.bot.config.protected_keys
         )
         return {k: v for k, v in data.items() if k in valid_keys}
 
 
-class Github(ApiClient):
+class GitHub(ApiClient):
+    """
+    The client for interacting with GitHub API.
+
+    Parameters
+    ----------
+    bot : Bot
+        The Modmail bot.
+    access_token : str, optional
+        GitHub's access token.
+    username : str, optional
+        GitHub username.
+    avatar_url : str, optional
+        URL to the avatar in GitHub.
+    url : str, optional
+        URL to the GitHub profile.
+
+    Attributes
+    ----------
+    bot : Bot
+        The Modmail bot.
+    access_token : str
+        GitHub's access token.
+    username : str
+        GitHub username.
+    avatar_url : str
+        URL to the avatar in GitHub.
+    url : str
+        URL to the GitHub profile.
+
+    Class Attributes
+    ----------------
+    BASE : str
+        GitHub API base URL.
+    REPO : str
+        Modmail repo URL for GitHub API.
+    HEAD : str
+        Modmail HEAD URL for GitHub API.
+    MERGE_URL : str
+        URL for merging upstream to master.
+    FORK_URL : str
+        URL to fork Modmail.
+    STAR_URL : str
+        URL to star Modmail.
+    """
+
     BASE = 'https://api.github.com'
     REPO = BASE + '/repos/kyb3r/modmail'
-    head = REPO + '/git/refs/heads/master'
+    HEAD = REPO + '/git/refs/heads/master'
     MERGE_URL = BASE + '/repos/{username}/modmail/merges'
     FORK_URL = REPO + '/forks'
     STAR_URL = BASE + '/user/starred/kyb3r/modmail'
@@ -56,15 +158,30 @@ def __init__(self, bot: Bot,
         super().__init__(bot)
         self.access_token = access_token
         self.username = username
-        self.id: str = kwargs.pop('id', '')
         self.avatar_url: str = kwargs.pop('avatar_url', '')
         self.url: str = kwargs.pop('url', '')
         if self.access_token:
             self.headers = {'Authorization': 'token ' + str(access_token)}
 
     async def update_repository(self, sha: str = None) -> Optional[dict]:
+        """
+        Update the repository from Modmail main repo.
+
+        Parameters
+        ----------
+        sha : Optional[str], optional
+            The commit SHA to update the repository.
+
+        Returns
+        -------
+        Optional[dict]
+            If the response is a dict.
+        """
+        if not self.username:
+            raise commands.CommandInvokeError("Username not found.")
+
         if sha is None:
-            resp: dict = await self.request(self.head)
+            resp: dict = await self.request(self.HEAD)
             sha = resp['object']['sha']
 
         payload = {
@@ -80,25 +197,52 @@ async def update_repository(self, sha: str = None) -> Optional[dict]:
             return resp
 
     async def fork_repository(self) -> None:
+        """
+        Forks Modmail's repository.
+        """
         await self.request(self.FORK_URL, method='POST')
 
     async def has_starred(self) -> bool:
+        """
+        Checks if shared Modmail.
+
+        Returns
+        -------
+        bool
+            `True`, if Modmail was starred.
+            Otherwise `False`.
+        """
         resp = await self.request(self.STAR_URL, return_response=True)
         return resp.status == 204
 
     async def star_repository(self) -> None:
+        """
+        Stars Modmail's repository.
+        """
         await self.request(self.STAR_URL, method='PUT',
                            headers={'Content-Length': '0'})
 
     @classmethod
-    async def login(cls, bot) -> 'Github':
+    async def login(cls, bot: Bot) -> 'GitHub':
+        """
+        Logs in to GitHub with configuration variable information.
+
+        Parameters
+        ----------
+        bot : Bot
+            The Modmail bot.
+
+        Returns
+        -------
+        GitHub
+            The newly created `GitHub` object.
+        """
         self = cls(bot, bot.config.get('github_access_token'), )
         resp: dict = await self.request('https://api.github.com/user')
         self.username: str = resp['login']
         self.avatar_url: str = resp['avatar_url']
         self.url: str = resp['html_url']
-        self.id: str = str(resp['id'])
-        print(f'Logged in to: {self.username} - {self.id}')
+        print(f'Logged in to: {self.username}')
         return self
 
 
@@ -361,7 +505,7 @@ async def post_log(self, channel_id, data):
         )
 
     async def update_repository(self):
-        user = await Github.login(self.bot)
+        user = await GitHub.login(self.bot)
         data = await user.update_repository()
         return {
             'data': data,
@@ -373,7 +517,7 @@ async def update_repository(self):
         }
 
     async def get_user_info(self):
-        user = await Github.login(self.bot)
+        user = await GitHub.login(self.bot)
         return {
             'user': {
                 'username': user.username,