telegrinder 0.3.4.post1__tar.gz → 0.4.0__tar.gz

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
-Copyright (c) 2022-2024 timoniq
-Copyright (c) 2024 luwqz1
+Copyright (c) 2022-2025 timoniq
+Copyright (c) 2024-2025 luwqz1
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

telegrinder-0.4.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.3
+Name: telegrinder
+Version: 0.4.0
+Summary: Modern visionary telegram bot framework.
+License: MIT License
+         
+         Copyright (c) 2022-2025 timoniq
+         Copyright (c) 2024-2025 luwqz1
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Keywords: asyncio,api schema,async,bot building,bot api,custom rules,telegram,telegram bot api framework,telegrinder framework,middleware,composition,framework,telegrinder,waiter machine
+Author: timoniq
+Author-email: tesseradecades@mail.ru
+Maintainer: luwqz1
+Maintainer-email: howluwqz1@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Provides-Extra: all
+Provides-Extra: fast
+Provides-Extra: loguru
+Provides-Extra: uvloop
+Requires-Dist: aiohttp (>=3.11.11,<4.0.0)
+Requires-Dist: certifi (>=2025.1.31)
+Requires-Dist: choicelib (>=0.1.5,<0.2.0)
+Requires-Dist: colorama (>=0.4.6,<0.5.0)
+Requires-Dist: envparse (>=0.2.0,<0.3.0)
+Requires-Dist: fntypes (>=0.1.4.post3,<0.2.0)
+Requires-Dist: loguru (>=0.7.0) ; extra == "all"
+Requires-Dist: loguru (>=0.7.0) ; extra == "loguru"
+Requires-Dist: msgspec (>=0.19.0,<0.20.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
+Requires-Dist: uvloop (>=0.21.0) ; extra == "all"
+Requires-Dist: uvloop (>=0.21.0) ; extra == "fast"
+Requires-Dist: uvloop (>=0.21.0) ; extra == "uvloop"
+Requires-Dist: vbml (>=1.1.post1,<2.0)
+Project-URL: Bug Tracker, https://github.com/timoniq/telegrinder/issues
+Project-URL: Documentation, https://telegrinder.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/timoniq/telegrinder
+Description-Content-Type: text/markdown
+
+# Telegrinder
+
+Framework for effective and reliable telegram bot building.
+
+Still in development.
+
+* Type hinted
+* Customizable and extensible
+* Ready to use scenarios and rules
+* Fast models built on [msgspec](https://github.com/jcrist/msgspec)
+* Both low-level and high-level API
+* Support [optional dependecies](https://github.com/timoniq/telegrinder/blob/dev/docs/guide/optional_dependencies.md)
+
+# Getting started
+
+Install using pip:
+
+```console
+pip install telegrinder
+```
+
+Using poetry:
+
+```console
+poetry add telegrinder
+```
+
+Install from github:
+
+```console
+pip install -U https://github.com/timoniq/telegrinder/archive/dev.zip
+```
+
+```console
+poetry add git+https://github.com/timoniq/telegrinder.git#dev
+```
+
+Basic example:
+
+```python
+from telegrinder import API, Message, Telegrinder, Token
+from telegrinder.modules import logger
+from telegrinder.rules import Text
+
+api = API(token=Token("123:token"))
+bot = Telegrinder(api)
+logger.set_level("INFO")
+
+
+@bot.on.message(Text("/start"))
+async def start(message: Message):
+    me = (await api.get_me()).unwrap()
+    await message.answer(f"Hello, {message.from_user.full_name}! I'm {me.full_name}.")
+
+
+bot.run_forever()
+```
+
+# Documentation
+
+[Readthedocs](https://telegrinder.readthedocs.io)
+
+# Community
+
+Join our [telegram forum](https://t.me/botoforum).
+
+# [Contributing](https://github.com/timoniq/telegrinder/blob/main/contributing.md)
+
+# License
+
+Telegrinder is [MIT licensed](./LICENSE)\
+Copyright © 2022-2025 [timoniq](https://github.com/timoniq)\
+Copyright © 2024-2025 [luwqz1](https://github.com/luwqz1)
+
+# Contributors
+
+<a href="https://github.com/timoniq/telegrinder/graphs/contributors">
+ <img src="https://contributors-img.web.app/image?repo=timoniq/telegrinder" />
+</a>
+

telegrinder-0.4.0/pyproject.toml

@@ -0,0 +1,164 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+requires-python = ">=3.12,<4.0"
+name = "telegrinder"
+version = "0.4.0"
+description = "Modern visionary telegram bot framework."
+authors = [
+  {name = "timoniq", email = "tesseradecades@mail.ru"}
+]
+maintainers = [
+  {name = "luwqz1", email = "howluwqz1@gmail.com"}
+]
+license = { file = "LICENSE" }
+readme = "readme.md"
+keywords = [
+  "asyncio",
+  "api schema",
+  "async",
+  "bot building",
+  "bot api",
+  "custom rules",
+  "telegram",
+  "telegram bot api framework",
+  "telegrinder framework",
+  "middleware",
+  "composition",
+  "framework",
+  "telegrinder",
+  "waiter machine"
+]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Software Development :: Quality Assurance",
+  "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp (>=3.11.11,<4.0.0)",
+    "colorama (>=0.4.6,<0.5.0)",
+    "vbml (>=1.1.post1,<2.0)",
+    "choicelib (>=0.1.5,<0.2.0)",
+    "envparse (>=0.2.0,<0.3.0)",
+    "pyyaml (>=6.0.2,<7.0.0)",
+    "certifi (>=2025.1.31)",
+    "msgspec (>=0.19.0,<0.20.0)",
+    "typing-extensions (>=4.12.2,<5.0.0)",
+    "fntypes (>=0.1.4.post3,<0.2.0)"
+]
+
+[project.urls]
+Source = "https://github.com/timoniq/telegrinder"
+"Bug Tracker" = "https://github.com/timoniq/telegrinder/issues"
+Documentation = "https://telegrinder.readthedocs.io/en/latest/"
+
+[project.optional-dependencies]
+all = [
+  "uvloop >= 0.21.0",
+  "loguru >= 0.7.0"
+]
+fast = [
+  "uvloop >= 0.21.0"
+]
+uvloop = [
+  "uvloop >= 0.21.0"
+]
+loguru = [
+  "loguru >= 0.7.0"
+]
+
+[tool.poetry]
+package-mode = true
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = ">=4.1.0,<5.0"
+ruff = "^0.9.2"
+basedpyright = "^1.26.0"
+requests = "^2.28.1"
+sort-all = "^1.2.0"
+libcst = "^1.4.0"
+pytest = "^8.0.0"
+pytest-asyncio = ">=0.23.5,<0.26.0"
+pytest-cov = ">=5,<7"
+pytest-mock = "^3.10.0"
+
+[tool.ruff]
+line-length = 115
+target-version = "py312"
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint]
+select = [
+  "I",
+  "D",
+  "N",
+  "PLR",
+  "Q",
+  "COM",
+  "TC",
+  "YTT",
+  "SIM"
+]
+ignore = [
+  "COM812",
+  "N805",
+  "N818",
+  "TC001",
+  "TC002",
+  "TC003",
+  "TC004",
+  "D100",
+  "D101",
+  "D102",
+  "D103",
+  "D104",
+  "D105",
+  "D107",
+  "D202",
+  "D203",
+  "D205",
+  "D209",
+  "D211",
+  "D213",
+  "D400",
+  "D401",
+  "D404",
+  "D415",
+  "PLR2004",
+  "PLR0911",
+  "PLR0912",
+  "PLR0913"
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"typegen/**.py" = ["N802"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.pyright]
+exclude = [
+  "**/__pycache__",
+  "docs",
+  "local",
+  "telegrinder/client/sonic.py"
+]
+typeCheckingMode = "basic"
+pythonPlatform = "All"
+pythonVersion = "3.12"
+reportMissingImports = true
+reportMissingTypeStubs = false
+enableExperimentalFeatures = true

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/readme.md

@@ -69,5 +69,11 @@ Join our [telegram forum](https://t.me/botoforum).
 # License
 
 Telegrinder is [MIT licensed](./LICENSE)\
-Copyright © 2022-2024 [timoniq](https://github.com/timoniq)\
-Copyright © 2024 [luwqz1](https://github.com/luwqz1)
+Copyright © 2022-2025 [timoniq](https://github.com/timoniq)\
+Copyright © 2024-2025 [luwqz1](https://github.com/luwqz1)
+
+# Contributors
+
+<a href="https://github.com/timoniq/telegrinder/graphs/contributors">
+ <img src="https://contributors-img.web.app/image?repo=timoniq/telegrinder" />
+</a>

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/__init__.py

@@ -33,7 +33,7 @@ bot.run_forever()
 
 import typing
 
-from .api import API, APIError, APIResponse, Token
+from .api import API, APIError, APIResponse, APIServerError, Token
 from .bot import (
     CALLBACK_QUERY_FOR_MESSAGE,
     CALLBACK_QUERY_FROM_CHAT,
@@ -82,6 +82,9 @@ from .bot import (
     MessageView,
     PhotoReplyHandler,
     Polling,
+    PreCheckoutQueryCute,
+    PreCheckoutQueryManager,
+    PreCheckoutQueryView,
     RawEventView,
     ShortState,
     StateViewHasher,
@@ -93,45 +96,37 @@ from .bot import (
     WaiterMachine,
     register_manager,
 )
-from .bot.rules import StateMeta
-from .client import ABCClient, AiohttpClient
+from .client import ABCClient, AiohttpClient, AiosonicClient
 from .model import Model
 from .modules import logger
-from .tools import (
-    ABCErrorHandler,
-    ABCGlobalContext,
-    ABCLoopWrapper,
-    ABCStateStorage,
+from .tools.error_handler import ABCErrorHandler, ErrorHandler
+from .tools.formatting import HTMLFormatter
+from .tools.global_context import ABCGlobalContext, CtxVar, GlobalContext, ctx_var
+from .tools.i18n import (
     ABCTranslator,
     ABCTranslatorMiddleware,
+    I18nEnum,
+    SimpleI18n,
+    SimpleTranslator,
+)
+from .tools.input_file_directory import InputFileDirectory
+from .tools.keyboard import (
     AnyMarkup,
     Button,
-    CtxVar,
-    DelayedTask,
-    ErrorHandler,
-    FormatString,
-    GlobalContext,
-    HTMLFormatter,
-    I18nEnum,
     InlineButton,
     InlineKeyboard,
     Keyboard,
-    KeyboardSetBase,
-    KeyboardSetYAML,
-    Lifespan,
-    LoopWrapper,
-    MemoryStateStorage,
-    ParseMode,
     RowButtons,
-    SimpleI18n,
-    SimpleTranslator,
-    StateData,
-    ctx_var,
-    magic_bundle,
 )
+from .tools.lifespan import Lifespan
+from .tools.loop_wrapper import ABCLoopWrapper, DelayedTask, LoopWrapper
+from .tools.magic import cache_translation, get_cached_translation, magic_bundle
+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
@@ -160,7 +155,9 @@ __all__ = (
     "API",
     "APIError",
     "APIResponse",
+    "APIServerError",
     "AiohttpClient",
+    "AiosonicClient",
     "AnyMarkup",
     "AudioReplyHandler",
     "BaseCute",
@@ -192,7 +189,6 @@ __all__ = (
     "Dispatch",
     "DocumentReplyHandler",
     "ErrorHandler",
-    "FormatString",
     "FuncHandler",
     "GlobalContext",
     "HTMLFormatter",
@@ -204,9 +200,8 @@ __all__ = (
     "InlineQueryCute",
     "InlineQueryReturnManager",
     "InlineQueryRule",
+    "InputFileDirectory",
     "Keyboard",
-    "KeyboardSetBase",
-    "KeyboardSetYAML",
     "Lifespan",
     "LoopWrapper",
     "MESSAGE_FROM_USER",
@@ -226,6 +221,10 @@ __all__ = (
     "ParseMode",
     "PhotoReplyHandler",
     "Polling",
+    "PreCheckoutQuery",
+    "PreCheckoutQueryCute",
+    "PreCheckoutQueryManager",
+    "PreCheckoutQueryView",
     "RawEventView",
     "RowButtons",
     "ShortState",
@@ -233,8 +232,6 @@ __all__ = (
     "SimpleTranslator",
     "StateData",
     "StateData",
-    "StateMeta",
-    "StateMeta",
     "StateViewHasher",
     "StickerReplyHandler",
     "Telegrinder",
@@ -244,7 +241,9 @@ __all__ = (
     "VideoReplyHandler",
     "ViewBox",
     "WaiterMachine",
+    "cache_translation",
     "ctx_var",
+    "get_cached_translation",
     "logger",
     "magic_bundle",
     "register_manager",

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/api/__init__.py

@@ -1,5 +1,5 @@
 from .api import API
-from .error import APIError, InvalidTokenError
+from .error import APIError, APIServerError, InvalidTokenError
 from .response import APIResponse
 from .token import Token
 
@@ -7,6 +7,7 @@ __all__ = (
     "API",
     "APIError",
     "APIResponse",
+    "APIServerError",
     "InvalidTokenError",
     "Token",
 )

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/api/api.py

@@ -1,39 +1,44 @@
-import typing
 from functools import cached_property
 
 import msgspec
+import typing_extensions as typing
 from fntypes.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, AiohttpClient
-from telegrinder.model import DataConverter, decoder
+from telegrinder.client import ABCClient, AiohttpClient, MultipartFormProto
+from telegrinder.model import decoder
 from telegrinder.types.methods import APIMethods
 
+HTTPClient = typing.TypeVar("HTTPClient", bound=ABCClient, default=AiohttpClient)
 
-def compose_data(
-    client: ABCClient,
+type Json = str | int | float | bool | list[Json] | dict[str, Json] | None
+
+
+def compose_data[MultipartForm: MultipartFormProto](
+    client: ABCClient[MultipartForm],
     data: dict[str, typing.Any],
     files: dict[str, tuple[str, bytes]],
-) -> typing.Any:
-    converter = DataConverter(_files=files.copy())
-    return client.get_form(
-        data={k: converter(v) for k, v in data.items()},
-        files=converter.files,
-    )
+) -> MultipartForm:
+    if not data and not files:
+        return client.multipart_form_factory()
+    return client.get_form(data=data, files=files)
 
 
-class API(APIMethods):
+class API(APIMethods[HTTPClient], typing.Generic[HTTPClient]):
     """Bot API with available API methods and http client."""
 
     API_URL = "https://api.telegram.org/"
     API_FILE_URL = "https://api.telegram.org/file/"
 
-    def __init__(self, token: Token, *, http: ABCClient | None = None) -> None:
+    token: Token
+    http: HTTPClient
+
+    def __init__(self, token: Token, *, http: HTTPClient | None = None) -> None:
         self.token = token
-        self.http = http or AiohttpClient()
-        super().__init__(self)
+        self.http = http or AiohttpClient()  # type: ignore
+        super().__init__(api=self)
 
     def __repr__(self) -> str:
         return "<{}: token={!r}, http={!r}>".format(
@@ -62,19 +67,20 @@ class API(APIMethods):
         method: str,
         data: dict[str, typing.Any] | None = None,
         files: dict[str, tuple[str, bytes]] | None = None,
-    ) -> Result[dict[str, typing.Any] | list[typing.Any] | bool, APIError]:
+    ) -> Result[Json, APIError]:
+        """Request a `JSON` response with the `POST` HTTP method and passing data, files as `multipart/form-data`."""
         response = await self.http.request_json(
             url=self.request_url + method,
+            method="POST",
             data=compose_data(self.http, data or {}, files or {}),
         )
-        if response.get("ok"):
-            assert "result" in response
+        if response.get("ok", False) is True:
             return Ok(response["result"])
         return Error(
             APIError(
                 code=response.get("error_code", 400),
-                error=response.get("description"),
-            )
+                error=response.get("description", "Something went wrong"),
+            ),
         )
 
     async def request_raw(
@@ -83,8 +89,10 @@ class API(APIMethods):
         data: dict[str, typing.Any] | None = None,
         files: dict[str, tuple[str, bytes]] | None = None,
     ) -> Result[msgspec.Raw, APIError]:
+        """Request a `raw` response with the `POST` HTTP method and passing data, files as `multipart/form-data`."""
         response_bytes = await self.http.request_bytes(
             url=self.request_url + method,
+            method="POST",
             data=compose_data(self.http, data or {}, files or {}),
         )
         return decoder.decode(response_bytes, type=APIResponse).to_result()

telegrinder-0.4.0/telegrinder/api/error.py

@@ -0,0 +1,20 @@
+class APIError(Exception):
+    def __init__(self, code: int, error: str) -> None:
+        self.code, self.error = code, error
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.error}"
+
+    def __repr__(self) -> str:
+        return f"<APIError: {self.__str__()}>"
+
+
+class APIServerError(Exception):
+    pass
+
+
+class InvalidTokenError(BaseException):
+    pass
+
+
+__all__ = ("APIError", "APIServerError", "InvalidTokenError")

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/api/response.py

@@ -8,8 +8,8 @@ from telegrinder.model import Model
 class APIResponse(Model):
     ok: bool = False
     result: msgspec.Raw = msgspec.Raw(b"")
-    error_code: int = 0
-    description: str = ""
+    error_code: int = 400
+    description: str = "Something went wrong"
 
     def to_result(self) -> Result[msgspec.Raw, APIError]:
         if self.ok:

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/api/token.py

@@ -8,9 +8,9 @@ from .error import InvalidTokenError
 
 
 class Token(str):
-    def __new__(cls, token: str) -> typing.Self:
+    def __new__(cls, token: str, /) -> typing.Self:
         if token.count(":") != 1 or not token.split(":")[0].isdigit():
-            raise InvalidTokenError("Invalid token, it should look like this '123:ABC'.")
+            raise InvalidTokenError("Invalid token, it should look like this: 12345:ABCdef")
         return super().__new__(cls, token)
 
     def __repr__(self) -> str:

{telegrinder-0.3.4.post1 → telegrinder-0.4.0}/telegrinder/bot/__init__.py

@@ -6,6 +6,7 @@ from telegrinder.bot.cute_types import (
     ChatMemberUpdatedCute,
     InlineQueryCute,
     MessageCute,
+    PreCheckoutQueryCute,
     UpdateCute,
 )
 from telegrinder.bot.dispatch import (
@@ -41,6 +42,8 @@ from telegrinder.bot.dispatch import (
     MessageReturnManager,
     MessageView,
     PhotoReplyHandler,
+    PreCheckoutQueryManager,
+    PreCheckoutQueryView,
     RawEventView,
     ShortState,
     StateViewHasher,
@@ -110,6 +113,9 @@ __all__ = (
     "MessageView",
     "PhotoReplyHandler",
     "Polling",
+    "PreCheckoutQueryCute",
+    "PreCheckoutQueryManager",
+    "PreCheckoutQueryView",
     "RawEventView",
     "ShortState",
     "StateViewHasher",