feat(doc): add docstrings
This commit is contained in:
parent
33fa6b7f1f
commit
50562059f9
5 changed files with 191 additions and 31 deletions
|
@ -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" />
|
||||
|
|
|
@ -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:])
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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'
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in a new issue