telekit 2.5.0b3__tar.gz → 2.5.1__tar.gz

{telekit-2.5.0b3 → telekit-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.5.0b3
+Version: 2.5.1
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -477,30 +477,13 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.5.0b3
+# Changes in version 2.5.1
 
-### 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.1 `(bug-fix)`
+- Implement `TelegramMarkdownV2Sanitizer` for improved `MarkdownV2` handling
 
-### 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 `(final)`
+- Refactor `CalendarPick` trait to use `set_keyboard`
 
 ### v2.5.0`b3`
 - Added `utils.Markers` class
@@ -513,3 +496,26 @@ It tries to make Telegram bot development easier.
 - 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`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`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`b0`
+- Added support for t-strings (PEP 750, Python 3.14+) in `TextEntity`.

{telekit-2.5.0b3 → telekit-2.5.1}/telekit/_handler.py

@@ -107,7 +107,7 @@ class Handler:
     def __init__(self, message: Message):
         self.message: Message = message
         self.user = User(self.message)
-        self.chat = Chat(self.message.chat.id, self.message.message_thread_id)
+        self.chat = Chat(self.message.chat.id, self.message.message_thread_id, self.message)
         self.new_chain()
 
     def handle(self) -> Any:

{telekit-2.5.0b3 → telekit-2.5.1}/telekit/_version.py

@@ -3,4 +3,4 @@
 # PyPI history: https://pypi.org/project/telekit/#history
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-__version__ = "2.5.0b3"
+__version__ = "2.5.1"

telekit-2.5.1/telekit/chat.py

@@ -0,0 +1,101 @@
+from typing import Any
+from telebot import TeleBot
+from telebot.types import Message, ReplyParameters
+from telekit.styles import TextEntity, Escape
+from ._logger import _library
+
+__all__ = ['Chat']
+
+
+class Chat:
+    bot: TeleBot
+
+    @classmethod
+    def _init(cls, bot: TeleBot) -> None:
+        cls.bot = bot
+
+    def __init__(self, chat_id: int, thread_id: int | None = None, initial_user_message: Message | None = None) -> None:
+        """
+        Represents a chat (or a specific thread within a chat) that messages can be sent to.
+
+        :param chat_id: The Telegram chat ID.
+        :param thread_id: The message thread ID, if the chat is a forum topic.
+            Defaults to ``None``.
+        :param initial_user_message: The original user message that triggered this chat context,
+            used as the target for :meth:`reply`. Defaults to ``None``.
+        """
+        self.id = chat_id
+        self.thread_id = thread_id
+        self.initial_user_message = initial_user_message
+
+    def _get_base_params(self) -> dict[str, Any]:
+        """
+        Builds the base set of parameters shared by outgoing requests.
+
+        :return: A dictionary with ``chat_id``, ``parse_mode``, and ``message_thread_id``.
+        :rtype: dict[str, Any]
+        """
+        return {
+            "chat_id": self.id,
+            "parse_mode": "html",
+            "message_thread_id": self.thread_id
+        }
+
+    def answer(self, text: str | TextEntity):
+        """
+        Sends a simple text message to the chat.
+
+        :param text: The message content. Plain strings are HTML-escaped automatically;
+            pass a ``TextEntity`` (e.g. ``Bold``, ``Italic``) for custom formatting.
+        :return: The sent message, or ``None`` if sending failed.
+        :rtype: Message | None
+        """
+        if not isinstance(text, TextEntity):
+            text = Escape(text)
+
+        try:
+            return self.bot.send_message(
+                chat_id           = self.id,
+                message_thread_id = self.thread_id,
+                text              = text.html,
+                parse_mode        = "html",
+            )
+        except Exception as exception:
+            text.debug("html")
+            _library.warning(f"^^^ [chat.answer]: Failed to send message (chat_id={self.id}; thread_id={self.thread_id}): {exception}")
+            return None
+
+    def reply(self, text: str | TextEntity):
+        """
+        Sends a simple text message to the chat as a reply to the user's initial message.
+
+        :param text: The message content. Plain strings are HTML-escaped automatically;
+            pass a ``TextEntity`` (e.g. ``Bold``, ``Italic``) for custom formatting.
+        :return: The sent message, or ``None`` if sending failed.
+        :rtype: Message | None
+        """
+        if not isinstance(text, TextEntity):
+            text = Escape(text)
+
+        try:
+            return self.bot.send_message(
+                chat_id           = self.id,
+                message_thread_id = self.thread_id,
+                text              = text.html,
+                parse_mode        = "html",
+                reply_parameters  = self._get_reply_parameters()
+            )
+        except Exception as exception:
+            text.debug("html")
+            _library.warning(f"^^^ [chat.reply]: Failed to send message (chat_id={self.id}; thread_id={self.thread_id}, reply_parameters={self._get_reply_parameters()}): {exception}")
+            return None
+
+    def _get_reply_parameters(self) -> ReplyParameters | None:
+        """
+        Builds reply parameters pointing to the initial user message, if any.
+
+        :return: ``ReplyParameters`` referencing :attr:`initial_user_message`, or ``None``
+            if no initial message was provided.
+        :rtype: ReplyParameters | None
+        """
+        return ReplyParameters(self.initial_user_message.message_id) if self.initial_user_message else None

{telekit-2.5.0b3 → telekit-2.5.1}/telekit/example/example_handlers/on_text.py

@@ -1,6 +1,7 @@
 import telekit
 
 from telekit.styles import *
+from telekit.types import TextBuilder
 
 class OnTextHandler(telekit.Handler):
 
@@ -16,7 +17,14 @@ class OnTextHandler(telekit.Handler):
         cls.on.text().invoke(cls.handle)
 
         cls.on.command("on_text").invoke(cls.handle)
-            
+
+    EXAMPLES = [
+        "Name: John. Age: 25",
+        "My name is Alice and I am 30 years old",
+        "My name is Romashka",
+        "I'm 18 years old"
+    ]
+    
     # ------------------------------------------
     # Handling Logic
     # ------------------------------------------
@@ -29,7 +37,7 @@ class OnTextHandler(telekit.Handler):
         if not age:
             age = "An unknown number of"
 
-        self.chain.sender.set_title(Group("Hello, ", Italic(name), "!"))
+        self.chain.sender.set_title("👋 Hello, ", Italic(name), "!")
         self.chain.sender.set_message(Italic(age), " years is a wonderful stage of life!")
         self.chain.disable_timeout_warnings()
         self.chain.send()
@@ -37,23 +45,20 @@ class OnTextHandler(telekit.Handler):
     # command
 
     def handle(self):
-        self.chain.sender.set_title(f"🦻 On Text Handler")
-        self.chain.sender.set_message(
-            "Try sending any of these example phrases to see the handler in action:\n\n"
+        reply = TextBuilder()
 
-            "- ", Code('Name: John. Age: 25'), "\n"
-            "- ", Code('My name is Alice and I am 30 years old'), "\n"
-            "- ", Code('My name is Romashka'), "\n"
-            "- ", Code('I\'m 18 years old'), "\n\n"
+        reply.add_bold("💡 Try sending any of these example phrases to see the", Code("on.text"), "in action:", sep=" ")
+        reply.spacer()
+        for example in self.EXAMPLES:
+            reply.add("-", Code(example), sep=" ")
+            reply.newln()
+        reply.newln()
+        reply.add("The bot will respond according to the information you provide")
 
-            "The bot will respond according to the information you provide."
-        )
+        self.chain.sender.set_text(reply)
         self.chain.set_entry_suggestions(
             {
-                "Test 1": "Name: John. Age: 25",
-                "2": "My name is Alice and I am 30 years old",
-                "3": "My name is Romashka",
-                "4": "I'm 18 years old"
+                str(i + 1): example for i, example in enumerate(self.EXAMPLES)
             }, row_width=4
         )
         self.chain.edit()