telekit 2.2.0a3__tar.gz → 2.3.0b1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a3
+Version: 2.3.0b1
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -101,7 +101,8 @@ Even in its beta stage, Telekit accelerates bot development, offering typed comm
     - [Dialogue](https://github.com/Romashkaa/telekit/blob/main/docs/examples/dialogue.md)
     - [Risk Game](https://github.com/Romashkaa/telekit/blob/main/docs/examples/risk_game.md)
     - [Counter](https://github.com/Romashkaa/telekit/blob/main/docs/examples/counter.md)
-    - [Quiz (Telekit DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Quiz (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Hotel (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
     - [More...](https://github.com/Romashkaa/telekit/blob/main/docs/examples/examples.md)
 
 ## Overview
@@ -378,49 +379,86 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a3
+# Changes in version 2.3.0b1
 
-## New Button Types
+## Traits
 
-| **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.          |
+| **Name**                   | **Description**                                                       |
+| -------------------------- | --------------------------------------------------------------------- |
+| `TrackHandoffOrigin`  | Tracks which handler transferred control to this one via `handoff()`.      |
+| `PaginatedChoice`    | Adds a paginated inline keyboard for choosing from a list of items.        |
 
-## User Improvements
+### TrackHandoffOrigin
 
-| **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.          |
+`TrackHandoffOrigin` adds three members to any handler that inherits it:
 
-- 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__`.
+| **Member**          | **Description**                                                                  |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `handoff_origin`    | The handler instance that handed off to this one, or `None` if invoked directly. |
+| `is_handed_off`     | `True` if this handler was reached via `handoff()`, `False` otherwise.           |
+| `handoff_back()`    | Transfer control back to the origin handler via `self.handoff_origin.handle()`   |
+| `handoff_back_or(handler)` | Like `handoff_back()`, but falls back to `handler` on fail.               |
 
-## Sender Improvements
+Set `TRACK_HANDOFF_ORIGIN = False` on any subclass to opt out of tracking.
 
-| **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.    |
+```python
+class MyHandler(TrackHandoffOrigin, telekit.Handler):
+
+    def handle(self):
+        ...
+        self.chain.set_inline_keyboard({
+            "« Back": self.handoff_back_or(StartHandler)
+        })
+        self.chain.edit()
+```
+
+### PaginatedChoice
 
-- Refactored sending system.
+Renders a paginated inline keyboard from any dict or iterable.
+Navigation buttons (`« Back`, `Next »`) are added automatically.
 
-## Chain Improvements
+| **Member**           | **Description**                                                              |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `paginated_choice(choices, on_choice, on_update, row_width)` | Display a paginated choice keyboard. |
 
-| **Name**    | **Description**                                              |
-| ----------- | ------------------------------------------------------------ |
-| `received`  | The message received from the user during entry processing.  |
+```python
+self.chain.sender.set_title("🔤 What is your initial?")
+self.chain.sender.set_message("Pick the first letter of your name")
+self.chain.sender.set_remove_text(False)
+
+self.paginated_choice(
+    choices="ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    on_choice=self.handle_letter,
+    row_width=5
+)
+```
+
+<details>
+  <summary>(Click to see the result)</summary>
+  <table>
+    <tr>
+      <td><img src="https://github.com/Romashkaa/telekit/blob/main/docs/images/paginated_choice.png?raw=true" alt="Example" width="300"></td>
+    </tr>
+  </table>
+</details>
+
+`choices` accepts a `dict[str, T]`, or any `Iterable[T]`.
+If only one item is present, `on_choice` is called immediately without rendering a keyboard.
+
+## Utils
+
+| **Name**         | **Description**                                                    |
+| ---------------- | ------------------------------------------------------------------ |
+| `load_env`       | Load all key-value pairs from a `.env` file into a dictionary.     |
+| `read_env_var`   | Read a single variable by name from a `.env` file.                 |
+
+- `read_token` and `read_canvas_path` now support reading from `.env` files.
+  Pass `".env"` to use the default key, or `".env:KEY"` to specify a custom one:
+
+```python
+read_token(".env")                 # reads TOKEN
+read_token(".env:BOT_TOKEN")       # reads BOT_TOKEN
+
+read_canvas_path(".env")           # reads CANVAS_PATH
+read_canvas_path(".env:MY_CANVAS") # reads MY_CANVAS
+```

{telekit-2.2.0a3 → telekit-2.3.0b1}/README.md

@@ -65,7 +65,8 @@ Even in its beta stage, Telekit accelerates bot development, offering typed comm
     - [Dialogue](https://github.com/Romashkaa/telekit/blob/main/docs/examples/dialogue.md)
     - [Risk Game](https://github.com/Romashkaa/telekit/blob/main/docs/examples/risk_game.md)
     - [Counter](https://github.com/Romashkaa/telekit/blob/main/docs/examples/counter.md)
-    - [Quiz (Telekit DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Quiz (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Hotel (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
     - [More...](https://github.com/Romashkaa/telekit/blob/main/docs/examples/examples.md)
 
 ## Overview

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/__init__.py

@@ -35,12 +35,14 @@ from . import parameters
 from . import inline_buttons
 from . import dices
 from . import utils
+from . import traits
 
 Styles = styles.Styles
 
 from ._version import __version__
     
 __all__ = [
+    "traits",
     "utils",
     "senders", 
     "types",

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/_handler.py

@@ -225,9 +225,16 @@ class Handler:
         
         handler_instance = handler(self.message)
         handler_instance.chain._set_previous_message(self.chain.get_previous_message())
+        handler_instance._on_handoff(self)
         
         return handler_instance
     
+
+    def _on_handoff(self, origin: "Handler") -> None:
+        """Called when this handler is reached via handoff(). Override to customize."""
+        pass
+    
+
     def freeze(self, func, *args):
         """
         Return a zero-argument callback that invokes the given function

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/_inline_buttons.py

@@ -339,8 +339,8 @@ 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,

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/_version.py

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

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

@@ -44,8 +44,12 @@ class EntryHandler(telekit.Handler):
     # Handling Logic
     # ------------------------------------------
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self._user_data = UserData(self.user.id)
+
     def handle(self) -> None:
-        self._user_data = UserData(self.message.chat.id)
         self.chain.disable_timeout_warnings()
         self.entry_name()
 

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/example/example_handlers/text_document.py

@@ -1,11 +1,10 @@
-from telebot.types import Message
 from telekit.types import (
     TextDocument, CopyTextButton, ParseMode
 )
 from telekit.styles import Quote, Escape
 import telekit
     
-class TextDocumentHandler(telekit.Handler):
+class TextDocumentHandler(telekit.traits.TrackHandoffOrigin, telekit.Handler):
 
     @classmethod
     def init_handler(cls) -> None:
@@ -26,6 +25,11 @@ class TextDocumentHandler(telekit.Handler):
             self.handle_text_document,
             allowed_extensions=(".txt", ".py", ".md", ".html")
         )
+        self.chain.set_inline_keyboard(
+            {
+                "« Back": self.handoff_back_or("StartHandler")
+            }
+        )
 
         self.chain.disable_timeout_warnings()
         self.chain.edit()

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/senders.py

@@ -17,7 +17,7 @@
 # along with Telekit. If not, see <https://www.gnu.org/licenses/>.
 # 
 
-from typing import Any, Literal
+from typing import Any, Literal, NoReturn
 import textwrap
 import io
 
@@ -27,7 +27,7 @@ from telebot.types import (
     ReplyParameters, LinkPreviewOptions,
     InputMediaPhoto, InputFile, 
     InputMediaAudio, InputMediaDocument, 
-    InputMediaVideo,
+    InputMediaVideo, InputMediaAnimation
 )
 
 from telekit.styles import TextEntity, Escape, Raw, Group, Bold, Italic
@@ -90,6 +90,9 @@ class TempMessageStore:
 # Base Sender
 # ---------------------------------------------------------------------------------
 
+class _FallbackToSend(Exception):
+    """Raised when editing is not supported — silently falls back to delete + send."""
+
 class BaseSender:
 
     bot: TeleBot
@@ -109,6 +112,15 @@ class BaseSender:
 
     parse_mode: Literal["html", "markdown"] | None
 
+    def _get_parse_mode(self):
+        match self.parse_mode:
+            case "html":
+                return "HTML"
+            case "markdown":
+                return "MarkdownV2"
+            case _:
+                return None
+
     def __init__(
             self,
             chat_id: int,
@@ -872,6 +884,25 @@ class BaseSender:
     # Internal send dispatcher
     # --------------------------------------------------------
 
+    def _edit_or_send(self) -> tuple[Message | None, bool]:
+        if self.edit_message_id:
+
+            try:
+                return self._edit(), True
+            except _FallbackToSend:
+                # silently delete and resend
+                self._delete_message(self.edit_message_id)
+            except Exception as exception:
+                if "Bad Request: there is no text in the message to edit" not in str(exception):
+                    library.warning(f"Failed to edit message {self.edit_message_id}, sending new one instead. Exception: {exception}")
+                self._delete_message(self.edit_message_id)
+        
+        return self._send(), False
+    
+    # --------------------------------------------------------
+    # Internal methods for sending messages
+    # --------------------------------------------------------
+
     def _send(self) -> Message | None:
         if self.photo:
             message = self._send_photo()
@@ -982,40 +1013,33 @@ class BaseSender:
         )
     
     # --------------------------------------------------------
-    # Internal methods for sending and editing messages
+    # Internal methods for editing messages
     # --------------------------------------------------------
 
-    def _get_parse_mode(self):
-        match self.parse_mode:
-            case "html":
-                return "HTML"
-            case "markdown":
-                return "MarkdownV2"
-            case _:
-                return None
-
     def _edit(self) -> Message | None:
         if not self.edit_message_id:
             raise ValueError("edit_message_id is None: Unable to edit message without a valid message ID.")
-        
-        configs = self._get_edit_params()
-        
+
         if self.photo:
-            media = InputMediaPhoto(
-                media=self.photo, 
-                caption=self.text, 
-                parse_mode=self._get_parse_mode()
-            )
-            message = self.bot.edit_message_media(
-                media=media,
-                **configs
-            )
+            message = self._edit_photo()
+        elif self.document:
+            message = self._edit_document()
+        elif self.video:
+            message = self._edit_video()
+        elif self.animation:
+            message = self._edit_animation()
+        elif self.audio:
+            message = self._edit_audio()
+        elif self.voice:
+            message = self._edit_voice()
+        elif self.video_note:
+            message = self._edit_video_note()
+        elif self.venue:
+            message = self._edit_venue()
+        elif self.media:
+            message = self._edit_media()
         else:
-            message = self.bot.edit_message_text(
-                text=self.text,
-                parse_mode=self._get_parse_mode(),
-                **configs
-            )
+            message = self._edit_text()
 
         self._reset_after_send()
 
@@ -1023,17 +1047,84 @@ class BaseSender:
             self.sent_message = message
             return message
 
-    def _edit_or_send(self) -> tuple[Message | None, bool]:
-        if self.edit_message_id:
+    def _edit_text(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+        return self.bot.edit_message_text(
+            text=self.text,
+            parse_mode=self._get_parse_mode(),
+            link_preview_options=self.link_preview_options,
+            **configs,
+        )
 
-            try:
-                return self._edit(), True
-            except Exception as exception:
-                if "Bad Request: there is no text in the message to edit" not in str(exception):
-                    library.warning(f"Failed to edit message {self.edit_message_id}, sending new one instead. Exception: {exception}")
-                self._delete_message(self.edit_message_id)
-        
-        return self._send(), False
+    def _edit_document(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+        media = InputMediaDocument(
+            media=self.document,
+            caption=self.text,
+            parse_mode=self._get_parse_mode(),
+        )
+        return self.bot.edit_message_media(media=media, **configs)
+
+    def _edit_video(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+        media = InputMediaVideo(
+            media=self.video,
+            caption=self.text,
+            show_caption_above_media=self.show_caption_above_media,
+            parse_mode=self._get_parse_mode(),
+        )
+        return self.bot.edit_message_media(media=media, **configs)
+
+    def _edit_animation(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+        media = InputMediaAnimation(
+            media=self.animation,
+            caption=self.text,
+            show_caption_above_media=self.show_caption_above_media,
+            parse_mode=self._get_parse_mode(),
+        )
+        return self.bot.edit_message_media(media=media, **configs)
+
+    def _edit_audio(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+        media = InputMediaAudio(
+            media=self.audio,
+            caption=self.text,
+            performer=self.audio_performer,
+            title=self.audio_title,
+            parse_mode=self._get_parse_mode(),
+        )
+        return self.bot.edit_message_media(media=media, **configs)
+    
+    def _edit_photo(self) -> Message | bool:
+        configs: dict = self._get_edit_params()
+
+        media = InputMediaPhoto(
+            media=self.photo, 
+            caption=self.text, 
+            show_caption_above_media=self.show_caption_above_media,
+            parse_mode=self._get_parse_mode()
+        )
+        return self.bot.edit_message_media(
+            media=media,
+            **configs
+        )
+
+    def _edit_voice(self) -> NoReturn:
+        # Voice messages cannot be edited.
+        raise _FallbackToSend() # fallback to _edit_or_send
+
+    def _edit_video_note(self) -> NoReturn:
+        # Video notes cannot be edited.
+        raise _FallbackToSend() # fallback to _edit_or_send
+
+    def _edit_venue(self) -> NoReturn:
+        # Venues cannot be edited.
+        raise _FallbackToSend() # fallback to _edit_or_send
+
+    def _edit_media(self) -> NoReturn:
+        # Media groups cannot be edited.
+        raise _FallbackToSend() # fallback to _edit_or_send
     
     # --------------------------------------------------------
     # Methods for deleting messages

telekit-2.3.0b1/telekit/traits/__init__.py

@@ -0,0 +1,2 @@
+from .track_handoff_origin import TrackHandoffOrigin
+from .paginated_choice import PaginatedChoice

telekit-2.3.0b1/telekit/traits/paginated_choice.py

@@ -0,0 +1,109 @@
+from typing import Callable, Any, Iterable
+
+import telekit
+from dataclasses import dataclass
+
+@dataclass
+class _NavButton:
+    start_index: int
+
+class PaginatedChoice(telekit.Handler):
+
+    # ── entry point ───────────────────────────────────────────────
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def paginated_choice[T](self, choices: dict[str, T] | Iterable[T], on_choice: Callable[[T], Any], on_update: Callable[[], Any] | None = None, row_width: int = 1, page_size: int = 10) -> None:
+        """
+        Display a paginated inline keyboard for choosing from a list of items.
+
+        Navigation buttons (``« Back``, ``Next »``) are added automatically
+        when the item count exceeds ``page_size``. If only one item is present,
+        ``on_choice`` is called immediately without rendering a keyboard.
+
+        :param choices: Items to display. Accepts a ``dict[str, T]`` (label: value),
+                        or any ``Iterable[T]``.
+        :type choices: ``dict[str, T] | Iterable[T]``
+        :param on_choice: Callback invoked with the selected value.
+        :type on_choice: ``Callable[[T], Any]``
+        :param on_update: Optional callback invoked before each page render.
+                        Useful for updating entry text.
+        :type on_update: ``Callable[[], Any] | None``
+        :param row_width: Number of choice buttons per row. Defaults to ``1``.
+        :type row_width: ``int``
+        :param page_size: Maximum number of items per page. Defaults to ``10``.
+        :type page_size: ``int``
+
+        Example::
+
+            self.paginated_choice(
+                choices="ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+                on_choice=self.handle_letter,
+                on_update=lambda: self.chain.set_entry_text(self.handle_letter),
+                row_width=5,
+            )
+        """
+        if isinstance(choices, dict):
+            _choices: dict[str, T] = choices.copy() # pyright: ignore[reportAssignmentType]
+        else:
+            _choices: dict[str, T] = {str(c): c for c in choices}
+
+        if len(_choices) == 1:
+            on_choice(next(iter(_choices.values())))
+            return
+        
+        self._paginated_choice(0, _choices, on_choice, on_update, row_width, page_size)
+
+    def _paginated_choice[T](self, start: int, choices: dict[str, T], on_choice: Callable[[T], Any], on_update: Callable[[], Any] | None, row_width: int, page_size: int) -> None:
+        total = len(choices)
+        
+        page  = start // page_size + 1
+        pages = (total + page_size - 1) // page_size
+        page_items = list(choices.items())[start : start + page_size]
+
+        if on_update is not None:
+            on_update()
+
+        keyboard: dict[str, T | _NavButton] = {}
+        keyboard.update(page_items)
+
+        # navigation row
+        has_back = start - page_size >= 0
+        has_next = start + page_size < total
+
+        nav: dict[str, T | _NavButton] = {}
+
+        if has_back:
+            nav["« Back"] = _NavButton(start - page_size)
+        if has_back and has_next:
+            nav[f"({page}/{pages})" ] = _NavButton(start)
+        if has_next:
+            nav["Next »"] = _NavButton(start + page_size)
+
+        # each choice on its own row, nav row at the end
+        choices_count  = len(keyboard)
+        nav_count      = len(nav)
+        
+        full_rows = choices_count // row_width
+        remainder = choices_count % row_width
+
+        if remainder > 0:
+            _row_width = (*([row_width] * full_rows), remainder, nav_count)
+        else:
+            _row_width = (*([row_width] * full_rows), nav_count)
+
+        keyboard.update(nav)
+
+        def _on_choice(choice: T | _NavButton):
+            if isinstance(choice, _NavButton):
+                self._paginated_choice(choice.start_index, choices, on_choice, on_update, row_width, page_size)
+            else:
+                on_choice(choice)
+
+        self.chain.set_inline_choice(
+            _on_choice,
+            keyboard,
+            row_width=_row_width,
+        )
+        self.chain.edit()

telekit-2.3.0b1/telekit/traits/track_handoff_origin.py

@@ -0,0 +1,99 @@
+from typing import Callable
+
+import telekit
+
+class TrackHandoffOrigin(telekit.Handler):
+
+    TRACK_HANDOFF_ORIGIN: bool = True
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.handoff_origin: telekit.Handler | None = None
+
+    def _on_handoff(self, origin: telekit.Handler) -> None:
+        """
+        Called when this handler is reached via :meth:`handoff`.
+        Override to customize handoff behaviour.
+        """
+        if self.TRACK_HANDOFF_ORIGIN:
+            self.handoff_origin = origin
+
+        super()._on_handoff(origin)
+
+    @property
+    def is_handed_off(self) -> bool:
+        """
+        Whether this handler was reached via :meth:`handoff`.
+
+        - ``True`` if a previous handler transferred control here,
+        - ``False`` if this handler was invoked directly.
+        """
+        return self.handoff_origin is not None
+    
+    def handoff_back(self, *args, **kwargs):
+        """
+        Transfer control back to the handler that handed off to this one.
+
+        Useful for implementing "« Back" buttons without hardcoding the
+        previous handler class:
+
+        .. code-block:: python
+            self.chain.set_inline_keyboard({
+                "« Back": self.handoff_back
+            })
+
+        Any positional or keyword arguments are forwarded directly to
+        ``handoff_origin.handle()``:
+
+        .. code-block:: python
+            self.handoff_back("some_arg", key="value")
+            # equivalent to: handoff_origin.handle("some_arg", key="value")
+
+
+        :raises RuntimeError: If this handler was not reached via :meth:`handoff`
+                            (i.e. ``handoff_origin`` is ``None``).
+        """
+        if self.handoff_origin is None:
+            raise RuntimeError(
+                f"{type(self).__name__}().handoff_back() called, but this handler "
+                "was not reached via handoff() - handoff_origin is None."
+            )
+        
+        self.handoff_origin.chain._set_previous_message(self.chain.get_previous_message())
+        self.handoff_origin.handle(*args, **kwargs)
+
+    def handoff_back_or(self, handler: type[telekit.Handler] | str) -> Callable[..., None]:
+        """
+        Return a callable that transfers control back to the origin handler,
+        or falls back to ``handler`` if this handler was invoked directly.
+
+        Useful for ``« Back`` buttons in handlers that can be reached both
+        via :meth:`handoff` and directly:
+
+        .. code-block:: python
+            self.chain.set_inline_keyboard({
+                "« Back": self.handoff_back_or(StartHandler)
+            })
+
+        Any positional or keyword arguments passed to the returned callable
+        are forwarded to ``handle()`` of whichever handler is invoked:
+
+        .. code-block:: python
+            back = self.handoff_back_or(StartHandler)
+            back("some_arg", key="value")
+            # if handed off:  handoff_origin.handle("some_arg", key="value")
+            # if direct:      StartHandler.handle("some_arg", key="value")
+
+        :param handler: Fallback handler class (or name) to transfer control to when
+                        ``handoff_origin`` is ``None``.
+        :type handler: ``type[Handler]`` | ``str``
+        :return: A zero-argument callable that performs the handoff.
+        :rtype: ``Callable[..., None]``
+        """
+        def handoff_invoker(*args, **kwargs):
+            if self.handoff_origin is None:
+                self.handoff(handler).handle(*args, **kwargs)
+            else:
+                self.handoff_back(*args, **kwargs)
+                    
+        return handoff_invoker

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit/utils.py

@@ -1,3 +1,4 @@
+import os
 import re
 
 from pathlib import Path
@@ -6,6 +7,10 @@ from typing import Literal
 
 ROOT_DIR = Path(__file__).resolve().parent  # telekit/
 
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Checks
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
 def is_valid_callback_data(callback_data: str) -> bool:
     """
     Check whether a callback data string is valid for Telegram inline buttons.
@@ -31,6 +36,9 @@ def is_valid_callback_data(callback_data: str) -> bool:
     byte_size = len(callback_data.encode('utf-8'))
     return 1 <= byte_size <= 64
 
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Formatting
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
 def format_file_size(size: int, precision: int = 1) -> str:
     """
@@ -105,46 +113,140 @@ def format_file_size(size: int, precision: int = 1) -> str:
 
     return f"{formatted} {units[index]}"
 
-def read_token(path: str = "token.txt") -> str:
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Environment
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+def _split_env_path(path: str, default: str) -> tuple[str, str]:
+    if ":" in path:
+        path, name = path.split(":", 1)
+    else:
+        path, name = path, default
+
+    return path, name
+
+
+def load_env(path=".env") -> dict[str, str]:
+    """
+    Load all key-value pairs from a ``.env`` file.
+
+    Lines starting with ``#`` and empty lines are ignored.
+
+    :param path: Path to the ``.env`` file. Defaults to ``".env"``.
+    :type path: ``str``
+    :return: Dictionary of all key-value pairs found in the file,
+             or an empty dict if the file does not exist.
+    :rtype: ``dict[str, str]``
+    """
+    if not os.path.exists(path):
+        return {}
+    
+    env: dict[str, str] = {}
+        
+    with open(path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            
+            key, value = line.split("=", 1)
+            env[key.strip()] = value.strip()
+
+    return env
+
+
+def read_envar(path: str, name: str) -> str:
+    """
+    Read a single environment variable from a ``.env`` file.
+
+    :param path: Path to the ``.env`` file.
+    :type path: ``str``
+    :param name: Name of the key to read.
+    :type name: ``str``
+    :return: Value of the key.
+    :rtype: ``str``
+    :raises KeyError: If ``name`` is not found in the file.
     """
-    Read the bot token from a file.
+    env: dict[str, str] = load_env(path)
 
-    Reads only the first line, so multiple tokens can be stored in the file
-    and swapped quickly by reordering lines — no need to delete or copy.
+    if name not in env:
+        raise KeyError(f"{name} not found in {path}")
 
-    Inline comments are supported — everything after the first whitespace
-    is ignored::
+    return env[name]
 
+
+def read_token(path: str = "token.txt") -> str:
+    """
+    Read the bot token from a file or ``.env``.
+
+    **Plain text file** (default)::
+
+        # token.txt
         123456789:BotSecretToken  Main production bot
         987654321:AnotherToken    Backup bot
 
-    :param path: Path to the token file
+    Reads only the first line. Inline comments (everything after the first
+    whitespace) are ignored. Multiple tokens can be stored and swapped by
+    reordering lines.
+
+    **Environment file** (``.env``)::
+
+        read_token(".env")          # reads the key named TOKEN
+        read_token(".env:TOKEN")    # same, explicit key
+        read_token(".env:BOT_KEY")  # reads a custom key
+
+    :param path: Path to a token file, or ``".env"`` / ``".env:KEY"`` for
+                 environment files. Defaults to ``"token.txt"``.
     :type path: ``str``
-    :return: Bot token string
+    :return: Bot token string.
     :rtype: ``str``
+    :raises KeyError: If the key is not found in the ``.env`` file.
+    :raises FileNotFoundError: If the file does not exist.
     """
+    if path.endswith(".env") or ".env:" in path:
+        return read_envar(*_split_env_path(path, "TOKEN"))
+    
     with open(path) as f:
         first_line: str = f.readline().strip()
         token, *_ = first_line.split()
         return token
+    
 
 def read_canvas_path(path: str = "canvas_path.txt") -> str:
     """
-    Read the ``.canvas`` file path from a file.
+    Read the ``.canvas`` file path from a file or ``.env``.
+
+    **Plain text file** (default)::
 
-    Reads only the first line, so multiple pathes can be stored in the file
-    and swapped quickly by reordering lines — no need to delete or copy.
+        # canvas_path.txt
+        /home/user/project/main.canvas  Production canvas
+        /home/user/project/test.canvas  Test canvas
 
-    :param path: Path to the file containing the canvas path
+    Reads only the first line. Multiple paths can be stored and swapped by
+    reordering lines.
+
+    **Environment file** (``.env``)::
+
+        read_canvas_path(".env")               # reads the key named CANVAS_PATH
+        read_canvas_path(".env:CANVAS_PATH")   # same, explicit key
+        read_canvas_path(".env:MY_CANVAS")     # reads a custom key
+
+    :param path: Path to a canvas path file, or ``".env"`` / ``".env:KEY"`` for
+                 environment files. Defaults to ``"canvas_path.txt"``.
     :type path: ``str``
-    :return: Path to the ``.canvas`` file
+    :return: Path to the ``.canvas`` file.
     :rtype: ``str``
+    :raises KeyError: If the key is not found in the ``.env`` file.
+    :raises FileNotFoundError: If the file does not exist.
     """
+    if path.endswith(".env") or ".env:" in path:
+        return read_envar(*_split_env_path(path, "CANVAS_PATH"))
+    
     with open(path) as f:
         return f.readline().strip()
     
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
-# Link Generators
+# Link Generating
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
 def make_bot_link(botname: str, start: str | None = None) -> str:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a3
+Version: 2.3.0b1
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -101,7 +101,8 @@ Even in its beta stage, Telekit accelerates bot development, offering typed comm
     - [Dialogue](https://github.com/Romashkaa/telekit/blob/main/docs/examples/dialogue.md)
     - [Risk Game](https://github.com/Romashkaa/telekit/blob/main/docs/examples/risk_game.md)
     - [Counter](https://github.com/Romashkaa/telekit/blob/main/docs/examples/counter.md)
-    - [Quiz (Telekit DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Quiz (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+    - [Hotel (DSL)](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
     - [More...](https://github.com/Romashkaa/telekit/blob/main/docs/examples/examples.md)
 
 ## Overview
@@ -378,49 +379,86 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a3
+# Changes in version 2.3.0b1
 
-## New Button Types
+## Traits
 
-| **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.          |
+| **Name**                   | **Description**                                                       |
+| -------------------------- | --------------------------------------------------------------------- |
+| `TrackHandoffOrigin`  | Tracks which handler transferred control to this one via `handoff()`.      |
+| `PaginatedChoice`    | Adds a paginated inline keyboard for choosing from a list of items.        |
 
-## User Improvements
+### TrackHandoffOrigin
 
-| **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.          |
+`TrackHandoffOrigin` adds three members to any handler that inherits it:
 
-- 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__`.
+| **Member**          | **Description**                                                                  |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `handoff_origin`    | The handler instance that handed off to this one, or `None` if invoked directly. |
+| `is_handed_off`     | `True` if this handler was reached via `handoff()`, `False` otherwise.           |
+| `handoff_back()`    | Transfer control back to the origin handler via `self.handoff_origin.handle()`   |
+| `handoff_back_or(handler)` | Like `handoff_back()`, but falls back to `handler` on fail.               |
 
-## Sender Improvements
+Set `TRACK_HANDOFF_ORIGIN = False` on any subclass to opt out of tracking.
 
-| **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.    |
+```python
+class MyHandler(TrackHandoffOrigin, telekit.Handler):
+
+    def handle(self):
+        ...
+        self.chain.set_inline_keyboard({
+            "« Back": self.handoff_back_or(StartHandler)
+        })
+        self.chain.edit()
+```
+
+### PaginatedChoice
 
-- Refactored sending system.
+Renders a paginated inline keyboard from any dict or iterable.
+Navigation buttons (`« Back`, `Next »`) are added automatically.
 
-## Chain Improvements
+| **Member**           | **Description**                                                              |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `paginated_choice(choices, on_choice, on_update, row_width)` | Display a paginated choice keyboard. |
 
-| **Name**    | **Description**                                              |
-| ----------- | ------------------------------------------------------------ |
-| `received`  | The message received from the user during entry processing.  |
+```python
+self.chain.sender.set_title("🔤 What is your initial?")
+self.chain.sender.set_message("Pick the first letter of your name")
+self.chain.sender.set_remove_text(False)
+
+self.paginated_choice(
+    choices="ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+    on_choice=self.handle_letter,
+    row_width=5
+)
+```
+
+<details>
+  <summary>(Click to see the result)</summary>
+  <table>
+    <tr>
+      <td><img src="https://github.com/Romashkaa/telekit/blob/main/docs/images/paginated_choice.png?raw=true" alt="Example" width="300"></td>
+    </tr>
+  </table>
+</details>
+
+`choices` accepts a `dict[str, T]`, or any `Iterable[T]`.
+If only one item is present, `on_choice` is called immediately without rendering a keyboard.
+
+## Utils
+
+| **Name**         | **Description**                                                    |
+| ---------------- | ------------------------------------------------------------------ |
+| `load_env`       | Load all key-value pairs from a `.env` file into a dictionary.     |
+| `read_env_var`   | Read a single variable by name from a `.env` file.                 |
+
+- `read_token` and `read_canvas_path` now support reading from `.env` files.
+  Pass `".env"` to use the default key, or `".env:KEY"` to specify a custom one:
+
+```python
+read_token(".env")                 # reads TOKEN
+read_token(".env:BOT_TOKEN")       # reads BOT_TOKEN
+
+read_canvas_path(".env")           # reads CANVAS_PATH
+read_canvas_path(".env:MY_CANVAS") # reads MY_CANVAS
+```

{telekit-2.2.0a3 → telekit-2.3.0b1}/telekit.egg-info/SOURCES.txt

@@ -66,4 +66,7 @@ telekit/example/example_handlers/qr.py
 telekit/example/example_handlers/quiz.py
 telekit/example/example_handlers/spells.py
 telekit/example/example_handlers/start.py
-telekit/example/example_handlers/text_document.py
+telekit/example/example_handlers/text_document.py
+telekit/traits/__init__.py
+telekit/traits/paginated_choice.py
+telekit/traits/track_handoff_origin.py