telekit 2.2.0a3__tar.gz → 2.3.0b2__tar.gz

{telekit-2.2.0a3 → telekit-2.3.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.2.0a3
+Version: 2.3.0b2
 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,148 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.2.0a3
+# Changes in version 2.3.0b2
 
-## New Button Types
+## Inline Buttons
 
-| **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**                                                                 |
+| ---------------- | ------------------------------------------------------------------------------- |
+| `StaticButton`   | A non-interactive inline button that performs no action when pressed.           |
+| `AnswerButton`   | A button that responds to a callback query with a notification or alert without executing custom logic. |
 
-## User Improvements
+- `AnswerButton` and its subclasses (`AlertButton`, `NotificationButton`) now support the `persistent` parameter (Defauts to `True`):
+  - `True` — non-blocking hint (does not affect further interactions)
+  - `False` — terminates interaction after click
 
-| **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.          |
+## Traits
 
-- 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__`.
+| **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.        |
 
-## Sender Improvements
+### TrackHandoffOrigin
 
-| **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.    |
+`TrackHandoffOrigin` adds three members to any handler that inherits it:
 
-- Refactored sending system.
+| **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.               |
 
-## Chain Improvements
+Set `TRACK_HANDOFF_ORIGIN = False` on any subclass to opt out of tracking.
 
-| **Name**    | **Description**                                              |
-| ----------- | ------------------------------------------------------------ |
-| `received`  | The message received from the user during entry processing.  |
+```python
+class MyHandler(TrackHandoffOrigin, telekit.Handler):
+
+    def handle(self):
+        ...
+        self.chain.set_inline_keyboard({
+            "« Back": self.handoff_back_or(StartHandler)
+        })
+        self.chain.edit()
+```
+
+### PaginatedChoice
+
+Renders a paginated inline keyboard from any dict or iterable.
+Navigation buttons (`« Back`, `Next »`) are added automatically.
+
+| **Member**           | **Description**                                                              |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `paginated_choice(choices, on_choice, ...)` | Display a paginated choice keyboard. |
+| `PAGINATED_CHOICE_BACK_LABEL` | Label for the back navigation button. Defaults to `« Back`. |
+| `PAGINATED_CHOICE_NEXT_LABEL` | Label for the next navigation button. Defaults to `Next »`. |
+| `PAGINATED_CHOICE_PAGE_LABEL` | Label template for the page indicator button. Supports `{page}` and `{pages}` placeholders. Set to `None` to hide. Defaults to `{page} / {pages}`. |
+
+
+```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
+)
+```
+
+Override labels per handler to localise or restyle navigation:
+
+```python
+class MyHandler(PaginatedChoice, telekit.Handler):
+    PAGINATED_CHOICE_BACK_LABEL = "⬅️ Назад"
+    PAGINATED_CHOICE_NEXT_LABEL = "Далі ➡️"
+    PAGINATED_CHOICE_PAGE_LABEL = None  # hide page indicator
+```
+
+<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.                 |
+| `compose_keyboard` | Merge multiple button groups into a single inline keyboard with computed `row_width`. |
+
+### Environment Utils
+
+- `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
+```
+
+### Inline Keyboard Utils
+
+`compose_keyboard` combines multiple button groups into a single keyboard and automatically calculates `row_width` for each group.
+
+Each group is laid out independently using its corresponding width from `widths`.
+A width of `-1` means "all buttons in one row" (i.e. ``len(group)``).
+
+| **Param** | **Type**         | **Description**                             |
+|-----------|------------------|---------------------------------------------|
+| `groups`  | `dict[str, Any]` | One or more button groups                   |
+| `widths`  | `Iterable[int]`  | Row width per group or single value for all |
+
+| **Returns** | **Type** |
+|------------|----------|
+| `keyboard` | `dict[str, Any]` |
+| `row_width` | `tuple[int, ...]` |
+
+```py
+# row_width → (1, 3, 3, 3, 2)
+# layout:
+#   |    🆕 Create    |
+#   |  1  |  2  |  3  |
+#   |  4  |  5  |  6  |
+#   |  7  |  8  |  9  |
+#   | « Back | Next » |
+
+keyboard, row_width = compose_keyboard(
+    {"🆕 Create": "create"},
+    {str(n): str(n) for n in range(1, 10)},
+    {"« Back": "back", "Next »": "next"},
+    widths=(-1, 3, -1), # or (1, 3, 2)
+)
+self.chain.set_inline_choice(keyboard, row_width)
+```

{telekit-2.2.0a3 → telekit-2.3.0b2}/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.0b2}/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.0b2}/telekit/_callback_query_handler.py

@@ -40,15 +40,17 @@ class CallbackQueryHandler:
             bot (TeleBot): The Telegram bot instance to be used for sending messages.
         """
         cls.bot = bot
-        cls.user_button_callbacks: dict[int, dict[str, Callable[[telebot.types.CallbackQuery], None]]] = {}
+        cls.user_button_callbacks: dict[int, dict[str, Callable[[CallbackQuery], None]]] = {}
 
         @bot.callback_query_handler(func=lambda call: True)
-        def handle(call: telebot.types.CallbackQuery) -> None:
+        def handle(call: CallbackQuery) -> None:
             if not call.data:
                 return
             
             if call.data.startswith(cls.INLINE_BUTTON):
                 cls._handle_inline_button(call)
+            elif call.data.startswith(cls.STATIC_BUTTON):
+                cls._handle_static_button(call)
             elif call.data.startswith(cls.SUGGEST):
                 cls._handle_suggestion(call)
             else:
@@ -59,7 +61,7 @@ class CallbackQueryHandler:
     # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
     @classmethod
-    def _handle_inline_button(cls, call: telebot.types.CallbackQuery):
+    def _handle_inline_button(cls, call: CallbackQuery):
         if not call.data:
             cls.bot.answer_callback_query(call.id, text=cls._invalid_data_answer[0], show_alert=cls._invalid_data_answer[1])
             return
@@ -76,10 +78,19 @@ class CallbackQueryHandler:
             cls.bot.answer_callback_query(call.id, text=cls._button_is_no_active_answer[0], show_alert=cls._button_is_no_active_answer[1])
             return
 
-        cls.remove_user_button_callbacks(call.from_user.id)
+        if not getattr(callback, "_persistent", False):
+            cls.remove_user_button_callbacks(call.from_user.id)
         
         callback(call)
 
+    # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+    # Static Buttons Handling
+    # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+    @classmethod
+    def _handle_static_button(cls, call: CallbackQuery):
+        cls.bot.answer_callback_query(call.id, text="")
+
     # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
     # Suggestion Handling
     # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
@@ -87,7 +98,7 @@ class CallbackQueryHandler:
     @classmethod
     def _handle_suggestion(cls, call: CallbackQuery):
         text: str = str(call.data)[len(cls.SUGGEST):]
-        cls.simulate(call.message, text, from_user=call.from_user)
+        cls.simulate(call.message, text, from_user=call.from_user) # pyright: ignore[reportArgumentType]
         cls.bot.answer_callback_query(call.id)
 
     @classmethod
@@ -126,9 +137,10 @@ class CallbackQueryHandler:
     # Query Types
     # –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
+    STATIC_BUTTON: str = "static_button"
     INLINE_BUTTON: str = "inline_button:"
     SUGGEST: str = "suggest:"
-
+    
     @classmethod
     def suggest(cls, suggestion: str):
         return f"{cls.SUGGEST}{suggestion}"

{telekit-2.2.0a3 → telekit-2.3.0b2}/telekit/_chain_inline_keyboards_logic.py

@@ -40,8 +40,7 @@ if typing.TYPE_CHECKING:
 class ChainInlineKeyboardLogic(ChainBase):
     def set_inline_keyboard(
             self, 
-            keyboard: dict[str, Callable[[], Any] | InlineButton | str], 
-            *,
+            keyboard: dict[str, Any], 
             row_width: int | Iterable[int] = 1
         ) -> None:
         """
@@ -118,7 +117,6 @@ class ChainInlineKeyboardLogic(ChainBase):
     def inline_keyboard[Caption: str, Value](
             self, 
             keyboard: dict[Caption, Value],
-            *,
             row_width: int | Iterable[int] = 1,
             enable_special_buttons: bool = True
         ) -> Callable[[Callable[[Value], None]], None]:
@@ -183,7 +181,6 @@ class ChainInlineKeyboardLogic(ChainBase):
     def inline_choice(
             self, 
             choices: list[Any] | tuple[Any, ...] | dict[str, Any | InlineButton],
-            *,
             row_width: int | Iterable[int] = 1,
             enable_special_buttons: bool = True
         ) -> Callable[[Callable[[Any], None]], None]:
@@ -219,7 +216,6 @@ class ChainInlineKeyboardLogic(ChainBase):
             self,
             func: Callable[[Any], None],
             choices: list[Any] | tuple[Any, ...] | dict[str, Any | InlineButton],
-            *,
             row_width: int | Iterable[int] = 1,
             enable_special_buttons: bool = True
         ) -> None:

{telekit-2.2.0a3 → telekit-2.3.0b2}/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.0b2}/telekit/_inline_buttons.py

@@ -27,13 +27,15 @@ from telebot import TeleBot
 from ._callback_query_handler import CallbackQueryHandler
 
 __all__ = [
-    "InlineButton", 
+    "InlineButton",
 
+    "StaticButton",
     "LinkButton", 
     "WebAppButton", 
     "SuggestButton",
     "CopyTextButton",
     "CallbackButton",
+    "AnswerButton",
     "AlertButton",
     "NotificationButton",
     "InvokeButton",
@@ -57,9 +59,11 @@ class InlineButton:
     - `SuggestButton`
     - `CopyTextButton`
     - `CallbackButton`
-    - `AlertButton`
-    - `NotificationButton`
-    - `InvokeButton`
+        - `InvokeButton`
+        - `AnswerButton`
+            - `AlertButton`
+            - `NotificationButton`
+    - `StaticButton`
     """
 
     _bot: TeleBot
@@ -70,12 +74,14 @@ class InlineButton:
 
     MAX_SIZE: int | None = None
     MIN_SIZE: int | None = None
-
+    
+    Static: type["StaticButton"]
     Link: type["LinkButton"]
     WebApp: type["WebAppButton"]
     Suggest: type["SuggestButton"]
     CopyText: type["CopyTextButton"]
     Callback: type["CallbackButton"]
+    Answer: type["AnswerButton"]
     Alert: type["AlertButton"]
     Notification: type["NotificationButton"]
     Invoke: type["InvokeButton"]
@@ -115,7 +121,20 @@ class InlineButton:
                 return normalized
             raise ValueError(f"Unknown style: {style!r}. Must be one of {_BUTTON_STYLES_LIST}")
         raise TypeError(f"Style must be str, ButtonStyle, or None, got {type(style)}")
+    
+class StaticButton(InlineButton):
 
+    def __init__(self, *, style: str | None | ButtonStyle = None, **kwargs):
+        self._style = self._normalize_style(style)
+        self._kwargs = kwargs
+        
+    def _compile(self, caption: str) -> InlineKeyboardButton:
+        return InlineKeyboardButton(
+            text=caption,
+            callback_data=CallbackQueryHandler.STATIC_BUTTON,
+            style=self._style,
+            **self._kwargs,
+        )
     
 class LinkButton(InlineButton):
     """
@@ -339,8 +358,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,
@@ -387,7 +406,77 @@ class CallbackButton(InlineButton):
             callback=callback,
         )
     
-class AlertButton(CallbackButton):
+class AnswerButton(CallbackButton):
+
+    class _CallbackInvoker(CallbackButton._CallbackInvoker):
+        def __init__(
+                self, 
+                chain_callback: Callable[[], None],
+
+                answer_text: str | None = None,
+                answer_as_alert: bool = True,
+
+                persistent: bool = True,
+
+                style: str | None | ButtonStyle = None,
+
+                kwargs: dict[str, Any] = {}
+            ):
+            self._answer_text = answer_text
+            self._answer_as_alert = answer_as_alert
+
+            self._persistent = persistent
+
+            self._style = style
+
+            self._kwargs = {"style": style} | kwargs
+            
+            self._chain_callback: Callable[[], None] = chain_callback
+
+        def _answer_callback_query(self, call: CallbackQuery):
+            if self._answer_text:
+                InlineButton._bot.answer_callback_query(
+                    call.id,
+                    self._answer_text,
+                    self._answer_as_alert
+                )
+
+        def __call__(self, call: CallbackQuery):
+            if not self._persistent:
+                self._invoke_chain_callback()
+            self._answer_callback_query(call)
+
+    def __init__(
+            self,
+            answer_text: str | None = None,
+            answer_as_alert: bool = True,
+
+            persistent: bool = True,
+
+            style: str | None | ButtonStyle = None,
+
+            **kwargs
+        ):
+        self._answer_text = answer_text
+        self._answer_as_alert = answer_as_alert
+
+        self._persistent = persistent
+
+        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,
+            answer_text=self._answer_text,
+            answer_as_alert=self._answer_as_alert,
+            persistent=self._persistent,
+            style=self._style,
+            kwargs=self._kwargs
+        )
+
+class AlertButton(AnswerButton):
     """
     An inline keyboard button that shows a popup alert when pressed and terminates the chain.
 
@@ -424,19 +513,19 @@ class AlertButton(CallbackButton):
     def __init__(
             self,
             text: str | None = None,
-            *,
+            persistent: bool = True,
             style: str | None | ButtonStyle = None,
             **kwargs
         ):
         super().__init__(
-            callback=None,
             answer_text=text,
             answer_as_alert=True,
+            persistent=persistent,
             style=style,
             **kwargs
         )
 
-class NotificationButton(CallbackButton):
+class NotificationButton(AnswerButton):
     """
     An inline keyboard button that shows a brief notification at the top of the chat screen
     when pressed and terminates the chain.
@@ -475,13 +564,14 @@ class NotificationButton(CallbackButton):
             self,
             text: str | None = None,
             *,
+            persistent: bool = True,
             style: str | None | ButtonStyle = None,
             **kwargs
         ):
         super().__init__(
-            callback=None,
             answer_text=text,
             answer_as_alert=False,
+            persistent=persistent,
             style=style,
             **kwargs
         )
@@ -611,10 +701,12 @@ class InvokeButton(CallbackButton):
         )
     
 InlineButton.Link = LinkButton
+InlineButton.Static = StaticButton
 InlineButton.WebApp = WebAppButton
 InlineButton.Suggest = SuggestButton
 InlineButton.CopyText = CopyTextButton
 InlineButton.Callback = CallbackButton
+InlineButton.Answer = AnswerButton
 InlineButton.Alert = AlertButton
 InlineButton.Notification = NotificationButton
 InlineButton.Invoke = InvokeButton

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

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

{telekit-2.2.0a3 → telekit-2.3.0b2}/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.0b2}/telekit/example/example_handlers/spells.py

@@ -1,25 +1,21 @@
 import telekit
 
-from telekit.inline_buttons import CallbackButton
+from telekit.inline_buttons import AlertButton
 
 spells_text = """
-# Expelliarmus
-
-The Disarming Charm. It causes whatever the victim is holding to fly out of their hand. It became Harry Potter's signature spell.
-
-# Wingardium Leviosa
+# 🦋 Wingardium Leviosa
 
 The Levitation Charm. Used to make objects fly. As Hermione Granger famously noted, it's "Levi-o-sa, not Levio-sar."
 
-# Expecto Patronum
+# 🧌 Expecto Patronum
 
 The Patronus Charm. A highly advanced spell that conjures a silver guardian to protect the caster against Dementors.
 
-# Alohomora
+# 🗝️ Alohomora
 
 The Unlocking Charm. Used to open doors and windows that are not protected by magic.
 
-# Lumos
+# 🪄 Lumos
 
 The Wand-Lighting Charm. Illuminates the tip of the caster's wand, allowing them to see in the dark.
 """
@@ -48,11 +44,14 @@ class SpellsHandler(telekit.Handler):
 
         self.chain.set_inline_keyboard(
             {
-                title: CallbackButton(self.display_spells, answer_text=content) 
+                title: AlertButton(content) 
                 for title, content in spells.items()
-            }
+            } | {"« Back": self.handle_back},
+            row_width=2
         )
-        self.chain.set_remove_inline_keyboard(False)
 
         self.chain.disable_timeout_warnings()
-        self.chain.edit()
+        self.chain.edit()
+
+    def handle_back(self):
+        self.handoff("StartHandler").handle()

{telekit-2.2.0a3 → telekit-2.3.0b2}/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()