Compare commits
26 Commits
v4.2.0
...
profitroll
Author | SHA1 | Date | |
---|---|---|---|
88786131f1
|
|||
ef7380ae45
|
|||
727d531d63
|
|||
7d95b1efee
|
|||
03115b4059
|
|||
6038b5058f
|
|||
e4ce5976f2
|
|||
32a9e14d0c
|
|||
3110bb64b1
|
|||
ad38dbdca1
|
|||
edc3e0717d
|
|||
d70fd4f491
|
|||
c4fb1dd5dd
|
|||
38bf43a5e7
|
|||
5dff5fa71d
|
|||
e596658c68
|
|||
1e1b04a8ff
|
|||
69b034c007
|
|||
|
54de950899 | ||
c17a206c44
|
|||
dc05eb0ccb
|
|||
3a7f748d96
|
|||
646229d919
|
|||
48fffb82ce
|
|||
29a90fc385
|
|||
4777b3dc41
|
20
docs/Makefile
Normal file
20
docs/Makefile
Normal file
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
61
docs/conf.py
Normal file
61
docs/conf.py
Normal file
@@ -0,0 +1,61 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
import os
|
||||
import sys
|
||||
from datetime import datetime
|
||||
from typing import List, Dict, Any
|
||||
|
||||
import libbot
|
||||
|
||||
sys.path.insert(0, os.path.abspath(".."))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
project: str = "LibBotUniversal"
|
||||
author: str = libbot.__author__
|
||||
version: str = libbot.__version__
|
||||
release: str = version
|
||||
copyright: str = f"{datetime.now().year} {author}"
|
||||
|
||||
html_title: str = f"{project} v{version} Documentation"
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions: List[str] = [
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.autosummary",
|
||||
"sphinx.ext.viewcode",
|
||||
"sphinx.ext.viewcode",
|
||||
"sphinx.ext.napoleon",
|
||||
"sphinx_copybutton",
|
||||
]
|
||||
|
||||
templates_path: List[str] = ["_templates"]
|
||||
exclude_patterns: List[str] = ["_build", "Thumbs.db", ".DS_Store"]
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
|
||||
html_theme: str = "furo"
|
||||
html_static_path: List[str] = ["_static"]
|
||||
|
||||
html_theme_options: Dict[str, Any] = {
|
||||
"source_repository": "https://git.end-play.xyz/profitroll/LibBotUniversal",
|
||||
"source_branch": "main",
|
||||
"source_directory": "docs/",
|
||||
"light_css_variables": {
|
||||
"font-stack": "'Outfit', sans-serif",
|
||||
},
|
||||
}
|
||||
|
||||
resource_links: Dict[str, Any] = {
|
||||
"issues": "https://git.end-play.xyz/profitroll/LibBotUniversal/issues",
|
||||
"examples": "https://git.end-play.xyz/profitroll/LibBotUniversal/tree/main/examples",
|
||||
}
|
29
docs/index.rst
Normal file
29
docs/index.rst
Normal file
@@ -0,0 +1,29 @@
|
||||
Welcome to LibBotUniversal
|
||||
=============================
|
||||
|
||||
LibBotUniversal (AKA libbot) simplifies development and maintenance of different chatbots.
|
||||
|
||||
Getting started
|
||||
*****************************
|
||||
|
||||
There are a few pages to take a look at if you're just getting started.
|
||||
|
||||
* Installing the library
|
||||
* Creating your first bot
|
||||
* Examples of different bots
|
||||
|
||||
Getting help
|
||||
*****************************
|
||||
|
||||
If you are looking for help or want to report a bug, we got you covered.
|
||||
|
||||
* Bug reports are being submitted on the repo's issue tracker.
|
||||
|
||||
Package
|
||||
*****************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: API reference
|
||||
|
||||
modules
|
35
docs/make.bat
Normal file
35
docs/make.bat
Normal file
@@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=.
|
||||
set BUILDDIR=_build
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.https://www.sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
7
docs/modules.rst
Normal file
7
docs/modules.rst
Normal file
@@ -0,0 +1,7 @@
|
||||
libbot
|
||||
======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 5
|
||||
|
||||
libbot
|
@@ -1,5 +1,5 @@
|
||||
[build-system]
|
||||
requires = ["setuptools>=62.6", "wheel"]
|
||||
requires = ["setuptools>=77.0.3", "wheel"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
|
||||
[project]
|
||||
@@ -9,11 +9,11 @@ authors = [{ name = "Profitroll" }]
|
||||
description = "Universal bot library with functions needed for basic Discord/Telegram bot development."
|
||||
readme = "README.md"
|
||||
requires-python = ">=3.11"
|
||||
license = { text = "GPLv3" }
|
||||
license = "GPL-3.0"
|
||||
license-files = ["LICENSE"]
|
||||
classifiers = [
|
||||
"Development Status :: 3 - Alpha",
|
||||
"Intended Audience :: Developers",
|
||||
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
|
||||
"Operating System :: OS Independent",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
"Programming Language :: Python :: 3.12",
|
||||
@@ -28,6 +28,7 @@ dependencies = { file = "requirements/_.txt" }
|
||||
|
||||
[tool.setuptools.dynamic.optional-dependencies]
|
||||
dev = { file = "requirements/dev.txt" }
|
||||
docs = { file = "requirements/docs.txt" }
|
||||
pycord = { file = "requirements/pycord.txt" }
|
||||
pyrogram = { file = "requirements/pyrogram.txt" }
|
||||
speed = { file = "requirements/speed.txt" }
|
||||
|
@@ -1,2 +1,2 @@
|
||||
aiofiles>=23.0.0
|
||||
typing-extensions~=4.13.0
|
||||
typing-extensions~=4.14.0
|
@@ -1,2 +1,2 @@
|
||||
pymemcache~=4.0.0
|
||||
redis~=6.1.0
|
||||
redis~=6.2.0
|
@@ -1,12 +1,12 @@
|
||||
black==25.1.0
|
||||
build==1.2.2.post1
|
||||
isort==5.13.2
|
||||
mypy==1.15.0
|
||||
mypy==1.16.1
|
||||
pylint==3.3.7
|
||||
pytest-asyncio==0.26.0
|
||||
pytest-cov==6.1.1
|
||||
pytest==8.3.5
|
||||
tox==4.26.0
|
||||
pytest-asyncio==1.0.0
|
||||
pytest-cov==6.2.1
|
||||
pytest==8.4.1
|
||||
tox==4.27.0
|
||||
twine==6.1.0
|
||||
types-aiofiles==24.1.0.20250516
|
||||
types-aiofiles==24.1.0.20250708
|
||||
types-ujson==5.10.0.20250326
|
3
requirements/docs.txt
Normal file
3
requirements/docs.txt
Normal file
@@ -0,0 +1,3 @@
|
||||
furo==2024.8.6
|
||||
sphinx==8.1.3
|
||||
sphinx_copybutton==0.5.2
|
@@ -1,4 +1,4 @@
|
||||
__version__ = "4.2.0"
|
||||
__version__ = "4.3.0"
|
||||
__license__ = "GPL3"
|
||||
__author__ = "Profitroll"
|
||||
|
||||
|
8
src/libbot/cache/classes/cache.py
vendored
8
src/libbot/cache/classes/cache.py
vendored
@@ -1,5 +1,5 @@
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any, Dict
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
import pymemcache
|
||||
import redis
|
||||
@@ -27,16 +27,16 @@ class Cache(ABC):
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def set_json(self, key: str, value: Any) -> None:
|
||||
def set_json(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
# TODO This method must also carry out ObjectId conversion!
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def set_string(self, key: str, value: str) -> None:
|
||||
def set_string(self, key: str, value: str, ttl_seconds: Optional[int] = None) -> None:
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def set_object(self, key: str, value: Any) -> None:
|
||||
def set_object(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
|
25
src/libbot/cache/classes/cache_memcached.py
vendored
25
src/libbot/cache/classes/cache_memcached.py
vendored
@@ -13,20 +13,23 @@ logger: Logger = logging.getLogger(__name__)
|
||||
class CacheMemcached(Cache):
|
||||
client: Client
|
||||
|
||||
def __init__(self, client: Client, prefix: Optional[str] = None):
|
||||
def __init__(
|
||||
self, client: Client, prefix: Optional[str] = None, default_ttl_seconds: Optional[int] = None
|
||||
) -> None:
|
||||
self.client: Client = client
|
||||
self.prefix: str | None = prefix
|
||||
self.default_ttl_seconds: int = default_ttl_seconds if default_ttl_seconds is not None else 0
|
||||
|
||||
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}"
|
||||
@@ -69,28 +72,34 @@ class CacheMemcached(Cache):
|
||||
def get_object(self, key: str) -> Any | None:
|
||||
raise NotImplementedError()
|
||||
|
||||
def set_json(self, key: str, value: Any) -> None:
|
||||
def set_json(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
key = self._get_prefixed_key(key)
|
||||
|
||||
try:
|
||||
self.client.set(key, _json_to_string(value))
|
||||
self.client.set(
|
||||
key,
|
||||
_json_to_string(value),
|
||||
expire=self.default_ttl_seconds if ttl_seconds is None else ttl_seconds,
|
||||
)
|
||||
logger.debug("Set json cache key '%s'", key)
|
||||
except Exception as exc:
|
||||
logger.error("Could not set json cache key '%s' due to: %s", key, exc)
|
||||
return None
|
||||
|
||||
def set_string(self, key: str, value: str) -> None:
|
||||
def set_string(self, key: str, value: str, ttl_seconds: Optional[int] = None) -> None:
|
||||
key = self._get_prefixed_key(key)
|
||||
|
||||
try:
|
||||
self.client.set(key, value)
|
||||
self.client.set(
|
||||
key, value, expire=self.default_ttl_seconds if ttl_seconds is None else ttl_seconds
|
||||
)
|
||||
logger.debug("Set string cache key '%s'", key)
|
||||
except Exception as exc:
|
||||
logger.error("Could not set string cache key '%s' due to: %s", key, exc)
|
||||
return None
|
||||
|
||||
# TODO Implement binary serialization
|
||||
def set_object(self, key: str, value: Any) -> None:
|
||||
def set_object(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
raise NotImplementedError()
|
||||
|
||||
def delete(self, key: str) -> None:
|
||||
|
25
src/libbot/cache/classes/cache_redis.py
vendored
25
src/libbot/cache/classes/cache_redis.py
vendored
@@ -5,7 +5,7 @@ from typing import Dict, Any, Optional
|
||||
from redis import Redis
|
||||
|
||||
from .cache import Cache
|
||||
from ..utils._objects import _string_to_json, _json_to_string
|
||||
from ..utils._objects import _json_to_string, _string_to_json
|
||||
|
||||
logger: Logger = logging.getLogger(__name__)
|
||||
|
||||
@@ -13,20 +13,23 @@ logger: Logger = logging.getLogger(__name__)
|
||||
class CacheRedis(Cache):
|
||||
client: Redis
|
||||
|
||||
def __init__(self, client: Redis, prefix: Optional[str] = None):
|
||||
def __init__(
|
||||
self, client: Redis, prefix: Optional[str] = None, default_ttl_seconds: Optional[int] = None
|
||||
) -> None:
|
||||
self.client: Redis = client
|
||||
self.prefix: str | None = prefix
|
||||
self.default_ttl_seconds: int | None = default_ttl_seconds
|
||||
|
||||
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}"
|
||||
@@ -69,28 +72,32 @@ class CacheRedis(Cache):
|
||||
def get_object(self, key: str) -> Any | None:
|
||||
raise NotImplementedError()
|
||||
|
||||
def set_json(self, key: str, value: Any) -> None:
|
||||
def set_json(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
key = self._get_prefixed_key(key)
|
||||
|
||||
try:
|
||||
self.client.set(key, _json_to_string(value))
|
||||
self.client.set(
|
||||
key,
|
||||
_json_to_string(value),
|
||||
ex=self.default_ttl_seconds if ttl_seconds is None else ttl_seconds,
|
||||
)
|
||||
logger.debug("Set json cache key '%s'", key)
|
||||
except Exception as exc:
|
||||
logger.error("Could not set json cache key '%s' due to: %s", key, exc)
|
||||
return None
|
||||
|
||||
def set_string(self, key: str, value: str) -> None:
|
||||
def set_string(self, key: str, value: str, ttl_seconds: Optional[int] = None) -> None:
|
||||
key = self._get_prefixed_key(key)
|
||||
|
||||
try:
|
||||
self.client.set(key, value)
|
||||
self.client.set(key, value, ex=self.default_ttl_seconds if ttl_seconds is None else ttl_seconds)
|
||||
logger.debug("Set string cache key '%s'", key)
|
||||
except Exception as exc:
|
||||
logger.error("Could not set string cache key '%s' due to: %s", key, exc)
|
||||
return None
|
||||
|
||||
# TODO Implement binary serialization
|
||||
def set_object(self, key: str, value: Any) -> None:
|
||||
def set_object(self, key: str, value: Any, ttl_seconds: Optional[int] = None) -> None:
|
||||
raise NotImplementedError()
|
||||
|
||||
def delete(self, key: str) -> None:
|
||||
|
16
src/libbot/cache/manager/manager.py
vendored
16
src/libbot/cache/manager/manager.py
vendored
@@ -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.")
|
||||
|
@@ -4,8 +4,8 @@ from typing import Any, List, Optional
|
||||
class ConfigKeyError(Exception):
|
||||
"""Raised when config key is not found.
|
||||
|
||||
### Attributes:
|
||||
* key (`str | List[str]`): Missing config key.
|
||||
Args:
|
||||
key (str | List[str]): Missing config key
|
||||
"""
|
||||
|
||||
def __init__(self, key: str | List[str]) -> None:
|
||||
@@ -21,9 +21,9 @@ class ConfigKeyError(Exception):
|
||||
class ConfigValueError(Exception):
|
||||
"""Raised when config key's value is invalid.
|
||||
|
||||
### Attributes:
|
||||
* key (`str | List[str]`): Invalid config key.
|
||||
* value (`Optional[Any]`): Key's correct value.
|
||||
Args:
|
||||
key (str | List[str]): Invalid config key
|
||||
value (Optional[Any]): Key's correct value
|
||||
"""
|
||||
|
||||
def __init__(self, key: str | List[str], value: Optional[Any] = None) -> None:
|
||||
|
@@ -18,16 +18,16 @@ def _(
|
||||
locale: str | None = "en",
|
||||
locales_root: str | Path = Path("locale"),
|
||||
) -> Any:
|
||||
"""Get value of locale string
|
||||
"""Get value of the 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 be 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 the 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 be 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,17 +94,16 @@ 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] = []
|
||||
|
||||
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
|
||||
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] = []
|
||||
@@ -161,20 +160,17 @@ async def in_all_locales(key: str, *args: str, locales_root: str | Path = Path("
|
||||
|
||||
|
||||
@asyncable
|
||||
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
|
||||
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.
|
||||
|
||||
### 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] = {}
|
||||
|
||||
for locale in _get_valid_locales(locales_root):
|
||||
@@ -200,15 +196,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] = {}
|
||||
|
@@ -14,6 +14,11 @@ class BotLocale:
|
||||
default_locale: str | None = "en",
|
||||
locales_root: str | Path = Path("locale"),
|
||||
) -> 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):
|
||||
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 be 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] = {}
|
||||
|
||||
|
@@ -19,16 +19,27 @@ logger: Logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PycordBot(Bot):
|
||||
# TODO Write a docstring
|
||||
@override
|
||||
def __init__(
|
||||
self,
|
||||
*args,
|
||||
config: Dict[str, Any] | None = None,
|
||||
config_path: str | Path = Path("config.json"),
|
||||
locales_root: str | Path | None = None,
|
||||
scheduler: AsyncIOScheduler | BackgroundScheduler | None = None,
|
||||
**kwargs,
|
||||
self,
|
||||
*args,
|
||||
config: Dict[str, Any] | None = None,
|
||||
config_path: str | Path = Path("config.json"),
|
||||
locales_root: str | Path | None = None,
|
||||
scheduler: AsyncIOScheduler | BackgroundScheduler | None = None,
|
||||
**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)
|
||||
|
||||
super().__init__(
|
||||
@@ -51,15 +62,30 @@ class PycordBot(Bot):
|
||||
|
||||
self.scheduler: AsyncIOScheduler | BackgroundScheduler | None = scheduler
|
||||
|
||||
# TODO Write a docstring
|
||||
@override
|
||||
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:
|
||||
self.scheduler.start()
|
||||
|
||||
await super().start(token, reconnect=reconnect)
|
||||
|
||||
# TODO Write a docstring
|
||||
@override
|
||||
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:
|
||||
self.scheduler.shutdown(scheduler_wait)
|
||||
|
||||
|
@@ -16,20 +16,24 @@ def _hex_from_int(color_int: int) -> str:
|
||||
|
||||
|
||||
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
|
||||
:type hex_string: str
|
||||
:return: Colour object
|
||||
Args:
|
||||
hex_string (str): Hexadecimal string to convert into :class:`discord.Colour` object
|
||||
|
||||
Returns:
|
||||
Colour: :class:`discord.Colour` object
|
||||
"""
|
||||
return Colour(_int_from_hex(hex_string))
|
||||
|
||||
|
||||
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
|
||||
:type color: Colour
|
||||
:return: Hexadecimal string in #XXXXXX format
|
||||
Args:
|
||||
color (Colour): :class:`discord.Colour` object to convert into the string
|
||||
|
||||
Returns:
|
||||
str: Hexadecimal string in #XXXXXX format
|
||||
"""
|
||||
return _hex_from_int(color.value)
|
||||
|
@@ -6,7 +6,7 @@ from logging import Logger
|
||||
from os import cpu_count, getpid
|
||||
from pathlib import Path
|
||||
from time import time
|
||||
from typing import Any, Dict, List
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from typing_extensions import override
|
||||
|
||||
@@ -46,27 +46,28 @@ logger: Logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class PyroClient(Client):
|
||||
# TODO Write a docstring
|
||||
@override
|
||||
def __init__(
|
||||
self,
|
||||
name: str = "bot_client",
|
||||
owner: int | None = None,
|
||||
config: Dict[str, Any] | None = None,
|
||||
config_path: str | Path = Path("config.json"),
|
||||
api_id: int | None = None,
|
||||
api_hash: str | None = None,
|
||||
bot_token: str | None = None,
|
||||
workers: int = min(32, cpu_count() + 4),
|
||||
locales_root: str | Path | None = None,
|
||||
plugins_root: str = "plugins",
|
||||
plugins_exclude: List[str] | None = None,
|
||||
sleep_threshold: int = 120,
|
||||
max_concurrent_transmissions: int = 1,
|
||||
commands_source: Dict[str, dict] | None = None,
|
||||
scoped_commands: bool | None = None,
|
||||
i18n_bot_info: bool = False,
|
||||
scheduler: AsyncIOScheduler | BackgroundScheduler | None = None,
|
||||
**kwargs,
|
||||
self,
|
||||
name: str = "bot_client",
|
||||
owner: int | None = None,
|
||||
config: Dict[str, Any] | None = None,
|
||||
config_path: str | Path = Path("config.json"),
|
||||
api_id: int | None = None,
|
||||
api_hash: str | None = None,
|
||||
bot_token: str | None = None,
|
||||
workers: int = min(32, cpu_count() + 4),
|
||||
locales_root: str | Path | None = None,
|
||||
plugins_root: str = "plugins",
|
||||
plugins_exclude: List[str] | None = None,
|
||||
sleep_threshold: int = 120,
|
||||
max_concurrent_transmissions: int = 1,
|
||||
commands_source: Dict[str, dict] | None = None,
|
||||
scoped_commands: bool | None = None,
|
||||
i18n_bot_info: bool = False,
|
||||
scheduler: AsyncIOScheduler | BackgroundScheduler | None = None,
|
||||
**kwargs,
|
||||
):
|
||||
self.config: Dict[str, Any] = config if config is not None else json_read(config_path)
|
||||
|
||||
@@ -119,6 +120,12 @@ class PyroClient(Client):
|
||||
|
||||
@override
|
||||
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()
|
||||
|
||||
self.start_time = time()
|
||||
@@ -209,8 +216,15 @@ class PyroClient(Client):
|
||||
|
||||
@override
|
||||
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:
|
||||
"""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:
|
||||
await self.send_message(
|
||||
chat_id=(
|
||||
@@ -237,10 +251,10 @@ class PyroClient(Client):
|
||||
raise SystemExit("Bot has been shut down, this is not an application error!") from exc
|
||||
|
||||
async def collect_commands(self) -> List[CommandSet] | None:
|
||||
"""Gather list of the bot's commands
|
||||
"""Gather list of the bot's commands.
|
||||
|
||||
### Returns:
|
||||
* `List[CommandSet]`: List of the commands' sets.
|
||||
Returns:
|
||||
List[CommandSet]: List of the commands' sets
|
||||
"""
|
||||
command_sets = None
|
||||
|
||||
@@ -308,7 +322,7 @@ class PyroClient(Client):
|
||||
# in it, if there are any. Then adds them to self.commands
|
||||
for handler in self.dispatcher.groups[0]:
|
||||
if isinstance(handler, MessageHandler) and (
|
||||
hasattr(handler.filters, "base") or hasattr(handler.filters, "other")
|
||||
hasattr(handler.filters, "base") or hasattr(handler.filters, "other")
|
||||
):
|
||||
for entry in [handler.filters.base, handler.filters.other]:
|
||||
if hasattr(entry, "commands"):
|
||||
@@ -319,13 +333,13 @@ class PyroClient(Client):
|
||||
return command_sets
|
||||
|
||||
def add_command(
|
||||
self,
|
||||
command: str,
|
||||
self,
|
||||
command: str,
|
||||
) -> None:
|
||||
"""Add command to the bot's internal commands list
|
||||
"""Add command to the bot's internal commands list.
|
||||
|
||||
### Args:
|
||||
* command (`str`)
|
||||
Args:
|
||||
command (str): Command's name
|
||||
"""
|
||||
self.commands.append(
|
||||
PyroCommand(
|
||||
@@ -338,9 +352,12 @@ class PyroClient(Client):
|
||||
command,
|
||||
)
|
||||
|
||||
async def register_commands(self, command_sets: List[CommandSet] | None = None) -> None:
|
||||
"""Register commands stored in bot's 'commands' attribute"""
|
||||
async def register_commands(self, command_sets: Optional[List[CommandSet]] = None) -> None:
|
||||
"""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:
|
||||
commands = [
|
||||
BotCommand(command=command.command, description=command.description)
|
||||
@@ -365,9 +382,12 @@ class PyroClient(Client):
|
||||
language_code=command_set.language_code,
|
||||
)
|
||||
|
||||
async def remove_commands(self, command_sets: List[CommandSet] | None = None) -> None:
|
||||
"""Remove commands stored in bot's 'commands' attribute"""
|
||||
async def remove_commands(self, command_sets: Optional[List[CommandSet]] = None) -> None:
|
||||
"""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:
|
||||
logger.info("Removing commands with a default scope 'BotCommandScopeDefault'")
|
||||
await self.delete_bot_commands(BotCommandScopeDefault())
|
||||
|
@@ -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)
|
||||
|
||||
|
@@ -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(
|
||||
|
@@ -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
|
||||
|
||||
|
Reference in New Issue
Block a user