diff --git a/requirements/dev.txt b/requirements/dev.txt index 7d23cf9..e51e930 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -8,5 +8,5 @@ pytest-cov==6.2.1 pytest==8.4.1 tox==4.27.0 twine==6.1.0 -types-aiofiles==24.1.0.20250606 +types-aiofiles==24.1.0.20250708 types-ujson==5.10.0.20250326 \ No newline at end of file diff --git a/src/libbot/cache/classes/cache_memcached.py b/src/libbot/cache/classes/cache_memcached.py index 4c74453..33b80ec 100644 --- a/src/libbot/cache/classes/cache_memcached.py +++ b/src/libbot/cache/classes/cache_memcached.py @@ -23,13 +23,13 @@ class CacheMemcached(Cache): logger.info("Initialized Memcached for caching") @classmethod - def from_config(cls, engine_config: Dict[str, Any], prefix: Optional[str] = None) -> "CacheMemcached": + def from_config(cls, engine_config: Dict[str, Any], prefix: Optional[str] = None, default_ttl_seconds: Optional[int] = None) -> "CacheMemcached": if "uri" not in engine_config: raise KeyError( "Cache configuration is invalid. Please check if all keys are set (engine: memcached)" ) - return cls(Client(engine_config["uri"], default_noreply=True), prefix=prefix) + return cls(Client(engine_config["uri"], default_noreply=True, default_ttl_seconds=default_ttl_seconds), prefix=prefix) def _get_prefixed_key(self, key: str) -> str: return key if self.prefix is None else f"{self.prefix}_{key}" diff --git a/src/libbot/cache/classes/cache_redis.py b/src/libbot/cache/classes/cache_redis.py index c5d0ad9..eecc7c0 100644 --- a/src/libbot/cache/classes/cache_redis.py +++ b/src/libbot/cache/classes/cache_redis.py @@ -23,13 +23,13 @@ class CacheRedis(Cache): logger.info("Initialized Redis for caching") @classmethod - def from_config(cls, engine_config: Dict[str, Any], prefix: Optional[str] = None) -> Any: + def from_config(cls, engine_config: Dict[str, Any], prefix: Optional[str] = None, default_ttl_seconds: Optional[int] = None) -> Any: if "uri" not in engine_config: raise KeyError( "Cache configuration is invalid. Please check if all keys are set (engine: memcached)" ) - return cls(Redis.from_url(engine_config["uri"]), prefix=prefix) + return cls(Redis.from_url(engine_config["uri"]), prefix=prefix, default_ttl_seconds=default_ttl_seconds) def _get_prefixed_key(self, key: str) -> str: return key if self.prefix is None else f"{self.prefix}_{key}" diff --git a/src/libbot/cache/manager/manager.py b/src/libbot/cache/manager/manager.py index 67d3f6b..153840f 100644 --- a/src/libbot/cache/manager/manager.py +++ b/src/libbot/cache/manager/manager.py @@ -7,7 +7,19 @@ def create_cache_client( config: Dict[str, Any], engine: Literal["memcached", "redis"] | None = None, 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}'") @@ -18,8 +30,8 @@ def create_cache_client( match engine: case "memcached": - return CacheMemcached.from_config(config["cache"][engine], prefix=prefix) + return CacheMemcached.from_config(config["cache"][engine], prefix=prefix, default_ttl_seconds=default_ttl_seconds) case "redis": - return CacheRedis.from_config(config["cache"][engine], prefix=prefix) + return CacheRedis.from_config(config["cache"][engine], prefix=prefix, default_ttl_seconds=default_ttl_seconds) case _: raise KeyError(f"Cache implementation for the engine '{engine}' is not present.") 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