telekit 2.0.1__tar.gz → 2.1.0__tar.gz

{telekit-2.0.1/telekit.egg-info → telekit-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.0.1
+Version: 2.1.0
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -62,7 +62,7 @@ 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**, giving you loops, conditionals, expressions, and filters to generate dynamic content.
+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 {
@@ -378,68 +378,20 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.0.1
-
-## Obsidian Canvas Mode *(Beta)*
-Build bots visually — no DSL required. Design your dialog flow as a flowchart in Obsidian and connect it to Telekit with a single method call.
-
-- Added `analyze_canvas()` to `DSLHandler` — loads a `.canvas` file as an executable model
-
-## Styles Improvements
-The style system has been rewritten from the ground up. Previously, automatic escaping was quite unpredictable — users couldn't always tell when a string would be escaped or not. That's over.
-
-- Migrated markdown rendering to **MarkdownV2**
-- Added `Stack` style for structured list rendering
-- Added `Mention` style
-- Renamed `Sanitize` to `Escape`
-- Renamed `NoSanitize` to `Raw`
-- Added `utils.sanitize_markdown()` — escapes all MarkdownV2 special characters outside valid entities
-- Added `utils.adapt_markdown()` — converts `**bold**` / `*italic*` to Telegram-compatible format
-- Added `utils.telegramify_markdown()` — convenience pipeline: adapt + sanitize
-- `StyleFormatter` renamed to `TextEntity`
-
-## Inline Keyboards
-
-Inline keyboards got a proper type system. Previously, any string value in the keyboard dict was treated as a link. Now every button type is explicit.
-
-- Introduced `InlineButton` base class with subclasses:
-  `LinkButton`, `WebAppButton`, `SuggestButton`, `CopyTextButton`, `CallbackButton`
-- `CallbackButton` — pass arguments to callbacks and set visual style
-- Added `ButtonStyle` enum — style your inline buttons (Bot API 9.4)
-- Added `inline_choice` / `set_inline_choice` methods
-- `set_entry_suggestions` now warns when Telegram Bot API limits are exceeded
-- It's no longer pass `Message` object to callbacks
-- Reduced closure size and improved callback performance
-
-## Chain Improvements
-- Added `set_break_only_on_match()` — control whether chain interrupts only on valid handler match, not random input
-- Added `set_break_on_commands()` — control whether commands take priority over entry handlers
-- Improved file extension validation via **pathlib**
-- `entry_*` handlers no longer pass `Message` by default — use `include_message=True` to restore
-
-## CallbackQueryHandler
-- Callbacks now invoked directly — no virtual message conversion, faster response times
-- Native alert support for expired or inactive buttons
-- Added `set_invalid_data_answer()` and `set_button_is_no_active_answer()` for global customization
-
-## DSL Improvements
-- `jinja_env` is now private — use `get_jinja_env()` instead
-- `TelekitDSL` class:
-  - All `from_*` factory methods now use `type()` for class creation
-
-## Fixes
-- Fixed one-time trigger bug — triggers like `on.text` now fire reliably across multiple messages while a chain timeout is active
-
-## Other
-- Added `utils.read_token()` and `utils.read_canvas_path()` — clean helpers for reading credentials from files
-- Added `utils.format_file_size()`
-- Added `set_license_text` to senders
-- Added `format_size` to `TextDocument`
-- Added `TelekitState` class
-- Bumped `pyTelegramBotAPI` to **v4.31.0**
-- Added GPL v3 License
-
-## 🚀 Upcoming
-
-- New triggers: `document`, `text_document`
-- Telekit DSL: shorter notation and button attributes with style, alert, ... support
+# Changes in version 2.1.0
+
+## Trigger Improvements
+
+| **Name** | **Description** |
+|----------|-----------------|
+| `on.text` | *BugFix:* Commands are no longer matched as text triggers. |
+
+- Internal refactor of the `On` class.
+
+## New Utils
+
+| **Name** | **Description** |
+|----------|-----------------|
+| `make_bot_link` | Builds a `t.me` URL to a bot with an optional deep-link payload. |
+| `make_user_link` | Builds a `t.me` URL to a user with an optional pre-filled message. |
+| `make_qrcode` | Generates a [QR code](./docs/examples/qr_gen.md) URL from any text or link. |

{telekit-2.0.1 → telekit-2.1.0}/README.md

@@ -26,7 +26,7 @@ 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**, giving you loops, conditionals, expressions, and filters to generate dynamic content.
+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 {

{telekit-2.0.1 → telekit-2.1.0}/telekit/_buildtext/styles.py

@@ -21,6 +21,8 @@ from urllib.parse import quote
 
 import telebot.formatting
 
+import telekit.utils
+
 from .formatter import TextEntity, EasyTextEntity, StaticTextEntity, EasyTextEntityWithPostRender, Group
 
 
@@ -516,20 +518,10 @@ class UserLink(Link):
     `Documentation <https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/6_styles.md>`_ · on GitHub
     """
     def __init__(self, *content, username: str, text: str | None = None, escape: bool = True, sep: Union["TextEntity", str] = ""):
-        url: str = self.gen_link(username, text)
+        url: str = telekit.utils.make_user_link(username, text)
 
         super().__init__(*content, url=url, escape=escape, sep=sep)
 
-    @staticmethod
-    def gen_link(username: str, text: str | None = None) -> str:
-        username = username.lstrip("@")
-
-        if text is None:
-            return f"https://t.me/{username}"
-        else:
-            encoded_text: str = quote(text, safe="")
-            return f"https://t.me/{username}?text={encoded_text}"
-
 
 class BotLink(Link):
     """
@@ -559,20 +551,10 @@ class BotLink(Link):
     """
     
     def __init__(self, *content, username: str, start: str | None = None, escape: bool = True, sep: Union["TextEntity", str] = ""):
-        url: str = self.gen_link(username, start)
+        url: str = telekit.utils.make_bot_link(username, start)
 
         super().__init__(*content, url=url, escape=escape, sep=sep)
 
-    @staticmethod
-    def gen_link(username: str, start: str | None = None) -> str:
-        username = username.lstrip("@")
-
-        if start is None:
-            return f"https://t.me/{username}"
-        else:
-            encoded_start = quote(start, safe="")
-            return f"https://t.me/{username}?start={encoded_start}"
-
 class EncodeURL(StaticTextEntity):
     """
     URL-encodes the provided content string.

{telekit-2.0.1 → telekit-2.1.0}/telekit/_on.py

@@ -23,6 +23,7 @@ import shlex
 import re
 
 import telebot
+import telebot.types
 
 from . import parameters
 from ._logger import logger
@@ -32,7 +33,7 @@ if typing.TYPE_CHECKING:
     from telekit._handler import Handler # only for type hints
 
 # --------------------------------------------------------
-# Event Handler
+# Invoker
 # --------------------------------------------------------
 
 class Invoker:
@@ -40,12 +41,11 @@ class Invoker:
     • [See Documentation on GitHub](https://github.com/Romashkaa/telekit/blob/main/docs/tutorial2/3_triggers.md)
     """
 
-    def __init__(self, decorator: Callable[[Callable], Callable | None], handler: type["Handler"]):
+    def __init__(self, registrar: Callable[[Callable], Callable | None], handler: type["Handler"]):
         """
-        Wraps an existing decorator (like cls.on_text) 
-        to add callback/trigger functionality.
+        Wraps a registrar to add callback/trigger functionality.
         """
-        self._decorator: Callable = decorator
+        self._register: Callable = registrar
         self._Handler = handler
 
     def __call__(self, func: Callable):
@@ -58,7 +58,7 @@ class Invoker:
             cls(message).handle(*args, **kwargs)
         ```
         """
-        return self._decorator(func)
+        return self._register(func)
 
     def invoke(self, callback: Callable, pass_args: bool = True):
         """
@@ -74,10 +74,10 @@ class Invoker:
             else:
                 callback(self._Handler(message))
 
-        self._decorator(handler)
+        self._register(handler)
 
 # --------------------------------------------------------
-# On Handlers
+# Triggers
 # --------------------------------------------------------
 
 class On:
@@ -149,7 +149,7 @@ class On:
         Returns:
             Invoker: An invoker object allowing `.invoke()` or @decorator-style usage.
         """
-        original_decorator = self.bot.message_handler(
+        register_trigger = self.bot.message_handler(
             commands=commands,
             regexp=regexp,
             func=func,
@@ -159,18 +159,18 @@ class On:
         )
 
         def decorator(handler: Callable[..., typing.Any]):
-            def wrapped(message):
+            def trigger(message):
                 if whitelist is not None and message.chat.id not in whitelist:
                     return
                 return handler(message)
 
-            return original_decorator(wrapped)
+            return register_trigger(trigger)
 
         return Invoker(decorator, self.handler)
 
     def text(
             self, 
-            *patterns: str, 
+            *patterns: str,
             chat_types: list[str] | None = None,
             whitelist: list[int] | None = None
         ):
@@ -225,11 +225,14 @@ class On:
                     re.IGNORECASE
                 ))
 
-            def _filter_func(message: telebot.types.Message) -> bool:
-                if whitelist is not None and message.chat.id not in whitelist:
+            def _filter(message: telebot.types.Message) -> bool:
+                if not message.text:
                     return False
                 
-                if not message.text:
+                if message.text.startswith("/"):
+                    return False
+                
+                if whitelist is not None and message.chat.id not in whitelist:
                     return False
                 
                 for cregex in compiled:
@@ -239,25 +242,37 @@ class On:
                     
                 return False
 
-            def decorator(func: Callable):
-                @self.bot.message_handler(func=_filter_func, chat_types=chat_types)
-                def _(message):
+            def register(func: Callable): # pyright: ignore[reportRedeclaration]
+                @self.bot.message_handler(func=_filter, chat_types=chat_types)
+                def trigger(message):
                     for cregex in compiled:
                         match = cregex.match(message.text)
                         if match:
                             func(message, **match.groupdict())
                             return
-                        
-                return func
+
+                return trigger
         else:
-            def decorator(func: Callable):
-                @self.bot.message_handler(content_types=["text"], chat_types=chat_types)
-                def _(message):
-                    if whitelist is not None and message.chat.id not in whitelist:
-                        return
-                    func(message)
-                return func
-        return Invoker(decorator, self.handler)
+            def _filter(message: telebot.types.Message) -> bool:
+                if not message.text:
+                    return False
+                
+                if message.text.startswith("/"):
+                    return False
+                
+                if whitelist is not None and message.chat.id not in whitelist:
+                    return False
+
+                return True
+            
+            def register(func: Callable):
+                return self.bot.message_handler(
+                    content_types=["text"],
+                    func=_filter, 
+                    chat_types=chat_types
+                )(func)
+
+        return Invoker(register, self.handler)
     
     def command(
         self,
@@ -305,14 +320,13 @@ class On:
         Returns:
             Invoker: An invoker object allowing `.invoke()` or decorator-style usage.
         """
-        original_decorator = self.bot.message_handler(
-            commands=[c.lstrip("/") for c in commands],
-            chat_types=chat_types,
-            **kwargs
-        )
-
-        def decorator(handler: Callable[..., typing.Any]):
-            def wrapped(message):
+        def register(handler: Callable[..., typing.Any]):
+            @self.bot.message_handler(
+                commands=[c.lstrip("/") for c in commands],
+                chat_types=chat_types,
+                **kwargs
+            )
+            def trigger(message):
                 if whitelist is not None and message.chat.id not in whitelist:
                     return
                 if params:
@@ -320,9 +334,9 @@ class On:
                 
                 return handler(message)
 
-            return original_decorator(wrapped)
+            return trigger
 
-        return Invoker(decorator, self.handler)
+        return Invoker(register, self.handler)
     
     def _analyze_params(self, text: str, types: list[parameters.Parameter]) -> list:
         values: list[str] = shlex.split(text)[1:] # skip the command name
@@ -380,21 +394,20 @@ class On:
         Returns:
             Invoker: An invoker object allowing `.invoke()` or decorator-style usage.
         """
-        original_decorator = self.bot.message_handler(
-            regexp=regexp,
-            chat_types=chat_types,
-            **kwargs
-        )
-
-        def decorator(handler: Callable[..., typing.Any]):
-            def wrapped(message):
+        def register(handler: Callable[..., typing.Any]):
+            @self.bot.message_handler(
+                regexp=regexp,
+                chat_types=chat_types,
+                **kwargs
+            )
+            def trigger(message):
                 if whitelist is not None and message.chat.id not in whitelist:
                     return
                 return handler(message)
 
-            return original_decorator(wrapped)
+            return trigger
 
-        return Invoker(decorator, self.handler)
+        return Invoker(register, self.handler)
     
     def photo(
         self,
@@ -422,8 +435,7 @@ class On:
         ```
         ---
 
-        Triggers:
-            - By receiving a photo message (content_type="photo")
+        Triggers when receive a photo (content_type="photo")
 
         Filters:
             - By chat type(s) (via `chat_types` argument)
@@ -438,21 +450,20 @@ class On:
         Returns:
             Invoker: An invoker object allowing `.invoke()` or decorator-style usage.
         """
-        original_decorator = self.bot.message_handler(
-            content_types=["photo"],
-            chat_types=chat_types,
-            **kwargs
-        )
-
-        def decorator(handler: Callable[..., typing.Any]):
-            def wrapped(message):
+        def register(handler: Callable[..., typing.Any]):
+            @self.bot.message_handler(
+                content_types=["photo"],
+                chat_types=chat_types,
+                **kwargs
+            )
+            def trigger(message):
                 if whitelist is not None and message.chat.id not in whitelist:
                     return
                 return handler(message)
 
-            return original_decorator(wrapped)
+            return trigger
 
-        return Invoker(decorator, self.handler) 
+        return Invoker(register, self.handler) 
     
     def func(
         self,
@@ -508,17 +519,20 @@ class On:
                 return False
             return bool(func(message))
 
-        original_decorator = self.bot.message_handler(
-            func=_filter,
-            chat_types=chat_types,
-            **kwargs
-        )
-
         def decorator(handler: Callable[..., typing.Any]):
             if not invoke_args and not invoke_kwargs:
-                return original_decorator(handler)
-
-            def _wrap_args(message, *args, **kwargs):
+                return self.bot.message_handler(
+                    func=_filter,
+                    chat_types=chat_types,
+                    **kwargs
+                )(handler)
+
+            @self.bot.message_handler(
+                func=_filter,
+                chat_types=chat_types,
+                **kwargs
+            )
+            def trigger(message, *args, **kwargs):
                 final_args = args
                 final_kwargs = kwargs
 
@@ -530,6 +544,6 @@ class On:
 
                 return handler(message, *final_args, **final_kwargs)
 
-            return original_decorator(_wrap_args)
+            return trigger
 
         return Invoker(decorator, self.handler)

telekit-2.1.0/telekit/_version.py

@@ -0,0 +1 @@
+__version__ = "2.1.0"

{telekit-2.0.1 → telekit-2.1.0}/telekit/example/example_handlers/__init__.py

@@ -11,5 +11,6 @@ from . import (
     quiz,
     hotel,
     complete_hotel,
-    text_document
+    text_document,
+    qr
 )

{telekit-2.0.1 → telekit-2.1.0}/telekit/example/example_handlers/on_text.py

@@ -13,6 +13,8 @@ class OnTextHandler(telekit.Handler):
             "I'm {age} years old"
         ).invoke(cls.handle_name_age)
 
+        cls.on.text().invoke(cls.handle)
+
         cls.on.command("on_text").invoke(cls.handle)
             
     # ------------------------------------------

telekit-2.1.0/telekit/example/example_handlers/qr.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+import telekit
+from telekit.styles import Quote
+
+
+class QRCode:
+    def __init__(self) -> None:
+        self.text:    str | None = None
+        self.caption: str | None = None
+
+    def get_url(self) -> str:
+        kwargs: dict[str, Any] = {"text": self.text or "Example"}
+        if self.caption is not None:
+            kwargs["caption"] = self.caption
+        return telekit.utils.make_qrcode(**kwargs)
+
+
+class QRHandler(telekit.Handler):
+
+    @classmethod
+    def init_handler(cls) -> None:
+        cls.on.command("start").invoke(cls.handle)
+
+    def handle(self) -> None:
+        self.qrcode = QRCode()
+        self.display_qrcode()
+
+    # ── entry points ──────────────────────────────────────────────
+
+    def change_text(self) -> None:
+        self.chain.sender.set_title("⌨️ Enter text")
+        self.chain.sender.set_message("Send any text or URL to encode into a QR code")
+        self.chain.set_entry_text(self.set_text, delete_user_response=True)
+
+        keyboard: dict[str, Any] = {}
+        keyboard["« Back"] = self.display_qrcode
+
+        if self.qrcode.text:
+            keyboard["✕ Remove"] = self.set_text
+
+        self.chain.set_inline_keyboard(keyboard, row_width=2)
+        self.chain.edit()
+
+    def change_caption(self) -> None:
+        self.chain.sender.set_title("⌨️ Enter caption")
+        self.chain.sender.set_message("Send a caption to display below the QR code")
+        self.chain.set_entry_text(self.set_caption, delete_user_response=True)
+
+        keyboard: dict[str, Any] = {}
+        keyboard["« Back"] = self.display_qrcode
+
+        if self.qrcode.caption:
+            keyboard["✕ Remove"] = self.set_caption
+
+        self.chain.set_inline_keyboard(keyboard, row_width=2)
+        self.chain.edit()
+
+    # ── entry handlers ──────────────────────────────────────────────────
+
+    def set_text(self, text: str | None = None) -> None:
+        self.qrcode.text = text
+        self.display_qrcode()
+
+    def set_caption(self, caption: str | None = None) -> None:
+        self.qrcode.caption = caption
+        self.display_qrcode()
+
+    # ── display QR code ───────────────────────────────────────────────────
+
+    def display_qrcode(self) -> None:
+        url: str = self.qrcode.get_url()
+
+        self.chain.sender.set_photo(url)
+        self.chain.sender.set_text(
+            Quote(url, expandable=True),
+            "Use the buttons below to edit the QR code:"
+        )
+        self.chain.set_inline_keyboard(
+            {
+                "✏️ Edit Text": self.change_text,
+                "✏️ Edit Caption" if self.qrcode.caption else "➕ Add Caption": self.change_caption,
+            },
+            row_width=2
+        )
+        self.chain.edit()

{telekit-2.0.1 → telekit-2.1.0}/telekit/example/example_handlers/start.py

@@ -22,11 +22,15 @@ class StartHandler(telekit.Handler):
                 "🧮 Counter":            "CounterHandler",
                 "🧙‍♀️ Spells":              "SpellsHandler",
                 "⌨️ Entry":                "EntryHandler",
+
                 "📚 Telekit DSL Examples":   "DSLExampleHandler",
+                
                 "📖 Pages":                "PagesHandler",
                 "🦻 On Text":             "OnTextHandler",
                 "📄 File Info":     "TextDocumentHandler",
-            }, row_width=[3, 1, 3]
+                
+                "🖼️ QR Editor":               "QRHandler",
+            }, row_width=[3, 1, 3, 1]
         )
         def handle_response(handler: str):
             self.handoff(handler).handle()

{telekit-2.0.1 → telekit-2.1.0}/telekit/utils.py

@@ -1,5 +1,8 @@
 import re
+
 from pathlib import Path
+from urllib.parse import urlencode, quote
+from typing import Literal
 
 ROOT_DIR = Path(__file__).resolve().parent  # telekit/
 
@@ -100,7 +103,6 @@ def read_token(path: str = "token.txt") -> str:
         token, *_ = first_line.split()
         return token
 
-
 def read_canvas_path(path: str = "canvas_path.txt") -> str:
     """
     Read the ``.canvas`` file path from a file.
@@ -115,7 +117,145 @@ def read_canvas_path(path: str = "canvas_path.txt") -> str:
     """
     with open(path) as f:
         return f.readline().strip()
+    
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Link Generators
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+
+def make_bot_link(botname: str, start: str | None = None) -> str:
+    """Return a t.me link to a bot.
+
+    >>> make_bot_link("UserNameOfBot")
+    "https://t.me/UserNameOfBot"
+
+    >>> make_bot_link("UserNameOfBot", start="Hello!")
+    "https://t.me/UserNameOfBot?start=Hello%21"
+
+    Args:
+        botname: Bot username with or without leading '@'.
+        start:   Optional deep-link payload appended as ?start=.
+
+    Returns:
+        A t.me URL string.
+    """
+    botname = botname.lstrip("@")
+    if start is None:
+        return f"https://t.me/{botname}"
+    encoded_start = quote(start, safe="")
+    return f"https://t.me/{botname}?start={encoded_start}"
+
+def make_user_link(username: str, text: str | None = None) -> str:
+    """Return a t.me link to a user.
+
+    >>> make_user_link("UserName")
+    "https://t.me/UserName"
+
+    >>> make_user_link("UserName", text="Hello!")
+    "https://t.me/UserName?text=Hello%21"
 
+    Args:
+        username: Telegram username with or without leading '@'.
+        text:     Optional pre-filled message text appended as ?text=.
+
+    Returns:
+        A t.me URL string.
+    """
+    username = username.lstrip("@")
+    if text is None:
+        return f"https://t.me/{username}"
+    encoded_text = quote(text, safe="")
+    return f"https://t.me/{username}?text={encoded_text}"
+
+def make_qrcode(
+    text: str,
+    *,
+    size: int | None = None,
+    margin: int | None = None,
+    dark: str | None = None,
+    light: str | None = None,
+    ec_level: Literal["L", "M", "Q", "H"] | None = None,
+    format: Literal["png", "svg", "base64"] | None = None,
+    center_image_url: str | None = None,
+    center_image_size_ratio: float | None = None,
+    center_image_width: int | None = None,
+    center_image_height: int | None = None,
+    caption: str | None = None,
+    caption_font_family: str | None = None,
+    caption_font_size: int | None = None,
+    caption_font_color: str | None = None,
+) -> str:
+    """Return a QuickChart URL that renders a QR code.
+
+    >>> make_qrcode("https://example.com")
+    'https://quickchart.io/qr?text=https%3A%2F%2Fexample.com'
+
+    >>> make_qrcode("Hello", dark="ff0000", size=300)
+    'https://quickchart.io/qr?text=Hello&size=300&dark=ff0000'
+
+    Use with sender:
+    >>> sender.set_photo(make_qrcode("https://example.com", caption="Scan Me"))
+
+    Check out the [QuickChart QR Code API](https://quickchart.io/documentation/qr-codes/)
+
+    Args:
+        text:                   Content to encode (URL or any string).
+        size:                   Width and height of the image in pixels.
+        margin:                 Whitespace around the QR image in modules.
+        dark:                   Hex color of dark cells, without '#'.
+        light:                  Hex color of light cells, without '#'.
+                                Use "0000" for a transparent background.
+        ec_level:               Error correction level — L, M, Q, or H.
+        format:                 Output format — png, svg, or base64.
+        center_image_url:       URL of an image to display in the center.
+                                Must be publicly accessible (PNG or JPG).
+        center_image_size_ratio: Float 0.0–1.0 — portion of QR area the
+                                center image occupies. Keep below ~0.3.
+        center_image_width:     Center image width in pixels.
+        center_image_height:    Center image height in pixels.
+        caption:                Caption text displayed below the QR code.
+        caption_font_family:    Font family of the caption.
+        caption_font_size:      Font size of the caption in pixels.
+        caption_font_color:     Color of the caption — name or hex.
+
+    Returns:
+        A quickchart.io URL string.
+    """
+    params: dict = {"text": text}
+
+    if size is not None: 
+        params["size"] = size
+    if margin is not None: 
+        params["margin"] = margin
+    if dark is not None: 
+        params["dark"] = dark
+    if light is not None: 
+        params["light"] = light
+    if ec_level is not None: 
+        params["ecLevel"] = ec_level
+    if format is not None: 
+        params["format"] = format
+    if center_image_url is not None: 
+        params["centerImageUrl"] = center_image_url
+    if center_image_size_ratio is not None: 
+        params["centerImageSizeRatio"] = center_image_size_ratio
+    if center_image_width is not None: 
+        params["centerImageWidth"] = center_image_width
+    if center_image_height is not None: 
+        params["centerImageHeight"] = center_image_height
+    if caption is not None: 
+        params["caption"] = caption
+    if caption_font_family is not None: 
+        params["captionFontFamily"] = caption_font_family
+    if caption_font_size is not None: 
+        params["captionFontSize"] = caption_font_size
+    if caption_font_color is not None: 
+        params["captionFontColor"] = caption_font_color
+
+    return "https://quickchart.io/qr?" + urlencode(params, quote_via=quote)
+
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
+# Markdown Sanitizing
+# ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
 # All special chars that must be escaped in MarkdownV2
 _SPECIAL = r'_*[]()~`>#+-=|{}.!' 

{telekit-2.0.1 → telekit-2.1.0/telekit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.0.1
+Version: 2.1.0
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -62,7 +62,7 @@ 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**, giving you loops, conditionals, expressions, and filters to generate dynamic content.
+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 {
@@ -378,68 +378,20 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.0.1
-
-## Obsidian Canvas Mode *(Beta)*
-Build bots visually — no DSL required. Design your dialog flow as a flowchart in Obsidian and connect it to Telekit with a single method call.
-
-- Added `analyze_canvas()` to `DSLHandler` — loads a `.canvas` file as an executable model
-
-## Styles Improvements
-The style system has been rewritten from the ground up. Previously, automatic escaping was quite unpredictable — users couldn't always tell when a string would be escaped or not. That's over.
-
-- Migrated markdown rendering to **MarkdownV2**
-- Added `Stack` style for structured list rendering
-- Added `Mention` style
-- Renamed `Sanitize` to `Escape`
-- Renamed `NoSanitize` to `Raw`
-- Added `utils.sanitize_markdown()` — escapes all MarkdownV2 special characters outside valid entities
-- Added `utils.adapt_markdown()` — converts `**bold**` / `*italic*` to Telegram-compatible format
-- Added `utils.telegramify_markdown()` — convenience pipeline: adapt + sanitize
-- `StyleFormatter` renamed to `TextEntity`
-
-## Inline Keyboards
-
-Inline keyboards got a proper type system. Previously, any string value in the keyboard dict was treated as a link. Now every button type is explicit.
-
-- Introduced `InlineButton` base class with subclasses:
-  `LinkButton`, `WebAppButton`, `SuggestButton`, `CopyTextButton`, `CallbackButton`
-- `CallbackButton` — pass arguments to callbacks and set visual style
-- Added `ButtonStyle` enum — style your inline buttons (Bot API 9.4)
-- Added `inline_choice` / `set_inline_choice` methods
-- `set_entry_suggestions` now warns when Telegram Bot API limits are exceeded
-- It's no longer pass `Message` object to callbacks
-- Reduced closure size and improved callback performance
-
-## Chain Improvements
-- Added `set_break_only_on_match()` — control whether chain interrupts only on valid handler match, not random input
-- Added `set_break_on_commands()` — control whether commands take priority over entry handlers
-- Improved file extension validation via **pathlib**
-- `entry_*` handlers no longer pass `Message` by default — use `include_message=True` to restore
-
-## CallbackQueryHandler
-- Callbacks now invoked directly — no virtual message conversion, faster response times
-- Native alert support for expired or inactive buttons
-- Added `set_invalid_data_answer()` and `set_button_is_no_active_answer()` for global customization
-
-## DSL Improvements
-- `jinja_env` is now private — use `get_jinja_env()` instead
-- `TelekitDSL` class:
-  - All `from_*` factory methods now use `type()` for class creation
-
-## Fixes
-- Fixed one-time trigger bug — triggers like `on.text` now fire reliably across multiple messages while a chain timeout is active
-
-## Other
-- Added `utils.read_token()` and `utils.read_canvas_path()` — clean helpers for reading credentials from files
-- Added `utils.format_file_size()`
-- Added `set_license_text` to senders
-- Added `format_size` to `TextDocument`
-- Added `TelekitState` class
-- Bumped `pyTelegramBotAPI` to **v4.31.0**
-- Added GPL v3 License
-
-## 🚀 Upcoming
-
-- New triggers: `document`, `text_document`
-- Telekit DSL: shorter notation and button attributes with style, alert, ... support
+# Changes in version 2.1.0
+
+## Trigger Improvements
+
+| **Name** | **Description** |
+|----------|-----------------|
+| `on.text` | *BugFix:* Commands are no longer matched as text triggers. |
+
+- Internal refactor of the `On` class.
+
+## New Utils
+
+| **Name** | **Description** |
+|----------|-----------------|
+| `make_bot_link` | Builds a `t.me` URL to a bot with an optional deep-link payload. |
+| `make_user_link` | Builds a `t.me` URL to a user with an optional pre-filled message. |
+| `make_qrcode` | Generates a [QR code](./docs/examples/qr_gen.md) URL from any text or link. |

{telekit-2.0.1 → telekit-2.1.0}/telekit.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ telekit/example/example_handlers/hotel.py
 telekit/example/example_handlers/on_text.py
 telekit/example/example_handlers/pages.py
 telekit/example/example_handlers/pyapi.py
+telekit/example/example_handlers/qr.py
 telekit/example/example_handlers/quiz.py
 telekit/example/example_handlers/spells.py
 telekit/example/example_handlers/start.py

telekit-2.0.1/telekit/_version.py

@@ -1 +0,0 @@
-__version__ = "2.0.1"