telekit 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.1.0
+Version: 2.2.0
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -36,9 +36,9 @@ Dynamic: summary
 
 ![TeleKit](https://github.com/Romashkaa/images/blob/main/TeleKitWide.png?raw=true)
 
-[![PyPi](https://img.shields.io/pypi/v/telekit.svg)](https://pypi.org/project/telekit/)
+[![PyPI](https://img.shields.io/pypi/v/telekit.svg)](https://pypi.org/project/telekit/)
 [![Python](https://img.shields.io/pypi/pyversions/telekit.svg)](https://pypi.org/project/telekit/)
-[![PyPi Downloads](https://static.pepy.tech/badge/telekit)](https://pepy.tech/project/telekit)
+[![PyPI Downloads](https://static.pepy.tech/badge/telekit)](https://pepy.tech/project/telekit)
 
 # Telekit
 
@@ -89,7 +89,7 @@ Even in its beta stage, Telekit accelerates bot development, offering typed comm
 - Fast to develop and easy-to-extend code
 
 [GitHub](https://github.com/Romashkaa/telekit)
-[PyPi](https://pypi.org/project/telekit/)
+[PyPI](https://pypi.org/project/telekit/)
 [Telegram](https://t.me/NotRomashka)
 [Community](https://t.me/+wu-dFrOBFIwyNzc0)
 
@@ -378,20 +378,55 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.1.0
+# Changes in version 2.2.0
 
-## Trigger Improvements
+## New Button Types
 
-| **Name** | **Description** |
-|----------|-----------------|
-| `on.text` | *BugFix:* Commands are no longer matched as text triggers. |
+| **Name**             | **Description**                                          |
+|----------------------|----------------------------------------------------------|
+| `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
+
+| **Name**               | **Description**                                           |
+| ---------------------- | --------------------------------------------------------- |
+| `bio`                  | Bio of the user or description of the chat.               |
+| `birthdate`            | Birthdate of the user, if set and visible.                |
+| `description`          | Description of the group or channel.                      |
+| `mention`              | `tg://user?id=` deep link, works even without a username. |
+| `is_private`           | Whether the message was sent in a private chat.           |
+| `is_group`             | Whether the message was sent in a group.                  |
+| `is_supergroup`        | Whether the message was sent in a supergroup.             |
+| `is_channel`           | Whether the message was sent in a channel.                |
+| `avatar`               | File ID of the user's most recent profile photo.          |
+| `profile_photos_count` | Total number of profile photos the user has set.          |
+
+- 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.
 
-- Internal refactor of the `On` class.
+## Chain Improvements
 
-## New Utils
+| **Name**    | **Description**                                              |
+| ----------- | ------------------------------------------------------------ |
+| `received`  | The message received from the user during entry processing.  |
 
+## Bug Fixes
 | **Name** | **Description** |
-|----------|-----------------|
-| `make_bot_link` | Builds a `t.me` URL to a bot with an optional deep-link payload. |
-| `make_user_link` | Builds a `t.me` URL to a user with an optional pre-filled message. |
-| `make_qrcode` | Generates a [QR code](./docs/examples/qr_gen.md) URL from any text or link. |
+| -------- | --------------- |
+| Media edit fallback | Fixed a bug where editing a text message with a new attachment (photo, audio, document, etc.) would only update the text, ignoring the attachment entirely. |
+| Callback answer order | Fixed a bug where `answer_callback_query` was not always displayed. |

{telekit-2.1.0 → telekit-2.2.0}/README.md

@@ -1,8 +1,8 @@
 ![TeleKit](https://github.com/Romashkaa/images/blob/main/TeleKitWide.png?raw=true)
 
-[![PyPi](https://img.shields.io/pypi/v/telekit.svg)](https://pypi.org/project/telekit/)
+[![PyPI](https://img.shields.io/pypi/v/telekit.svg)](https://pypi.org/project/telekit/)
 [![Python](https://img.shields.io/pypi/pyversions/telekit.svg)](https://pypi.org/project/telekit/)
-[![PyPi Downloads](https://static.pepy.tech/badge/telekit)](https://pepy.tech/project/telekit)
+[![PyPI Downloads](https://static.pepy.tech/badge/telekit)](https://pepy.tech/project/telekit)
 
 # Telekit
 
@@ -53,7 +53,7 @@ Even in its beta stage, Telekit accelerates bot development, offering typed comm
 - Fast to develop and easy-to-extend code
 
 [GitHub](https://github.com/Romashkaa/telekit)
-[PyPi](https://pypi.org/project/telekit/)
+[PyPI](https://pypi.org/project/telekit/)
 [Telegram](https://t.me/NotRomashka)
 [Community](https://t.me/+wu-dFrOBFIwyNzc0)
 

{telekit-2.1.0 → telekit-2.2.0}/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.1.0 → telekit-2.2.0}/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.1.0 → telekit-2.2.0}/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.1.0 → telekit-2.2.0}/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.1.0 → telekit-2.2.0}/telekit/_handler.py

@@ -98,7 +98,7 @@ class Handler:
 
     def __init__(self, message: Message):
         self.message: Message = message
-        self.user = User(self.message.chat.id, self.message.from_user)
+        self.user = User(self.message)
         self.new_chain()
 
     def handle(self) -> Any:
@@ -112,7 +112,7 @@ class Handler:
         avoids the need for multiple custom entry methods 
         like `start` or `handle_start`.
         """
-        library.warning("Handler `handle` was called but not overridden; no logic executed.")
+        library.warning(f"`{type(self).__qualname__}().handle()` was called but not overridden; no logic executed.")
         return
 
     # -----------------------------------------------------

{telekit-2.1.0 → telekit-2.2.0}/telekit/_inline_buttons.py

@@ -34,6 +34,9 @@ __all__ = [
     "SuggestButton",
     "CopyTextButton",
     "CallbackButton",
+    "AlertButton",
+    "NotificationButton",
+    "InvokeButton",
 
     "ButtonStyle"
 ]
@@ -54,6 +57,9 @@ class InlineButton:
     - `SuggestButton`
     - `CopyTextButton`
     - `CallbackButton`
+    - `AlertButton`
+    - `NotificationButton`
+    - `InvokeButton`
     """
 
     _bot: TeleBot
@@ -70,6 +76,9 @@ class InlineButton:
     Suggest: type["SuggestButton"]
     CopyText: type["CopyTextButton"]
     Callback: type["CallbackButton"]
+    Alert: type["AlertButton"]
+    Notification: type["NotificationButton"]
+    Invoke: type["InvokeButton"]
     
     Styles: type[ButtonStyle] = ButtonStyle
 
@@ -330,11 +339,11 @@ class CallbackButton(InlineButton):
 
         def __call__(self, call: CallbackQuery):
             self._invoke_chain_callback()
-            self._invoke_callback()
             self._answer_callback_query(call)
+            self._invoke_callback()
 
     def __init__(
-            self, 
+            self,
             callback: Callable[..., Any] | None, 
 
             pass_args: tuple | list | None = None, 
@@ -378,8 +387,234 @@ class CallbackButton(InlineButton):
             callback=callback,
         )
     
+class AlertButton(CallbackButton):
+    """
+    An inline keyboard button that shows a popup alert when pressed and terminates the chain.
+
+    When the user presses this button, the specified text is displayed as a modal alert dialog.
+    The chain is finalized: all other buttons in the message become inactive and no further
+    interaction is expected. Typically used as a session-ending buttons.
+
+    :param text: Text to display in the alert popup.
+    :type text: `str | None`
+
+    :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::
+
+        def entry_word(self) -> None:
+            self.chain.sender.set_title("✏️ Add a new word")
+            self.chain.sender.set_message("Type the word you want to save to your dictionary:")
+            self.chain.set_inline_keyboard({
+                "✕ Cancel": AlertButton(text="Cancelled")
+            })
+            self.chain.set_entry_text(
+                self.entry_translation,
+                delete_user_response=True,
+            )
+            self.chain.edit()
+    """
+    def __init__(
+            self,
+            text: str | None = None,
+            *,
+            style: str | None | ButtonStyle = None,
+            **kwargs
+        ):
+        super().__init__(
+            callback=None,
+            answer_text=text,
+            answer_as_alert=True,
+            style=style,
+            **kwargs
+        )
+
+class NotificationButton(CallbackButton):
+    """
+    An inline keyboard button that shows a brief notification at the top of the chat screen
+    when pressed and terminates the chain.
+
+    When the user presses this button, the specified text appears as a short non-blocking
+    notification. The chain is finalized: all other buttons in the message become inactive
+    and no further interaction is expected. Typically used as a session-ending buttons.
+
+    :param text: Text to display in the notification.
+    :type text: `str | None`
+
+    :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::
+
+        def entry_word(self) -> None:
+            self.chain.sender.set_title("✏️ Add a new word")
+            self.chain.sender.set_message("Type the word you want to save to your dictionary:")
+            self.chain.set_inline_keyboard({
+                "✕ Cancel": NotificationButton(text="Cancelled")
+            })
+            self.chain.set_entry_text(
+                self.entry_translation,
+                delete_user_response=True,
+            )
+            self.chain.edit()
+    """
+    def __init__(
+            self,
+            text: str | None = None,
+            *,
+            style: str | None | ButtonStyle = None,
+            **kwargs
+        ):
+        super().__init__(
+            callback=None,
+            answer_text=text,
+            answer_as_alert=False,
+            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
 InlineButton.Suggest = SuggestButton
 InlineButton.CopyText = CopyTextButton
-InlineButton.Callback = CallbackButton
+InlineButton.Callback = CallbackButton
+InlineButton.Alert = AlertButton
+InlineButton.Notification = NotificationButton
+InlineButton.Invoke = InvokeButton