telekit 2.3.0b3__tar.gz → 2.4.0__tar.gz

telekit-2.4.0/PKG-INFO

@@ -0,0 +1,672 @@
+Metadata-Version: 2.4
+Name: telekit
+Version: 2.4.0
+Summary: Declarative, developer-friendly library for building Telegram bots
+Home-page: https://github.com/Romashkaa/telekit
+Author: romashka
+Author-email: notromashka@gmail.com
+License: GPLv3
+Project-URL: GitHub, https://github.com/Romashkaa/telekit
+Project-URL: Telegram, https://t.me/TelekitLib
+Keywords: telegram bot api declarative tools bot-api
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: charset_normalizer==3.4.2
+Requires-Dist: Jinja2==3.1.6
+Requires-Dist: pyTelegramBotAPI==4.31.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+![TeleKit](https://github.com/Romashkaa/images/blob/main/TeleKitWide.png?raw=true)
+
+[![PyPI](https://img.shields.io/pypi/v/telekit.svg)](https://pypi.org/project/telekit/)
+[![Python](https://img.shields.io/pypi/pyversions/telekit.svg)](https://pypi.org/project/telekit/)
+[![PyPI Downloads](https://static.pepy.tech/badge/telekit)](https://pepy.tech/project/telekit)
+
+# Telekit
+
+**Telekit** is a declarative, developer-friendly library for building Telegram bots. It gives developers a dedicated Sender for composing and sending messages and a Chain for handling dialogue between the user and the bot. The library also handles inline keyboards and callback routing automatically, letting you focus on the bot's behavior instead of repetitive tasks.
+
+```py
+import telekit
+
+class MyStartHandler(telekit.Handler):
+    @classmethod
+    def init_handler(cls):
+        cls.on.command('start').invoke(cls.handle_start)
+
+    def handle_start(self):
+        self.chain.sender.set_text("Hello!")
+        self.chain.sender.set_photo("robot.png")
+        self.chain.send()
+
+telekit.Server("BOT_TOKEN").polling()
+```
+
+> Send "Hello!" with a photo on `/start`
+
+Telekit comes with a [built-in DSL](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md), allowing developers to create fully interactive bots with minimal code. It also integrates [**Jinja**](https://github.com/Romashkaa/telekit/blob/main/docs/examples/jinja_engine.md), giving you loops, conditionals, expressions, and filters to generate dynamic content.
+
+```js
+@ main {
+    title   = "🎉 Fun Facts Quiz";
+    message = "Test your knowledge with 10 fun questions!";
+
+    buttons {
+        question_1("Start Quiz");
+    }
+}
+```
+
+> 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.
+
+**Key features:**  
+- Declarative bot logic with **chains** for effortless handling of complex conversations
+- [Ready-to-use DSL](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial/11_telekit_dsl.md) for FAQs and other interactive scripts
+- Automatic handling of [message formatting](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/6_styles.md) via [Sender](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/5_senders.md) and **callback routing**
+- **Deep Linking** support with type-checked [Command Parameters](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/command_trigger_parameters.md) for flexible user input
+- Built-in **Permission** and **Logging** system for user management
+- Reusable **Traits** system for pluggable, self-contained behavior modules
+- Seamless integration with [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI)
+- Fast to develop and easy-to-extend code
+
+[GitHub](https://github.com/Romashkaa/telekit)
+[PyPI](https://pypi.org/project/telekit/)
+[Telegram](https://t.me/NotRomashka)
+[Community](https://t.me/+wu-dFrOBFIwyNzc0)
+
+## Contents
+
+- 🌟 [Tutorial](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/0_tutorial.md)
+- 🎆 [Gallery](https://github.com/Romashkaa/telekit/blob/main/docs/documentation/gallery.md)
+- 👀 [Examples](https://github.com/Romashkaa/telekit/blob/main/docs/examples/examples.md)
+    - [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 (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** is a library for building Telegram bots where dialogs look like normal method calls. No bulky state machines. No scattered handlers.
+
+The idea is simple: you point to the next step — Telekit calls it when the user replies.
+
+### Entries
+
+No state machines. Just tell Telekit which method should handle the next user message.
+
+```py
+def handle(self):
+    self.chain.sender.set_text("👋 Hello! What is your name?")
+    self.chain.set_entry_text(self.handle_name)
+    self.chain.send()
+
+def handle_name(self, name: str):
+    self.chain.sender.set_text(f"Nice to meet you, {name}!")
+    self.chain.send()
+```
+
+The `handle` method sends a message and registers `handle_name` as the next step using `set_entry_text`. When the user replies, Telekit automatically calls `handle_name` and passes the user's message as a plain `str` argument.
+
+> That's it. No enums. No manual state tracking. No boilerplate.
+
+### Inline Keyboards
+
+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:
+
+```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
+)
+```
+
+```
+╭──────────┬──────────┬──────────╮
+│   One    │   Two    │  Three   │
+├──────────┴──┬───────┴──────────┤
+│    Four     │       Five       │
+╰─────────────┴──────────────────╯
+```
+
+**Need more control?**
+
+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)
+)
+```
+
+```
+╭──────────┬──────────╮
+│    -     │    +     │
+├──────────┴──────────┤
+│       ↺ 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
+
+Telekit can parse and validate command parameters for you.
+
+```py
+from telekit.parameters import *
+
+class GreetHandler(telekit.Handler):
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.on.command("greet", params=[Int(), Str()]).invoke(cls.handle)
+
+    def handle(self, age: int | None = None, name: str | None = None):
+        if age is None or name is None:
+            self.chain.sender.set_text("Usage: /greet <age> <name>")
+        else:
+            self.chain.sender.set_text(f"Hello, {name}! You are {age} years old. Next year you'll turn {age + 1} 😅")
+        self.chain.send()
+```
+
+Now `/greet 64 "Alice Reingold"` or `/greet 128 Dracula` are parsed automatically.
+
+> [!NOTE]
+> If arguments are invalid or missing, you simply receive `None` and decide how to respond.
+
+### Dialogue
+
+Dialogs are built as a chain of steps. Each method waits for the user before continuing.
+
+```py
+class DialogueHandler(telekit.Handler):
+
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.on.text("hello", "hi", "hey").invoke(cls.handle_hello)
+
+    def handle_hello(self) -> None:
+        self.chain.sender.set_text("👋 Hello! What is your name?")
+        if self.user.first_name:
+            self.chain.set_entry_suggestions([self.user.first_name])
+        self.chain.set_entry_text(self.handle_name)
+        self.chain.send()
+
+    def handle_name(self, name: str) -> None:
+        self.user_name = name
+        self.chain.sender.set_text("Nice! How are you feeling today?")
+        self.chain.set_entry_text(self.handle_feeling)
+        self.chain.send()
+
+    def handle_feeling(self, feeling: str) -> None:
+        self.chain.sender.set_text(f"Got it, {self.user_name.title()}! You feel: {feeling}")
+        self.chain.set_inline_keyboard({"↺ Restart": self.handle_hello})
+        self.chain.send()
+```
+
+How it works:
+
+- The handler reacts to "hello", "hi", or "hey" (lowercase, UPPERCASE, or mixed).
+- `handle_hello` asks for the user's name.
+- `set_entry_suggestions` attaches the user's Telegram `first_name` as a suggestion button.
+- `handle_name` stores the name in `self.user_name`.
+- `handle_feeling` completes the flow and adds a `"↺ Restart"` button that routes back to the beginning.
+
+It looks like regular Python. And reads like it too.
+
+### Sender
+
+Want to add an image, document or an effect in a single line?
+
+```python
+self.chain.sender.set_effect(Effect.HEART) # Add effect to message. Use enum or string
+self.chain.sender.set_photo("robot.png") # Attach photo. URL, file_id, or path
+self.chain.sender.set_document("README.md") # Attach document. URL, file_id, or path
+self.chain.sender.set_text_as_document("Hello, this is a text document!") # Convert string to text document
+self.chain.sender.send_chat_action(ChatAction.TYPING) # Send chat action. Use enum or string
+```
+
+> [!NOTE]
+> Telekit automatically decides whether to use `bot.send_message` or `bot.send_photo` based on the content
+
+### Styles
+
+Telekit lets you describe formatting as objects instead of writing raw HTML or Markdown.
+
+```py
+from telekit.styles import *
+
+def handle(self) -> None:
+    self.chain.sender.set_text(
+        Bold("Text style examples:\n"),
+        Stack(
+            Bold("Bold text"),
+            Italic("Italic text"),
+            Bold(Italic("Bold + italic")),
+            Link("Link", url="https://example.com"),
+            BotLink("Deep link", username="MyBot", start="promo_42"),
+            start="- {{index}}. ",
+            sep=".\n",
+        )
+    )
+    self.chain.send()
+```
+
+You describe structure. Telekit generates HTML or MarkdownV2 automatically:
+
+```html
+<b>Text style examples:</b>
+
+- 1. <b>Bold text</b>.
+- 2. <i>Italic text</i>.
+- 3. <b><i>Bold + italic</i></b>.
+- 4. <a href="https://example.com">Link</a>.
+- 5. <a href="https://t.me/MyBot?start=promo_42">Deep link</a>
+```
+
+No manual escaping. No broken formatting because of one missing character.
+
+### Telekit DSL
+
+If you prefer not to write dialog logic in Python, you can use the built-in DSL with Jinja support.
+
+```py
+import telekit
+
+class QuizHandler(telekit.DSLHandler):
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.analyze_string(script)
+        cls.on.command("start").invoke(cls.start_script)
+
+script = """
+$ timeout {
+    time = 20; // 20 sec.
+}
+
+@ main {
+    title   = "🎉 Fun Facts Quiz";
+    message = "Test your knowledge with 10 fun questions!";
+
+    buttons {
+        next("Start Quiz");
+    }
+}
+
+@ question_1 {
+    title   = "🐶 Question 1";
+    message = "Which animal is the fastest on land?";
+    buttons {
+        _lose("Elephant");
+        next("Cheetah");       // correct answer
+        _lose("Horse");
+        _lose("Lion");
+    }
+}
+
+/* ... */
+"""
+
+telekit.Server(BOT_TOKEN).polling()
+```
+
+**Key features of the Telekit DSL:**
+
+- Scene-based architecture
+- Anonymous scenes
+- Automatic navigation stack management
+- Input handling
+- Images support and link buttons
+- Template variables
+- Custom variables
+- Hooks (Python API integration)
+- Jinja template engine
+
+<details>
+  <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>
+      <td><img src="./docs/images/telekit_example_8.jpg" alt="Telekit Example 8" width="300"></td>
+    </tr>
+    <tr>
+      <td><img src="./docs/images/telekit_example_6.jpg" alt="Telekit Example 7" width="300"></td>
+      <td><img src="./docs/images/telekit_example_1.jpg" alt="Telekit Example 8" width="300"></td>
+    </tr>
+  </table>
+</details>
+
+> [!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
+
+Traits are reusable behavior modules you can mix into any handler.
+
+This example demonstrates the simplest way to use the built-in CalendarPick trait. It allows a user to pick a date from an inline calendar and handles the result via a callback.
+
+```py
+from telekit.traits import CalendarPick
+
+class CalendarHandler(CalendarPick, telekit.Handler):
+
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.on.command("calendar").invoke(cls.handle)
+
+    def handle(self) -> None:
+        self.chain.sender.set_title("📅 Choose a date")
+        self.chain.sender.set_message("Select any date — past or future:")
+        self.chain.sender.set_remove_text(False)
+
+        self.calendar_pick(self.handle_date) # HERE
+
+    def handle_date(self, date: datetime.date) -> None:
+        self.chain.sender.set_text(f"You picked: {date}")
+        self.chain.send()
+```
+
+<details>
+  <summary>Result</summary>
+  <table>
+    <tr>
+      <td><img src="./docs/images/calendar.png" alt="Telekit Calendar Example" width="500"></td>
+    </tr>
+  </table>
+</details>
+
+### Example Bot
+
+You can launch an example bot by **running the following code**:
+
+```py
+import telekit
+
+telekit.example(YOUR_BOT_TOKEN)
+```
+
+It includes example commands, dialogs, keyboards, and style usage.
+
+## Why Telekit
+
+- No FSM — just **chains**.
+- Declarative, behavior-focused bot logic with minimal boilerplate.
+- Automatic **callback routing** and **input handling**.
+- **Styles API** for rich text (`Bold`, `Italic`, `Links`) with **automatic escaping**.
+- Deep linking and **typed command parameters**.
+- **Built-in DSL** for menus, FAQs, and simple bots.
+- Reusable **Traits** for composable, plug-and-play behavior (for example, a built-in declarative calendar picker).
+- **Zero-code** [Obsidian Canvas](https://github.com/Romashkaa/telekit/blob/main/docs/examples/canvas_faq.md) mode.
+- Seamless integration with **pyTelegramBotAPI**.
+
+Telekit doesn't try to be everything.  
+It tries to make Telegram bot development easier.
+
+> [!TIP]
+> If you're interested and want to learn more, check out the [Tutorial](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/0_tutorial.md)
+
+---
+
+# Changes in version 2.4.0
+
+## Inline and Reply Keyboards
+
+### `chain.set_keyboard()`
+
+Universal method for attaching a keyboard to the current chain message.
+Accepts either an `InlineKeyboard` or a `ReplyKeyboard` instance.
+
+```python
+# Inline keyboard
+self.chain.set_keyboard(
+    InlineKeyboard()
+        .add_callback("Click Me!", self.handle)
+    .row()
+        .add_link("YouTube", "https://youtube.com")
+)
+
+# Reply keyboard
+self.chain.set_keyboard(
+    ReplyKeyboard(one_time_keyboard=True)
+        .add_text("Hello!")
+        .add_text("Hi")
+    .row()
+        .add_contact("📱 Share phone")
+)
+```
+
+> [!NOTE]
+> Inline and reply keyboards are mutually exclusive in Telegram.
+> Only one keyboard can be displayed at a time per message.
+> Passing an `InlineKeyboard` attaches buttons directly to the message;
+> passing a `ReplyKeyboard` replaces the user's system keyboard below the input field.
+
+### `InlineKeyboard`
+
+Fluent builder for Telegram inline keyboards. Supports all standard inline button types, conditional rendering via `when=`, and row/column layout helpers.
+
+**Layout helpers**
+
+| **Method**     | **Description** |
+| -------------- | --------------- |
+| `row()`        | Finalize the current row and start a new one. |
+| `column()`     | Every subsequent button gets its own row. Alias for `grid(1)`. |
+| `column_end()` | Exit column mode and flush the current row. Alias for `grid_end()`. |
+| `grid(width)`  | Every subsequent button is automatically split into rows of `width` buttons. |
+| `grid_end()`   | Exit grid mode and flush the current row. |
+
+**Button methods**
+
+| **Method** | **Description** |
+|------------|-----------------|
+| `add(text, button, when=)` | Attach any `InlineButton` instance. |
+| `add_callback(text, callback, pass_args, pass_kwargs, answer_text, answer_as_alert, style, when=)` | Button that fires a callback function. |
+| `add_link(text, url, style, when=)` | Button that opens a URL or `tg://` link. |
+| `add_webapp(text, url, style, when=)` | Button that opens a Telegram Mini App. |
+| `add_suggest(text, suggestion, style, strict, when=)` | Button that simulates the user sending a message. |
+| `add_copy(text, copy_text, style, strict, when=)` | Button that copies text to the clipboard. |
+| `add_static(text, style, when=)` | Decorative button with no action. |
+| `add_alert(text, alert_text, persistent, style, when=)` | Button that shows a popup alert dialog. |
+| `add_notification(text, notification_text, persistent, style, when=)` | Button that shows a brief top-of-chat notification. |
+| `add_invoke(text, obj, invoke, pass_args, pass_kwargs, answer_text, answer_as_alert, style, when=)` | Button that calls a named method on an arbitrary object. |
+
+**Bulk helpers**
+
+| **Method** | **Description** |
+|------------|-----------------|
+| `extend(buttons, column=, when=)` | Add multiple buttons from a `dict[str, InlineButton \| None]` or `list[str]`. |
+| `extend_rows(*rows, when=)` | Append one or more pre-built `list[tuple[str, InlineButton]]` rows. |
+
+All button methods accept a `style` parameter: `"danger"` (red), `"success"` (green), or `"primary"` (blue).
+
+```python
+InlineKeyboard()
+    .add_link("YouTube", "https://youtube.com")
+    .add_copy("Copy Me", "copied!")
+    .add_alert("Info", "This is an alert")
+.row()
+    .add_callback("Click Me!", self.handle)
+.column()
+    .add_link("A", "https://example.com")
+    .add_callback("B", self.handle_b)
+.column_end()
+.extend({"Alert": AlertButton("Hi!"), "Notify": NotificationButton("Hey")}, column=True)
+```
+
+### `ReplyKeyboard`
+
+Fluent builder for Telegram reply keyboards. Mirrors the `InlineKeyboard` layout API (`row`, `column`, `column_end`, `extend`, `extend_rows`).
+
+**Constructor parameters**
+
+| **Parameter** | **Default** | **Description** |
+|---|---|---|
+| `resize_keyboard` | `True` | Shrink the keyboard to fit its buttons. |
+| `one_time_keyboard` | `False` | Hide the keyboard after the first press. |
+| `input_field_placeholder` | `None` | Placeholder text shown while the keyboard is active (max 64 chars). |
+| `selective` | `False` | Show only to mentioned users or the original sender. |
+| `is_persistent` | `False` | Always show the keyboard; do not collapse it to an icon. |
+
+**Button methods**
+
+| **Method** | **Description** |
+|---|---|
+| `add(text, button, when=)` | Attach any `ReplyButton` instance. |
+| `add_text(text, when=)` | Plain text button — sends the label as a message. |
+| `add_contact(text, when=)` | Prompts the user to share their phone number (private chats only). |
+| `add_location(text, when=)` | Prompts the user to share their geolocation (private chats only). |
+| `add_poll(text, poll_type, when=)` | Opens the poll creation dialog; `poll_type` can be `"quiz"`, `"regular"`, or `None`. |
+| `add_webapp(text, url, when=)` | Opens a Telegram Mini App. |
+| `add_request_user(text, request_id, user_is_bot, user_is_premium, when=)` | Lets the user pick a Telegram user; result returned as a service message. |
+| `add_request_chat(text, request_id, chat_is_channel, chat_is_forum, chat_has_username, chat_is_created, user_administrator_rights, bot_administrator_rights, bot_is_member, when=)` | Lets the user pick a chat; result returned as a service message. |
+
+```python
+ReplyKeyboard(input_field_placeholder="Choose:", one_time_keyboard=True)
+    .add_text("Hello!")
+    .add_text("Hi")
+.row()
+    .add_contact("📱 Phone")
+    .add_location("📍 Location")
+    .add_poll("📊 Poll")
+.row()
+    .add_request_user("Pick user", request_id=1)
+    .add_request_chat("Pick chat", request_id=2)
+```
+
+## 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.                                                         |
+
+## Scheduler
+
+- Added `every` decorator for scheduling functions in a background daemon thread.
+- Implemented `PeriodicTask` class to manage periodic execution and error handling.
+
+## Others
+
+- Enhanced `Debug` class with callback query tracing functionality.
+- Refactored `BaseSender` to use `send_or_handle_error`.