telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/msgspec_utils/__init__.py

@@ -0,0 +1,42 @@
+from telegrinder.msgspec_utils.abc import SupportsCast, is_supports_cast
+from telegrinder.msgspec_utils.custom_types.datetime import datetime, timedelta
+from telegrinder.msgspec_utils.custom_types.enum_meta import BaseEnumMeta
+from telegrinder.msgspec_utils.custom_types.literal import Literal
+from telegrinder.msgspec_utils.custom_types.option import Option
+from telegrinder.msgspec_utils.decoder import Decoder, convert, decoder
+from telegrinder.msgspec_utils.encoder import Encoder, encoder, to_builtins
+from telegrinder.msgspec_utils.json import dumps, loads
+from telegrinder.msgspec_utils.tools import (
+    get_class_annotations,
+    get_origin,
+    get_type_hints,
+    is_common_type,
+    is_none,
+    struct_asdict,
+    type_check,
+)
+
+__all__ = (
+    "BaseEnumMeta",
+    "Decoder",
+    "Encoder",
+    "Literal",
+    "Option",
+    "SupportsCast",
+    "convert",
+    "datetime",
+    "decoder",
+    "dumps",
+    "encoder",
+    "get_class_annotations",
+    "get_origin",
+    "get_type_hints",
+    "is_common_type",
+    "is_none",
+    "is_supports_cast",
+    "loads",
+    "struct_asdict",
+    "timedelta",
+    "to_builtins",
+    "type_check",
+)

telegrinder/msgspec_utils/abc.py

@@ -0,0 +1,16 @@
+import abc
+import typing
+
+
+def is_supports_cast(obj: typing.Any, /) -> typing.TypeGuard[SupportsCast]:
+    return isinstance(obj, SupportsCast)
+
+
+@typing.runtime_checkable
+class SupportsCast(typing.Protocol):
+    @classmethod
+    @abc.abstractmethod
+    def cast(cls, obj: typing.Any) -> typing.Self: ...
+
+
+__all__ = ("SupportsCast", "is_supports_cast")

telegrinder/msgspec_utils/custom_types/__init__.py

@@ -0,0 +1,6 @@
+from telegrinder.msgspec_utils.custom_types.datetime import datetime, timedelta
+from telegrinder.msgspec_utils.custom_types.enum_meta import BaseEnumMeta
+from telegrinder.msgspec_utils.custom_types.literal import Literal
+from telegrinder.msgspec_utils.custom_types.option import Option
+
+__all__ = ("BaseEnumMeta", "Literal", "Option", "datetime", "timedelta")

telegrinder/msgspec_utils/custom_types/datetime.py

@@ -0,0 +1,24 @@
+import datetime as dt
+import typing
+
+from telegrinder.msgspec_utils.abc import SupportsCast
+
+
+class datetime(dt.datetime, SupportsCast):  # noqa: N801  # type: ignore
+    @classmethod
+    def cast(cls, obj: dt.datetime) -> typing.Self:
+        return cls.fromtimestamp(timestamp=obj.timestamp(), tz=obj.tzinfo)
+
+
+class timedelta(dt.timedelta, SupportsCast):  # noqa: N801  # type: ignore
+    @classmethod
+    def cast(cls, obj: dt.timedelta) -> typing.Self:
+        return cls(seconds=obj.total_seconds())
+
+
+if typing.TYPE_CHECKING:
+    datetime: typing.TypeAlias = dt.datetime
+    timedelta: typing.TypeAlias = dt.timedelta
+
+
+__all__ = ("datetime", "timedelta")

telegrinder/msgspec_utils/custom_types/enum_meta.py

@@ -0,0 +1,61 @@
+import enum
+import math
+import sys
+import typing
+
+from telegrinder.modules import logger
+
+NOT_SUPPORTED: typing.Final = "NOT_SUPPORTED"
+ENUM_FRIENDS: typing.Final = (str, int, float)
+NOT_SUPPORTED_VALUES: typing.Final = {
+    str: NOT_SUPPORTED,
+    int: math.inf,
+    float: sys.maxsize,
+}
+
+
+def _is_friend(bases: tuple[type[typing.Any], ...], /) -> bool:
+    return any(friend in bases for friend in ENUM_FRIENDS)
+
+
+class BaseEnumMeta(enum.EnumMeta, type):
+    if typing.TYPE_CHECKING:
+
+        class _BaseEnumMeta(enum.Enum):  # noqa
+            NOT_SUPPORTED = enum.auto()
+
+        NOT_SUPPORTED: typing.Literal[_BaseEnumMeta.NOT_SUPPORTED]
+
+    else:
+
+        @staticmethod
+        def _member_missing(cls, value):
+            logger.warning(
+                "Unsupported value {!r} for enum of type {}. Probably telegrinder needs "
+                "to be updated to support the latest version of Telegram Bot API.",
+                value,
+                cls,
+            )
+            return cls._member_map_["NOT_SUPPORTED"]
+
+        def __new__(
+            metacls,
+            cls,
+            bases,
+            classdict,
+            *,
+            boundary=None,
+            _simple=False,
+            **kwds,
+        ):
+            if _is_friend(bases):
+                classdict["NOT_SUPPORTED"] = next(
+                    (value for base, value in NOT_SUPPORTED_VALUES.items() if base in bases),
+                    NOT_SUPPORTED,
+                )
+
+            classdict["_missing_"] = classmethod(BaseEnumMeta._member_missing)
+            return super().__new__(metacls, cls, bases, classdict, boundary=boundary, _simple=_simple, **kwds)
+
+
+__all__ = ("BaseEnumMeta",)

telegrinder/msgspec_utils/custom_types/literal.py

@@ -0,0 +1,25 @@
+import typing
+
+
+class _LiteralMeta(type):
+    __args__: tuple[typing.Any, ...]
+
+    def __getitem__[T](cls: type[T], values: typing.Any, /) -> type[T]:
+        values = (values,) if not isinstance(values, tuple) else values
+        return _LiteralMeta(cls.__name__, (cls,), {"__args__": values})  # type: ignore
+
+    def __instancecheck__(cls, instance: typing.Any, /) -> bool:
+        return instance in cls.__args__
+
+
+class _Literal(metaclass=_LiteralMeta):
+    pass
+
+
+if typing.TYPE_CHECKING:
+    from typing import Literal
+else:
+    Literal = _Literal
+
+
+__all__ = ("Literal",)

telegrinder/msgspec_utils/custom_types/option.py

@@ -0,0 +1,17 @@
+import typing
+
+if typing.TYPE_CHECKING:
+    from kungfu.library.monad.option import Option
+else:
+    import kungfu.library
+    import msgspec
+
+    class OptionMeta(type):
+        def __instancecheck__(cls, __instance):
+            return isinstance(__instance, (kungfu.library.Some | kungfu.library.Nothing, msgspec.UnsetType))
+
+    class Option[Value](metaclass=OptionMeta):
+        pass
+
+
+__all__ = ("Option",)

telegrinder/msgspec_utils/decoder.py

@@ -0,0 +1,388 @@
+import datetime as dt
+import typing
+from contextlib import contextmanager
+
+import kungfu.library
+import msgspec
+from kungfu.library.monad.option import NOTHING
+
+from telegrinder.msgspec_utils.abc import SupportsCast
+from telegrinder.msgspec_utils.custom_types.datetime import datetime, timedelta
+from telegrinder.msgspec_utils.custom_types.enum_meta import BaseEnumMeta
+from telegrinder.msgspec_utils.custom_types.literal import _Literal
+from telegrinder.msgspec_utils.custom_types.option import Option
+from telegrinder.msgspec_utils.tools import (
+    bundle,
+    fullname,
+    get_origin,
+    is_common_type,
+    type_check,
+)
+
+type Context = dict[str, typing.Any]
+type DecHook[T] = typing.Callable[typing.Concatenate[type[T], typing.Any, ...], typing.Any]
+
+
+def option_dec_hook(
+    tp: type[Option[typing.Any]],
+    obj: typing.Any,
+    /,
+) -> kungfu.library.Option[typing.Any] | msgspec.UnsetType:
+    if obj is msgspec.UNSET:
+        return obj
+
+    if obj is None or obj is NOTHING:
+        return NOTHING
+
+    (value_type,) = typing.get_args(tp) or (typing.Any,)
+    orig_value_type = typing.get_origin(value_type) or value_type
+    orig_obj = obj
+
+    if not isinstance(orig_obj, dict | list) and is_common_type(orig_value_type):
+        if orig_value_type is kungfu.library.Sum:
+            obj = value_type(orig_obj)  # type: ignore
+            orig_value_type = typing.get_args(value_type)
+
+        if not type_check(orig_obj, orig_value_type):
+            raise msgspec.ValidationError(
+                f"Expected `{fullname(orig_value_type)}` or `builtins.None`, got `{fullname(orig_obj)}`.",
+            )
+
+        return kungfu.library.Some(obj)
+
+    return kungfu.library.Some(decoder.convert(orig_obj, type=value_type))
+
+
+def sum_dec_hook(tp: type[kungfu.library.Sum], obj: typing.Any, /) -> kungfu.library.Sum:
+    union_types = typing.get_args(tp)
+
+    if isinstance(obj, dict):
+        reverse = False
+        models_fields_count: dict[type[msgspec.Struct], int] = {
+            m: sum(1 for k in obj if k in m.__struct_fields__)
+            for m in union_types
+            if issubclass(get_origin(m), msgspec.Struct)
+        }
+        union_types = tuple(t for t in union_types if t not in models_fields_count)
+
+        if len(set(models_fields_count.values())) != len(models_fields_count.values()):
+            models_fields_count = {m: len(m.__struct_fields__) for m in models_fields_count}
+            reverse = True
+
+        union_types = (
+            *sorted(
+                models_fields_count,
+                key=lambda k: models_fields_count[k],
+                reverse=reverse,
+            ),
+            *union_types,
+        )
+
+    if not isinstance(obj, dict | list) and any(is_common_type(t) and type_check(obj, t) for t in union_types):
+        return tp(obj)
+
+    for t in union_types:
+        match convert(obj, t):
+            case kungfu.library.Ok(value):
+                return tp(value)
+            case kungfu.library.Error(_):
+                continue
+            case _ as arg:
+                typing.assert_never(arg)
+
+    raise msgspec.ValidationError(
+        "Object of type `{}` doesn't belong to `{}[{}]`.".format(
+            fullname(obj),
+            fullname(kungfu.library.Sum),
+            ", ".join(fullname(get_origin(x)) for x in union_types),
+        )
+    )
+
+
+def datetime_dec_hook(tp: type[datetime], obj: typing.Any, /) -> datetime:
+    if isinstance(obj, datetime):
+        return obj
+
+    if isinstance(obj, dt.datetime):
+        assert issubclass(tp, SupportsCast)
+        return tp.cast(obj)
+
+    if isinstance(obj, int | float):
+        return tp.fromtimestamp(timestamp=obj)
+
+    raise TypeError(
+        "Cannot validate object of type `{}` into `datetime.datetime`".format(
+            fullname(obj),
+        ),
+    )
+
+
+def timedelta_dec_hook(tp: type[timedelta], obj: typing.Any, /) -> timedelta:
+    if isinstance(obj, timedelta):
+        return obj
+
+    if isinstance(obj, dt.timedelta):
+        assert issubclass(tp, SupportsCast)
+        return tp.cast(obj)
+
+    if isinstance(obj, int | float):
+        return tp(seconds=obj)
+
+    raise TypeError(
+        "Cannot validate object of type `{}` into `datetime.timedelta`".format(
+            fullname(obj),
+        ),
+    )
+
+
+def convert[T](
+    obj: typing.Any,
+    t: type[T],
+    /,
+    *,
+    context: Context | None = None,
+) -> kungfu.library.Result[T, str]:
+    try:
+        return kungfu.library.Ok(decoder.convert(obj, type=t, strict=True, context=context))
+    except msgspec.ValidationError:
+        return kungfu.library.Error(
+            "Expected object of type `{}`, got `{}`.".format(
+                fullname(t),
+                fullname(obj),
+            )
+        )
+
+
+def literal_dec_hook(literal: type[_Literal], obj: typing.Any, /) -> typing.Any:
+    if obj in literal.__args__:
+        return obj
+
+    raise msgspec.ValidationError(
+        "Invalid literal value {!r} of either {}.".format(
+            obj,
+            literal.__args__[0]
+            if len(literal.__args__) == 1
+            else (", ".join(f"`{x}`" for x in literal.__args__[:-1])) + f" or `{literal.__args__[-1]}`",
+        )
+    )
+
+
+class Decoder:
+    """Class `Decoder` for `msgspec` module with decode hook
+    for objects with the specified type.
+
+    ```
+    import enum
+
+    from datetime import datetime as dt
+
+    class Digit(enum.IntEnum):
+        ONE = 1
+        TWO = 2
+        THREE = 3
+
+    decoder = Decoder()
+    decoder.dec_hooks[dt] = lambda t, timestamp: t.fromtimestamp(timestamp)
+
+    decoder.dec_hook(dt, 1713354732)  #> datetime.datetime(2024, 4, 17, 14, 52, 12)
+
+    decoder.convert("123", type=int, strict=False)  #> 123
+    decoder.convert(1, type=Digit)  #> <Digit.ONE: 1>
+
+    decoder.decode(b'{"digit":3}', type=dict[str, Digit])  #> {'digit': <Digit.THREE: 3>}
+    ```
+    """
+
+    dec_hooks: dict[typing.Any, DecHook[typing.Any]]
+    abstract_dec_hooks: dict[typing.Any, DecHook[typing.Any]]
+
+    def __init__(self) -> None:
+        self.dec_hooks = {
+            Option: option_dec_hook,
+            kungfu.library.Sum: sum_dec_hook,
+            datetime: datetime_dec_hook,
+            timedelta: timedelta_dec_hook,
+            kungfu.library.Some: option_dec_hook,
+            kungfu.library.Nothing: option_dec_hook,
+        }
+        self.abstract_dec_hooks = {
+            BaseEnumMeta: lambda enum_type, member: enum_type(member),
+            _Literal: literal_dec_hook,
+        }
+
+    def __repr__(self) -> str:
+        return "<{}: dec_hooks={!r}, abstract_dec_hooks={!r}>".format(
+            type(self).__name__,
+            self.dec_hooks,
+            self.abstract_dec_hooks,
+        )
+
+    @typing.overload
+    def __call__[T](
+        self,
+        type: type[T],
+        context: Context | None = None,
+    ) -> typing.ContextManager[msgspec.json.Decoder[T]]: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        type: typing.Any,
+        context: Context | None = None,
+    ) -> typing.ContextManager[msgspec.json.Decoder[typing.Any]]: ...
+
+    @typing.overload
+    def __call__[T](
+        self,
+        type: type[T],
+        *,
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> typing.ContextManager[msgspec.json.Decoder[T]]: ...
+
+    @typing.overload
+    def __call__(
+        self,
+        type: typing.Any,
+        *,
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> typing.ContextManager[msgspec.json.Decoder[typing.Any]]: ...
+
+    @contextmanager
+    def __call__(
+        self,
+        type: typing.Any = object,
+        *,
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> typing.Generator[msgspec.json.Decoder, typing.Any, None]:
+        """Context manager returns an `msgspec.json.Decoder` object with passed the `dec_hook`."""
+        yield msgspec.json.Decoder(
+            type=typing.Any if type is object else type,
+            strict=strict,
+            dec_hook=self.dec_hook(context),
+        )
+
+    def add_dec_hook[T](self, t: type[T], /) -> typing.Callable[[DecHook[T]], DecHook[T]]:
+        def decorator(func: DecHook[T], /) -> DecHook[T]:
+            return self.dec_hooks.setdefault(get_origin(t), func)
+
+        return decorator
+
+    def add_abstract_dec_hook[T](self, abstract_type: type[T], /) -> typing.Callable[[DecHook[T]], DecHook[T]]:
+        def decorator(func: DecHook[T], /) -> DecHook[T]:
+            return self.abstract_dec_hooks.setdefault(get_origin(abstract_type), func)
+
+        return decorator
+
+    def get_abstract_dec_hook(self, subtype: type[typing.Any], /) -> DecHook[typing.Any] | None:
+        for abstract, dec_hook in self.abstract_dec_hooks.items():
+            if issubclass(subtype, abstract) or issubclass(type(subtype), abstract):
+                return dec_hook
+
+        return None
+
+    def dec_hook(self, context: Context | None = None, /) -> DecHook[typing.Any]:
+        def inner(tp: typing.Any, obj: typing.Any, /) -> typing.Any:
+            origin_type = get_origin(tp)
+
+            if (dec_hook_func := self.dec_hooks.get(origin_type)) is None and (
+                dec_hook_func := self.get_abstract_dec_hook(origin_type)
+            ) is None:
+                raise NotImplementedError(
+                    f"Not implemented decode hook for type `{fullname(origin_type)}`. "
+                    "You can implement decode hook for this type.",
+                )
+
+            return bundle(dec_hook_func, context or {}, start_idx=2)(tp, obj)
+
+        return inner
+
+    def convert[T](
+        self,
+        obj: object,
+        *,
+        type: type[T] = dict,
+        strict: bool = True,
+        from_attributes: bool = False,
+        builtin_types: typing.Iterable[type[typing.Any]] | None = None,
+        str_keys: bool = False,
+        context: Context | None = None,
+    ) -> T:
+        return msgspec.convert(
+            obj,
+            type,
+            strict=strict,
+            from_attributes=from_attributes,
+            dec_hook=self.dec_hook(context),
+            builtin_types=builtin_types,
+            str_keys=str_keys,
+        )
+
+    @typing.overload
+    def decode(
+        self,
+        buf: str | bytes,
+        *,
+        context: Context | None = None,
+    ) -> typing.Any: ...
+
+    @typing.overload
+    def decode[T](
+        self,
+        buf: str | bytes,
+        *,
+        type: type[T],
+        context: Context | None = None,
+    ) -> T: ...
+
+    @typing.overload
+    def decode(
+        self,
+        buf: str | bytes,
+        *,
+        type: typing.Any,
+        context: Context | None = None,
+    ) -> typing.Any: ...
+
+    @typing.overload
+    def decode[T](
+        self,
+        buf: str | bytes,
+        *,
+        type: type[T],
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> T: ...
+
+    @typing.overload
+    def decode(
+        self,
+        buf: str | bytes,
+        *,
+        type: typing.Any,
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> typing.Any: ...
+
+    def decode(
+        self,
+        buf: str | bytes,
+        *,
+        type: typing.Any = object,
+        strict: bool = True,
+        context: Context | None = None,
+    ) -> typing.Any:
+        return msgspec.json.decode(
+            buf,
+            type=typing.Any if type is object else type,
+            strict=strict,
+            dec_hook=self.dec_hook(context),
+        )
+
+
+decoder: typing.Final = Decoder()
+
+
+__all__ = ("Decoder", "convert", "decoder")