telekit 2.3.0b1__tar.gz → 2.3.0b2__tar.gz

{telekit-2.3.0b1 → telekit-2.3.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.3.0b1
+Version: 2.3.0b2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -379,7 +379,18 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.3.0b1
+# Changes in version 2.3.0b2
+
+## Inline Buttons
+
+| **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. |
+
+- `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
 
 ## Traits
 
@@ -419,7 +430,11 @@ Navigation buttons (`« Back`, `Next »`) are added automatically.
 
 | **Member**           | **Description**                                                              |
 | -------------------- | ---------------------------------------------------------------------------- |
-| `paginated_choice(choices, on_choice, on_update, row_width)` | Display a paginated choice keyboard. |
+| `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?")
@@ -433,6 +448,15 @@ self.paginated_choice(
 )
 ```
 
+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>
@@ -447,10 +471,13 @@ If only one item is present, `on_choice` is called immediately without rendering
 
 ## 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.                 |
+| **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:
@@ -462,3 +489,38 @@ 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.3.0b1 → 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.3.0b1 → 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.3.0b1 → 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):
     """
@@ -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.3.0b1 → telekit-2.3.0b2}/telekit/_version.py

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

{telekit-2.3.0b1 → 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.3.0b1 → telekit-2.3.0b2}/telekit/inline_buttons.py

@@ -19,6 +19,7 @@
 
 from ._inline_buttons import (
     InlineButton,
+    StaticButton,
 
     LinkButton,
     WebAppButton,
@@ -26,13 +27,16 @@ from ._inline_buttons import (
     CopyTextButton,
     
     CallbackButton,
+    InvokeButton,
+
+    AnswerButton,
     AlertButton,
     NotificationButton,
-    InvokeButton,
 )
 
 __all__ = [
     "InlineButton", 
+    "StaticButton",
 
     "LinkButton", 
     "WebAppButton", 
@@ -40,7 +44,9 @@ __all__ = [
     "CopyTextButton",
 
     "CallbackButton",
+    "InvokeButton",
+
+    "AnswerButton",
     "AlertButton",
     "NotificationButton",
-    "InvokeButton",
 ]

{telekit-2.3.0b1 → telekit-2.3.0b2}/telekit/traits/paginated_choice.py

@@ -1,18 +1,67 @@
 from typing import Callable, Any, Iterable
+from dataclasses import dataclass
 
 import telekit
-from dataclasses import dataclass
+from telekit.inline_buttons import StaticButton
+from telekit.utils import compose_keyboard
 
 @dataclass
 class _NavButton:
     start_index: int
 
 class PaginatedChoice(telekit.Handler):
+    """
+    A trait that adds a paginated inline keyboard to any handler.
+
+    Inherit alongside ``telekit.Handler`` to get the :meth:`paginated_choice`
+    method, which renders a multi-page inline keyboard from any iterable or dict.
+
+    Navigation buttons (``« Back``, ``Next »``) and an optional page indicator
+    are added automatically. Layout is handled via :func:`compose_keyboard`.
+
+    **Customising navigation labels** - override at the class level:
+
+    .. code-block:: python
+
+        class MyHandler(PaginatedChoice, telekit.Handler):
+            PAGINATED_CHOICE_BACK_LABEL = "« Back"
+            PAGINATED_CHOICE_NEXT_LABEL = "Next »"
+            PAGINATED_CHOICE_PAGE_LABEL = "{page} / {pages}"
+
+    **Class attributes:**
 
-    # ── entry point ───────────────────────────────────────────────
+    .. list-table::
+        :widths: 30 70
 
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+        * - ``PAGINATED_CHOICE_BACK_LABEL``
+          - Label for the back button. Defaults to ``« Back``.
+        * - ``PAGINATED_CHOICE_NEXT_LABEL``
+          - Label for the next button. Defaults to ``Next »``.
+        * - ``PAGINATED_CHOICE_PAGE_LABEL``
+          - Label template for the page indicator. Defaults to ``{page} / {pages}``.
+
+    Example::
+
+        class LetterPickerHandler(PaginatedChoice, telekit.Handler):
+
+            def handle(self) -> None:
+                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
+                )
+
+            def handle_letter(self, letter: str) -> None:
+                ...
+    """
+
+    PAGINATED_CHOICE_BACK_LABEL: str = "« Back"
+    PAGINATED_CHOICE_NEXT_LABEL: str = "Next »"
+    PAGINATED_CHOICE_PAGE_LABEL: str | None = "{page} / {pages}"  # use .format(page=..., pages=...)
 
     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:
         """
@@ -56,44 +105,32 @@ class PaginatedChoice(telekit.Handler):
         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:
+        if on_update is not None:
+            on_update()
+
         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)
+        # choices
+        page_items = list(choices.items())[start : start + page_size]
 
         # navigation row
         has_back = start - page_size >= 0
         has_next = start + page_size < total
 
-        nav: dict[str, T | _NavButton] = {}
+        nav: dict[str, T | _NavButton | StaticButton] = {}
 
         if has_back:
-            nav["« Back"] = _NavButton(start - page_size)
-        if has_back and has_next:
-            nav[f"({page}/{pages})" ] = _NavButton(start)
+            nav[self.PAGINATED_CHOICE_BACK_LABEL] = \
+                _NavButton(start - page_size)
+        if has_back and has_next and self.PAGINATED_CHOICE_PAGE_LABEL:
+            nav[self.PAGINATED_CHOICE_PAGE_LABEL.format(page=page, pages=pages)] = \
+                StaticButton()
         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)
+            nav[self.PAGINATED_CHOICE_NEXT_LABEL] = \
+                _NavButton(start + page_size)
 
         def _on_choice(choice: T | _NavButton):
             if isinstance(choice, _NavButton):
@@ -103,7 +140,6 @@ class PaginatedChoice(telekit.Handler):
 
         self.chain.set_inline_choice(
             _on_choice,
-            keyboard,
-            row_width=_row_width,
+            *compose_keyboard(dict(page_items), nav, widths=(row_width, -1))
         )
         self.chain.edit()

{telekit-2.3.0b1 → telekit-2.3.0b2}/telekit/utils.py

@@ -3,7 +3,7 @@ import re
 
 from pathlib import Path
 from urllib.parse import urlencode, quote
-from typing import Literal
+from typing import Literal, Any, Iterable
 
 ROOT_DIR = Path(__file__).resolve().parent  # telekit/
 
@@ -245,6 +245,79 @@ def read_canvas_path(path: str = "canvas_path.txt") -> str:
     with open(path) as f:
         return f.readline().strip()
     
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Inline Keyboards
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+def compose_keyboard(
+    *groups: dict[str, Any],
+    widths: Iterable[int] = (1, -1),
+) -> tuple[dict[str, Any], tuple[int, ...]]:
+    """
+    Merge multiple button groups into a single keyboard dict with computed row widths.
+
+    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 groups: One or more dicts mapping button labels to values.
+    :type groups: ``dict[str, Any]``
+    :param widths: Row width for each group. Must match the number of groups,
+                   or be a single value applied to all groups.
+                   Use ``-1`` to fit the entire group on one row.
+    :type widths: ``Iterable[int]``
+    :return: Merged keyboard dict and the computed row_width tuple.
+    :rtype: ``tuple[dict[str, Any], tuple[int, ...]]``
+
+    Example::
+
+        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),
+        )
+        chain.set_inline_choice(keyboard, row_width)
+        # row_width → (1, 3, 3, 3, 2)
+        # layout:
+        #   | 🆕 Create        |
+        #   | 1  | 2  | 3      |
+        #   | 4  | 5  | 6      |
+        #   | 7  | 8  | 9      |
+        #   | « Back | Next »  |
+    """
+    widths_list = list(widths)
+
+    if len(widths_list) == 1:
+        widths_list = widths_list * len(groups)
+
+    if len(widths_list) != len(groups):
+        raise ValueError(
+            f"Number of widths ({len(widths_list)}) must match "
+            f"number of groups ({len(groups)}) or be 1."
+        )
+
+    keyboard: dict[str, Any] = {}
+    row_width: list[int] = []
+
+    for group, width in zip(groups, widths_list):
+        if not group:
+            continue
+
+        count = len(group)
+        w = count if width == -1 else width
+
+        full_rows = count // w
+        remainder = count % w
+
+        row_width.extend([w] * full_rows)
+        if remainder:
+            row_width.append(remainder)
+
+        keyboard.update(group)
+
+    return keyboard, tuple(row_width)
+
+
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 # Link Generating
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.3.0b1
+Version: 2.3.0b2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -379,7 +379,18 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.3.0b1
+# Changes in version 2.3.0b2
+
+## Inline Buttons
+
+| **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. |
+
+- `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
 
 ## Traits
 
@@ -419,7 +430,11 @@ Navigation buttons (`« Back`, `Next »`) are added automatically.
 
 | **Member**           | **Description**                                                              |
 | -------------------- | ---------------------------------------------------------------------------- |
-| `paginated_choice(choices, on_choice, on_update, row_width)` | Display a paginated choice keyboard. |
+| `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?")
@@ -433,6 +448,15 @@ self.paginated_choice(
 )
 ```
 
+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>
@@ -447,10 +471,13 @@ If only one item is present, `on_choice` is called immediately without rendering
 
 ## 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.                 |
+| **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:
@@ -462,3 +489,38 @@ 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)
+```