profitroll/LibBotUniversal
profitroll/LibBotUniversal
1
0
Fork 0
Code Issues 4 Pull Requests 3 Actions Packages Releases 35 Wiki Activity

WIP: Convert docstrings to Google's format

Browse Source
This commit is contained in:
Profitroll 2025-01-05 22:46:40 +01:00
parent 4777b3dc41
commit 29a90fc385
Signed by: profitroll
GPG Key ID: FA35CAB49DACD3B2
6 changed files with 173 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/libbot/errors/config.py
View File

@ -4,8 +4,8 @@ from typing import Any, List, Optional
class ConfigKeyError(Exception): class ConfigKeyError(Exception):
"""Raised when config key is not found. """Raised when config key is not found.
### Attributes: Args:
* key (`str | List[str]`): Missing config key. key (str | List[str]): Missing config key
""" """
def __init__(self, key: str | List[str]) -> None: def __init__(self, key: str | List[str]) -> None:
@ -21,9 +21,9 @@ class ConfigKeyError(Exception):
class ConfigValueError(Exception): class ConfigValueError(Exception):
"""Raised when config key's value is invalid. """Raised when config key's value is invalid.
### Attributes: Args:
* key (`str | List[str]`): Invalid config key. key (str | List[str]): Invalid config key
* value (`Optional[Any]`): Key's correct value. value (Optional[Any]): Key's correct value
""" """
def __init__(self, key: str | List[str], value: Optional[Any] = None) -> None: def __init__(self, key: str | List[str], value: Optional[Any] = None) -> None:

94
src/libbot/i18n/_functions.py
View File

@ -18,16 +18,16 @@ def _(
locale: str | None = "en", locale: str | None = "en",
locales_root: str | Path = Path("locale"), locales_root: str | Path = Path("locale"),
) -> Any: ) -> Any:
"""Get value of locale string """Get value of the locale string.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locale (`str | None`): Locale to looked up in. Defaults to `"en"`. locale (str | None): Locale to be looked up in. Defaults to `"en"`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional):Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` Any: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]`
""" """
if locale is None: if locale is None:
locale: str = config_get("locale") locale: str = config_get("locale")
@ -58,16 +58,16 @@ async def _(
locale: str | None = "en", locale: str | None = "en",
locales_root: str | Path = Path("locale"), locales_root: str | Path = Path("locale"),
) -> Any: ) -> Any:
"""Get value of locale string """Get value of the locale string.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locale (`str | None`): Locale to looked up in. Defaults to `"en"`. locale (str | None): Locale to be looked up in. Defaults to `"en"`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional):Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` Any: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]`
""" """
locale: str = config_get("locale") if locale is None else locale locale: str = config_get("locale") if locale is None else locale
@ -94,17 +94,16 @@ async def _(
@asyncable @asyncable
def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale")) -> List[Any]: def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale")) -> List[Any]:
"""Get value of the provided key and path in all available locales """Get value of the provided key and path in all available locales.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional): Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `List[Any]`: List of values in all locales List[Any]: List of values in all locales
""" """
output: List[Any] = [] output: List[Any] = []
for locale in _get_valid_locales(locales_root): for locale in _get_valid_locales(locales_root):
@ -128,15 +127,15 @@ def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale
@in_all_locales.asynchronous @in_all_locales.asynchronous
async def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale")) -> List[Any]: async def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale")) -> List[Any]:
"""Get value of the provided key and path in all available locales """Get value of the provided key and path in all available locales.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional): Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `List[Any]`: List of values in all locales List[Any]: List of values in all locales
""" """
output: List[Any] = [] output: List[Any] = []
@ -161,20 +160,17 @@ async def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("
@asyncable @asyncable
def in_every_locale( def in_every_locale(key: str, *args: str, locales_root: str | Path = Path("locale")) -> Dict[str, Any]:
key: str, *args: str, locales_root: str | Path = Path("locale") """Get value of the provided key and path in every available locale with locale tag.
) -> Dict[str, Any]:
"""Get value of the provided key and path in every available locale with locale tag
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional): Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value Dict[str, Any]: Locale is a key, and it's value from locale file is a value
""" """
output: Dict[str, Any] = {} output: Dict[str, Any] = {}
for locale in _get_valid_locales(locales_root): for locale in _get_valid_locales(locales_root):
@ -200,15 +196,15 @@ def in_every_locale(
async def in_every_locale( async def in_every_locale(
key: str, *args: str, locales_root: str | Path = Path("locale") key: str, *args: str, locales_root: str | Path = Path("locale")
) -> Dict[str, Any]: ) -> Dict[str, Any]:
"""Get value of the provided key and path in every available locale with locale tag """Get value of the provided key and path in every available locale with locale tag.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
* locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. locales_root (str | Path, optional): Folder where locales are located. Defaults to `Path("locale")`
### Returns: Returns:
* `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value Dict[str, Any]: Locale is a key, and it's value from locale file is a value
""" """
output: Dict[str, Any] = {} output: Dict[str, Any] = {}

43
src/libbot/i18n/classes/bot_locale.py
View File

@ -14,6 +14,11 @@ class BotLocale:
default_locale: str | None = "en", default_locale: str | None = "en",
locales_root: str | Path = Path("locale"), locales_root: str | Path = Path("locale"),
) -> None: ) -> None:
"""
Args:
default_locale (str | None): Default bot's locale. Defaults to `"en"`
locales_root (str | Path): Folder where locales are located. Defaults to `Path("locale")`
"""
if isinstance(locales_root, str): if isinstance(locales_root, str):
locales_root = Path(locales_root) locales_root = Path(locales_root)
elif not isinstance(locales_root, Path): elif not isinstance(locales_root, Path):
@ -30,15 +35,15 @@ class BotLocale:
self.locales[locale] = json_read(Path(f"{locales_root}/{locale}.json")) self.locales[locale] = json_read(Path(f"{locales_root}/{locale}.json"))
def _(self, key: str, *args: str, locale: str | None = None) -> Any: def _(self, key: str, *args: str, locale: str | None = None) -> Any:
"""Get value of locale string """Get value of locale string.
### Args: Args:
* key (`str`): The last key of the locale's keys path key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]` *args (str): Path to key like: `dict[args][key]`
* locale (`str | None`, *optional*): Locale to looked up in. Defaults to config's `"locale"` value locale (str | None, optional): Locale to be looked up in. Defaults to config's `"locale"` value
### Returns: Returns:
* `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` Any: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]`
""" """
if locale is None: if locale is None:
locale: str = self.default locale: str = self.default
@ -64,14 +69,14 @@ class BotLocale:
return f'⚠️ Locale in config is invalid: could not get "{key}" in {args} from locale "{locale}"' return f'⚠️ Locale in config is invalid: could not get "{key}" in {args} from locale "{locale}"'
def in_all_locales(self, key: str, *args: str) -> List[Any]: def in_all_locales(self, key: str, *args: str) -> List[Any]:
"""Get value of the provided key and path in all available locales """Get value of the provided key and path in all available locales.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
### Returns: Returns:
* `List[Any]`: List of values in all locales List[Any]: List of values in all locales
""" """
output: List[Any] = [] output: List[Any] = []
@ -94,14 +99,14 @@ class BotLocale:
return output return output
def in_every_locale(self, key: str, *args: str) -> Dict[str, Any]: def in_every_locale(self, key: str, *args: str) -> Dict[str, Any]:
"""Get value of the provided key and path in every available locale with locale tag """Get value of the provided key and path in every available locale with locale tag.
### Args: Args:
* key (`str`): The last key of the locale's keys path. key (str): The last key of the locale's keys path
* *args (`str`): Path to key like: `dict[args][key]`. *args (str): Path to key like: `dict[args][key]`
### Returns: Returns:
* `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value Dict[str, Any]: Locale is a key, and it's value from locale file is a value
""" """
output: Dict[str, Any] = {} output: Dict[str, Any] = {}

26
src/libbot/pycord/classes/bot.py
View File

@ -19,6 +19,7 @@ logger: Logger = logging.getLogger(__name__)
class PycordBot(Bot): class PycordBot(Bot):
# TODO Write a docstring
@override @override
def __init__( def __init__(
self, self,
@ -29,6 +30,16 @@ class PycordBot(Bot):
scheduler: AsyncIOScheduler | BackgroundScheduler | None = None, scheduler: AsyncIOScheduler | BackgroundScheduler | None = None,
**kwargs, **kwargs,
): ):
"""
Args:
*args:
config:
config_path:
locales_root:
scheduler:
**kwargs:
"""
self.config: Dict[str, Any] = config if config is not None else json_read(config_path) self.config: Dict[str, Any] = config if config is not None else json_read(config_path)
super().__init__( super().__init__(
@ -51,15 +62,30 @@ class PycordBot(Bot):
self.scheduler: AsyncIOScheduler | BackgroundScheduler | None = scheduler self.scheduler: AsyncIOScheduler | BackgroundScheduler | None = scheduler
# TODO Write a docstring
@override @override
async def start(self, token: str, reconnect: bool = True, scheduler_start: bool = True) -> None: async def start(self, token: str, reconnect: bool = True, scheduler_start: bool = True) -> None:
"""
Args:
token:
reconnect:
scheduler_start:
"""
if self.scheduler is not None and scheduler_start: if self.scheduler is not None and scheduler_start:
self.scheduler.start() self.scheduler.start()
await super().start(token, reconnect=reconnect) await super().start(token, reconnect=reconnect)
# TODO Write a docstring
@override @override
async def close(self, scheduler_shutdown: bool = True, scheduler_wait: bool = True) -> None: async def close(self, scheduler_shutdown: bool = True, scheduler_wait: bool = True) -> None:
"""
Args:
scheduler_shutdown:
scheduler_wait:
"""
if self.scheduler is not None and scheduler_shutdown: if self.scheduler is not None and scheduler_shutdown:
self.scheduler.shutdown(scheduler_wait) self.scheduler.shutdown(scheduler_wait)

20
src/libbot/pycord/utils/color.py
View File

@ -16,20 +16,24 @@ def _hex_from_int(color_int: int) -> str:
def color_from_hex(hex_string: str) -> Colour: def color_from_hex(hex_string: str) -> Colour:
"""Convert valid hexadecimal string to discord.Colour. """Convert valid hexadecimal string to :class:`discord.Colour`.
:param hex_string: Hexadecimal string to convert into Colour object Args:
:type hex_string: str hex_string (str): Hexadecimal string to convert into :class:`discord.Colour` object
:return: Colour object
Returns:
Colour: :class:`discord.Colour` object
""" """
return Colour(_int_from_hex(hex_string)) return Colour(_int_from_hex(hex_string))
def hex_from_color(color: Colour) -> str: def hex_from_color(color: Colour) -> str:
"""Convert discord.Colour to hexadecimal string. """Convert :class:`discord.Colour` to hexadecimal string.
:param color: Colour object to convert into the string Args:
:type color: Colour color (Colour): :class:`discord.Colour` object to convert into the string
:return: Hexadecimal string in #XXXXXX format
Returns:
str: Hexadecimal string in #XXXXXX format
""" """
return _hex_from_int(color.value) return _hex_from_int(color.value)

42
src/libbot/pyrogram/classes/client.py
View File

@ -6,7 +6,7 @@ from logging import Logger
from os import cpu_count, getpid from os import cpu_count, getpid
from pathlib import Path from pathlib import Path
from time import time from time import time
from typing import Any, Dict, List from typing import Any, Dict, List, Optional
from typing_extensions import override from typing_extensions import override
@ -46,6 +46,7 @@ logger: Logger = logging.getLogger(__name__)
class PyroClient(Client): class PyroClient(Client):
# TODO Write a docstring
@override @override
def __init__( def __init__(
self, self,
@ -119,6 +120,12 @@ class PyroClient(Client):
@override @override
async def start(self, register_commands: bool = True, scheduler_start: bool = True) -> None: async def start(self, register_commands: bool = True, scheduler_start: bool = True) -> None:
"""Start the bot and it's services.
Args:
register_commands (bool, optional): Register commands on start. Defaults to `True`
scheduler_start (bool, optional): Start the scheduler on start. Defaults to `True`
"""
await super().start() await super().start()
self.start_time = time() self.start_time = time()
@ -211,6 +218,13 @@ class PyroClient(Client):
async def stop( async def stop(
self, exit_completely: bool = True, scheduler_shutdown: bool = True, scheduler_wait: bool = True self, exit_completely: bool = True, scheduler_shutdown: bool = True, scheduler_wait: bool = True
) -> None: ) -> None:
"""Stop the bot and it's services.
Args:
exit_completely (bool, optional): Exit the program. Defaults to `True`
scheduler_shutdown (bool): Shutdown the scheduler. Defaults to `True`
scheduler_wait (bool): Wait for tasks to finish. Defaults to `True`
"""
try: try:
await self.send_message( await self.send_message(
chat_id=( chat_id=(
@ -237,10 +251,10 @@ class PyroClient(Client):
raise SystemExit("Bot has been shut down, this is not an application error!") from exc raise SystemExit("Bot has been shut down, this is not an application error!") from exc
async def collect_commands(self) -> List[CommandSet] | None: async def collect_commands(self) -> List[CommandSet] | None:
"""Gather list of the bot's commands """Gather list of the bot's commands.
### Returns: Returns:
* `List[CommandSet]`: List of the commands' sets. List[CommandSet]: List of the commands' sets
""" """
command_sets = None command_sets = None
@ -322,10 +336,10 @@ class PyroClient(Client):
self, self,
command: str, command: str,
) -> None: ) -> None:
"""Add command to the bot's internal commands list """Add command to the bot's internal commands list.
### Args: Args:
* command (`str`) command (str): Command's name
""" """
self.commands.append( self.commands.append(
PyroCommand( PyroCommand(
@ -338,9 +352,12 @@ class PyroClient(Client):
command, command,
) )
async def register_commands(self, command_sets: List[CommandSet] | None = None) -> None: async def register_commands(self, command_sets: Optional[List[CommandSet]] = None) -> None:
"""Register commands stored in bot's 'commands' attribute""" """Register commands stored in bot's 'commands' attribute.
Args:
command_sets (List[CommandSet], optional): List of command sets. Commands will be parsed from bot's 'commands' attribute if not provided
"""
if command_sets is None: if command_sets is None:
commands = [ commands = [
BotCommand(command=command.command, description=command.description) BotCommand(command=command.command, description=command.description)
@ -365,9 +382,12 @@ class PyroClient(Client):
language_code=command_set.language_code, language_code=command_set.language_code,
) )
async def remove_commands(self, command_sets: List[CommandSet] | None = None) -> None: async def remove_commands(self, command_sets: Optional[List[CommandSet]] = None) -> None:
"""Remove commands stored in bot's 'commands' attribute""" """Remove commands stored in bot's 'commands' attribute.
Args:
command_sets (List[CommandSet], optional): List of command sets. Commands with scope :class:`pyrogram.types.BotCommandScopeDefault` will be removed if not provided
"""
if command_sets is None: if command_sets is None:
logger.info("Removing commands with a default scope 'BotCommandScopeDefault'") logger.info("Removing commands with a default scope 'BotCommandScopeDefault'")
await self.delete_bot_commands(BotCommandScopeDefault()) await self.delete_bot_commands(BotCommandScopeDefault())