telegrinder 0.4.2__py3-none-any.whl → 0.5.1__py3-none-any.whl

telegrinder/tools/__init__.py

@@ -1,28 +1,19 @@
-from .adapter import (
-    ABCAdapter,
-    DataclassAdapter,
-    EventAdapter,
-    NodeAdapter,
-    RawEventAdapter,
-    RawUpdateAdapter,
+from telegrinder.tools.aio import (
+    cancel_future,
+    maybe_awaitable,
+    next_generator,
+    run_task,
+    send_generator_value,
+    stop_generator,
 )
-from .buttons import BaseButton
-from .callback_data_serilization import (
+from telegrinder.tools.callback_data_serialization import (
     ABCDataSerializer,
     JSONSerializer,
     MsgPackSerializer,
 )
-from .error_handler import ABCErrorHandler, Catcher, CatcherError, ErrorHandler
-from .formatting import (
-    Base,
-    BlockQuote,
+from telegrinder.tools.formatting import (
     FormatString,
     HTMLFormatter,
-    Link,
-    Mention,
-    PreCode,
-    SpecialFormat,
-    TgEmoji,
     block_quote,
     bold,
     code_inline,
@@ -61,119 +52,88 @@ from .formatting import (
     tg_story_link,
     underline,
 )
-from .functional import from_optional
-from .global_context import (
+from telegrinder.tools.fullname import fullname
+from telegrinder.tools.global_context import (
     ABCGlobalContext,
     CtxVar,
     GlobalContext,
     GlobalCtxVar,
     TelegrinderContext,
     ctx_var,
+    runtime_init,
 )
-from .i18n import (
-    ABCI18n,
-    ABCTranslator,
-    ABCTranslatorMiddleware,
-    I18nEnum,
-    SimpleI18n,
-    SimpleTranslator,
-)
-from .input_file_directory import InputFileDirectory
-from .keyboard import (
-    AnyMarkup,
-    Button,
-    InlineButton,
-    InlineKeyboard,
-    Keyboard,
-    RowButtons,
-)
-from .limited_dict import LimitedDict
-from .loop_wrapper import ABCLoopWrapper, DelayedTask, Lifespan, LoopWrapper
-from .magic import (
-    cancel_future,
-    get_annotations,
-    get_cached_translation,
+from telegrinder.tools.input_file_directory import InputFileDirectory
+from telegrinder.tools.lifespan import Lifespan
+from telegrinder.tools.limited_dict import LimitedDict
+from telegrinder.tools.loop_wrapper import DelayedTask, LoopWrapper
+from telegrinder.tools.magic import (
+    Annotations,
+    Bundle,
+    bundle,
     get_default_args,
+    get_func_annotations,
     get_func_parameters,
-    get_polymorphic_implementations,
-    impl,
-    magic_bundle,
+    get_generic_parameters,
+    join_dicts,
     resolve_arg_names,
+    resolve_kwonly_arg_names,
+    resolve_posonly_arg_names,
+    shortcut,
 )
-from .parse_mode import ParseMode
-from .state_storage import ABCStateStorage, MemoryStateStorage, StateData
+from telegrinder.tools.parse_mode import ParseMode
+from telegrinder.tools.singleton import ABCSingleton, ABCSingletonMeta, Singleton, SingletonMeta
 
 __all__ = (
-    "ABCAdapter",
     "ABCDataSerializer",
-    "ABCErrorHandler",
     "ABCGlobalContext",
-    "ABCI18n",
-    "ABCLoopWrapper",
-    "ABCStateStorage",
-    "ABCTranslator",
-    "ABCTranslatorMiddleware",
-    "AnyMarkup",
-    "Base",
-    "BaseButton",
-    "BlockQuote",
-    "Button",
-    "Catcher",
-    "CatcherError",
+    "ABCSingleton",
+    "ABCSingletonMeta",
+    "Annotations",
+    "Bundle",
     "CtxVar",
-    "DataclassAdapter",
     "DelayedTask",
-    "ErrorHandler",
-    "EventAdapter",
     "FormatString",
     "GlobalContext",
     "GlobalCtxVar",
     "HTMLFormatter",
-    "I18nEnum",
-    "InlineButton",
-    "InlineKeyboard",
     "InputFileDirectory",
     "JSONSerializer",
-    "Keyboard",
     "Lifespan",
     "LimitedDict",
-    "Link",
     "LoopWrapper",
-    "MemoryStateStorage",
-    "Mention",
     "MsgPackSerializer",
-    "NodeAdapter",
     "ParseMode",
-    "PreCode",
-    "RawEventAdapter",
-    "RawUpdateAdapter",
-    "RowButtons",
-    "SimpleI18n",
-    "SimpleTranslator",
-    "SpecialFormat",
-    "StateData",
+    "Singleton",
+    "SingletonMeta",
     "TelegrinderContext",
-    "TgEmoji",
     "block_quote",
     "bold",
+    "bundle",
     "cancel_future",
     "code_inline",
     "ctx_var",
     "escape",
-    "from_optional",
-    "get_annotations",
-    "get_cached_translation",
+    "fullname",
     "get_default_args",
+    "get_func_annotations",
     "get_func_parameters",
-    "get_polymorphic_implementations",
-    "impl",
+    "get_generic_parameters",
     "italic",
+    "join_dicts",
     "link",
-    "magic_bundle",
+    "maybe_awaitable",
     "mention",
+    "next_generator",
     "pre_code",
     "resolve_arg_names",
+    "resolve_kwonly_arg_names",
+    "resolve_posonly_arg_names",
+    "run_task",
+    "runtime_init",
+    "send_generator_value",
+    "shortcut",
     "spoiler",
+    "stop_generator",
     "strike",
     "tg_bot_attach_open_any_chat",
     "tg_bot_attach_open_current_chat",

telegrinder/tools/aio.py

@@ -0,0 +1,103 @@
+import asyncio
+from inspect import isasyncgen, isawaitable
+
+import typing_extensions as typing
+
+type Generator[Yield, Send, Return] = typing.AsyncGenerator[Yield, Send] | typing.Generator[Yield, Send, Return]
+
+
+def run_task[T](
+    task: typing.Awaitable[T],
+    /,
+    *,
+    loop: asyncio.AbstractEventLoop | None = None,
+) -> T:
+    loop = loop or asyncio.get_event_loop()
+    return loop.run_until_complete(future=task)
+
+
+async def next_generator[T](generator: Generator[T, typing.Any, typing.Any], /) -> T:
+    return await send_generator_value(generator, None)
+
+
+async def send_generator_value[Yield, Send](
+    generator: Generator[Yield, Send, typing.Any],
+    value: Send | None,
+    /,
+) -> Yield:
+    try:
+        return (
+            await generator.asend(value) if isasyncgen(generator) else generator.send(value)  # type: ignore
+        )
+    except StopIteration as exc:
+        raise StopGenerator(exc.value, exc.args) from exc
+
+
+async def stop_generator[Send, Return](
+    generator: Generator[typing.Any, Send, Return],
+    with_value: Send | None = None,
+    /,
+) -> Return | None:
+    try:
+        await send_generator_value(generator, with_value)
+    except (StopGenerator, StopAsyncIteration) as exc:
+        return exc.value if isinstance(exc, StopGenerator) else None
+
+
+async def maybe_awaitable[T](obj: T | typing.Awaitable[T], /) -> T:
+    if isawaitable(obj):
+        return await obj
+    return obj
+
+
+# Source code: https://github.com/facebookincubator/later/blob/main/later/task.py#L75
+async def cancel_future(fut: asyncio.Future[typing.Any], /) -> None:
+    if fut.done():
+        return
+
+    fut.cancel()
+    exc: asyncio.CancelledError | None = None
+
+    while not fut.done():
+        shielded = asyncio.shield(fut)
+        try:
+            await asyncio.wait([shielded])
+        except asyncio.CancelledError as ex:
+            exc = ex
+        finally:
+            # Insure we handle the exception/value that may exist on the shielded task
+            # This will prevent errors logged to the asyncio logger
+            if shielded.done() and not shielded.cancelled() and not shielded.exception():
+                shielded.result()
+
+    if fut.cancelled():
+        if exc is None:
+            return
+        raise exc from None
+
+    ex = fut.exception()
+    if ex is not None:
+        raise ex from None
+
+    raise asyncio.InvalidStateError(
+        f"Task did not raise CancelledError on cancel: {fut!r} had result {fut.result()!r}",
+    )
+
+
+class StopGenerator(Exception):
+    value: typing.Any
+
+    def __init__(self, value: typing.Any, *args: object) -> None:
+        super().__init__(*args)
+        self.value = value
+
+
+__all__ = (
+    "StopGenerator",
+    "cancel_future",
+    "maybe_awaitable",
+    "next_generator",
+    "run_task",
+    "send_generator_value",
+    "stop_generator",
+)

telegrinder/tools/callback_data_serialization/__init__.py

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

telegrinder/tools/{callback_data_serilization → callback_data_serialization}/json_ser.py

@@ -5,8 +5,7 @@ from fntypes.result import Error, Ok, Result
 
 from telegrinder.modules import json
 from telegrinder.msgspec_utils import decoder
-
-from .abc import ABCDataSerializer, ModelType
+from telegrinder.tools.callback_data_serialization.abc import ABCDataSerializer, ModelType
 
 type Json = dict[str, typing.Any] | ModelType
 
@@ -39,7 +38,7 @@ class JSONSerializer[JsonT: Json](ABCDataSerializer[JsonT]):
         return self.key + json.dumps(data)
 
     def deserialize(self, serialized_data: str) -> Result[JsonT, str]:
-        if self.ident_key and not serialized_data.startswith(self.key):
+        if not serialized_data.startswith(self.key):
             return Error("Data is not corresponding to key.")
 
         data = serialized_data.removeprefix(self.key)

telegrinder/tools/{callback_data_serilization → callback_data_serialization}/msgpack_ser.py

@@ -10,8 +10,20 @@ import msgspec
 from fntypes.result import Error, Ok, Result
 
 from telegrinder.msgspec_utils import decoder, encoder, get_class_annotations
+from telegrinder.tools.callback_data_serialization.abc import ABCDataSerializer, ModelType
 
-from .abc import ABCDataSerializer, ModelType
+DESERIALIZE_EXCEPTIONS: typing.Final[set[type[BaseException]]] = {
+    msgspec.DecodeError,
+    msgspec.ValidationError,
+    binascii.Error,
+}
+
+try:
+    import brotli  # type: ignore
+
+    DESERIALIZE_EXCEPTIONS.add(brotli.error)  # type: ignore
+except ImportError:
+    brotli = None
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
@@ -37,16 +49,18 @@ class ModelParser[Model: ModelType]:
         return isinstance(inspected_type, msgspec.inspect.DataclassType | msgspec.inspect.StructType)
 
     def _is_iter_of_model(
-        self, inspected_type: msgspec.inspect.Type, /
+        self,
+        inspected_type: msgspec.inspect.Type,
+        /,
     ) -> typing.TypeGuard[msgspec.inspect.ListType]:
         return isinstance(
             inspected_type,
             msgspec.inspect.ListType | msgspec.inspect.SetType | msgspec.inspect.FrozenSetType,
         ) and self._is_model_type(inspected_type.item_type)
 
-    def _validate_annotation(self, annotation: typing.Any, /) -> tuple[type[ModelType], bool] | None:
+    def _inspect_annotation(self, annotation: typing.Any, /) -> tuple[type[ModelType], bool] | None:
         is_iter_of_model = False
-        type_args: tuple[msgspec.inspect.Type, ...] | None = None
+        type_args: tuple[msgspec.inspect.Type, ...] = tuple()
         inspected_type = msgspec.inspect.type_info(annotation)
 
         if self._is_union(inspected_type):
@@ -57,14 +71,15 @@ class ModelParser[Model: ModelType]:
         elif self._is_model_type(inspected_type):
             type_args = (inspected_type,)
 
-        if type_args is not None:
-            for arg in type_args:
-                if self._is_union(arg):
-                    type_args += arg.types
-                if self._is_model_type(arg):
-                    return (arg.cls, is_iter_of_model)
-                if self._is_iter_of_model(arg):
-                    return (arg.item_type.cls, True)  # type: ignore
+        for arg in type_args:
+            if self._is_union(arg):
+                type_args += arg.types
+
+            if self._is_model_type(arg):
+                return (arg.cls, is_iter_of_model)
+
+            if self._is_iter_of_model(arg):
+                return (arg.item_type.cls, True)  # type: ignore
 
         return None
 
@@ -103,8 +118,8 @@ class ModelParser[Model: ModelType]:
             for index, (field, annotation) in enumerate(get_class_annotations(current_model).items()):
                 obj, model_type, is_iter_of_model = current_data[index], None, False
 
-                if isinstance(obj, list) and (validated := self._validate_annotation(annotation)):
-                    model_type, is_iter_of_model = validated
+                if isinstance(obj, list) and (inspected := self._inspect_annotation(annotation)):
+                    model_type, is_iter_of_model = inspected
 
                 if model_type is not None:
                     if is_iter_of_model:
@@ -145,19 +160,22 @@ class MsgPackSerializer[Model: ModelType](ABCDataSerializer[Model]):
 
     @cached_property
     def key(self) -> bytes:
-        if self.ident_key:
-            return msgspec.msgpack.encode(super().key)
-        return b""
-
-    def serialize(self, data: Model) -> str:
-        return base64.urlsafe_b64encode(
-            self.key + msgspec.msgpack.encode(self._model_parser.parse(data), enc_hook=encoder.enc_hook),
-        ).decode()
-
-    def deserialize(self, serialized_data: str) -> Result[Model, str]:
-        with suppress(msgspec.DecodeError, msgspec.ValidationError, binascii.Error):
-            ser_data = base64.urlsafe_b64decode(serialized_data)
-            if self.ident_key and not ser_data.startswith(self.key):
+        return msgspec.msgpack.encode(super().key) if self.ident_key else b""
+
+    def serialize(self, data: Model, /) -> str:
+        encoded = self.key + msgspec.msgpack.encode(self._model_parser.parse(data), enc_hook=encoder.enc_hook)
+        if brotli is not None:
+            return base64.b85encode(brotli.compress(encoded, quality=11)).decode()  # type: ignore
+        return base64.urlsafe_b64encode(encoded).decode()
+
+    def deserialize(self, serialized_data: str, /) -> Result[Model, str]:
+        with suppress(*DESERIALIZE_EXCEPTIONS):
+            if brotli is not None:
+                ser_data = typing.cast("bytes", brotli.decompress(base64.b85decode(serialized_data)))
+            else:
+                ser_data = base64.urlsafe_b64decode(serialized_data)
+
+            if not ser_data.startswith(self.key):
                 return Error("Data is not corresponding to key.")
 
             data: list[typing.Any] = msgspec.msgpack.decode(

telegrinder/tools/final.py

@@ -0,0 +1,21 @@
+import typing
+
+from telegrinder.tools.fullname import fullname
+
+
+class Final:
+    if not typing.TYPE_CHECKING:
+
+        def __new__(cls, *args, **kwargs):
+            if cls is Final:
+                raise TypeError("Class Final cannot be instantiate.")
+            return super().__new__(cls, *args, **kwargs)
+
+    @typing.final
+    def __init_subclass__(cls, **kwargs: typing.Any) -> None:
+        for base in cls.__bases__:
+            if base is not Final and issubclass(base, Final):
+                raise TypeError(f"Final class `{fullname(base)}` cannot be subclassed.")
+
+
+__all__ = ("Final",)

telegrinder/tools/formatting/__init__.py

@@ -1,4 +1,4 @@
-from .deep_links import (
+from telegrinder.tools.formatting.deep_links import (
     tg_bot_attach_open_any_chat,
     tg_bot_attach_open_current_chat,
     tg_bot_attach_open_specific_chat,
@@ -25,7 +25,7 @@ from .deep_links import (
     tg_share_link,
     tg_story_link,
 )
-from .html_formatter import (
+from telegrinder.tools.formatting.html_formatter import (
     FormatString,
     HTMLFormatter,
     block_quote,
@@ -41,26 +41,10 @@ from .html_formatter import (
     tg_emoji,
     underline,
 )
-from .spec_html_formats import (
-    Base,
-    BlockQuote,
-    Link,
-    Mention,
-    PreCode,
-    SpecialFormat,
-    TgEmoji,
-)
 
 __all__ = (
-    "Base",
-    "BlockQuote",
     "FormatString",
     "HTMLFormatter",
-    "Link",
-    "Mention",
-    "PreCode",
-    "SpecialFormat",
-    "TgEmoji",
     "block_quote",
     "bold",
     "code_inline",

telegrinder/tools/formatting/deep_links/__init__.py

@@ -0,0 +1,39 @@
+from telegrinder.tools.formatting.deep_links.links import *
+from telegrinder.tools.formatting.deep_links.parsing import *
+from telegrinder.tools.formatting.deep_links.validators import *
+
+__all__ = (
+    "NO_VALUE",
+    "NoValue",
+    "Parameter",
+    "get_parameter_metadata",
+    "get_query_params",
+    "parse_deep_link",
+    "parse_query_params",
+    "separate_by_plus_char",
+    "tg_bot_attach_open_any_chat",
+    "tg_bot_attach_open_current_chat",
+    "tg_bot_attach_open_specific_chat",
+    "tg_bot_start_link",
+    "tg_bot_startchannel_link",
+    "tg_bot_startgroup_link",
+    "tg_chat_folder_link",
+    "tg_chat_invite_link",
+    "tg_direct_mini_app_link",
+    "tg_emoji_link",
+    "tg_emoji_stickerset_link",
+    "tg_invoice_link",
+    "tg_language_pack_link",
+    "tg_main_mini_app_link",
+    "tg_mention_link",
+    "tg_open_message_link",
+    "tg_premium_multigift_link",
+    "tg_premium_offer_link",
+    "tg_private_channel_boost_link",
+    "tg_private_message_link",
+    "tg_public_channel_boost_link",
+    "tg_public_message_link",
+    "tg_public_username_link",
+    "tg_share_link",
+    "tg_story_link",
+)

telegrinder/tools/formatting/{deep_links.py → deep_links/links.py}

@@ -1,14 +1,17 @@
-import types
 import typing
-from collections import OrderedDict
 from datetime import timedelta
 from functools import wraps
-from urllib.parse import urlencode
 
-from telegrinder.tools.magic import get_annotations
+from telegrinder.tools.formatting.deep_links.parsing import (
+    NO_VALUE,
+    DeepLinkFunction,
+    NoValue,
+    Parameter,
+    get_query_params,
+    parse_deep_link,
+)
+from telegrinder.tools.formatting.deep_links.validators import separate_by_plus_char
 
-type DeepLinkFunction[**P] = typing.Callable[P, str]
-type NoValue = types.EllipsisType
 type Permission = typing.Literal[
     "change_info",
     "post_messages",
@@ -32,9 +35,6 @@ type Peer = typing.Literal[
     "groups",
     "channels",
 ]
-Parameter = typing.Annotated
-
-NO_VALUE: typing.Final[NoValue] = typing.cast(NoValue, ...)
 
 
 def deep_link[**P](
@@ -61,79 +61,6 @@ def deep_link[**P](
     return inner
 
 
-def get_query_params(
-    func: DeepLinkFunction[...],
-    kwargs: dict[str, typing.Any],
-    order_params: set[str] | None = None,
-) -> dict[str, typing.Any]:
-    annotations = get_annotations(func)
-    params = OrderedDict()
-    param_names = (
-        [*order_params, *(p for p in annotations if p not in order_params)] if order_params else annotations
-    )
-
-    for param_name in param_names:
-        annotation = annotations[param_name]
-        if param_name in kwargs:
-            value = kwargs[param_name]
-            if typing.get_origin(annotation) is Parameter:
-                param_name, validator = get_parameter_metadata(annotation)
-                value = validator(value) if validator is not None else value
-
-            params[param_name] = value
-
-    return params
-
-
-def parse_query_params(
-    params: dict[str, typing.Any],
-    no_value_params: set[str] | None = None,
-    /,
-) -> tuple[set[str], dict[str, typing.Any]]:
-    no_value_params = no_value_params or set()
-    params_: dict[str, typing.Any] = {}
-
-    for key, value in params.items():
-        if value in (False, None):
-            continue
-
-        if value in (True, NO_VALUE):
-            no_value_params.add(key)
-            continue
-        if isinstance(value, timedelta):
-            value = int(value.total_seconds())
-
-        params_[key] = value
-
-    return (no_value_params, params_)
-
-
-def get_parameter_metadata(
-    parameter: typing.Any,
-) -> tuple[str, typing.Callable[[typing.Any], typing.Any] | None]:
-    meta: tuple[typing.Any, ...] = getattr(parameter, "__metadata__")
-    return meta if len(meta) == 2 else (meta[0], None)
-
-
-def parse_deep_link(
-    *,
-    link: str,
-    params: dict[str, typing.Any],
-    no_value_params: set[str] | None = None,
-) -> str:
-    no_value_params, params = parse_query_params(params, no_value_params)
-    query = urlencode(params, encoding="UTF-8") + ("&" if no_value_params else "") + "&".join(no_value_params)
-    return f"{link}?{query}"
-
-
-def validate_permissions(perms: list[Permission] | None, /) -> str | None:
-    return None if not perms else "+".join(perms)
-
-
-def validate_peer(peer: list[Peer] | None, /) -> str | None:
-    return None if not peer else "+".join(peer)
-
-
 @deep_link("tg://resolve")
 def tg_public_username_link(
     *,
@@ -364,7 +291,7 @@ def tg_bot_startgroup_link(
     *,
     bot_username: Parameter[str, "domain"],
     parameter: Parameter[str | NoValue, "startgroup"] = NO_VALUE,
-    permissions: Parameter[list[Permission] | None, "admin", validate_permissions] = None,
+    permissions: Parameter[list[Permission] | None, "admin", separate_by_plus_char] = None,
 ) -> str:
     """Used to add bots to groups.
     First of all, check that the `<bot_username>` indeed links to a bot.
@@ -394,7 +321,7 @@ def tg_bot_startgroup_link(
 def tg_bot_startchannel_link(
     *,
     bot_username: Parameter[str, "domain"],
-    permissions: Parameter[list[Permission], "admin", validate_permissions],
+    permissions: Parameter[list[Permission], "admin", separate_by_plus_char],
 ) -> str:
     """Used to add bots to channels.
     First of all, check that the `<bot_username>` indeed links to a bot.
@@ -499,7 +426,7 @@ def tg_bot_attach_open_any_chat(
     *,
     bot_username: Parameter[str, "domain"],
     parameter: Parameter[str | NoValue, "startattach"] = NO_VALUE,
-    peer: Parameter[list[Peer] | None, "choose", validate_peer] = None,
+    peer: Parameter[list[Peer] | None, "choose", separate_by_plus_char] = None,
 ) -> str:
     """After installing the `attachment/side` menu entry globally, opens a dialog selection form that will open the attachment menu
     mini app using `messages.requestWebView` in a specific chat (pass it to the peer parameter of `messages.requestWebView`).