telekit 2.2.0a2__tar.gz → 2.2.0a3__tar.gz

{telekit-2.2.0a2/telekit.egg-info → telekit-2.2.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a2
+Version: 2.2.0a3
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -378,7 +378,7 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a2
+# Changes in version 2.2.0a3
 
 ## New Button Types
 
@@ -386,6 +386,7 @@ It tries to make Telegram bot development easier.
 |----------------------|----------------------------------------------------------|
 | `AlertButton`        | A callback button that shows a popup alert when pressed. |
 | `NotificationButton` | A callback button that shows a notification.             |
+| `InvokeButton`       | A callback button that calls the object method.          |
 
 ## User Improvements
 
@@ -404,3 +405,22 @@ It tries to make Telegram bot development easier.
 
 - Refactor: `User` now accepts a `Message` object instead of `chat_id` + `from_user`. All properties are derived from `_sender` (`from_user` or `chat`) and migrated to `cached_property`. Fixed broken `get_id` and `get_full_name` references.
 - Added `__repr__`.
+
+## Sender Improvements
+
+| **Name**                   | **Description**                                        |
+| -------------------------- | ------------------------------------------------------ |
+| `sent_message`             | The last message sent by this sender instance.         |
+| `disable_notification`     | Disables notification sound when the message is sent.  |
+| `protect_content`          | Protects the message contents from forwarding and saving. |
+| `reply_parameters`         | Reply parameters for the message to be sent.           |
+| `link_preview_options`     | Link preview options for the message to be sent.       |
+| `show_caption_above_media` | Shows the caption above the media instead of below.    |
+
+- Refactored sending system.
+
+## Chain Improvements
+
+| **Name**    | **Description**                                              |
+| ----------- | ------------------------------------------------------------ |
+| `received`  | The message received from the user during entry processing.  |

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_chain.py

@@ -28,11 +28,8 @@ from telebot.types import Message
 from . import senders
 from .styles import TextEntity
 
-# Logging
-from ._logger import logger
-library = logger.library
-
 # Chain modules
+from ._chain_base import library
 from ._chain_inline_keyboards_logic import ChainInlineKeyboardLogic
 from ._chain_entry_logic import ChainEntryLogic, TextDocument
 

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_chain_base.py

@@ -30,6 +30,10 @@ from . import senders
 from . import _input_handler
 from . import _timeout
 
+# Logging
+from ._logger import logger
+library = logger.library
+
 class ChainBase:
 
     bot: telebot.TeleBot
@@ -49,6 +53,8 @@ class ChainBase:
     def __init__(self, chat_id: int, *, previous_message: Message | None = None):
         self.chat_id = chat_id
         self.sender = senders.Sender(chat_id)
+        self.received = None
+        
         self._handler = _input_handler.InputHandler(chat_id)
         self._previous_message = previous_message
         self._timeout_handler = _timeout.TimeoutHandler()

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_chain_entry_logic.py

@@ -68,6 +68,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+
             if delete_user_response:
                 self.sender.delete_message(message, True)
 
@@ -154,6 +156,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+
             if delete_user_response:
                 self.sender.delete_message(message, True)
 
@@ -246,6 +250,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+
             if delete_user_response:
                 self.sender.delete_message(message, True)
 
@@ -340,6 +346,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+
             if delete_user_response:
                 self.sender.delete_message(message, True)
 
@@ -453,6 +461,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+
             if delete_user_response:
                 self.sender.delete_message(message, True)
 
@@ -592,6 +602,8 @@ class ChainEntryLogic(ChainBase):
         """
 
         def callback(message: Message) -> bool:
+            self.received = message
+            
             if delete_user_response:
                 self.sender.delete_message(message, True)
 

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_chain_inline_keyboards_logic.py

@@ -32,7 +32,7 @@ from telebot.types import (
 
 from ._callback_query_handler import CallbackQueryHandler
 from ._inline_buttons import InlineButton, CallbackButton
-from ._chain_base import ChainBase
+from ._chain_base import ChainBase, library
 
 if typing.TYPE_CHECKING:
     from ._chain import Chain # only for type hints
@@ -151,15 +151,24 @@ class ChainInlineKeyboardLogic(ChainBase):
             buttons: list[InlineKeyboardButton] = []
 
             for index, (caption, value) in enumerate(keyboard.items()):
-                if enable_special_buttons and isinstance(value, InlineButton):
+                if enable_special_buttons and isinstance(value, InlineButton) and not isinstance(value, CallbackButton):
                     buttons.append(value._compile(caption))
                 else:
+                    if isinstance(value, CallbackButton):
+                        invoker = value.build_invoker(self._cancel_timeout_and_handlers)
+                    else:
+                        invoker = self._get_invoker_with_argument(func, value)
+
                     callback_data = CallbackQueryHandler.inline_button(f"{index}:{random.randint(1000, 9999)}")
-                    callback_functions[callback_data] = self._get_callback_with_argument(func, value)
+                    callback_functions[callback_data] = invoker
+
+                    kwargs: dict[str, Any] = getattr(invoker, "_kwargs", None) or {}
+
                     buttons.append(
                         InlineKeyboardButton(
                             text=caption,
-                            callback_data=callback_data
+                            callback_data=callback_data,
+                            **kwargs
                         )
                     )
 
@@ -242,18 +251,34 @@ class ChainInlineKeyboardLogic(ChainBase):
         buttons: list[InlineKeyboardButton] = []
 
         if not isinstance(choices, dict):
+            for c in choices:
+                if type(c).__str__ is object.__str__:
+                    library.warning(
+                        f"{type(c).__name__} does not implement __str__. "
+                        f"Consider passing a dict with explicit labels.",
+                        stacklevel=3
+                    )
             choices = {str(c): c for c in choices}
 
         for index, (caption, value) in enumerate(choices.items()):
-            if enable_special_buttons and isinstance(value, InlineButton):
+            if enable_special_buttons and isinstance(value, InlineButton) and not isinstance(value, CallbackButton):
                 buttons.append(value._compile(caption))
             else:
+                if isinstance(value, CallbackButton):
+                    invoker = value.build_invoker(self._cancel_timeout_and_handlers)
+                else:
+                    invoker = self._get_invoker_with_argument(func, value)
+
                 callback_data = CallbackQueryHandler.inline_button(f"{index}:{random.randint(1000, 9999)}")
-                callback_functions[callback_data] = self._get_callback_with_argument(func, value)
+                callback_functions[callback_data] = invoker
+
+                kwargs: dict[str, Any] = getattr(invoker, "_kwargs", None) or {}
+
                 buttons.append(
                     InlineKeyboardButton(
                         text=caption,
-                        callback_data=callback_data
+                        callback_data=callback_data,
+                        **kwargs
                     )
                 )
 
@@ -314,21 +339,21 @@ class ChainInlineKeyboardLogic(ChainBase):
 
         self.sender.set_reply_markup(markup)
 
-    def _get_callback_with_argument(self, func: Callable, argument: Any, query_answer: tuple[str, bool] | None = None) -> Callable[[CallbackQuery], None]:
-        def callback(call: CallbackQuery) -> None:
+    def _get_invoker_with_argument(self, callback: Callable, argument: Any, query_answer: tuple[str, bool] | None = None) -> Callable[[CallbackQuery], None]:
+        def invoker(call: CallbackQuery) -> None:
             self._cancel_timeout_and_handlers()
-            func(argument)
+            callback(argument)
             self._answer_callback_query(call, query_answer)
 
-        return callback
+        return invoker
     
-    def _get_callback(self, func: Callable[..., None], query_answer: tuple[str, bool] | None = None) -> Callable[[CallbackQuery], None]:
-        def callback(call: CallbackQuery):
+    def _get_invoker(self, callback: Callable[..., None], query_answer: tuple[str, bool] | None = None) -> Callable[[CallbackQuery], None]:
+        def invoker(call: CallbackQuery):
             self._cancel_timeout_and_handlers()
-            func()
+            callback()
             self._answer_callback_query(call, query_answer)
 
-        return callback
+        return invoker
     
     def _answer_callback_query(self, call: CallbackQuery, query_answer: tuple[str, bool] | None = None):
         if query_answer is None:
@@ -369,8 +394,4 @@ class ChainInlineKeyboardLogic(ChainBase):
                 rows.append(buttons[index:index + last_width])
                 index += last_width
 
-        return rows
-    
-    def _is_valid_telegram_callback(self, data: str) -> bool:
-        byte_size = len(data.encode('utf-8'))
-        return 1 <= byte_size <= 64
+        return rows

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_inline_buttons.py

@@ -36,6 +36,7 @@ __all__ = [
     "CallbackButton",
     "AlertButton",
     "NotificationButton",
+    "InvokeButton",
 
     "ButtonStyle"
 ]
@@ -56,8 +57,9 @@ class InlineButton:
     - `SuggestButton`
     - `CopyTextButton`
     - `CallbackButton`
-    - `AlertButton
-    - `NotificationButton
+    - `AlertButton`
+    - `NotificationButton`
+    - `InvokeButton`
     """
 
     _bot: TeleBot
@@ -76,6 +78,7 @@ class InlineButton:
     Callback: type["CallbackButton"]
     Alert: type["AlertButton"]
     Notification: type["NotificationButton"]
+    Invoke: type["InvokeButton"]
     
     Styles: type[ButtonStyle] = ButtonStyle
 
@@ -340,7 +343,7 @@ class CallbackButton(InlineButton):
             self._answer_callback_query(call)
 
     def __init__(
-            self, 
+            self,
             callback: Callable[..., Any] | None, 
 
             pass_args: tuple | list | None = None, 
@@ -482,6 +485,130 @@ class NotificationButton(CallbackButton):
             style=style,
             **kwargs
         )
+
+class InvokeButton(CallbackButton):
+    """
+    An inline keyboard button that calls a named method on a given object when pressed.
+
+    Unlike `CallbackButton`, which takes a callable directly, `InvokeButton` resolves
+    the method at invocation time via `getattr(obj, invoke)`.
+
+    :param obj: The object on which the method will be called.
+    :type obj: `Any`
+
+    :param invoke: Name of the method to call on `obj`.
+    :type invoke: `str`
+
+    :param pass_args: Positional arguments to pass into the method.
+    :type pass_args: `tuple | list | None`
+
+    :param pass_kwargs: Keyword arguments to pass into the method.
+    :type pass_kwargs: `dict[str, Any] | None`
+
+    :param answer_text: Optional text to send as an answer to the callback query.
+    :type answer_text: `str | None`
+
+    :param answer_as_alert: If `True`, the answer is shown as a popup alert.
+        If `False`, it appears as a notification at the top of the chat.
+    :type answer_as_alert: `bool`
+
+    :param style: Style of the button. Must be one of `ButtonStyle.DANGER` (red),
+              `*.SUCCESS` (green) or `*.PRIMARY` (blue).
+              You can also pass these as string values: "danger", "success", "primary".
+              If omitted, an app-specific default style is used.
+    :type style: `str | ButtonStyle | None`
+
+    :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
+    :type kwargs: `Any`
+
+    Example::
+
+        self.chain.set_inline_keyboard({
+            "📖 My Deck": InvokeButton(self.handoff(DeckHandler), "handle"),
+        })
+    """
+    class _CallbackInvoker(CallbackButton._CallbackInvoker):
+        def __init__(
+                self,
+                chain_callback: Callable[[], None],
+                
+                obj: Any,
+                invoke: str,
+
+                pass_args: tuple | list | None = None, 
+                pass_kwargs: dict[str, Any] | None = None, 
+
+                answer_text: str | None = None,
+                answer_as_alert: bool = True,
+
+                style: str | None | ButtonStyle = None,
+
+                kwargs: dict[str, Any] = {}
+            ):
+            self._obj = obj
+            self._invoke = invoke
+
+            self._pass_args = pass_args
+            self._pass_kwargs = pass_kwargs
+
+            self._answer_text = answer_text
+            self._answer_as_alert = answer_as_alert
+
+            self._style = style
+
+            self._kwargs = {"style": style} | kwargs
+            
+            self._chain_callback: Callable[[], None] = chain_callback
+
+        def _invoke_callback(self):
+            obj: Any = self.__dict__["_obj"]
+            callback: Any = getattr(obj, self._invoke)
+            
+            args = self._pass_args or ()
+            kwargs = self._pass_kwargs or {}
+
+            callback(*args, **kwargs)
+
+    def __init__(
+            self, 
+            obj: Any,
+            invoke: str,
+
+            pass_args: tuple | list | None = None, 
+            pass_kwargs: dict[str, Any] | None = None, 
+            *,
+            answer_text: str | None = None,
+            answer_as_alert: bool = True,
+
+            style: str | None | ButtonStyle = None,
+
+            **kwargs
+        ):
+        self._obj = obj
+        self._invoke = invoke
+
+        self._pass_args = pass_args
+        self._pass_kwargs = pass_kwargs
+
+        self._answer_text = answer_text
+        self._answer_as_alert = answer_as_alert
+
+        self._style = self._normalize_style(style)
+
+        self._kwargs = kwargs
+        
+    def build_invoker(self, chain_callback: Callable[[], None]) -> _CallbackInvoker:
+        return self._CallbackInvoker(
+            chain_callback=chain_callback,
+            obj=self._obj,
+            invoke=self._invoke,
+            pass_args=self._pass_args,
+            pass_kwargs=self._pass_kwargs,
+            answer_text=self._answer_text,
+            answer_as_alert=self._answer_as_alert,
+            style=self._style,
+            kwargs=self._kwargs
+        )
     
 InlineButton.Link = LinkButton
 InlineButton.WebApp = WebAppButton
@@ -489,4 +616,5 @@ InlineButton.Suggest = SuggestButton
 InlineButton.CopyText = CopyTextButton
 InlineButton.Callback = CallbackButton
 InlineButton.Alert = AlertButton
-InlineButton.Notification = NotificationButton
+InlineButton.Notification = NotificationButton
+InlineButton.Invoke = InvokeButton

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_telekit_dsl/mixin.py

@@ -368,7 +368,7 @@ class DSLHandler(telekit.Handler):
         if not hasattr(self, "_script_data_factory"):
             message: str = f"{type(self).__name__}().start_script(): Script is not analyzed yet. Call cls.analyze_file() or cls.analyze_string() before starting it."
             library.error(message)
-            self.chain.sender.pyerror(RuntimeError(message))
+            self.chain.sender.send_error("DSLError", message)
             return
 
         self.script_data = self._script_data_factory()
@@ -799,7 +799,7 @@ class DSLHandler(telekit.Handler):
     # ----------------------------------------------------------------------------
 
     def _fail(self, message: str, exception: type[Exception]=Exception):
-        self.chain.sender.error("🤷 Something went wrong...", message)
+        self.chain.sender.send_error("🤷 Something went wrong...", message)
         library.error(message)
         return exception(message)
         

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/_version.py

@@ -3,4 +3,4 @@
 # PyPI history: https://pypi.org/project/telekit/#history
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-__version__ = "2.2.0a2"
+__version__ = "2.2.0a3"

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/example/example_handlers/pages.py

@@ -1,6 +1,7 @@
-import telebot.types
 import telekit
 
+from telekit.inline_buttons import CallbackButton
+
 source = """
 # Page Title
 
@@ -46,9 +47,12 @@ class PagesHandler(telekit.Handler):
         self.chain.sender.set_title("Simple Pages Example")
         self.chain.sender.set_message("Here are some common questions and answers to help you get started:")
 
-        @self.chain.inline_keyboard(pages)
-        def _(page: tuple[str, str]) -> None:
-            self.display_page(page)
+        self.chain.set_inline_choice(
+            self.display_page, 
+            pages | {
+                "« Back": CallbackButton(self.handoff_start)
+            }
+        )
 
         self.chain.disable_timeout_warnings()
         self.chain.edit()
@@ -60,4 +64,7 @@ class PagesHandler(telekit.Handler):
         self.chain.sender.set_message(page[1])
 
         self.chain.set_inline_keyboard({"« Back": self.display_home_page})
-        self.chain.edit()
+        self.chain.edit()
+
+    def handoff_start(self):
+        self.handoff("StartHandler").handle()

{telekit-2.2.0a2 → telekit-2.2.0a3}/telekit/inline_buttons.py

@@ -28,6 +28,7 @@ from ._inline_buttons import (
     CallbackButton,
     AlertButton,
     NotificationButton,
+    InvokeButton,
 )
 
 __all__ = [
@@ -41,4 +42,5 @@ __all__ = [
     "CallbackButton",
     "AlertButton",
     "NotificationButton",
+    "InvokeButton",
 ]