telekit 2.4.0b0__tar.gz → 2.5.0__tar.gz

{telekit-2.4.0b0 → telekit-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.4.0b0
+Version: 2.5.0
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -75,7 +75,7 @@ Telekit comes with a [built-in DSL](https://github.com/Romashkaa/telekit/blob/ma
 }
 ```
 
-> See the [full example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+> See the [full example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
 
 Even in its beta stage, Telekit accelerates bot development, offering typed **command parameters**, **text styling** via `Bold()`, `Italic()`, a built-in declarative **calendar picker**, emoji **game results** for `🎲 🎯 🏀 ⚽ 🎳 🎰`, and much more out of the box. Its declarative design makes bots easier to read, maintain, and extend.
 
@@ -133,36 +133,91 @@ The `handle` method sends a message and registers `handle_name` as the next step
 
 ### Inline Keyboards
 
-Buttons can either **return a value** or **call a method directly**.
+The fastest way to add buttons to a message. Pass a plain `dict` where each key is the button label and each value is the callback to invoke when pressed:
 
-**Choice keyboard** — map button labels to values. The selected value is passed straight into your handler:
-
-```py
-self.chain.set_inline_choice(
-    self.on_choice,
-    choices={
-        "Option 1": "Value 1",
-        "Option 2": "Value 2",
-        "Option 3": [3, "Yes, it's an array"],
+```python
+self.chain.set_inline_keyboard(
+    {
+        "✏️ Change": self.change_name,
+        "❌ Delete": self.delete,
     }
 )
+```
+
+`row_width` controls how many buttons appear per row:
+
+```python
+self.chain.set_inline_keyboard(
+    {
+        "One":   self.one,
+        "Two":   self.two,
+        "Three": self.three,
+        "Four":  self.four,
+        "Five":  self.five,
+    },
+    row_width=(3, 2)  # first row: 3 buttons, second row: 2
+)
+```
 
-def on_choice(self, choice: str | list):
-    print(f"{choice!r}") # "Value 1", "Value 2" or [3, "Yes, it's an array"]
+```
+╭──────────┬──────────┬──────────╮
+│   One    │   Two    │  Three   │
+├──────────┴──┬───────┴──────────┤
+│    Four     │       Five       │
+╰─────────────┴──────────────────╯
 ```
 
-Inside `on_choice`, you receive exactly what you defined in `choices`: a string, list, number, function — anything.
+**Need more control?**
 
-**Callback keyboard** — each button calls its own method:
+When you need precise row layout or conditional buttons, use `InlineKeyboard` — a fluent builder that composes keyboards step by step:
+
+```python
+self.chain.set_keyboard(
+    InlineKeyboard()
+        .add_callback("-", self.decrement, style="danger")
+        .add_callback("+", self.increment, style="success")
+    .row()
+        .add_callback("↺ Reset", self.reset)
+)
+```
 
-```py
-self.chain.set_inline_keyboard({
-    "« Back": self.display_previous_page,
-    "Next »": self.display_next_page,
-})
 ```
+╭──────────┬──────────╮
+│    -     │    +     │
+├──────────┴──────────┤
+│       ↺ Reset       │
+╰─────────────────────╯
+```
+
+> `InlineKeyboard` is built by chaining method calls. Just call `.row()` to start a new row.
+
+**Not just callback buttons**
 
-Useful for pagination, navigation, or menus.
+| **Method**            | **Description**                                                  |
+| --------------------- | ---------------------------------------------------------------- |
+| `add_callback(...)`   | Button that fires a callback function.                           |
+| `add_link(...)`       | Button that opens a URL.                                         |
+| `add_copy(...)`       | Button that copies text to the clipboard.                        |
+| `add_alert(...)`      | Button that shows a popup alert dialog.                          |
+| `add_notification(...)` | Button that shows a brief top-of-chat notification.            |
+| `add_static(...)`     | Decorative button with no action.                                |
+| `add_webapp(...)`     | Button that opens a Telegram Mini App.                           |
+| `add_suggest(...)`    | Button that simulates the user sending a message.                |
+
+### Reply Keyboards
+
+Unlike inline keyboards, reply keyboards replace the user's system keyboard with buttons shown at the bottom of the chat. Tapping a button either sends its text as a regular message or triggers a system action, such as sharing a phone number or location.
+
+```python
+self.chain.set_keyboard(
+    ReplyKeyboard(one_time_keyboard=True)
+        .add_text("Hello!")
+        .add_text("Hi")
+    .row()
+        .add_contact("📱 Share phone")
+        .add_location("📍 Share location")
+)
+```
 
 ### Command Parameters
 
@@ -186,7 +241,7 @@ class GreetHandler(telekit.Handler):
 
 Now `/greet 64 "Alice Reingold"` or `/greet 128 Dracula` are parsed automatically.
 
-> [!INFO]
+> [!NOTE]
 > If arguments are invalid or missing, you simply receive `None` and decide how to respond.
 
 ### Dialogue
@@ -242,7 +297,7 @@ self.chain.sender.send_chat_action(ChatAction.TYPING) # Send chat action. Use en
 ```
 
 > [!NOTE]
-> Telekit automatically decides whether to use 'bot.send_message' or 'bot.send_photo' based on the content
+> Telekit automatically decides whether to use `bot.send_message` or `bot.send_photo` based on the content
 
 ### Styles
 
@@ -288,7 +343,7 @@ If you prefer not to write dialog logic in Python, you can use the built-in DSL
 ```py
 import telekit
 
-class QuizHandler(telekit.TelekitDSL.Mixin):
+class QuizHandler(telekit.DSLHandler):
     @classmethod
     def init_handler(cls) -> None:
         cls.analyze_string(script)
@@ -338,7 +393,7 @@ telekit.Server(BOT_TOKEN).polling()
 - Jinja template engine
 
 <details>
-  <summary>Click to see what you can do with the DSL</summary>
+  <summary>🎆 Click to see what you can do with the DSL</summary>
   <table>
     <tr>
       <td><img src="./docs/images/telekit_example_7.jpg" alt="Telekit Example 7" width="300"></td>
@@ -351,7 +406,8 @@ telekit.Server(BOT_TOKEN).polling()
   </table>
 </details>
 
-You can find a [full quiz example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md) and [DSL reference](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) in the repository.
+> [!TIP]
+> You can find a [full quiz example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md) and [DSL reference](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) in the repository.
 
 ### Traits
 
@@ -421,72 +477,42 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.4.0b0
-
-## Scheduler
-
-- Added `every` decorator for scheduling functions in a background daemon thread.
-- Implemented `PeriodicTask` class to manage periodic execution and error handling.
-
-## Telekit DSL
-
-### `InstanceDSLHandler`
-
-Instance-oriented variant of `DSLHandler` where each instance carries its own
-`executable_model`, `_script_data_factory`, and `_jinja_env` — allowing multiple
-instances to run completely independent scripts simultaneously.
-
-Use the `*_locally` instance methods instead of the class-level ones:
-
-```python
-class MyHandler(telekit.InstanceDSLHandler):
-    @classmethod
-    def init_handler(cls) -> None:
-        cls.on.message().invoke(cls.handle)
-
-    def handle(self):
-        script = fetch_script_from_db(self.user.id)  # per-user DSL
-        self.analyze_string_locally(script)
-        self.start_script()
-```
-
-| **Method**                              | **Description**                                      |
-| --------------------------------------- | ---------------------------------------------------- |
-| `analyze_file_locally(path, encoding)`  | Analyse a script file on this instance.              |
-| `analyze_string_locally(script)`        | Analyse a DSL string on this instance.               |
-| `analyze_canvas_locally(file_path)`     | Analyse an Obsidian `.canvas` file on this instance. |
-| `analyze_executable_model_locally(model)` | Load a pre-built model dict on this instance.      |
-
-**Security**
-
-When accepting scripts from untrusted users, restrict dangerous features via the
-`RESTRICTED` class attribute. Set `DEFAULT_TIMEOUT` to control the fallback timeout,
-and `DEFAULT_CONFIG` to provide a safe base config.
-
-```python
-class SafeDSL(telekit.InstanceDSLHandler):
-    RESTRICTED: list[RestrictedToken] = ["hook", "jinja", "redirect", "handoff", "config"]
-    DEFAULT_TIMEOUT = 120
-    DEFAULT_CONFIG  = {"template": "vars"}
-```
-
-| **Token**      | **Effect**                                                                                      |
-| -------------- | ----------------------------------------------------------------------------------------------- |
-| `"handoff"`    | Disables `handoff` button type (cross-handler transitions).                                     |
-| `"redirect"`   | Disables `redirect` button type (simulated user messages).                                      |
-| `"hook"`       | Removes all `on_enter`, `on_enter_once`, `on_exit`, `on_timeout` hooks.                        |
-| `"jinja"`      | Forces template engine to `"vars"`; Jinja is never executed.                                    |
-| `"timeout"`    | Ignores per-script `timeout_time`; uses `DEFAULT_TIMEOUT` only.                                 |
-| `"config"`     | Replaces script config with `DEFAULT_CONFIG`; `vars_*` keys are preserved unless `"vars"` is also set. |
-| `"vars"`       | Removes all `vars_*` keys and disables `{{variable}}` substitution.                             |
-| `"images"`     | Strips `image` field from every scene.                                                          |
-| `"links"`      | Disables `link` button type (external URLs).                                                    |
-| `"suggest"`    | Disables `suggest` button type (pre-filled entry suggestions).                                  |
-| `"entry"`      | Disables entry handlers (free-text input routing).                                              |
-| `"next"`       | Disables `next` magic scene navigation.                                                         |
-| `"back"`       | Disables `back` magic scene navigation.                                                         |
-
-## Others
-
-- Enhanced `Debug` class with callback query tracing functionality.
-- Refactored `BaseSender` to use `send_or_handle_error`.
+# Changes in version 2.5.0
+
+### v2.5.0`b0`
+- Added support for t-strings (PEP 750, Python 3.14+) in `TextEntity`.
+
+### v2.5.0`b1`
+- Added `Sender.send_message` method.
+- Added `utils.make_mention` utility for generating `tg://user?id=` mention links.
+- Added new inline button types to `inline_buttons`:
+  - `ContactButton` — mentions a user by Telegram ID via `tg://user?id=`.
+  - `UserLinkButton` — opens a user profile by username; supports pre-filled message text.
+  - `BotLinkButton` — opens a bot by username; supports deep-link `?start=` payload.
+- Added new methods to `InlineKeyboard`:
+  - `add_contact` — adds a `ContactButton`.
+  - `add_user_link` — adds a `UserLinkButton`.
+  - `add_bot_link` — adds a `BotLinkButton`.
+
+### v2.5.0`b2`
+- Added the `escape` parameter to `telekit.utils.*`:
+  - `make_user_link`
+  - `make_bot_link`
+- `Handler.handlers_dict` now excludes private handlers (classes whose names start with `_`).
+- Added `Debug.duplicate_handler_warnings` to warn about duplicate handler names during initialization.
+- Added `Handler.chat` object (BETA)
+
+### v2.5.0`b3`
+- Added `utils.Markers` class
+- Added `HTMLText` class for handling Telegram HTML strings with tag-aware indexing and slicing.
+- Added `PaginatedText` trait for displaying long HTML text in a paginated format, supporting navigation and smart splitting.
+- Added `__radd__` to `TextEntity`: `"Regular" + Bold(" and Bold")`
+- Added `__mul__` to `TextEntity`: `Bold("Text") * 3`
+- Added `enabled=` parameter to `TextEntity`: `Bold("bold text", enabled=is_text_bold)`
+- Added `TextBuilder` class – a fluent message composition API mirroring `InlineKeyboard`'s builder pattern
+- Added styles to `telekit.types`
+- Added `utils.CyclicList`
+- Fixed `_answer_callback_query` to always call `bot.answer_callback_query()`, even without a popup text
+
+### v2.5.0`rc2`
+- Refactor `CalendarPick` trait to use `set_keyboard`

{telekit-2.4.0b0 → telekit-2.5.0}/README.md

@@ -39,7 +39,7 @@ Telekit comes with a [built-in DSL](https://github.com/Romashkaa/telekit/blob/ma
 }
 ```
 
-> See the [full example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/quiz.md)
+> See the [full example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md)
 
 Even in its beta stage, Telekit accelerates bot development, offering typed **command parameters**, **text styling** via `Bold()`, `Italic()`, a built-in declarative **calendar picker**, emoji **game results** for `🎲 🎯 🏀 ⚽ 🎳 🎰`, and much more out of the box. Its declarative design makes bots easier to read, maintain, and extend.
 
@@ -97,36 +97,91 @@ The `handle` method sends a message and registers `handle_name` as the next step
 
 ### Inline Keyboards
 
-Buttons can either **return a value** or **call a method directly**.
+The fastest way to add buttons to a message. Pass a plain `dict` where each key is the button label and each value is the callback to invoke when pressed:
 
-**Choice keyboard** — map button labels to values. The selected value is passed straight into your handler:
-
-```py
-self.chain.set_inline_choice(
-    self.on_choice,
-    choices={
-        "Option 1": "Value 1",
-        "Option 2": "Value 2",
-        "Option 3": [3, "Yes, it's an array"],
+```python
+self.chain.set_inline_keyboard(
+    {
+        "✏️ Change": self.change_name,
+        "❌ Delete": self.delete,
     }
 )
+```
 
-def on_choice(self, choice: str | list):
-    print(f"{choice!r}") # "Value 1", "Value 2" or [3, "Yes, it's an array"]
+`row_width` controls how many buttons appear per row:
+
+```python
+self.chain.set_inline_keyboard(
+    {
+        "One":   self.one,
+        "Two":   self.two,
+        "Three": self.three,
+        "Four":  self.four,
+        "Five":  self.five,
+    },
+    row_width=(3, 2)  # first row: 3 buttons, second row: 2
+)
 ```
 
-Inside `on_choice`, you receive exactly what you defined in `choices`: a string, list, number, function — anything.
+```
+╭──────────┬──────────┬──────────╮
+│   One    │   Two    │  Three   │
+├──────────┴──┬───────┴──────────┤
+│    Four     │       Five       │
+╰─────────────┴──────────────────╯
+```
 
-**Callback keyboard** — each button calls its own method:
+**Need more control?**
 
-```py
-self.chain.set_inline_keyboard({
-    "« Back": self.display_previous_page,
-    "Next »": self.display_next_page,
-})
+When you need precise row layout or conditional buttons, use `InlineKeyboard` — a fluent builder that composes keyboards step by step:
+
+```python
+self.chain.set_keyboard(
+    InlineKeyboard()
+        .add_callback("-", self.decrement, style="danger")
+        .add_callback("+", self.increment, style="success")
+    .row()
+        .add_callback("↺ Reset", self.reset)
+)
 ```
 
-Useful for pagination, navigation, or menus.
+```
+╭──────────┬──────────╮
+│    -     │    +     │
+├──────────┴──────────┤
+│       ↺ Reset       │
+╰─────────────────────╯
+```
+
+> `InlineKeyboard` is built by chaining method calls. Just call `.row()` to start a new row.
+
+**Not just callback buttons**
+
+| **Method**            | **Description**                                                  |
+| --------------------- | ---------------------------------------------------------------- |
+| `add_callback(...)`   | Button that fires a callback function.                           |
+| `add_link(...)`       | Button that opens a URL.                                         |
+| `add_copy(...)`       | Button that copies text to the clipboard.                        |
+| `add_alert(...)`      | Button that shows a popup alert dialog.                          |
+| `add_notification(...)` | Button that shows a brief top-of-chat notification.            |
+| `add_static(...)`     | Decorative button with no action.                                |
+| `add_webapp(...)`     | Button that opens a Telegram Mini App.                           |
+| `add_suggest(...)`    | Button that simulates the user sending a message.                |
+
+### Reply Keyboards
+
+Unlike inline keyboards, reply keyboards replace the user's system keyboard with buttons shown at the bottom of the chat. Tapping a button either sends its text as a regular message or triggers a system action, such as sharing a phone number or location.
+
+```python
+self.chain.set_keyboard(
+    ReplyKeyboard(one_time_keyboard=True)
+        .add_text("Hello!")
+        .add_text("Hi")
+    .row()
+        .add_contact("📱 Share phone")
+        .add_location("📍 Share location")
+)
+```
 
 ### Command Parameters
 
@@ -150,7 +205,7 @@ class GreetHandler(telekit.Handler):
 
 Now `/greet 64 "Alice Reingold"` or `/greet 128 Dracula` are parsed automatically.
 
-> [!INFO]
+> [!NOTE]
 > If arguments are invalid or missing, you simply receive `None` and decide how to respond.
 
 ### Dialogue
@@ -206,7 +261,7 @@ self.chain.sender.send_chat_action(ChatAction.TYPING) # Send chat action. Use en
 ```
 
 > [!NOTE]
-> Telekit automatically decides whether to use 'bot.send_message' or 'bot.send_photo' based on the content
+> Telekit automatically decides whether to use `bot.send_message` or `bot.send_photo` based on the content
 
 ### Styles
 
@@ -252,7 +307,7 @@ If you prefer not to write dialog logic in Python, you can use the built-in DSL
 ```py
 import telekit
 
-class QuizHandler(telekit.TelekitDSL.Mixin):
+class QuizHandler(telekit.DSLHandler):
     @classmethod
     def init_handler(cls) -> None:
         cls.analyze_string(script)
@@ -302,7 +357,7 @@ telekit.Server(BOT_TOKEN).polling()
 - Jinja template engine
 
 <details>
-  <summary>Click to see what you can do with the DSL</summary>
+  <summary>🎆 Click to see what you can do with the DSL</summary>
   <table>
     <tr>
       <td><img src="./docs/images/telekit_example_7.jpg" alt="Telekit Example 7" width="300"></td>
@@ -315,7 +370,8 @@ telekit.Server(BOT_TOKEN).polling()
   </table>
 </details>
 
-You can find a [full quiz example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md) and [DSL reference](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) in the repository.
+> [!TIP]
+> You can find a [full quiz example](https://github.com/Romashkaa/telekit/blob/main/docs/examples/complete_hotel.md) and [DSL reference](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) in the repository.
 
 ### Traits
 

{telekit-2.4.0b0 → telekit-2.5.0}/telekit/__init__.py

@@ -22,12 +22,16 @@ from ._trait import Trait
 from ._chain import Chain
 from ._callback_query_handler import CallbackQueryHandler
 from .server import Server, example
+from ._inline_keyboard import InlineKeyboard
+from ._reply_keyboard import ReplyKeyboard
+from ._text_builder import TextBuilder
 from ._snapvault import Vault
 from ._chapters import chapters
 from ._user import User
 from ._telekit_dsl.telekit_dsl import TelekitDSL
 from ._telekit_dsl.mixin import DSLHandler, InstanceDSLHandler
 from ._logger import enable_file_logging
+from .chat import Chat
 
 from . import senders
 from . import types
@@ -39,6 +43,8 @@ from . import utils
 from . import traits
 from . import debug
 from . import scheduler
+from . import chat
+from . import html_text
 
 Styles = styles.Styles
 
@@ -54,16 +60,23 @@ __all__ = [
     "inline_buttons",
     "dices",
     "scheduler",
+    "chat",
+    "html_text",
 
     "Styles",
     "User",
 
-    "Server", 
+    "Server",
+    "Chat",
     "Chain", 
     "Trait",
     "Handler", 
     "CallbackQueryHandler",
 
+    "InlineKeyboard",
+    "ReplyKeyboard",
+    "TextBuilder",
+
     "TelekitDSL",
     "DSLHandler",
     "InstanceDSLHandler",