telekit 2.2.0a1__tar.gz → 2.2.0a3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a1
+Version: 2.2.0a3
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -378,15 +378,49 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a1
+# Changes in version 2.2.0a3
 
 ## New Button Types
 
-| **Name** | **Description** |
-|----------|-----------------|
-| `AlertButton` | A callback button that shows a popup alert when pressed. |
-| `NotificationButton` | A callback button that shows a brief notification at the top of the chat screen. |
-
-## User 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.
+| **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.
+
+## Chain Improvements
+
+| **Name**    | **Description**                                              |
+| ----------- | ------------------------------------------------------------ |
+| `received`  | The message received from the user during entry processing.  |

{telekit-2.2.0a1 → 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.0a1 → 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.0a1 → 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.0a1 → 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.0a1 → 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.0a1 → 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.0a3/telekit/_user.py

@@ -0,0 +1,199 @@
+# 
+# Copyright (C) 2026 Romashka
+# 
+# This file is part of Telekit.
+# 
+# Telekit is free software: you can redistribute it and/or modify it 
+# under the terms of the GNU General Public License as published by 
+# the Free Software Foundation, either version 3 of the License, or 
+# (at your option) any later version.
+# 
+# Telekit is distributed in the hope that it will be useful, 
+# but WITHOUT ANY WARRANTY; without even the implied warranty 
+# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See 
+# the GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License 
+# along with Telekit. If not, see <https://www.gnu.org/licenses/>.
+# 
+from functools import cached_property
+from typing import Literal
+
+import telebot
+import telebot.types
+
+from ._logger import logger
+
+__all__ = ["User"]
+
+
+class User:
+
+    bot: telebot.TeleBot
+
+    @classmethod
+    def _init(cls, bot: telebot.TeleBot) -> None:
+        cls.bot = bot
+
+    def __init__(self, message: telebot.types.Message) -> None:
+        self._message: telebot.types.Message = message
+        self._chat_id: int = message.chat.id
+        self.logger = logger.users(self._chat_id)
+
+    # ── Internal ──────────────────────────────────────────────────
+
+    @cached_property
+    def _sender(self) -> telebot.types.User | telebot.types.Chat:
+        """Resolves to `from_user` if available, otherwise falls back to `chat`."""
+        return self._message.from_user or self._message.chat
+
+    # ── Logging ───────────────────────────────────────────────────
+
+    def enable_logging(self, *user_ids: int | str) -> None:
+        """
+        Enable logging for this user or for additional user IDs.
+        If no arguments are passed, enables logging for this instance's chat ID.
+        """
+        logger.enable_user_logging(*(user_ids or (self._chat_id,)))
+
+    # ── Telegram native fields ────────────────────────────────────
+
+    @property
+    def id(self) -> int:
+        """Unique identifier of the user or chat."""
+        return self._sender.id
+
+    @property
+    def username(self) -> str | None:
+        """Telegram username without the leading `@`, or `None` if not set."""
+        return self._sender.username
+
+    @cached_property
+    def first_name(self) -> str | None:
+        """First name of the user, or the group/channel title as a fallback."""
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.first_name
+        return self._sender.first_name or self._sender.title
+
+    @property
+    def last_name(self) -> str | None:
+        """Last name of the user, or `None` for chats and users without one."""
+        return self._sender.last_name
+
+    @cached_property
+    def is_bot(self) -> bool:
+        """Whether the sender is a bot. Always `False` for chats."""
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.is_bot
+        return False
+
+    @cached_property
+    def language_code(self) -> str | None:
+        """
+        IETF language code of the user's Telegram client (e.g. `"en"`, `"uk"`).
+        Always `None` for chats.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.language_code
+        return None
+
+    @cached_property
+    def is_premium(self) -> bool:
+        """Whether the user has an active Telegram Premium subscription.
+        Always `False` for chats and bots.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return bool(self._sender.is_premium)
+        return False
+
+    @cached_property
+    def added_to_attachment_menu(self) -> bool:
+        """Whether this bot has been added to the user's attachment menu.
+        Always `False` for chats.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return bool(self._sender.added_to_attachment_menu)
+        return False
+
+    @property
+    def chat_type(self) -> Literal["private", "group", "supergroup", "channel"]:
+        """Type of the chat the message was sent in."""
+        return self._message.chat.type  # pyright: ignore[reportReturnType]
+
+    @property
+    def bio(self) -> str | None:
+        """Bio of the user or description of the chat, as set in Telegram."""
+        return self._message.chat.bio
+
+    @property
+    def birthdate(self) -> telebot.types.Birthdate | None:
+        """Birthdate of the user, if set and visible."""
+        return self._message.chat.birthdate
+
+    @property
+    def description(self) -> str | None:
+        """Description of the group or channel. `None` for private chats."""
+        return self._message.chat.description
+
+    # ── Computed helpers ──────────────────────────────────────────
+
+    @cached_property
+    def full_name(self) -> str | None:
+        """Full name of the user (`first_name + last_name`), or the chat title.
+        Returns `None` if neither is available.
+        """
+        if isinstance(self._sender, telebot.types.User):
+            return self._sender.full_name
+        return " ".join(filter(None, [self.first_name, self.last_name])) or None
+
+    @property
+    def mention(self) -> str:
+        """
+        A `tg://user?id=` deep link that mentions the user in any context,
+        even without a username.
+        """
+        return f"tg://user?id={self.id}"
+
+    @property
+    def is_private(self) -> bool:
+        """Whether the message was sent in a private chat."""
+        return self.chat_type == "private"
+
+    @property
+    def is_group(self) -> bool:
+        """Whether the message was sent in a group chat."""
+        return self.chat_type == "group"
+
+    @property
+    def is_supergroup(self) -> bool:
+        """Whether the message was sent in a supergroup."""
+        return self.chat_type == "supergroup"
+
+    @property
+    def is_channel(self) -> bool:
+        """Whether the message was sent in a channel."""
+        return self.chat_type == "channel"
+
+    @property
+    def avatar(self) -> str | None:
+        """
+        File ID of the user's most recent profile photo, or `None` if not set.
+        Makes an API call each time — cache the result if called frequently.
+        """
+        photos = self.bot.get_user_profile_photos(self.id, limit=1)
+        if photos.total_count == 0:
+            return None
+        return photos.photos[0].file_id
+
+    @property
+    def profile_photos_count(self) -> int:
+        """
+        Total number of profile photos the user has set.
+        Makes an API call each time.
+        """
+        return self.bot.get_user_profile_photos(self.id).total_count
+
+    # ── Dunder ────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        return f"User(id={self.id}, username={self.username!r})"

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

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

{telekit-2.2.0a1 → telekit-2.2.0a3}/telekit/example/example_handlers/entry.py

@@ -63,9 +63,7 @@ class EntryHandler(telekit.Handler):
         # Priority:
         # 1. Previous response (internal database)
         # 2. Telegram username (fallback)
-        name: str | None = self._user_data.get_name(
-            default=self.user.username
-        )
+        name: str | None = self._user_data.get_name() or self.user.username
         
         if name:
             self.chain.set_entry_suggestions([name])