feat(doc): add docstrings

This commit is contained in:
Romain J 2020-06-04 00:46:53 +02:00
parent 33fa6b7f1f
commit 50562059f9
5 changed files with 191 additions and 31 deletions

View file

@ -2,31 +2,11 @@
<project version="4"> <project version="4">
<component name="ChangeListManager"> <component name="ChangeListManager">
<list default="true" id="c97c8a30-7573-4dcd-a0d4-5bf94b8ddbbd" name="5ed57ed9960f35191182a924 core" comment=""> <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$/.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/__main__.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/__main__.py" afterDir="false" />
<change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/SOURCES.txt" beforeDir="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_bot.egg-info/dependency_links.txt" beforeDir="false" /> <change beforePath="$PROJECT_DIR$/tuxbot/logging.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/logging.py" afterDir="false" />
<change beforePath="$PROJECT_DIR$/Tuxbot_bot.egg-info/entry_points.txt" beforeDir="false" /> <change beforePath="$PROJECT_DIR$/tuxbot/setup.py" beforeDir="false" afterPath="$PROJECT_DIR$/tuxbot/setup.py" afterDir="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" />
</list> </list>
<list id="a3abf5c0-7587-46e4-8f09-88e34a1ab8a4" name="5ed41911b012e33f68a07e7a i18n" comment="" /> <list id="a3abf5c0-7587-46e4-8f09-88e34a1ab8a4" name="5ed41911b012e33f68a07e7a i18n" comment="" />
<list id="6566fca1-2e90-48bb-9e74-dd3badbaca99" name="Default Changelist" comment="" /> <list id="6566fca1-2e90-48bb-9e74-dd3badbaca99" name="Default Changelist" comment="" />
@ -137,7 +117,7 @@
<workItem from="1591049956280" duration="4910000" /> <workItem from="1591049956280" duration="4910000" />
<workItem from="1591054878071" duration="1039000" /> <workItem from="1591054878071" duration="1039000" />
<workItem from="1591088657371" duration="4107000" /> <workItem from="1591088657371" duration="4107000" />
<workItem from="1591128560850" duration="38413000" /> <workItem from="1591128560850" duration="40157000" />
</task> </task>
<option name="localTasksCounter" value="2" /> <option name="localTasksCounter" value="2" />
<option name="createBranch" value="false" /> <option name="createBranch" value="false" />

View file

@ -7,6 +7,7 @@ import platform
import signal import signal
import sys import sys
from typing import NoReturn from typing import NoReturn
from argparse import Namespace
import discord import discord
import pip import pip
@ -24,6 +25,9 @@ init()
def list_instances() -> NoReturn: def list_instances() -> NoReturn:
"""List all available instances
"""
with data_manager.config_file.open() as fs: with data_manager.config_file.open() as fs:
datas = json.load(fs) datas = json.load(fs)
@ -42,6 +46,9 @@ def list_instances() -> NoReturn:
def debug_info() -> NoReturn: def debug_info() -> NoReturn:
"""Show debug infos relatives to the bot
"""
python_version = sys.version.replace('\n', '') python_version = sys.version.replace('\n', '')
pip_version = pip.__version__ pip_version = pip.__version__
tuxbot_version = __version__ tuxbot_version = __version__
@ -72,7 +79,17 @@ def debug_info() -> NoReturn:
sys.exit(0) 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( parser = argparse.ArgumentParser(
description="Tuxbot - OpenSource bot", description="Tuxbot - OpenSource bot",
usage="tuxbot <instance_name> [arguments]" usage="tuxbot <instance_name> [arguments]"
@ -102,7 +119,20 @@ def parse_cli_flags(args):
return 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: if signal_type:
log.info("%s received. Quitting...", signal_type) log.info("%s received. Quitting...", signal_type)
sys.exit(0) sys.exit(0)
@ -126,7 +156,21 @@ async def shutdown_handler(tux, signal_type, exit_code=None):
await asyncio.gather(*pending, return_exceptions=True) 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) data_path = data_manager.get_data_path(tux.instance_name)
tuxbot.logging.init_logging( tuxbot.logging.init_logging(
@ -155,7 +199,10 @@ async def run_bot(tux: Tux, cli_flags: argparse.Namespace) -> None:
return None return None
def main(): def main() -> NoReturn:
"""Main function
"""
tux = None tux = None
cli_flags = parse_cli_flags(sys.argv[1:]) cli_flags = parse_cli_flags(sys.argv[1:])

View file

@ -8,19 +8,64 @@ config_file = config_dir / "config.json"
def get_data_path(instance_name: str) -> Path: 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 return Path(app_dir.user_data_dir) / "data" / instance_name
def get_core_path(instance_name: str) -> Path: 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) data_path = get_data_path(instance_name)
return data_path / "data" / instance_name / "core" return data_path / "data" / instance_name / "core"
def get_cogs_path(instance_name: str) -> Path: 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) data_path = get_data_path(instance_name)
return data_path / "data" / instance_name / "cogs" return data_path / "data" / instance_name / "cogs"
def get_cog_path(instance_name: str, cog_name: str) -> Path: 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) data_path = get_data_path(instance_name)
return data_path / "data" / instance_name / "cogs" / cog_name return data_path / "data" / instance_name / "cogs" / cog_name

View file

@ -8,6 +8,15 @@ MAX_BYTES = 5_000_000
def init_logging(level: int, location: pathlib.Path) -> None: 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 = logging.getLogger("discord")
dpy_logger.setLevel(logging.WARN) dpy_logger.setLevel(logging.WARN)
dpy_logger_file = location / 'discord.log' dpy_logger_file = location / 'discord.log'

View file

@ -22,6 +22,14 @@ config_file = config_dir / "config.json"
def load_existing_config() -> dict: def load_existing_config() -> dict:
"""Loading and returning configs.
Returns
-------
dict
a dict containing all configurations.
"""
if not config_file.exists(): if not config_file.exists():
return {} return {}
@ -36,7 +44,18 @@ else:
instances_list = list(instances_data.keys()) 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() _config = load_existing_config()
if delete and name in _config: if delete and name in _config:
@ -49,6 +68,13 @@ def save_config(name, data, delete=False):
def get_name() -> str: def get_name() -> str:
"""Get instance name via input.
Returns
-------
str
The instance name choose by user.
"""
name = "" name = ""
while not name: while not name:
print( print(
@ -68,6 +94,19 @@ def get_name() -> str:
def get_data_dir(instance_name: str) -> Path: 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 = Path(app_dir.user_data_dir) / "data" / instance_name
data_path_input = "" data_path_input = ""
print() print()
@ -136,6 +175,13 @@ def get_data_dir(instance_name: str) -> Path:
def get_token() -> str: def get_token() -> str:
"""Get token via input.
Returns
-------
str
The token choose by user.
"""
token = "" token = ""
while not token: while not token:
@ -156,6 +202,22 @@ def get_token() -> str:
def get_multiple(question: str, confirmation: str, value_type: type)\ def get_multiple(question: str, confirmation: str, value_type: type)\
-> List[Union[str, int]]: -> 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) print(question)
values = [value_type(input('> '))] values = [value_type(input('> '))]
@ -166,6 +228,13 @@ def get_multiple(question: str, confirmation: str, value_type: type)\
def additional_config() -> dict: 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') p = Path(r'tuxbot/cogs').glob('**/additional_config.json')
datas = {} datas = {}
@ -188,6 +257,13 @@ def additional_config() -> dict:
def finish_setup(data_dir: Path) -> NoReturn: 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") print("Now, it's time to finish this setup by giving bot informations\n")
token = get_token() token = get_token()
@ -232,6 +308,9 @@ def finish_setup(data_dir: Path) -> NoReturn:
def basic_setup() -> NoReturn: def basic_setup() -> NoReturn:
"""Configs who refer to instances.
"""
print("Hi ! it's time for you to give me informations about you instance") print("Hi ! it's time for you to give me informations about you instance")
name = get_name() name = get_name()
@ -269,7 +348,7 @@ def basic_setup() -> NoReturn:
) )
def setup(): def setup() -> NoReturn:
try: try:
"""Create a new instance.""" """Create a new instance."""
level = logging.DEBUG level = logging.DEBUG