telegrinder 1.0.0rc1__py3-none-any.whl

telegrinder/__init__.py

@@ -0,0 +1,258 @@
+"""Modern visionary telegram bot framework.
+
+* Type hinted & [type functional](https://github.com/timoniq/telegrinder/blob/dev/docs/tutorial/en/3_functional_bits.md)
+* Customizable and extensible
+* Fast models built on [msgspec](https://github.com/jcrist/msgspec)
+* API client powered by fast [rnet](https://github.com/0x676e67/rnet) library
+* Both low-level and high-level API
+* Convenient [dependency injection](https://github.com/timoniq/telegrinder/blob/dev/docs/tutorial/en/5_nodes.md) via nodes
+
+Basic example:
+
+```python
+from telegrinder import API, Message, Telegrinder, Token
+from telegrinder.modules import setup_logger
+from telegrinder.rules import Text
+
+setup_logger(level="INFO")
+api = API(token=Token("123:token"))
+bot = Telegrinder(api)
+
+
+@bot.on.message(Text("/start"))
+async def start(message: Message) -> None:
+    me = (await api.get_me()).unwrap()
+    await message.answer(f"Hello, {message.from_user.full_name}! I'm {me.full_name}.")
+
+
+bot.run_forever()
+```
+"""
+
+import typing
+
+from .api import API, APIError, APIResponse, APIServerError, Token
+from .bot import (
+    CALLBACK_QUERY_FOR_MESSAGE,
+    CALLBACK_QUERY_FROM_CHAT,
+    CALLBACK_QUERY_IN_CHAT_FOR_MESSAGE,
+    MESSAGE_FROM_USER,
+    MESSAGE_FROM_USER_IN_CHAT,
+    MESSAGE_IN_CHAT,
+    ABCDispatch,
+    ABCHandler,
+    ABCMiddleware,
+    ABCPolling,
+    ABCReturnManager,
+    ABCRouter,
+    ABCRule,
+    ABCScenario,
+    ABCView,
+    AudioReplyHandler,
+    BaseCute,
+    BaseReturnManager,
+    BusinessConnectionCute,
+    BusinessMessagesDeletedCute,
+    CallbackQueryCute,
+    CallbackQueryReturnManager,
+    ChatBoostRemovedCute,
+    ChatBoostUpdatedCute,
+    ChatJoinRequestCute,
+    ChatMemberUpdatedCute,
+    Checkbox,
+    Choice,
+    ChosenInlineResultCute,
+    Context,
+    Dispatch,
+    DocumentReplyHandler,
+    ErrorView,
+    EventModelView,
+    EventView,
+    FilterMiddleware,
+    FuncHandler,
+    Hasher,
+    InlineQueryCute,
+    InlineQueryReturnManager,
+    MediaGroupMiddleware,
+    MediaGroupReplyHandler,
+    MediaGroupView,
+    MessageCute,
+    MessageReactionCountUpdatedCute,
+    MessageReactionUpdatedCute,
+    MessageReplyHandler,
+    MessageReturnManager,
+    MiddlewareBox,
+    PaidMediaPurchasedCute,
+    PhotoReplyHandler,
+    PollAnswerCute,
+    PollCute,
+    Polling,
+    PreCheckoutQueryCute,
+    PreCheckoutQueryReturnManager,
+    RawEventView,
+    Router,
+    ShippingQueryCute,
+    ShortState,
+    StickerReplyHandler,
+    Telegrinder,
+    UpdateCute,
+    VideoReplyHandler,
+    View,
+    ViewBox,
+    WaiterMachine,
+    action,
+    register_manager,
+)
+from .client import ABCClient, RnetClient
+from .model import Model, field
+from .modules import configure_dotenv, logger, setup_logger
+from .tools.global_context import ABCGlobalContext, GlobalContext, TelegrinderContext
+from .tools.input_file_directory import InputFileDirectory
+from .tools.keyboard import (
+    ABCKeyboard,
+    Button,
+    InlineButton,
+    InlineKeyboard,
+    Keyboard,
+    RowButtons,
+)
+from .tools.lifespan import Lifespan
+from .tools.loop_wrapper import DelayedTask, LoopWrapper
+from .tools.parse_mode import ParseMode
+from .tools.state_storage import ABCStateStorage, MemoryStateStorage, StateData
+
+Update: typing.TypeAlias = UpdateCute
+Message: typing.TypeAlias = MessageCute
+PreCheckoutQuery: typing.TypeAlias = PreCheckoutQueryCute
+ChatJoinRequest: typing.TypeAlias = ChatJoinRequestCute
+ChatMemberUpdated: typing.TypeAlias = ChatMemberUpdatedCute
+CallbackQuery: typing.TypeAlias = CallbackQueryCute
+InlineQuery: typing.TypeAlias = InlineQueryCute
+ChosenInlineResult: typing.TypeAlias = ChosenInlineResultCute
+ShippingQuery: typing.TypeAlias = ShippingQueryCute
+Poll: typing.TypeAlias = PollCute
+PollAnswer: typing.TypeAlias = PollAnswerCute
+PaidMediaPurchased: typing.TypeAlias = PaidMediaPurchasedCute
+ChatBoostRemoved: typing.TypeAlias = ChatBoostRemovedCute
+ChatBoostUpdated: typing.TypeAlias = ChatBoostUpdatedCute
+BusinessConnection: typing.TypeAlias = BusinessConnectionCute
+BusinessMessagesDeleted: typing.TypeAlias = BusinessMessagesDeletedCute
+MessageReactionCountUpdated: typing.TypeAlias = MessageReactionCountUpdatedCute
+MessageReactionUpdated: typing.TypeAlias = MessageReactionUpdatedCute
+Bot: typing.TypeAlias = Telegrinder
+
+
+__all__ = (
+    "API",
+    "CALLBACK_QUERY_FOR_MESSAGE",
+    "CALLBACK_QUERY_FROM_CHAT",
+    "CALLBACK_QUERY_IN_CHAT_FOR_MESSAGE",
+    "MESSAGE_FROM_USER",
+    "MESSAGE_FROM_USER_IN_CHAT",
+    "MESSAGE_IN_CHAT",
+    "ABCClient",
+    "ABCDispatch",
+    "ABCGlobalContext",
+    "ABCHandler",
+    "ABCKeyboard",
+    "ABCMiddleware",
+    "ABCPolling",
+    "ABCReturnManager",
+    "ABCRouter",
+    "ABCRule",
+    "ABCScenario",
+    "ABCStateStorage",
+    "ABCView",
+    "APIError",
+    "APIResponse",
+    "APIServerError",
+    "AudioReplyHandler",
+    "BaseCute",
+    "BaseReturnManager",
+    "Bot",
+    "Button",
+    "CallbackQuery",
+    "CallbackQueryCute",
+    "CallbackQueryReturnManager",
+    "ChatBoostRemoved",
+    "ChatBoostUpdatedCute",
+    "ChatJoinRequest",
+    "ChatJoinRequestCute",
+    "ChatMemberUpdated",
+    "ChatMemberUpdatedCute",
+    "Checkbox",
+    "Choice",
+    "ChosenInlineResult",
+    "ChosenInlineResultCute",
+    "Context",
+    "DelayedTask",
+    "Dispatch",
+    "DocumentReplyHandler",
+    "ErrorView",
+    "EventModelView",
+    "EventView",
+    "FilterMiddleware",
+    "FuncHandler",
+    "GlobalContext",
+    "Hasher",
+    "InlineButton",
+    "InlineKeyboard",
+    "InlineQuery",
+    "InlineQueryCute",
+    "InlineQueryReturnManager",
+    "InputFileDirectory",
+    "Keyboard",
+    "Lifespan",
+    "LoopWrapper",
+    "MediaGroupMiddleware",
+    "MediaGroupReplyHandler",
+    "MediaGroupView",
+    "MemoryStateStorage",
+    "Message",
+    "MessageCute",
+    "MessageReactionCountUpdated",
+    "MessageReactionCountUpdatedCute",
+    "MessageReactionUpdated",
+    "MessageReactionUpdatedCute",
+    "MessageReplyHandler",
+    "MessageReturnManager",
+    "MiddlewareBox",
+    "Model",
+    "PaidMediaPurchased",
+    "PaidMediaPurchasedCute",
+    "ParseMode",
+    "PhotoReplyHandler",
+    "Poll",
+    "PollAnswer",
+    "PollAnswerCute",
+    "PollCute",
+    "Polling",
+    "PreCheckoutQuery",
+    "PreCheckoutQueryCute",
+    "PreCheckoutQueryReturnManager",
+    "RawEventView",
+    "RnetClient",
+    "Router",
+    "RowButtons",
+    "ShippingQuery",
+    "ShippingQueryCute",
+    "ShortState",
+    "StateData",
+    "StickerReplyHandler",
+    "Telegrinder",
+    "TelegrinderContext",
+    "Token",
+    "Update",
+    "UpdateCute",
+    "VideoReplyHandler",
+    "View",
+    "ViewBox",
+    "ViewBox",
+    "WaiterMachine",
+    "action",
+    "configure_dotenv",
+    "field",
+    "logger",
+    "register_manager",
+    "setup_logger",
+)

telegrinder/__meta__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0rc1"

telegrinder/api/__init__.py

@@ -0,0 +1,15 @@
+from telegrinder.api.api import API
+from telegrinder.api.error import APIError, APIServerError, InvalidTokenError
+from telegrinder.api.response import APIResponse
+from telegrinder.api.token import Token
+from telegrinder.api.validators import validate_token
+
+__all__ = (
+    "API",
+    "APIError",
+    "APIResponse",
+    "APIServerError",
+    "InvalidTokenError",
+    "Token",
+    "validate_token",
+)

telegrinder/api/api.py

@@ -0,0 +1,175 @@
+import asyncio
+import pathlib
+import typing
+from datetime import timedelta
+from functools import cached_property, wraps
+from http import HTTPStatus
+
+import msgspec
+from kungfu.library.misc import is_ok
+from kungfu.library.monad.result import Error, Ok, Result
+
+from telegrinder.api.error import APIError
+from telegrinder.api.response import APIResponse
+from telegrinder.api.token import Token
+from telegrinder.client import ABCClient, RnetClient
+from telegrinder.msgspec_utils import decoder
+from telegrinder.types.methods import APIMethods
+
+type Json = str | int | float | bool | list[Json] | dict[str, Json] | None
+type Data = dict[str, typing.Any]
+type Files = dict[str, tuple[str, bytes]]
+type APIRequestMethod[T: API, **P, R] = typing.Callable[
+    typing.Concatenate[T, P],
+    typing.Coroutine[typing.Any, typing.Any, Result[R, APIError]],
+]
+
+
+DEFAULT_MAX_RETRIES: typing.Final = 5
+DEFAULT_TIMEOUT: typing.Final = timedelta(seconds=30)
+
+
+def retryer[T: API, **P, R](func: APIRequestMethod[T, P, R], /) -> APIRequestMethod[T, P, R]:
+    @wraps(func)
+    async def wrapper(
+        self: T,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> Result[typing.Any, APIError]:
+        retries_counter = 0
+
+        while True:
+            result = await func(self, *args, **kwargs)
+
+            if is_ok(result) or not self.retryer_is_enabled or retries_counter >= self.max_retries:
+                return result
+
+            if result.error.status_code == HTTPStatus.TOO_MANY_REQUESTS:
+                await asyncio.sleep(result.error.retry_after.unwrap_or(5.0))
+
+            elif result.error.status_code == HTTPStatus.INTERNAL_SERVER_ERROR and "restart" in result.error.error:
+                await asyncio.sleep(10.0)
+
+            elif result.error.migrate_to_chat_id:
+                kwargs["chat_id"] = result.error.migrate_to_chat_id.value
+
+            else:
+                return result
+
+            retries_counter += 1
+
+    return wrapper  # type: ignore
+
+
+class API(APIMethods):
+    """Bot API with available API methods and http client."""
+
+    http: ABCClient
+
+    API_URL = "https://api.telegram.org/"
+    API_FILE_URL = "https://api.telegram.org/file/"
+
+    def __init__(
+        self,
+        token: Token,
+        *,
+        http: ABCClient | None = None,
+        retryer: bool = True,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self.token = token
+        self.http = http or RnetClient()
+        self._retryer_is_enabled = retryer
+        self._max_retries = max_retries
+        super().__init__(api=self)
+
+    def __repr__(self) -> str:
+        return "<{}: id={}, http={!r}, max_retries={}>".format(
+            type(self).__name__,
+            self.id,
+            self.http,
+            self._max_retries,
+        )
+
+    @cached_property
+    def id(self) -> int:
+        return self.token.bot_id
+
+    @property
+    def request_url(self) -> str:
+        return self.API_URL + f"bot{self.token}/"
+
+    @property
+    def request_file_url(self) -> str:
+        return self.API_FILE_URL + f"bot{self.token}/"
+
+    @property
+    def retryer_is_enabled(self) -> bool:
+        return self._retryer_is_enabled
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries
+
+    async def download_file(
+        self,
+        file_path: str | pathlib.Path,
+        timeout: int | float | timedelta = DEFAULT_TIMEOUT,
+    ) -> Result[bytes, APIError]:
+        response = await self.http.request(
+            url=f"{self.request_file_url}/{file_path}",
+            timeout=timeout,
+        )
+
+        if response.status.is_success:
+            return Ok(response.content)
+
+        error = decoder.decode(response.content, type=APIResponse)
+        return Error(APIError(code=error.error_code, error=error.description, data=error.parameters))
+
+    @retryer
+    async def request(
+        self,
+        method: str,
+        data: Data | None = None,
+        files: Files | None = None,
+        **kwargs: typing.Any,
+    ) -> Result[Json, APIError]:
+        """Request a `JSON` response using http method `POST` and passing data & files as `multipart`."""
+        response = await self.http.request_json(
+            url=self.request_url + method,
+            method="POST",
+            data=self.http.get_form(data=data, files=files),
+            **kwargs,
+        )
+
+        if response.get("ok", False) is True:
+            return Ok(response["result"])
+
+        return Error(
+            APIError(
+                code=response.get("error_code", 400),
+                error=response.get("description", "Something went wrong"),
+                data=response.get("parameters", {}),
+            ),
+        )
+
+    @retryer
+    async def request_raw(
+        self,
+        method: str,
+        data: Data | None = None,
+        files: Files | None = None,
+        **kwargs: typing.Any,
+    ) -> Result[msgspec.Raw, APIError]:
+        """Request a `raw` response using http method `POST` and passing data & files as `multipart`."""
+        response_bytes = await self.http.request_bytes(
+            url=self.request_url + method,
+            method="POST",
+            data=self.http.get_form(data=data, files=files),
+            **kwargs,
+        )
+        return decoder.decode(response_bytes, type=APIResponse).to_result()
+
+
+__all__ = ("API",)

telegrinder/api/error.py

@@ -0,0 +1,50 @@
+import typing
+from functools import cached_property
+from http import HTTPStatus
+
+from kungfu.library.misc import from_optional
+from kungfu.library.monad.option import Option
+
+
+class ReprErrorMixin:
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}: {self}"
+
+
+class APIError(ReprErrorMixin, Exception):
+    def __init__(
+        self,
+        code: int,
+        error: str,
+        data: dict[str, typing.Any],
+    ) -> None:
+        self.code, self.error, self.parameters = code, error, data
+
+    @cached_property
+    def status_code(self) -> HTTPStatus:
+        return HTTPStatus(self.code)
+
+    @property
+    def retry_after(self) -> Option[int]:
+        return from_optional(self.parameters.get("retry_after"))
+
+    @property
+    def migrate_to_chat_id(self) -> Option[int]:
+        return from_optional(self.parameters.get("migrate_to_chat_id"))
+
+    def __str__(self) -> str:
+        return f"[{self.code}] ({self.status_code.name}) {self.error}"
+
+
+class APIServerError(ReprErrorMixin, Exception):
+    def __init__(self, message: str, retry_after: int | None = None) -> None:
+        self.message = message
+        self.retry_after = retry_after
+        super().__init__(message)
+
+
+class InvalidTokenError(BaseException):
+    pass
+
+
+__all__ = ("APIError", "APIServerError", "InvalidTokenError")

telegrinder/api/response.py

@@ -0,0 +1,23 @@
+import typing
+
+import msgspec
+from kungfu.library.monad.result import Error, Ok, Result
+
+from telegrinder.api.error import APIError
+from telegrinder.model import Model
+
+
+class APIResponse(Model):
+    ok: bool = False
+    result: msgspec.Raw = msgspec.Raw(b"")
+    error_code: int = 400
+    description: str = "Something went wrong"
+    parameters: dict[str, typing.Any] = msgspec.field(default_factory=dict[str, typing.Any])
+
+    def to_result(self) -> Result[msgspec.Raw, APIError]:
+        if self.ok:
+            return Ok(self.result)
+        return Error(APIError(code=self.error_code, error=self.description, data=self.parameters))
+
+
+__all__ = ("APIResponse",)

telegrinder/api/token.py

@@ -0,0 +1,30 @@
+import typing
+from functools import cached_property
+
+from telegrinder.api.error import InvalidTokenError
+from telegrinder.modules import take_env
+
+
+class Token(str):
+    def __new__(cls, token: str, /) -> typing.Self:
+        if token.count(":") != 1 or not token.split(":")[0].isdigit():
+            raise InvalidTokenError("Invalid token format, it should look like 12345:ABCdef")
+        return super().__new__(cls, token)
+
+    def __repr__(self) -> str:
+        return f"<Token: {self.bot_id}:{self.token[:9]}...>"
+
+    @classmethod
+    def from_env(cls, var_name: str = "BOT_TOKEN") -> typing.Self:
+        return cls(take_env(var_name))
+
+    @cached_property
+    def token(self) -> str:
+        return self.split(":")[1]
+
+    @cached_property
+    def bot_id(self) -> int:
+        return int(self.split(":")[0])
+
+
+__all__ = ("Token",)

telegrinder/api/validators.py

@@ -0,0 +1,30 @@
+from http import HTTPStatus
+
+from kungfu import Error, Ok, Result
+
+from telegrinder.api.api import API
+from telegrinder.api.error import InvalidTokenError
+from telegrinder.api.token import Token
+
+
+async def validate_token(token: str, /) -> Result[Token, InvalidTokenError]:
+    try:
+        token = Token(token)
+        api = API(token)
+
+        match await api.get_me():
+            case Ok(_):
+                return Ok(token)
+            case Error(error):
+                return Error(
+                    InvalidTokenError(
+                        "Token seems to be invalid."
+                        if error.status_code in (HTTPStatus.UNAUTHORIZED, HTTPStatus.NOT_FOUND)
+                        else f"Unknown error {error!r} while validating token, please try again later.",
+                    ),
+                )
+    except InvalidTokenError as error:
+        return Error(error)
+
+
+__all__ = ("validate_token",)