From 50562059f94d523b3565b68e4b0d82679053c608 Mon Sep 17 00:00:00 2001
From: Romain J <romain.ordi@gmail.com>
Date: Thu, 4 Jun 2020 00:46:53 +0200
Subject: [PATCH] feat(doc): add docstrings

---
 .idea/workspace.xml         | 30 +++-----------
 tuxbot/__main__.py          | 55 ++++++++++++++++++++++--
 tuxbot/core/data_manager.py | 45 ++++++++++++++++++++
 tuxbot/logging.py           |  9 ++++
 tuxbot/setup.py             | 83 ++++++++++++++++++++++++++++++++++++-
 5 files changed, 191 insertions(+), 31 deletions(-)

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 6f023d6..da45671 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -2,31 +2,11 @@
 <project version="4">
   <component name="ChangeListManager">
     <list default="true" id="c97c8a30-7573-4dcd-a0d4-5bf94b8ddbbd" name="5ed57ed9960f35191182a924 core" comment="">
-      <change beforePath="$PROJECT_DIR$/.gitignore" beforeDir="false" afterPath="$PROJECT_DIR$/.gitignore" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/PKG-INFO" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/SOURCES.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/dependency_links.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/entry_points.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/requires.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/top_level.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/__init__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/__main__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/images/__init__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/images/images.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/logs/__init__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/logs/logs.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/network/__init__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/cogs/network/network.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/__init__.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/bot.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/config.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/data_manager.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/utils/functions/cli.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/core/utils/functions/extra.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/logging.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/build/lib/tuxbot/setup.py" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/dist/Tuxbot_bot-3.0.0-py3.8.egg" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/tuxbot/__main__.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/__main__.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tuxbot/core/data_manager.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/core/data_manager.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tuxbot/logging.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/logging.py" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/tuxbot/setup.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/setup.py" afterDir="false" />
     </list>
     <list id="a3abf5c0-7587-46e4-8f09-88e34a1ab8a4" name="5ed41911b012e33f68a07e7a i18n" comment="" />
     <list id="6566fca1-2e90-48bb-9e74-dd3badbaca99" name="Default Changelist" comment="" />
@@ -137,7 +117,7 @@
       <workItem from="1591049956280" duration="4910000" />
       <workItem from="1591054878071" duration="1039000" />
       <workItem from="1591088657371" duration="4107000" />
-      <workItem from="1591128560850" duration="38413000" />
+      <workItem from="1591128560850" duration="40157000" />
     </task>
     <option name="localTasksCounter" value="2" />
     <option name="createBranch" value="false" />
diff --git a/tuxbot/__main__.py b/tuxbot/__main__.py
index e09cbe0..9126e6b 100644
--- a/tuxbot/__main__.py
+++ b/tuxbot/__main__.py
@@ -7,6 +7,7 @@ import platform
 import signal
 import sys
 from typing import NoReturn
+from argparse import Namespace
 
 import discord
 import pip
@@ -24,6 +25,9 @@ init()
 
 
 def list_instances() -> NoReturn:
+    """List all available instances
+
+    """
     with data_manager.config_file.open() as fs:
         datas = json.load(fs)
 
@@ -42,6 +46,9 @@ def list_instances() -> NoReturn:
 
 
 def debug_info() -> NoReturn:
+    """Show debug infos relatives to the bot
+
+    """
     python_version = sys.version.replace('\n', '')
     pip_version = pip.__version__
     tuxbot_version = __version__
@@ -72,7 +79,17 @@ def debug_info() -> NoReturn:
     sys.exit(0)
 
 
-def parse_cli_flags(args):
+def parse_cli_flags(args: list) -> Namespace:
+    """Parser for cli values.
+
+    Parameters
+    ----------
+    args:list
+        Is a list of all passed values.
+    Returns
+    -------
+    Namespace
+    """
     parser = argparse.ArgumentParser(
         description="Tuxbot - OpenSource bot",
         usage="tuxbot <instance_name> [arguments]"
@@ -102,7 +119,20 @@ def parse_cli_flags(args):
     return args
 
 
-async def shutdown_handler(tux, signal_type, exit_code=None):
+async def shutdown_handler(tux: Tux, signal_type, exit_code=None) -> NoReturn:
+    """Handler when the bot shutdown
+
+    It cancels all running task.
+
+    Parameters
+    ----------
+    tux:Tux
+        Object for the bot.
+    signal_type:int
+        Exiting signal code.
+    exit_code:None|int
+        Code to show when exiting.
+    """
     if signal_type:
         log.info("%s received. Quitting...", signal_type)
         sys.exit(0)
@@ -126,7 +156,21 @@ async def shutdown_handler(tux, signal_type, exit_code=None):
         await asyncio.gather(*pending, return_exceptions=True)
 
 
-async def run_bot(tux: Tux, cli_flags: argparse.Namespace) -> None:
+async def run_bot(tux: Tux, cli_flags: Namespace) -> None:
+    """This run the bot.
+
+    Parameters
+    ----------
+    tux:Tux
+        Object for the bot.
+    cli_flags:Namespace
+        All different flags passed in the console.
+
+    Returns
+    -------
+    None
+        When exiting, this function return None.
+    """
     data_path = data_manager.get_data_path(tux.instance_name)
 
     tuxbot.logging.init_logging(
@@ -155,7 +199,10 @@ async def run_bot(tux: Tux, cli_flags: argparse.Namespace) -> None:
     return None
 
 
-def main():
+def main() -> NoReturn:
+    """Main function
+
+    """
     tux = None
     cli_flags = parse_cli_flags(sys.argv[1:])
 
diff --git a/tuxbot/core/data_manager.py b/tuxbot/core/data_manager.py
index 473ea42..6e8b7a3 100644
--- a/tuxbot/core/data_manager.py
+++ b/tuxbot/core/data_manager.py
@@ -8,19 +8,64 @@ config_file = config_dir / "config.json"
 
 
 def get_data_path(instance_name: str) -> Path:
+    """Return Path for data configs.
+
+    Parameters
+    ----------
+    instance_name:str
+
+    Returns
+    -------
+    Path
+        Generated path for data configs.
+    """
     return Path(app_dir.user_data_dir) / "data" / instance_name
 
 
 def get_core_path(instance_name: str) -> Path:
+    """Return Path for core configs.
+
+    Parameters
+    ----------
+    instance_name:str
+
+    Returns
+    -------
+    Path
+        Generated path for core configs.
+    """
     data_path = get_data_path(instance_name)
     return data_path / "data" / instance_name / "core"
 
 
 def get_cogs_path(instance_name: str) -> Path:
+    """Return Path for cogs configs.
+
+    Parameters
+    ----------
+    instance_name:str
+
+    Returns
+    -------
+    Path
+        Generated path for cogs configs.
+    """
     data_path = get_data_path(instance_name)
     return data_path / "data" / instance_name / "cogs"
 
 
 def get_cog_path(instance_name: str, cog_name: str) -> Path:
+    """Return Path for chosen configs for cog.
+
+    Parameters
+    ----------
+    instance_name:str
+    cog_name:str
+
+    Returns
+    -------
+    Path
+        Generated path for cog's configs.
+    """
     data_path = get_data_path(instance_name)
     return data_path / "data" / instance_name / "cogs" / cog_name
diff --git a/tuxbot/logging.py b/tuxbot/logging.py
index 4880004..8a9b381 100644
--- a/tuxbot/logging.py
+++ b/tuxbot/logging.py
@@ -8,6 +8,15 @@ MAX_BYTES = 5_000_000
 
 
 def init_logging(level: int, location: pathlib.Path) -> None:
+    """Initialize loggers.
+
+    Parameters
+    ----------
+    level:int
+        Level of debug.
+    location:Path
+        Where to store logs.
+    """
     dpy_logger = logging.getLogger("discord")
     dpy_logger.setLevel(logging.WARN)
     dpy_logger_file = location / 'discord.log'
diff --git a/tuxbot/setup.py b/tuxbot/setup.py
index 6d13e0f..b8fa076 100644
--- a/tuxbot/setup.py
+++ b/tuxbot/setup.py
@@ -22,6 +22,14 @@ config_file = config_dir / "config.json"
 
 
 def load_existing_config() -> dict:
+    """Loading and returning configs.
+
+    Returns
+    -------
+    dict
+        a dict containing all configurations.
+
+    """
     if not config_file.exists():
         return {}
 
@@ -36,7 +44,18 @@ else:
     instances_list = list(instances_data.keys())
 
 
-def save_config(name, data, delete=False):
+def save_config(name: str, data: dict, delete=False) -> NoReturn:
+    """save data in config file.
+
+    Parameters
+    ----------
+    name:str
+        name of instance.
+    data:dict
+        settings for `name` instance.
+    delete:bool
+        delete or no data.
+    """
     _config = load_existing_config()
 
     if delete and name in _config:
@@ -49,6 +68,13 @@ def save_config(name, data, delete=False):
 
 
 def get_name() -> str:
+    """Get instance name via input.
+
+    Returns
+    -------
+    str
+        The instance name choose by user.
+    """
     name = ""
     while not name:
         print(
@@ -68,6 +94,19 @@ def get_name() -> str:
 
 
 def get_data_dir(instance_name: str) -> Path:
+    """Returning data path.
+
+    Parameters
+    ----------
+    instance_name:str
+        Instance name.
+
+    Returns
+    -------
+    Path
+        The data config path corresponding to the instance.
+
+    """
     data_path = Path(app_dir.user_data_dir) / "data" / instance_name
     data_path_input = ""
     print()
@@ -136,6 +175,13 @@ def get_data_dir(instance_name: str) -> Path:
 
 
 def get_token() -> str:
+    """Get token via input.
+
+    Returns
+    -------
+    str
+        The token choose by user.
+    """
     token = ""
 
     while not token:
@@ -156,6 +202,22 @@ def get_token() -> str:
 
 def get_multiple(question: str, confirmation: str, value_type: type)\
         -> List[Union[str, int]]:
+    """Give possibility to user to fill multiple value.
+
+    Parameters
+    ----------
+    question:str
+        First question.
+    confirmation:str
+        Asking text if user want to add another.
+    value_type:type
+        The type of values inside the list.
+
+    Returns
+    -------
+    List[Union[str, int]]
+        List containing user filled values.
+    """
     print(question)
     values = [value_type(input('> '))]
 
@@ -166,6 +228,13 @@ def get_multiple(question: str, confirmation: str, value_type: type)\
 
 
 def additional_config() -> dict:
+    """Asking for additional configs in cogs.
+
+    Returns
+    -------
+    dict:
+        Dict with cog name as key and configs as value.
+    """
     p = Path(r'tuxbot/cogs').glob('**/additional_config.json')
     datas = {}
 
@@ -188,6 +257,13 @@ def additional_config() -> dict:
 
 
 def finish_setup(data_dir: Path) -> NoReturn:
+    """Configs who directly refer to the bot.
+
+    Parameters
+    ----------
+    data_dir:Path
+        Where to save configs.
+    """
     print("Now, it's time to finish this setup by giving bot informations\n")
 
     token = get_token()
@@ -232,6 +308,9 @@ def finish_setup(data_dir: Path) -> NoReturn:
 
 
 def basic_setup() -> NoReturn:
+    """Configs who refer to instances.
+
+    """
     print("Hi ! it's time for you to give me informations about you instance")
     name = get_name()
 
@@ -269,7 +348,7 @@ def basic_setup() -> NoReturn:
     )
 
 
-def setup():
+def setup() -> NoReturn:
     try:
         """Create a new instance."""
         level = logging.DEBUG