telekit 2.5.0b1__tar.gz → 2.5.0b2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.5.0b1
+Version: 2.5.0b2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -477,7 +477,7 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.5.0b1
+# Changes in version 2.5.0b2
 
 ### v2.5.0`b0`
 - Added support for t-strings (PEP 750, Python 3.14+) in `TextEntity`.
@@ -493,3 +493,11 @@ It tries to make Telegram bot development easier.
   - `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)

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/__init__.py

@@ -30,6 +30,7 @@ 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
@@ -41,6 +42,7 @@ from . import utils
 from . import traits
 from . import debug
 from . import scheduler
+from . import chat
 
 Styles = styles.Styles
 
@@ -56,11 +58,13 @@ __all__ = [
     "inline_buttons",
     "dices",
     "scheduler",
+    "chat",
 
     "Styles",
     "User",
 
-    "Server", 
+    "Server",
+    "Chat",
     "Chain", 
     "Trait",
     "Handler", 

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/_chain_base.py

@@ -18,7 +18,6 @@
 # 
 
 # Standard library
-import inspect
 from typing import Callable
 
 # Third-party packages

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/_handler.py

@@ -27,8 +27,9 @@ library = logger.library
 from ._chain import Chain
 from ._callback_query_handler import CallbackQueryHandler
 from ._user import User
+from .chat import Chat
 from ._on import On
-from . import senders
+from .debug import Debug
 
 class Handler:
     
@@ -40,6 +41,7 @@ class Handler:
 
     # Instance Attributes
     user: User
+    chat: Chat
     chain: Chain
     message: Message
 
@@ -74,6 +76,12 @@ class Handler:
             handler.on = On(handler, bot)
             handler.init_handler()
 
+            if handler.__name__.startswith("_"):
+                continue
+
+            if handler.__name__ in cls.handlers_dict and Debug.duplicate_handler_warnings:
+                library.warning("Multiple handlers are named 'StartHandler'. Only the last registered handler is available through Handler.handlers_dict.")
+
             cls.handlers_dict[handler.__name__] = handler
     
     @classmethod
@@ -99,6 +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.new_chain()
 
     def handle(self) -> Any:

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/_init.py

@@ -25,6 +25,7 @@ from ._inline_buttons import InlineButton
 from ._user import User
 from .senders import BaseSender
 from ._state import TelekitState
+from .chat import Chat
 
 import telebot
 
@@ -33,6 +34,7 @@ __all__ = ["init"]
 def init(bot: telebot.TeleBot) -> None:
     TelekitState._init(bot)
     BaseSender._init(bot)
+    Chat._init(bot)
     Handler._init(bot)
     Chain._init(bot)
     InputHandler._init(bot)

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/_inline_buttons.py

@@ -166,7 +166,7 @@ class LinkButton(InlineButton):
     :param style: Style of the button. Must be one of `telekit.types.ButtonStyle.DANGER` (red), 
               `*.SUCCESS` (green) or `*.PRIMARY` (blue). 
               You can also pass these as string values: "danger", "success", "primary". 
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -197,16 +197,17 @@ class ContactButton(LinkButton):
     :type user_id: :class:`str` | :class:`int`
     :param style: Visual style of the button. Accepts a :class:`~telekit.types.ButtonStyle`
         enum value or its string equivalent: ``"danger"`` (red), ``"success"`` (green),
-        ``"primary"`` (blue). Defaults to the app-specific style if omitted.
+        ``"primary"`` (blue). Defaults to the client-specific style if omitted.
     :type style: :class:`~telekit.types.ButtonStyle` | :class:`str` | ``None``
     :param kwargs: Additional keyword arguments forwarded to
         :class:`~telekit.types.InlineKeyboardButton`.
     """
     def __init__(self, user_id: str | int, *, style: str | None | ButtonStyle = None, **kwargs):
-        self._url = telekit.utils.make_mention(user_id)
-            
-        self._style = self._normalize_style(style)
-        self._kwargs = kwargs
+        super().__init__(
+            url=telekit.utils.make_mention(user_id),
+            style=style,
+            **kwargs
+        )
 
 class UserLinkButton(LinkButton):
     """
@@ -221,16 +222,17 @@ class UserLinkButton(LinkButton):
     :type text: :class:`str` | ``None``
     :param style: Visual style of the button. Accepts a :class:`~telekit.types.ButtonStyle`
         enum value or its string equivalent: ``"danger"`` (red), ``"success"`` (green),
-        ``"primary"`` (blue). Defaults to the app-specific style if omitted.
+        ``"primary"`` (blue). Defaults to the client-specific style if omitted.
     :type style: :class:`~telekit.types.ButtonStyle` | :class:`str` | ``None``
     :param kwargs: Additional keyword arguments forwarded to
         :class:`~telekit.types.InlineKeyboardButton`.
     """
     def __init__(self, username: str, text: str | None = None, *, style: str | None | ButtonStyle = None, **kwargs):
-        self._url = telekit.utils.make_user_link(username, text)
-            
-        self._style = self._normalize_style(style)
-        self._kwargs = kwargs
+        super().__init__(
+            url=telekit.utils.make_user_link(username, text),
+            style=style,
+            **kwargs
+        )
 
 class BotLinkButton(LinkButton):
     """
@@ -245,16 +247,17 @@ class BotLinkButton(LinkButton):
     :type start: :class:`str` | ``None``
     :param style: Visual style of the button. Accepts a :class:`~telekit.types.ButtonStyle`
         enum value or its string equivalent: ``"danger"`` (red), ``"success"`` (green),
-        ``"primary"`` (blue). Defaults to the app-specific style if omitted.
+        ``"primary"`` (blue). Defaults to the client-specific style if omitted.
     :type style: :class:`~telekit.types.ButtonStyle` | :class:`str` | ``None``
     :param kwargs: Additional keyword arguments forwarded to
         :class:`~telekit.types.InlineKeyboardButton`.
     """
     def __init__(self, botname: str, start: str | None = None, *, style: str | None | ButtonStyle = None, **kwargs):
-        self._url = telekit.utils.make_bot_link(botname, start)
-            
-        self._style = self._normalize_style(style)
-        self._kwargs = kwargs
+        super().__init__(
+            url=telekit.utils.make_bot_link(botname, start),
+            style=style,
+            **kwargs
+        )
 
 class WebAppButton(InlineButton):
     """
@@ -266,7 +269,7 @@ class WebAppButton(InlineButton):
     :param style: Style of the button. Must be one of `telekit.types.ButtonStyle.DANGER` (red), 
               `*.SUCCESS` (green) or `*.PRIMARY` (blue). 
               You can also pass these as string values: "danger", "success", "primary". 
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -295,7 +298,7 @@ class CopyTextButton(InlineButton):
     :param style: Style of the button. Must be one of `telekit.types.ButtonStyle.DANGER` (red), 
               `*.SUCCESS` (green) or `*.PRIMARY` (blue). 
               You can also pass these as string values: "danger", "success", "primary". 
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -335,7 +338,7 @@ class SuggestButton(InlineButton):
     :param style: Style of the button. Must be one of `telekit.types.ButtonStyle.DANGER` (red), 
               `*.SUCCESS` (green) or `*.PRIMARY` (blue). 
               You can also pass these as string values: "danger", "success", "primary". 
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -388,7 +391,7 @@ class CallbackButton(InlineButton):
     :param style: Style of the button. Must be one of `telekit.types.ButtonStyle.DANGER` (red), 
               `*.SUCCESS` (green) or `*.PRIMARY` (blue). 
               You can also pass these as string values: "danger", "success", "primary". 
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -581,7 +584,7 @@ class AlertButton(AnswerButton):
     :param style: Style of the button. Must be one of `ButtonStyle.DANGER` (red),
               `*.SUCCESS` (green) or `*.PRIMARY` (blue).
               You can also pass these as string values: "danger", "success", "primary".
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str | ButtonStyle | None`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -631,7 +634,7 @@ class NotificationButton(AnswerButton):
     :param style: Style of the button. Must be one of `ButtonStyle.DANGER` (red),
               `*.SUCCESS` (green) or `*.PRIMARY` (blue).
               You can also pass these as string values: "danger", "success", "primary".
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str | ButtonStyle | None`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.
@@ -696,7 +699,7 @@ class InvokeButton(CallbackButton):
     :param style: Style of the button. Must be one of `ButtonStyle.DANGER` (red),
               `*.SUCCESS` (green) or `*.PRIMARY` (blue).
               You can also pass these as string values: "danger", "success", "primary".
-              If omitted, an app-specific default style is used.
+              If omitted, an client-specific default style is used.
     :type style: `str | ButtonStyle | None`
 
     :param kwargs: Additional keyword arguments passed directly to `InlineKeyboardButton`.

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/_version.py

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

telekit-2.5.0b2/telekit/chat.py

@@ -0,0 +1,59 @@
+from typing import Any
+
+from telebot import TeleBot
+from telebot.types import Message
+
+import telekit
+from telekit.styles import TextEntity, Escape, Raw, Group, Bold, Italic
+from ._logger import _library
+
+__all__ = ['Chat']
+
+class Chat:
+
+    bot: TeleBot
+
+    @classmethod
+    def _init(cls, bot: TeleBot):
+        """
+        Initializes the bot instance for the class.
+        """
+        cls.bot = bot
+
+    def __init__(self, chat_id: int, thread_id: int | None = None, previous_user_message: Message | None = None) -> None:
+        self.id = chat_id
+        self.thread_id = thread_id
+        self.previous_user_message = previous_user_message
+
+    def _get_base_params(self) -> 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 text message to the chat.
+
+        Returns:
+            Message | None: The sent message or None if sending failed.
+        """
+        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 answer (chat_id={self.id}; thread_id={self.thread_id}): {exception}")
+            return None
+
+    
+
+    

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit/debug.py

@@ -2,6 +2,7 @@ class Debug:
     timeout_warnings: bool = False
     deletion_warnings: bool = False
     callback_query_tracing: bool = False
+    duplicate_handler_warnings: bool = True
 
     @classmethod
     def set_all(cls, value: bool) -> None:

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

@@ -322,8 +322,20 @@ def compose_keyboard(
 # Link Generating
 # ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
 
-def make_bot_link(botname: str, start: str | None = None) -> str:
-    """Return a t.me link to a bot.
+def make_mention(user_id: int | str) -> str:
+    """
+    Creates a Telegram mention link by user ID.
+
+    Examples::
+
+        make_mention(123456789)
+        >>> 'tg://user?id=123456789'
+    """
+    return f"tg://user?id={user_id}"
+
+def make_bot_link(botname: str, start: str | None = None, escape: bool = True) -> str:
+    """
+    Return a t.me link to a bot.
 
     >>> make_bot_link("UserNameOfBot")
     "https://t.me/UserNameOfBot"
@@ -341,22 +353,12 @@ def make_bot_link(botname: str, start: str | None = None) -> str:
     botname = botname.lstrip("@")
     if start is None:
         return f"https://t.me/{botname}"
-    encoded_start = quote(start, safe="")
+    encoded_start = quote(start, safe="") if escape else start
     return f"https://t.me/{botname}?start={encoded_start}"
 
-def make_mention(user_id: int | str) -> str:
+def make_user_link(username: str, text: str | None = None, escape: bool = True) -> str:
     """
-    Creates a Telegram mention link by user ID.
-
-    Examples::
-
-        make_mention(123456789)
-        >>> 'tg://user?id=123456789'
-    """
-    return f"tg://user?id={user_id}"
-
-def make_user_link(username: str, text: str | None = None) -> str:
-    """Return a t.me link to a user.
+    Return a t.me link to a user.
 
     >>> make_user_link("UserName")
     "https://t.me/UserName"
@@ -374,7 +376,7 @@ def make_user_link(username: str, text: str | None = None) -> str:
     username = username.lstrip("@")
     if text is None:
         return f"https://t.me/{username}"
-    encoded_text = quote(text, safe="")
+    encoded_text = quote(text, safe="") if escape else text
     return f"https://t.me/{username}?text={encoded_text}"
 
 def make_qrcode(
@@ -395,7 +397,8 @@ def make_qrcode(
     caption_font_size: int | None = None,
     caption_font_color: str | None = None,
 ) -> str:
-    """Return a QuickChart URL that renders a QR code.
+    """
+    Return a QuickChart URL that renders a QR code.
 
     >>> make_qrcode("https://example.com")
     'https://quickchart.io/qr?text=https%3A%2F%2Fexample.com'
@@ -438,9 +441,9 @@ def make_qrcode(
     if margin is not None: 
         params["margin"] = margin
     if dark is not None: 
-        params["dark"] = dark
+        params["dark"] = dark.lstrip("#")
     if light is not None: 
-        params["light"] = light
+        params["light"] = light.lstrip("#")
     if ec_level is not None: 
         params["ecLevel"] = ec_level
     if format is not None: 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telekit
-Version: 2.5.0b1
+Version: 2.5.0b2
 Summary: Declarative, developer-friendly library for building Telegram bots
 Home-page: https://github.com/Romashkaa/telekit
 Author: romashka
@@ -477,7 +477,7 @@ It tries to make Telegram bot development easier.
 
 ---
 
-# Changes in version 2.5.0b1
+# Changes in version 2.5.0b2
 
 ### v2.5.0`b0`
 - Added support for t-strings (PEP 750, Python 3.14+) in `TextEntity`.
@@ -493,3 +493,11 @@ It tries to make Telegram bot development easier.
   - `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)

{telekit-2.5.0b1 → telekit-2.5.0b2}/telekit.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ telekit/_timeout.py
 telekit/_trait.py
 telekit/_user.py
 telekit/_version.py
+telekit/chat.py
 telekit/debug.py
 telekit/dices.py
 telekit/inline_buttons.py