telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/tools/magic/descriptors.py

@@ -0,0 +1,57 @@
+import typing
+
+_NOVALUE: typing.Any = object()
+
+
+def private_func_name(func: typing.Callable[..., typing.Any], /) -> str:
+    return "__" + func.__name__
+
+
+class additional_property[T, R]:  # noqa: N801
+    def __init__(self, func: typing.Callable[[T], R], /) -> None:
+        self.func = func
+        self.func_name = private_func_name(func)
+
+    def __set__(self, instance: T, value: typing.Any, /) -> None:
+        instance.__dict__[self.func_name] = value
+
+    def __get__(self, instance: T | None, owner: type[T], /) -> typing.Any:
+        if instance is None:
+            raise AttributeError("Cannot access additional property from class.")
+
+        value = instance.__dict__.get(self.func_name, _NOVALUE)
+        if value is _NOVALUE:
+            value = self.func(instance)
+            instance.__dict__[self.func_name] = value
+
+        return value
+
+    def __delete__(self, instance: T, /) -> None:
+        instance.__dict__.pop(self.func_name, None)
+
+
+class class_property[T]:  # noqa: N801
+    def __init__(self, func: typing.Callable[..., T], /) -> None:
+        self.func = func
+        self.func_name = private_func_name(func)
+
+    def __get__(self, instance: typing.Any | None, owner: type[typing.Any], /) -> T:
+        return self.func(owner)
+
+
+class class_cached_property[T]:  # noqa: N801
+    def __init__(self, func: typing.Callable[..., T], /) -> None:
+        self.func = func
+        self.func_name = private_func_name(func)
+
+    def __get__(self, instance: typing.Any | None, owner: type[typing.Any], /) -> T:
+        value = getattr(owner, self.func_name, _NOVALUE)
+
+        if value is _NOVALUE:
+            value = self.func(owner)
+            setattr(owner, self.func_name, value)
+
+        return value
+
+
+__all__ = ("additional_property", "class_cached_property", "class_property")

telegrinder/tools/magic/function.py

@@ -0,0 +1,254 @@
+import dataclasses
+import enum
+import inspect
+import types
+import typing
+from functools import cached_property, lru_cache, partial
+
+from telegrinder.tools.magic.annotations import Annotations, MappingAnnotations
+
+type AnyFunction = Func[..., typing.Any]
+type Func[**P, R] = typing.Callable[P, R]
+type Function[**P, R] = typing.Callable[
+    P,
+    typing.Union[
+        typing.Coroutine[typing.Any, typing.Any, R],
+        typing.Awaitable[R],
+        typing.AsyncGenerator[R, typing.Any],
+        typing.Generator[typing.Any, typing.Any, R],
+        typing.AsyncContextManager[R, typing.Any],
+        typing.ContextManager[R, typing.Any],
+        R,
+    ],
+]
+
+
+def _to_str(obj: typing.Any, /) -> str:
+    if isinstance(obj, enum.Enum):
+        return str(obj.value)
+    return str(obj) if not isinstance(obj, str) else obj
+
+
+@lru_cache(maxsize=1024)
+def _unwrap_func(obj: typing.Any, /) -> typing.Any:
+    while True:
+        if isinstance(obj, partial):
+            obj = obj.func
+            continue
+
+        if hasattr(obj, "__wrapped__"):
+            obj = obj.__wrapped__
+            continue
+
+        break
+
+    return obj
+
+
+def _resolve_arg_names(
+    func: AnyFunction,
+    /,
+    *,
+    start_idx: int,
+    stop_idx: int,
+    exclude: set[str] | None = None,
+) -> tuple[str, ...]:
+    exclude = exclude or set()
+    varnames = func.__code__.co_varnames[start_idx:stop_idx]
+    return tuple(name for name in varnames if name not in exclude)
+
+
+class FunctionParameters(typing.TypedDict):
+    args: list[tuple[str, typing.Any | inspect.Parameter.empty]]
+    kwargs: list[tuple[str, typing.Any | inspect.Parameter.empty]]
+    var_star_args: typing.NotRequired[str]
+    var_star_kwargs: typing.NotRequired[str]
+
+
+@dataclasses.dataclass(frozen=True, repr=False)
+class Bundle[R]:
+    function: Func[..., R]
+    start_idx: int
+    context: types.MappingProxyType[str, typing.Any]
+
+    @cached_property
+    def args(self) -> tuple[typing.Any, ...]:
+        return tuple(
+            self.context[name]
+            for name in resolve_posonly_arg_names(self.function, start_idx=self.start_idx)
+            if name in self.context
+        )
+
+    @cached_property
+    def kwargs(self) -> dict[str, typing.Any]:
+        posonly_arg_names = resolve_posonly_arg_names(self.function, start_idx=self.start_idx)
+        return {name: value for name, value in self.context.items() if name not in posonly_arg_names}
+
+    @classmethod
+    def from_context(
+        cls,
+        function: Func[..., R],
+        context: typing.Mapping[str, typing.Any],
+        /,
+        *,
+        start_idx: int = 1,
+    ) -> typing.Self:
+        return cls(function, start_idx, types.MappingProxyType(context))
+
+    def __repr__(self) -> str:
+        return "<{}: function={!r} bundle args={!r} kwargs={!r}>".format(
+            type(self).__name__,
+            self.function,
+            self.args,
+            self.kwargs,
+        )
+
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> R:
+        return self.function(*args, *self.args, **kwargs, **self.kwargs)
+
+    def __and__(self, other: object, /) -> typing.Self:
+        if not isinstance(other, Bundle):
+            return NotImplemented
+
+        if self.function != other.function:
+            raise ValueError(
+                f"Cannot merge contexts because bundle {other!r} is intended for a different function.",
+            )
+
+        return dataclasses.replace(
+            self,
+            context=types.MappingProxyType(mapping=self.context | other.context),
+        )
+
+    def __iand__(self, other: object, /) -> typing.Self:
+        return self.__and__(other)
+
+
+def resolve_arg_names(
+    func: AnyFunction,
+    /,
+    *,
+    start_idx: int = 1,
+    exclude: set[str] | None = None,
+) -> tuple[str, ...]:
+    func = _unwrap_func(func)
+    return _resolve_arg_names(
+        func,
+        start_idx=start_idx,
+        stop_idx=func.__code__.co_argcount + func.__code__.co_kwonlyargcount,
+        exclude=exclude,
+    )
+
+
+def resolve_kwonly_arg_names(
+    func: AnyFunction,
+    /,
+    *,
+    start_idx: int = 1,
+    exclude: set[str] | None = None,
+) -> tuple[str, ...]:
+    func = _unwrap_func(func)
+    return _resolve_arg_names(
+        func,
+        start_idx=func.__code__.co_argcount + start_idx,
+        stop_idx=func.__code__.co_argcount + func.__code__.co_kwonlyargcount,
+        exclude=exclude,
+    )
+
+
+def resolve_posonly_arg_names(
+    func: AnyFunction,
+    /,
+    *,
+    start_idx: int = 1,
+    exclude: set[str] | None = None,
+) -> tuple[str, ...]:
+    func = _unwrap_func(func)
+    return _resolve_arg_names(
+        func,
+        start_idx=start_idx,
+        stop_idx=func.__code__.co_posonlyargcount,
+        exclude=exclude,
+    )
+
+
+@lru_cache(maxsize=1024)
+def get_default_args(func: AnyFunction, /) -> dict[str, typing.Any]:
+    parameters = get_func_parameters(func)
+    return {
+        key: value
+        for sublist in (parameters["args"], parameters["kwargs"])
+        for key, value in sublist
+        if value is not inspect.Parameter.empty
+    }
+
+
+@lru_cache(maxsize=1024)
+def get_func_parameters(func: AnyFunction, /) -> FunctionParameters:
+    func_params = FunctionParameters(args=[], kwargs=[])
+
+    for k, p in inspect.signature(func).parameters.items():
+        if k in ("self", "cls"):
+            continue
+
+        match p.kind:
+            case p.POSITIONAL_OR_KEYWORD | p.POSITIONAL_ONLY:
+                func_params["args"].append((k, p.default))
+            case p.KEYWORD_ONLY:
+                func_params["kwargs"].append((k, p.default))
+            case p.VAR_POSITIONAL:
+                func_params["var_star_args"] = k
+            case p.VAR_KEYWORD:
+                func_params["var_star_kwargs"] = k
+
+    return func_params
+
+
+@lru_cache(maxsize=1024)
+def get_func_annotations(func: AnyFunction, /) -> MappingAnnotations:
+    return Annotations(obj=func).get(
+        ignore_failed_evals=True,
+        exclude_forward_refs=True,
+        cache=False,
+    )
+
+
+def bundle[R](
+    function: Function[..., R],
+    context: dict[typing.Any, typing.Any],
+    /,
+    *,
+    start_idx: int = 1,
+    bundle_kwargs: bool = False,
+    typebundle: bool = False,
+    omit_defaults: bool = False,
+) -> Bundle[R]:
+    if typebundle:
+        return Bundle.from_context(
+            function,
+            {name: context[ann] for name, ann in get_func_annotations(function).items() if ann in context},
+            start_idx=start_idx,
+        )
+
+    kwargs = {_to_str(k): v for k, v in context.items()}
+    if not bundle_kwargs or "var_star_kwargs" not in get_func_parameters(function):
+        names = resolve_arg_names(function, start_idx=start_idx, exclude={"cls", "self"})
+        kwargs = {k: v for k, v in kwargs.items() if k in names}
+
+    return Bundle.from_context(
+        function,
+        kwargs if omit_defaults else get_default_args(function) | kwargs,
+        start_idx=start_idx,
+    )
+
+
+__all__ = (
+    "Bundle",
+    "bundle",
+    "get_default_args",
+    "get_func_annotations",
+    "get_func_parameters",
+    "resolve_arg_names",
+    "resolve_kwonly_arg_names",
+    "resolve_posonly_arg_names",
+)

telegrinder/tools/magic/inspect.py

@@ -0,0 +1,16 @@
+import sys
+
+
+def get_frame_module_name() -> str:
+    frame = sys._getframe()
+
+    while frame:
+        if frame.f_globals.get("__name__", "").startswith("telegrinder"):
+            frame = frame.f_back
+        else:
+            break
+
+    return "<module>" if frame is None else frame.f_globals.get("__name__", "<module>")
+
+
+__all__ = ("get_frame_module_name",)

telegrinder/tools/magic/shortcut.py

@@ -0,0 +1,107 @@
+import dataclasses
+import inspect
+import typing
+from collections import OrderedDict
+from functools import wraps
+
+from kungfu.library.monad.result import Result
+
+from telegrinder.tools.magic.function import get_func_parameters
+from telegrinder.types.methods_utils import get_params
+
+if typing.TYPE_CHECKING:
+    from telegrinder.api.error import APIError
+    from telegrinder.bot.cute_types.base import BaseCute, BaseShortcuts
+
+type Executor[T] = typing.Callable[
+    [T, str, dict[str, typing.Any]],
+    typing.Awaitable[Result[typing.Any, APIError]],
+]
+type CuteMethod[T, **P, R] = typing.Callable[
+    typing.Concatenate[T, P],
+    typing.Awaitable[Result[R, APIError]],
+]
+type ShortcutMethod[**P, R] = typing.Callable[
+    typing.Concatenate[typing.Any, P],
+    typing.Coroutine[typing.Any, typing.Any, Result[R, APIError]],
+]
+
+
+@dataclasses.dataclass(slots=True, frozen=True)
+class Shortcut[T]:
+    method_name: str
+    executor: Executor[T] | None = dataclasses.field(default=None, kw_only=True)
+    custom_params: set[str] = dataclasses.field(default_factory=lambda: set[str](), kw_only=True)
+
+
+@typing.overload
+def shortcut[T: BaseCute, S: BaseShortcuts, **P, R](
+    method_name: str,
+    /,
+    *,
+    custom_params: set[str] = ...,
+) -> typing.Callable[[CuteMethod[T, P, R] | CuteMethod[S, P, R]], ShortcutMethod[P, R]]: ...
+
+
+@typing.overload
+def shortcut[T: BaseCute, S: BaseShortcuts, **P, R](
+    method_name: str,
+    /,
+    *,
+    executor: Executor[T],
+    custom_params: set[str] = ...,
+) -> typing.Callable[[CuteMethod[T, P, R] | CuteMethod[S, P, R]], ShortcutMethod[P, R]]: ...
+
+
+def shortcut[**P, R](
+    method_name: str,
+    /,
+    *,
+    executor: Executor[typing.Any] | None = None,
+    custom_params: set[str] | None = None,
+) -> typing.Callable[[CuteMethod[typing.Any, P, R]], ShortcutMethod[P, R]]:
+    """Decorate a cute method as a shortcut."""
+
+    def wrapper(func: CuteMethod[typing.Any, P, R]) -> ShortcutMethod[P, R]:
+        @wraps(func)
+        async def inner(
+            self: typing.Any,
+            *args: P.args,
+            **kwargs: P.kwargs,
+        ) -> Result[R, typing.Any]:
+            if executor is None:
+                return await func(self, *args, **kwargs)
+
+            params: dict[str, typing.Any] = OrderedDict()
+            func_params = get_func_parameters(func)
+
+            for index, (arg, default) in enumerate(func_params["args"]):
+                if len(args) > index:
+                    params[arg] = args[index]
+                elif default is not inspect.Parameter.empty:
+                    params[arg] = default
+
+            if var_args := func_params.get("var_star_args"):
+                params[var_args] = args[len(func_params["args"]) :]
+
+            for kwarg, default in func_params["kwargs"]:
+                params[kwarg] = (
+                    kwargs.pop(kwarg, default) if default is not inspect.Parameter.empty else kwargs.pop(kwarg)
+                )
+
+            if var_kwargs := func_params.get("var_star_kwargs"):
+                params[var_kwargs] = kwargs.copy()
+
+            return await executor(self, method_name, get_params(params))
+
+        inner.__shortcut__ = Shortcut(  # type: ignore
+            method_name=method_name,
+            executor=executor,
+            custom_params=custom_params or set(),
+        )
+        return inner  # type: ignore
+
+    return wrapper
+
+
+__all__ = ("Shortcut", "shortcut")

telegrinder/tools/member_descriptor_proxy.py

@@ -0,0 +1,95 @@
+import dataclasses
+import operator
+import types
+import typing
+
+type Operation = GetAttribute | GetItem | MethodCall
+
+
+def evaluate_operations(
+    obj: typing.Any,
+    member_name: str,
+    operations: list[Operation],
+    /,
+) -> typing.Any:
+    obj = getattr(obj, member_name)
+
+    for operation in operations:
+        match operation:
+            case GetAttribute(attribute_name=attribute_name):
+                obj = getattr(obj, attribute_name)
+            case GetItem():
+                obj = operation[obj]
+            case MethodCall():
+                obj = operation(obj)
+
+    return obj
+
+
+@dataclasses.dataclass(slots=True, frozen=True, kw_only=True)
+class MethodCall:
+    caller: operator.methodcaller
+
+    def __call__(self, obj: typing.Any, /) -> typing.Any:
+        return self.caller(obj)
+
+
+@dataclasses.dataclass(slots=True, frozen=True, kw_only=True)
+class GetAttribute:
+    attribute_name: str
+
+
+@dataclasses.dataclass(slots=True, frozen=True, kw_only=True)
+class GetItem:
+    itemgetter: operator.itemgetter[typing.Any]
+
+    def __getitem__(self, obj: typing.Any, /) -> typing.Any:
+        return self.itemgetter(obj)
+
+
+class MemberDescriptorProxy:
+    _operations: list[Operation]
+    _objclass: type[typing.Any]
+
+    __slots__ = ("_descriptor", "_operations", "_member_name", "_objclass")
+
+    def __init__(self, descriptor: types.MemberDescriptorType) -> None:
+        self._descriptor = descriptor
+        self._member_name = descriptor.__name__
+        self._objclass = descriptor.__objclass__
+        self._operations = []
+
+    def __getattr__(self, __name: str) -> typing.Any:
+        if __name in getattr(type(self), "__static_attributes__"):
+            return super().__getattribute__(__name)
+
+        self._operations.append(GetAttribute(attribute_name=__name))
+        return self
+
+    def __getitem__(self, __item: typing.Any) -> typing.Any:
+        self._operations.append(GetItem(itemgetter=operator.itemgetter(__item)))
+        return self
+
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
+        if not self._operations or not isinstance(operation := self._operations.pop(-1), GetAttribute):
+            raise SyntaxError("No operations to call.")
+
+        self._operations.append(MethodCall(caller=operator.methodcaller(operation.attribute_name, *args, **kwargs)))
+        return self
+
+    def __get__(self, instance: typing.Any, owner: typing.Type[typing.Any]) -> typing.Any:
+        if instance is None:
+            return self
+        return self._descriptor.__get__(instance, owner)
+
+    def __set__(self, instance: typing.Any, value: typing.Any) -> None:
+        self._descriptor.__set__(instance, value)
+
+    def __delete__(self, instance: typing.Any) -> None:
+        self._descriptor.__delete__(instance)
+
+    def __repr__(self) -> str:
+        return self._descriptor.__repr__()
+
+
+__all__ = ("MemberDescriptorProxy", "evaluate_operations")

telegrinder/tools/parse_mode.py

@@ -0,0 +1,12 @@
+import typing
+
+from telegrinder.tools.final import Final
+
+
+@typing.final
+class ParseMode(Final):
+    MARKDOWNV2: typing.Final[typing.Literal["MarkdownV2"]] = "MarkdownV2"
+    HTML: typing.Final[typing.Literal["HTML"]] = "HTML"
+
+
+__all__ = ("ParseMode",)

telegrinder/tools/serialization/__init__.py

@@ -0,0 +1,5 @@
+from telegrinder.tools.serialization.abc import ABCDataSerializer
+from telegrinder.tools.serialization.json_ser import JSONSerializer
+from telegrinder.tools.serialization.msgpack_ser import MsgPackSerializer
+
+__all__ = ("ABCDataSerializer", "JSONSerializer", "MsgPackSerializer")

telegrinder/tools/serialization/abc.py

@@ -0,0 +1,34 @@
+import abc
+import typing
+from functools import cached_property
+
+import msgspec
+from kungfu.library.monad.result import Result
+
+if typing.TYPE_CHECKING:
+    from _typeshed import DataclassInstance
+
+type ModelType = msgspec.Struct | DataclassInstance
+
+
+class ABCDataSerializer[Data = typing.Any](abc.ABC):
+    ident_key: str | None = None
+
+    @abc.abstractmethod
+    def __init__(self, data_type: type[Data], /) -> None:
+        pass
+
+    @cached_property
+    def key(self) -> str:
+        return self.ident_key + "_" if self.ident_key else ""
+
+    @abc.abstractmethod
+    def serialize(self, data: Data) -> str:
+        pass
+
+    @abc.abstractmethod
+    def deserialize(self, serialized_data: str) -> Result[Data, str]:
+        pass
+
+
+__all__ = ("ABCDataSerializer",)

telegrinder/tools/serialization/json_ser.py

@@ -0,0 +1,60 @@
+import typing
+
+import msgspec
+from kungfu.library.monad.result import Error, Ok, Result
+
+from telegrinder.modules import json
+from telegrinder.msgspec_utils import decoder
+from telegrinder.tools.serialization.abc import ABCDataSerializer, ModelType
+from telegrinder.tools.serialization.utils import get_model_ident_key
+
+type Json = dict[str, typing.Any] | ModelType
+
+
+class JSONSerializer[JsonT: Json](ABCDataSerializer[JsonT]):
+    @typing.overload
+    def __init__(self, model_t: type[JsonT]) -> None: ...
+
+    @typing.overload
+    def __init__(self, model_t: type[JsonT], *, ident_key: str | None = ...) -> None: ...
+
+    def __init__(
+        self,
+        model_t: type[JsonT] = dict[str, typing.Any],
+        *,
+        ident_key: str | None = None,
+    ) -> None:
+        self.model_t = model_t
+        self.ident_key = ident_key or get_model_ident_key(model_t)
+
+    @classmethod
+    def serialize_from_json(cls, data: JsonT, *, ident_key: str | None = None) -> str:
+        return cls(type(data), ident_key=ident_key).serialize(data)
+
+    @classmethod
+    def deserialize_to_json(cls, serialized_data: str, model_t: type[JsonT]) -> Result[JsonT, str]:
+        return cls(model_t).deserialize(serialized_data)
+
+    def serialize(self, data: JsonT) -> str:
+        return self.key + json.dumps(data)
+
+    def deserialize(self, serialized_data: str) -> Result[JsonT, str]:
+        if not serialized_data.startswith(self.key):
+            return Error("Data is not corresponding to key.")
+
+        data = serialized_data.removeprefix(self.key)
+        try:
+            data_obj = json.loads(data)
+        except (msgspec.ValidationError, msgspec.DecodeError):
+            return Error("Cannot decode json.")
+
+        if not issubclass(self.model_t, dict):
+            try:
+                return Ok(decoder.convert(data_obj, type=self.model_t))
+            except (msgspec.ValidationError, msgspec.DecodeError):
+                return Error("Incorrect data.")
+
+        return Ok(data_obj)
+
+
+__all__ = ("JSONSerializer",)