Improved typing and linting

libbot/__main__.py

@@ -6,17 +6,62 @@ from ujson import dumps, loads
 
 
 async def json_read(path: Union[str, Path]) -> Any:
+    """Read contents of a JSON file
+
+    ### Args:
+        * path (`Union[str, Path]`): Path-like object or path as a string
+
+    ### Returns:
+        * `Any`: File contents
+    """
     async with aiofiles.open(str(path), mode="r", encoding="utf-8") as f:
         data = await f.read()
     return loads(data)
 
 
 async def json_write(data: Any, path: Union[str, Path]) -> None:
+    """Write contents to a JSON file
+
+    ### Args:
+        * data (`Any`): Contents to write. Must be a JSON serializable
+        * path (`Union[str, Path]`): Path-like object or path as a string of a destination
+    """
     async with aiofiles.open(str(path), mode="w", encoding="utf-8") as f:
         await f.write(dumps(data, ensure_ascii=False, escape_forward_slashes=False))
 
 
-async def config_get(key: str, *path: str, config_file: str = "config.json") -> Any:
+async def config_get(
+    key: str, *path: str, config_file: Union[str, Path] = "config.json"
+) -> 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"`
+
+    ### Args:
+        * key (`str`): Key that contains the value
+        * *path (`str`): Path to the key that contains the value
+        * config_file (`Union[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
+
+    ### Example:
+    Get the "salary" of "Pete" from this JSON structure:
+    ```json
+    {
+        "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_key = await json_read(config_file)
     for dict_key in path:
         this_key = this_key[dict_key]
@@ -24,8 +69,16 @@ async def config_get(key: str, *path: str, config_file: str = "config.json") ->
 
 
 async def config_set(
-    key: str, value: Any, *path: str, config_file: str = "config.json"
+    key: str, value: Any, *path: str, config_file: Union[str, Path] = "config.json"
 ) -> None:
+    """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
+        * config_file (`Union[str, Path]`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    """
     this_dict = await json_read(config_file)
     string = "this_dict"
     for arg in path:

libbot/sync/__init__.py

@@ -5,17 +5,62 @@ from ujson import dumps, loads
 
 
 def json_read(path: Union[str, Path]) -> Any:
+    """Read contents of a JSON file
+
+    ### Args:
+        * path (`Union[str, Path]`): Path-like object or path as a string
+
+    ### Returns:
+        * `Any`: File contents
+    """
     with open(str(path), mode="r", encoding="utf-8") as f:
         data = f.read()
     return loads(data)
 
 
 def json_write(data: Any, path: Union[str, Path]) -> None:
+    """Write contents to a JSON file
+
+    ### Args:
+        * data (`Any`): Contents to write. Must be a JSON serializable
+        * path (`Union[str, Path]`): Path-like object or path as a string of a destination
+    """
     with open(str(path), mode="w", encoding="utf-8") as f:
         f.write(dumps(data, ensure_ascii=False, escape_forward_slashes=False, indent=4))
 
 
-def config_get(key: str, *path: str, config_file: str = "config.json") -> Any:
+def config_get(
+    key: str, *path: str, config_file: Union[str, Path] = "config.json"
+) -> 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"`
+
+    ### Args:
+        * key (`str`): Key that contains the value
+        * *path (`str`): Path to the key that contains the value
+        * config_file (`Union[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
+
+    ### Example:
+    Get the "salary" of "Pete" from this JSON structure:
+    ```json
+    {
+        "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_key = json_read(config_file)
     for dict_key in path:
         this_key = this_key[dict_key]
@@ -23,8 +68,16 @@ def config_get(key: str, *path: str, config_file: str = "config.json") -> Any:
 
 
 def config_set(
-    key: str, value: Any, *path: str, config_file: str = "config.json"
+    key: str, value: Any, *path: str, config_file: Union[str, Path] = "config.json"
 ) -> None:
+    """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
+        * config_file (`Union[str, Path]`, *optional*): Path-like object or path as a string of a location of the config file. Defaults to `"config.json"`
+    """
     this_dict = json_read(config_file)
     string = "this_dict"
     for arg in path: