From ef7380ae450499f34aca2ef1efd7c96bdc1cc8c6 Mon Sep 17 00:00:00 2001 From: Profitroll Date: Wed, 9 Jul 2025 14:32:50 +0200 Subject: [PATCH] WIP: Documentation improvement and format change to Google --- src/libbot/cache/manager/manager.py | 11 ++ src/libbot/i18n/_functions.py | 88 ++++++++-------- src/libbot/i18n/classes/bot_locale.py | 43 ++++---- src/libbot/utils/config/_functions.py | 140 +++++++++++--------------- src/libbot/utils/json/_functions.py | 36 +++---- src/libbot/utils/misc/_functions.py | 44 ++++---- 6 files changed, 179 insertions(+), 183 deletions(-) diff --git a/src/libbot/cache/manager/manager.py b/src/libbot/cache/manager/manager.py index 6a96b60..153840f 100644 --- a/src/libbot/cache/manager/manager.py +++ b/src/libbot/cache/manager/manager.py @@ -9,6 +9,17 @@ def create_cache_client( prefix: Optional[str] = None, default_ttl_seconds: Optional[int] = None, ) -> CacheMemcached | CacheRedis: + """Create a cache client of a provided type. + + Args: + config (Dict[str, Any]): Cache client configuration. + engine (Literal["memcached", "redis"] | None): Cache engine to use. Defaults to None. + prefix (:obj:`str`, optional): Prefix used for each key-value pair. Defaults to None (no prefix). + default_ttl_seconds (:obj:`int`, optional): Default TTL for values (in seconds). Defaults to None (does not expire). + + Returns: + CacheMemcached | CacheRedis: Cache client. + """ if engine not in ["memcached", "redis"] or engine is None: raise KeyError(f"Incorrect cache engine provided. Expected 'memcached' or 'redis', got '{engine}'") diff --git a/src/libbot/i18n/_functions.py b/src/libbot/i18n/_functions.py index 05944ed..2d6bc34 100644 --- a/src/libbot/i18n/_functions.py +++ b/src/libbot/i18n/_functions.py @@ -18,16 +18,16 @@ def _( locale: str | None = "en", locales_root: str | Path = Path("locale"), ) -> Any: - """Get value of locale string + """Get value of locale string. - ### Args: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locale (`str | None`): Locale to looked up in. Defaults to `"en"`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locale (str | None): Locale to looked up in. Defaults to "en". + locales_root (str | Path, optional): Folder where locales are located. Defaults to Path("locale"). - ### Returns: - * `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` + Returns: + Any: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]`. """ if locale is None: locale: str = config_get("locale") @@ -58,16 +58,16 @@ async def _( locale: str | None = "en", locales_root: str | Path = Path("locale"), ) -> Any: - """Get value of locale string + """Get value of locale string. - ### Args: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locale (`str | None`): Locale to looked up in. Defaults to `"en"`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locale (str | None): Locale to looked up in. Defaults to "en". + locales_root (str | Path, optional): Folder where locales are located. Defaults to Path("locale"). - ### Returns: - * `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` + Returns: + 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 @@ -94,15 +94,15 @@ async def _( @asyncable 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locales_root (str | Path, optional): Folder where locales are located. Defaults to `Path("locale")`. - ### Returns: - * `List[Any]`: List of values in all locales + Returns: + List[Any]: List of values in all locales. """ output: List[Any] = [] @@ -128,15 +128,15 @@ def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("locale @in_all_locales.asynchronous 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locales_root (str | Path, optional): Folder where locales are located. Defaults to Path("locale"). - ### Returns: - * `List[Any]`: List of values in all locales + Returns: + List[Any]: List of values in all locales. """ output: List[Any] = [] @@ -164,15 +164,15 @@ async def in_all_locales(key: str, *args: str, locales_root: str | Path = Path(" def in_every_locale( key: str, *args: str, locales_root: str | Path = Path("locale") ) -> 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locales_root (str | Path, optional): Folder where locales are located. Defaults to Path("locale"). - ### Returns: - * `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value + Returns: + Dict[str, Any]: Locale is a key, and it's value from locale file is a value. """ output: Dict[str, Any] = {} @@ -200,15 +200,15 @@ def in_every_locale( async def in_every_locale( key: str, *args: str, locales_root: str | Path = Path("locale") ) -> 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. - * locales_root (`str | Path`, *optional*): Folder where locales are located. Defaults to `Path("locale")`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locales_root (str | Path, optional): Folder where locales are located. Defaults to Path("locale"). - ### Returns: - * `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value + Returns: + Dict[str, Any]: Locale is a key, and it's value from locale file is a value. """ output: Dict[str, Any] = {} diff --git a/src/libbot/i18n/classes/bot_locale.py b/src/libbot/i18n/classes/bot_locale.py index c1970dc..bf50555 100644 --- a/src/libbot/i18n/classes/bot_locale.py +++ b/src/libbot/i18n/classes/bot_locale.py @@ -14,6 +14,11 @@ class BotLocale: default_locale: str | None = "en", locales_root: str | Path = Path("locale"), ) -> None: + """ + Args: + default_locale (str | None, optional): Default locale. Defaults to "en". + locales_root (str | Path, optional): Path to a directory with locale files. Defaults to Path("locale"). + """ if isinstance(locales_root, str): locales_root = Path(locales_root) elif not isinstance(locales_root, Path): @@ -30,15 +35,15 @@ class BotLocale: self.locales[locale] = json_read(Path(f"{locales_root}/{locale}.json")) def _(self, key: str, *args: str, locale: str | None = None) -> Any: - """Get value of locale string + """Get value of locale string. - ### Args: - * key (`str`): The last key of the locale's keys path - * *args (`str`): Path to key like: `dict[args][key]` - * locale (`str | None`, *optional*): Locale to looked up in. Defaults to config's `"locale"` value + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. + locale (str | None, optional): Locale to looked up in. Defaults to config's `"locale"` value. - ### Returns: - * `Any`: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]` + Returns: + Any: Value of provided locale key. Is usually `str`, `Dict[str, Any]` or `List[Any]`. """ if locale is None: 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}"' 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. - ### Returns: - * `List[Any]`: List of values in all locales + Returns: + List[Any]: List of values in all locales. """ output: List[Any] = [] @@ -94,14 +99,14 @@ class BotLocale: return output 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: - * key (`str`): The last key of the locale's keys path. - * *args (`str`): Path to key like: `dict[args][key]`. + Args: + key (str): The last key of the locale's keys path. + *args (str): Path to key like: `dict[args][key]`. - ### Returns: - * `Dict[str, Any]`: Locale is a key, and it's value from locale file is a value + Returns: + Dict[str, Any]: Locale is a key, and it's value from locale file is a value. """ output: Dict[str, Any] = {} diff --git a/src/libbot/utils/config/_functions.py b/src/libbot/utils/config/_functions.py index 7aeb285..663effc 100644 --- a/src/libbot/utils/config/_functions.py +++ b/src/libbot/utils/config/_functions.py @@ -15,34 +15,24 @@ DEFAULT_CONFIG_LOCATION: str = "config.json" @asyncable def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> Any: - """Get a value of the config key by its path provided - For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"` + """Get a value of the config key by its path provided. + For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`. - ### Args: - * key (`str`): Key that contains the value - * *path (`str`): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level) - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key that contains the value + *path (str): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level) + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` - ### Returns: - * `Any`: Key's value + Returns: + Any: Key's value - ### Example: - Get the "salary" of "Pete" from this JSON structure: - ```json - { - "users": { - "Pete": { - "salary": 10.0 - } - } - } - ``` + Example: + Get the "salary" of "Pete" from this JSON structure: `{"users": {"Pete": {"salary": 10.0}}}` - This can be easily done with the following code: - ```python - import libbot - salary = libbot.sync.config_get("salary", "users", "Pete") - ``` + This can be easily done with the following code: + + >>> import libbot + salary: float = libbot.sync.config_get("salary", "users", "Pete") """ this_key: Dict[str, Any] = json_read(config_file) @@ -54,34 +44,24 @@ def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LO @config_get.asynchronous async def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> Any: - """Get a value of the config key by its path provided - For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"` + """Get a value of the config key by its path provided. + For example, `foo.bar.key` has a path of `"foo", "bar"` and the key `"key"`. - ### Args: - * key (`str`): Key that contains the value - * *path (`str`): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level) - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key that contains the value + *path (str): Path to the key that contains the value (pass *[] or don't pass anything at all to get on the top/root level) + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` - ### Returns: - * `Any`: Key's value + Returns: + Any: Key's value - ### Example: - Get the "salary" of "Pete" from this JSON structure: - ```json - { - "users": { - "Pete": { - "salary": 10.0 - } - } - } - ``` + Example: + Get the "salary" of "Pete" from this JSON structure: `{"users": {"Pete": {"salary": 10.0}}}` - This can be easily done with the following code: - ```python - import libbot - salary = await libbot.config_get("salary", "users", "Pete") - ``` + This can be easily done with the following code: + + >>> import libbot + salary: float = libbot.sync.config_get("salary", "users", "Pete") """ this_key: Dict[str, Any] = await json_read(config_file) @@ -93,16 +73,16 @@ async def config_get(key: str, *path: str, config_file: str | Path = DEFAULT_CON @asyncable def config_set(key: str, value: Any, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION) -> None: - """Set config's key by its path to the value + """Set config's key by its path to the value. - ### Args: - * key (`str`): Key that leads to the value - * value (`Any`): Any JSON serializable data - * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level) - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key that leads to the value. + value (Any): Any JSON-serializable data. + *path (str): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level). + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json". - ### Raises: - * `KeyError`: Key is not found under path provided + Raises: + KeyError: Key was not found under the provided path. """ json_write(nested_set(json_read(config_file), value, *(*path, key)), config_file) @@ -111,16 +91,16 @@ def config_set(key: str, value: Any, *path: str, config_file: str | Path = DEFAU async def config_set( key: str, value: Any, *path: str, config_file: str | Path = DEFAULT_CONFIG_LOCATION ) -> None: - """Set config's key by its path to the value + """Set config's key by its path to the value. - ### Args: - * key (`str`): Key that leads to the value - * value (`Any`): Any JSON serializable data - * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level) - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key that leads to the value. + value (Any): Any JSON-serializable data. + *path (str): Path to the key of the target (pass *[] or don't pass anything at all to set on the top/root level). + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json". - ### Raises: - * `KeyError`: Key is not found under path provided + Raises: + KeyError: Key was not found under the provided path. """ await json_write(nested_set(await json_read(config_file), value, *(*path, key)), config_file) @@ -132,16 +112,16 @@ def config_delete( missing_ok: bool = False, config_file: str | Path = DEFAULT_CONFIG_LOCATION, ) -> None: - """Set config's key by its path + """Delete config's key by its path. - ### Args: - * key (`str`): Key to delete - * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level) - * missing_ok (`bool`): Do not raise an exception if the key is missing. Defaults to `False` - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key to delete. + *path (str): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level) + missing_ok (bool): Do not raise an exception if the key is missing. Defaults to False. + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json". - ### Raises: - * `KeyError`: Key is not found under path provided and `missing_ok` is `False` + Raises: + KeyError: Key is not found under path provided and `missing_ok` is False. """ config_data: Dict[str, Any] = json_read(config_file) @@ -161,16 +141,16 @@ async def config_delete( missing_ok: bool = False, config_file: str | Path = DEFAULT_CONFIG_LOCATION, ) -> None: - """Set config's key by its path + """Delete config's key by its path. - ### Args: - * key (`str`): Key to delete - * *path (`str`): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level) - * missing_ok (`bool`): Do not raise an exception if the key is missing. Defaults to `False` - * config_file (`str | Path`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"` + Args: + key (str): Key to delete. + *path (str): Path to the key of the target (pass *[] or don't pass anything at all to delete on the top/root level) + missing_ok (bool): Do not raise an exception if the key is missing. Defaults to False. + config_file (str | Path, optional): Path-like object or path as a string of a location of the config file. Defaults to "config.json". - ### Raises: - * `KeyError`: Key is not found under path provided and `missing_ok` is `False` + Raises: + KeyError: Key is not found under path provided and `missing_ok` is False. """ config_data: Dict[str, Any] = await json_read(config_file) diff --git a/src/libbot/utils/json/_functions.py b/src/libbot/utils/json/_functions.py index a6cc876..35e1dfe 100644 --- a/src/libbot/utils/json/_functions.py +++ b/src/libbot/utils/json/_functions.py @@ -14,13 +14,13 @@ except ImportError: @asyncable def json_read(path: str | Path) -> Any: - """Read contents of a JSON file + """Read contents of a JSON file and return it. - ### Args: - * path (`str | Path`): Path-like object or path as a string + Args: + path (str | Path): Path-like object or path to the file as a string. - ### Returns: - * `Any`: File contents + Returns: + Any: File contents. """ with open(str(path), mode="r", encoding="utf-8") as f: data = f.read() @@ -30,13 +30,13 @@ def json_read(path: str | Path) -> Any: @json_read.asynchronous async def json_read(path: str | Path) -> Any: - """Read contents of a JSON file + """Read contents of a JSON file and return it. - ### Args: - * path (`str | Path`): Path-like object or path as a string + Args: + path (str | Path): Path-like object or path to the file as a string. - ### Returns: - * `Any`: File contents + Returns: + Any: File contents. """ async with aiofiles.open(str(path), mode="r", encoding="utf-8") as f: data = await f.read() @@ -46,11 +46,11 @@ async def json_read(path: str | Path) -> Any: @asyncable def json_write(data: Any, path: str | Path) -> None: - """Write contents to a JSON file + """Write contents to a JSON file. - ### Args: - * data (`Any`): Contents to write. Must be a JSON serializable - * path (`str | Path`): Path-like object or path as a string of a destination + Args: + data (Any): Contents to write. Must be a JSON-serializable object. + path (str | Path): Path-like object or path to the file as a string. """ with open(str(path), mode="w", encoding="utf-8") as f: f.write( @@ -62,11 +62,11 @@ def json_write(data: Any, path: str | Path) -> None: @json_write.asynchronous async def json_write(data: Any, path: str | Path) -> None: - """Write contents to a JSON file + """Write contents to a JSON file. - ### Args: - * data (`Any`): Contents to write. Must be a JSON serializable - * path (`str | Path`): Path-like object or path as a string of a destination + Args: + data (Any): Contents to write. Must be a JSON-serializable object. + path (str | Path): Path-like object or path to the file as a string. """ async with aiofiles.open(str(path), mode="w", encoding="utf-8") as f: await f.write( diff --git a/src/libbot/utils/misc/_functions.py b/src/libbot/utils/misc/_functions.py index 87c84cf..7e24865 100644 --- a/src/libbot/utils/misc/_functions.py +++ b/src/libbot/utils/misc/_functions.py @@ -4,14 +4,14 @@ from typing import Callable def supports_argument(func: Callable[..., Any], arg_name: str) -> bool: - """Check whether a function has a specific argument + """Check whether a function has a specific argument. - ### Args: - * func (`Callable[..., Any]`): Function to be inspected - * arg_name (`str`): Argument to be checked + Args: + func (Callable[..., Any]): Function to be inspected. + arg_name (str): Argument to be checked. - ### Returns: - * `bool`: `True` if argument is supported and `False` if not + Returns: + bool: True if argument is supported and False if not. """ if hasattr(func, "__code__"): return arg_name in inspect.signature(func).parameters @@ -29,17 +29,17 @@ def nested_set( ) -> Dict[str, Any]: """Set the key by its path to the value - ### Args: - * target (`Dict[str, Any]`): Dictionary to perform modifications on - * value (`Any`): Any data - * *path (`str`): Path to the key of the target - * create_missing (`bool`, *optional*): Create keys on the way if they're missing. Defaults to `True` + Args: + target (Dict[str, Any]): Dictionary to perform the modification on. + value (Any): New value. + *path (str): Path to the key. + create_missing (:obj:`bool`, optional): Create keys on the way if they're missing. Defaults to True. - ### Raises: - * `KeyError`: Key is not found under path provided + Raises: + KeyError: Key is not found under the provided path. - ### Returns: - * `Dict[str, Any]`: Changed dictionary + Returns: + Dict[str, Any]: Modified dictionary. """ target_copy: Dict[str, Any] = target @@ -60,16 +60,16 @@ def nested_set( def nested_delete(target: Dict[str, Any], *path: str) -> Dict[str, Any]: - """Delete the key by its path + """Delete the key by its path. - ### Args: - * target (`Dict[str, Any]`): Dictionary to perform modifications on + Args: + target (Dict[str, Any]): Dictionary to perform the modification on. - ### Raises: - * `KeyError`: Key is not found under path provided + Raises: + KeyError: Key is not found under the provided path. - ### Returns: - `Dict[str, Any]`: Changed dictionary + Returns: + Dict[str, Any]: Modified dictionary. """ target_copy: Dict[str, Any] = target