python-trueconf-bot 1.2.3.dev1__py3-none-any.whl → 1.4.0__py3-none-any.whl

trueconf/types/message.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 from dataclasses import dataclass, field
-from typing import Optional, Union
+from typing import Union, TYPE_CHECKING
 from mashumaro import DataClassDictMixin
 from trueconf.enums.message_type import MessageType
 from trueconf.types.author_box import EnvelopeAuthor, EnvelopeBox
@@ -21,9 +21,16 @@ from trueconf.enums.parse_mode import ParseMode
 from trueconf.types.input_file import InputFile
 
 import logging
+import re
 
-logger = logging.getLogger("chat_bot")
+if TYPE_CHECKING:
+    from trueconf.types.responses.send_file_response import SendFileResponse
+    from trueconf.types.responses.send_message_response import SendMessageResponse
+    from trueconf.types.responses.forward_message_response import ForwardMessageResponse
+    from trueconf.types.responses.remove_message_response import RemoveMessageResponse
 
+logger = logging.getLogger("chat_bot")
+MENTION_RE = re.compile(r"href=[\"']trueconf:([^\"'&]+)(?:&do=profile)?[\"']")
 
 @dataclass
 class Message(BoundToBot, DataClassDictMixin):
@@ -55,6 +62,7 @@ class Message(BoundToBot, DataClassDictMixin):
             from_user (EnvelopeAuthor): Shortcut for accessing the message author.
             content_type (MessageType): Returns the type of the message.
             text (Optional[str]): Returns the message text if it contains text, else None.
+            mention (Optional[bool]): Returns True if the message mentions the bot, else None.
             document (Optional[Document]): Returns a document attachment if the message
                 contains a non-media file (not photo, video, sticker).
             photo (Optional[Photo]): Returns a photo attachment if available.
@@ -89,7 +97,7 @@ class Message(BoundToBot, DataClassDictMixin):
     message_id: str = field(metadata={"alias": "messageId"})
     chat_id: str = field(metadata={"alias": "chatId"})
     is_edited: bool = field(metadata={"alias": "isEdited"})
-    reply_message_id: Optional[str] = field(default=None, metadata={"alias": "replyMessageId"})
+    reply_message_id: str | None = field(default=None, metadata={"alias": "replyMessageId"})
 
     @property
     def from_user(self) -> EnvelopeAuthor:
@@ -122,7 +130,7 @@ class Message(BoundToBot, DataClassDictMixin):
         return self.content.text if isinstance(self.content, TextContent) else None
 
     @property
-    def document(self) -> Optional["Document"]:
+    def document(self) -> Document | None:
         """
         Returns the attached document if the message contains a non-media file.
 
@@ -146,7 +154,7 @@ class Message(BoundToBot, DataClassDictMixin):
         return None
 
     @property
-    def photo(self) -> Optional["Photo"]:
+    def photo(self) -> Photo | None:
         """
         Returns the attached photo object if the current message contains an image.
 
@@ -166,7 +174,7 @@ class Message(BoundToBot, DataClassDictMixin):
         return None
 
     @property
-    def video(self) -> Optional["Video"]:
+    def video(self) -> Video | None:
         """
         Returns the attached video object if the current message contains a video.
 
@@ -186,7 +194,7 @@ class Message(BoundToBot, DataClassDictMixin):
         return None
 
     @property
-    def sticker(self) -> Optional["Sticker"]:
+    def sticker(self) -> Sticker | None:
         """
         Returns the attached sticker object if the current message contains a sticker.
 
@@ -203,13 +211,41 @@ class Message(BoundToBot, DataClassDictMixin):
             ).bind(self.bot)
         return None
 
+    @property
+    def mention(self) -> bool | None:
+        """
+        Returns whether the current text message mentions the bot.
+
+        The shortcut checks two supported mention formats:
+
+        - ``@all`` — treated as a mention because it targets all chat participants.
+        - TrueConf user mentions rendered as HTML links, for example
+          ``<a href="trueconf:john_doe@video.example.com">John Doe</a>``.
+
+        For user mentions, the extracted TrueConf ID is compared with ``bot.me_id``.
+
+        Returns:
+            bool | None: ``True`` if the message mentions the bot, otherwise ``None``.
+        """
+        if not isinstance(self.content, TextContent):
+            return None
+
+        text = self.content.text.strip()
+        if text == "@all":
+            return True
+
+        return any(
+            match.group(1) == self.bot.me_id
+            for match in MENTION_RE.finditer(text)
+        ) or None
+
     async def answer_photo(
             self,
             file: InputFile,
             preview: InputFile | None,
             caption: str | None = None,
             parse_mode: ParseMode | str = ParseMode.TEXT
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_photo`][trueconf.Bot.send_photo] method of the bot instance. Use this method to send a photo in response to the current message.
 
@@ -247,7 +283,7 @@ class Message(BoundToBot, DataClassDictMixin):
             file: InputFile,
             caption: str | None = None,
             parse_mode: ParseMode | str = ParseMode.TEXT
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_document`][trueconf.Bot.send_document] method of the bot instance. Use this method to send a document in response to the current message.
 
@@ -281,7 +317,7 @@ class Message(BoundToBot, DataClassDictMixin):
     async def answer_sticker(
             self,
             file: InputFile
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_sticker`][trueconf.Bot.send_sticker] method of the bot instance. Use this method to send a sticker in response to the current message.
 
@@ -308,7 +344,7 @@ class Message(BoundToBot, DataClassDictMixin):
             file=file,
         )
 
-    async def answer(self, text: str, parse_mode: ParseMode | str = ParseMode.HTML) -> object:
+    async def answer(self, text: str, parse_mode: ParseMode | str = ParseMode.HTML) -> SendMessageResponse:
         """
         Shortcut for the [`send_message`][trueconf.Bot.send_message] method of the bot instance. Use this method to send a text message to the current chat.
 
@@ -341,7 +377,7 @@ class Message(BoundToBot, DataClassDictMixin):
             parse_mode=parse_mode
         )
 
-    async def reply(self, text: str, parse_mode: ParseMode | str = ParseMode.HTML) -> object:
+    async def reply(self, text: str, parse_mode: ParseMode | str = ParseMode.HTML) -> SendMessageResponse:
         """
         Shortcut for the [`send_message`][trueconf.Bot.send_message] method.
         Sends a reply to this message in the current chat.
@@ -374,7 +410,7 @@ class Message(BoundToBot, DataClassDictMixin):
             caption: str | None = None,
             parse_mode: ParseMode | str = ParseMode.TEXT,
 
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_photo`][trueconf.Bot.send_photo] method of the bot instance.
         Sends a photo as a reply to the current message in this chat.
@@ -416,7 +452,7 @@ class Message(BoundToBot, DataClassDictMixin):
             file: InputFile,
             caption: str | None = None,
             parse_mode: ParseMode | str = ParseMode.TEXT
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_document`][trueconf.Bot.send_document] method of the bot instance.
         Sends a document as a reply to the current message in this chat.
@@ -453,7 +489,7 @@ class Message(BoundToBot, DataClassDictMixin):
     async def reply_sticker(
             self,
             file: InputFile
-    ) -> object:
+    ) -> SendFileResponse:
         """
         Shortcut for the [`send_sticker`][trueconf.Bot.send_sticker] method of the bot instance.
         Sends a sticker as a reply to the current message in this chat.
@@ -483,7 +519,7 @@ class Message(BoundToBot, DataClassDictMixin):
             reply_message_id=self.message_id
         )
 
-    async def forward(self, chat_id: str) -> object:
+    async def forward(self, chat_id: str) -> ForwardMessageResponse:
         """
         Shortcut for the [`forward_message`][trueconf.Bot.forward_message] method of the bot instance. Use this method to forward the current message to another chat.
 
@@ -505,7 +541,7 @@ class Message(BoundToBot, DataClassDictMixin):
             message_id=self.message_id,
         )
 
-    async def copy_to(self, chat_id: str) -> object:
+    async def copy_to(self, chat_id: str) -> SendMessageResponse | None:
         """
         Shortcut for the [`send_message`][trueconf.Bot.send_message] method of the bot instance. Use this method to send a copy of the current message (without metadata or reply context) to another chat.
 
@@ -537,7 +573,7 @@ class Message(BoundToBot, DataClassDictMixin):
         )
         return None
 
-    async def delete(self, for_all: bool = False) -> object:
+    async def delete(self, for_all: bool = False) -> RemoveMessageResponse:
         """
         Shortcut for the [`remove_message`][trueconf.Bot.remove_message] method of the bot instance. Use this method to delete the current message from the chat.
 
@@ -560,7 +596,7 @@ class Message(BoundToBot, DataClassDictMixin):
             for_all=for_all,
         )
 
-    async def save_to_favorites(self, copy: bool = False) -> object:
+    async def save_to_favorites(self, copy: bool = False) -> SendMessageResponse | ForwardMessageResponse | None:
         """
         Saves the current message to the bot's "Favorites" chat.
 
@@ -592,7 +628,7 @@ class Message(BoundToBot, DataClassDictMixin):
         """
 
         if copy:
-            return await self.copy_to(await self.bot.me)
+            return await self.copy_to(await self.bot.me_chat)
         else:
-            return await self.forward(await self.bot.me)
+            return await self.forward(await self.bot.me_chat)
 

trueconf/utils/_ssl.py

@@ -0,0 +1,44 @@
+import ssl
+from pathlib import Path
+from typing import TypeAlias
+import truststore
+
+SSLVerify: TypeAlias = bool | str | ssl.SSLContext
+
+def _build_ssl_context(verify_ssl: SSLVerify) -> ssl.SSLContext:
+    if isinstance(verify_ssl, ssl.SSLContext):
+        return verify_ssl
+
+    if verify_ssl is False:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        return ctx
+
+    if verify_ssl is True:
+        return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+
+    if isinstance(verify_ssl, str):
+        cafile = Path(verify_ssl).expanduser()
+        if not cafile.is_file():
+            raise FileNotFoundError(
+                f"SSL CA bundle file not found: {cafile}. "
+                "Pass verify_ssl=True to use the system trust store, "
+                "verify_ssl=False to disable verification, or provide a valid path to a CA bundle."
+            )
+        return ssl.create_default_context(cafile=str(cafile))
+
+    raise TypeError(
+        "verify_ssl must be bool, str path to CA bundle, or ssl.SSLContext"
+    )
+
+def _describe_ssl_context(ctx: ssl.SSLContext) -> str:
+    if ctx.verify_mode == ssl.CERT_NONE:
+        return "disabled"
+
+    return (
+        f"enabled "
+        f"(context={type(ctx).__module__}.{type(ctx).__name__}, "
+        f"verify_mode={ctx.verify_mode.name}, "
+        f"check_hostname={ctx.check_hostname})"
+    )

trueconf/utils/_token.py

@@ -4,8 +4,8 @@ from datetime import datetime
 from functools import lru_cache
 from typing import Optional
 
-from httpx import AsyncClient, Client, HTTPStatusError
-
+from httpx import Client, HTTPStatusError
+from ._ssl import SSLVerify
 from ..exceptions import TokenValidationError, InvalidGrantError
 
 
@@ -13,7 +13,7 @@ def _get_auth_token(
     server: str,
     username: str,
     password: str,
-    verify: bool,
+    ssl_context: SSLVerify,
     *,
     protocol: str = "https",
     port: int = 443,
@@ -26,7 +26,7 @@ def _get_auth_token(
         "username": str(username),
         "password": str(password)
     }
-    with Client(timeout=timeout, verify=verify) as client:
+    with Client(timeout=timeout, verify=ssl_context) as client:
         r = client.post(url, json=params)
 
         try:

trueconf/utils/_version_checker.py

@@ -21,6 +21,12 @@ class _VersionChecker:
             library_spec=None,
             message="Chatbots are not supported (server version 5.5.0+ required).",
         ),
+        CompatibilityRule(
+            server_spec=SpecifierSet(">=5.5.0,<=5.5.2"),
+            library_spec=SpecifierSet(">=1.1.0,<1.2.0"),
+            message="Server version 5.5.0–5.5.2 requires python-trueconf-bot v1.1.x.",
+            install_hint='uv pip install "python-trueconf-bot>=1.1.0,<1.2.0"',
+        ),
     )
 
     @classmethod

trueconf/utils/formatting/__init__.py

@@ -0,0 +1,21 @@
+from .text import (
+    AllMention,
+    Bold,
+    Italic,
+    Link,
+    Mention,
+    Strikethrough,
+    Text,
+    Underline,
+)
+
+__all__ = [
+    "AllMention",
+    "Bold",
+    "Italic",
+    "Link",
+    "Mention",
+    "Strikethrough",
+    "Text",
+    "Underline"
+]

trueconf/utils/formatting/decorations.py

@@ -0,0 +1,87 @@
+from abc import ABC, abstractmethod
+from html import escape
+import re
+
+
+class TextDecoration(ABC):
+    @abstractmethod
+    def escape(self, value: str) -> str: ...
+
+    @abstractmethod
+    def bold(self, value: str) -> str: ...
+
+    @abstractmethod
+    def italic(self, value: str) -> str: ...
+
+    @abstractmethod
+    def underline(self, value: str) -> str: ...
+
+    @abstractmethod
+    def strikethrough(self, value: str) -> str: ...
+
+    @abstractmethod
+    def link(self, value: str, url: str) -> str: ...
+
+    @abstractmethod
+    def mention(self, value: str, user_id: str) -> str: ...
+
+    @abstractmethod
+    def all_mention(self) -> str: ...
+
+
+class HtmlDecoration(TextDecoration):
+    def escape(self, value: str) -> str:
+        return escape(value, quote=False)
+
+    def bold(self, value: str) -> str:
+        return f"<b>{value}</b>"
+
+    def italic(self, value: str) -> str:
+        return f"<i>{value}</i>"
+
+    def underline(self, value: str) -> str:
+        return f"<u>{value}</u>"
+
+    def strikethrough(self, value: str) -> str:
+        return f"<s>{value}</s>"
+
+    def link(self, value: str, url: str) -> str:
+        return f'<a href="{escape(url, quote=True)}">{value}</a>'
+
+    def mention(self, value: str, user_id: str) -> str:
+        return self.link(value, f"trueconf:{user_id}")
+
+    def all_mention(self) -> str:
+        return "@all"
+
+
+class MarkdownDecoration(TextDecoration):
+    PATTERN = re.compile(r"([_*\[\]()~`>#+\-=|{}.!\\])")
+
+    def escape(self, value: str) -> str:
+        return self.PATTERN.sub(r"\\\1", value)
+
+    def bold(self, value: str) -> str:
+        return f"**{value}**"
+
+    def italic(self, value: str) -> str:
+        return f"*{value}*"
+
+    def underline(self, value: str) -> str:
+        return value
+
+    def strikethrough(self, value: str) -> str:
+        return f"~~{value}~~"
+
+    def link(self, value: str, url: str) -> str:
+        return f"[{value}]({url})"
+
+    def mention(self, value: str, user_id: str) -> str:
+        return self.link(value, f"trueconf:{user_id}")
+
+    def all_mention(self) -> str:
+        return "@all"
+
+
+html_decoration = HtmlDecoration()
+markdown_decoration = MarkdownDecoration()

trueconf/utils/formatting/text.py

@@ -0,0 +1,252 @@
+
+from __future__ import annotations
+
+"""
+Utilities for building formatted message text.
+
+The module provides a small tree-based formatting API similar to aiogram's formatting
+helpers. Formatting nodes can be composed and rendered either as HTML or Markdown.
+
+Example:
+    ```python
+    from trueconf.utils.formatting import Bold, Link, Mention, Text
+
+    content = Text(
+        Bold("Important"),
+        " message for ",
+        Mention("John Doe", user_id="john_doe@video.example.com"),
+        "\n",
+        Link("Open website", url="https://trueconf.com"),
+    )
+
+    html = content.as_html()
+    markdown = content.as_markdown()
+    ```
+"""
+
+from abc import ABC, abstractmethod
+
+from .decorations import TextDecoration, html_decoration, markdown_decoration
+
+class TextNode(ABC):
+    """
+    Base class for all formatting nodes.
+
+    Formatting nodes render themselves using a text decoration strategy, such as
+    HTML or Markdown. End users usually do not instantiate this class directly;
+    use :class:`Text`, :class:`Bold`, :class:`Italic`, :class:`Link`, and other
+    concrete nodes instead.
+    """
+
+    @abstractmethod
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the node using the provided decoration strategy.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used to render the node.
+
+        Returns:
+            str: Rendered text.
+        """
+        ...
+
+
+class Text(TextNode):
+    """
+    Container node for plain text and nested formatting nodes.
+
+    Args:
+        *body (str | TextNode): Plain strings or formatting nodes to concatenate.
+
+    Example:
+        ```python
+        content = Text("Hello, ", Bold("world"))
+        html = content.as_html()
+        ```
+    """
+    def __init__(self, *body: str | TextNode):
+        """
+        Initializes a text container.
+
+        Args:
+            *body (str | TextNode): Plain strings or formatting nodes.
+        """
+        self.body = body
+
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the text container using the provided decoration strategy.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered text.
+        """
+        parts: list[str] = []
+
+        for item in self.body:
+            if isinstance(item, TextNode):
+                parts.append(item.render(decoration))
+            else:
+                parts.append(decoration.escape(str(item)))
+
+        return "".join(parts)
+
+    def as_html(self) -> str:
+        """
+        Renders the text container as HTML.
+
+        Returns:
+            str: HTML representation of the formatted text.
+        """
+        return self.render(html_decoration)
+
+    def as_markdown(self) -> str:
+        """
+        Renders the text container as Markdown.
+
+        Returns:
+            str: Markdown representation of the formatted text.
+        """
+        return self.render(markdown_decoration)
+
+
+class Bold(Text):
+    """Represents bold text."""
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as bold text.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered bold text.
+        """
+        return decoration.bold(super().render(decoration))
+
+
+class Italic(Text):
+    """Represents italic text."""
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as italic text.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered italic text.
+        """
+        return decoration.italic(super().render(decoration))
+
+
+class Underline(Text):
+    """Represents underlined text."""
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as underlined text.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered underlined text.
+        """
+        return decoration.underline(super().render(decoration))
+
+
+class Strikethrough(Text):
+    """Represents strikethrough text."""
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as strikethrough text.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered strikethrough text.
+        """
+        return decoration.strikethrough(super().render(decoration))
+
+
+class Link(Text):
+    """
+    Represents a hyperlink.
+
+    Args:
+        *body (str | TextNode): Link label as plain text or formatting nodes.
+        url (str): Link target URL.
+    """
+    def __init__(self, *body: str | TextNode, url: str):
+        """
+        Initializes a hyperlink node.
+
+        Args:
+            *body (str | TextNode): Link label as plain text or formatting nodes.
+            url (str): Link target URL.
+        """
+        super().__init__(*body)
+        self.url = url
+
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as a hyperlink.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered hyperlink.
+        """
+        return decoration.link(super().render(decoration), self.url)
+
+
+class Mention(Text):
+    """
+    Represents a TrueConf user mention.
+
+    Args:
+        *body (str | TextNode): Mention label as plain text or formatting nodes.
+        user_id (str): TrueConf user ID, for example ``john_doe@video.example.com``.
+    """
+    def __init__(self, *body: str | TextNode, user_id: str):
+        """
+        Initializes a TrueConf mention node.
+
+        Args:
+            *body (str | TextNode): Mention label as plain text or formatting nodes.
+            user_id (str): TrueConf user ID.
+        """
+        super().__init__(*body)
+        self.user_id = user_id
+
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders the nested content as a TrueConf user mention.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered mention.
+        """
+        return decoration.mention(super().render(decoration), self.user_id)
+
+
+class AllMention(TextNode):
+    """Represents an ``@all`` mention."""
+    def render(self, decoration: TextDecoration) -> str:
+        """
+        Renders an ``@all`` mention.
+
+        Args:
+            decoration (TextDecoration): Formatting strategy used for rendering.
+
+        Returns:
+            str: Rendered ``@all`` mention.
+        """
+        return decoration.all_mention()