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

trueconf/exceptions.py

@@ -1,19 +1,41 @@
-
-
-
 class TrueConfChatBotError(Exception):
     """
     Base exception for all TrueConf ChatBot Connector errors.
+
+    All custom exceptions raised by the library inherit from this class.
+    You can catch this exception to handle any library-specific error in a
+    single place.
     """
 
 class TokenValidationError(TrueConfChatBotError):
+    """
+    Raised when the bot token fails local validation.
+
+    This error indicates that the token value has an invalid format or
+    cannot be used by the connector before the authorization request is sent.
+    """
     pass
 
 class InvalidGrantError(TrueConfChatBotError):
+    """
+    Raised when the server rejects the provided authorization grant.
+
+    This usually means that the token or credentials are invalid, expired,
+    revoked, or cannot be used to authorize the bot.
+    """
     pass
 
 class LimitExceededError(TrueConfChatBotError):
-    """Base exception for all limit-related errors (length, size, etc.)."""
+    """
+    Base exception for all limit-related errors.
+
+    This class is used for errors related to text length, title length,
+    file size, and other numeric limits.
+
+    Attributes:
+        actual_value: Actual value that exceeded the limit.
+        limit: Maximum allowed value.
+    """
     def __init__(self, message: str, actual_value: int, limit: int):
         super().__init__(message)
         self.actual_value = actual_value
@@ -21,7 +43,17 @@ class LimitExceededError(TrueConfChatBotError):
 
 
 class TextMessageTooLongError(LimitExceededError):
-    """Raised when the message text exceeds TrueConf's allowed length."""
+    """
+    Raised when a text message exceeds the maximum allowed length.
+
+    The default text message limit is 4096 visible characters. For long texts,
+    such as LLM-generated responses, use `safe_split_text` from `trueconf.utils`
+    and send the returned chunks one by one.
+
+    Attributes:
+        actual_value: Actual visible length of the message text.
+        limit: Maximum allowed message length.
+    """
     def __init__(self, actual_length: int, limit: int = 4096):
         message = (
             f"Bad Request: text message is too long. "
@@ -31,7 +63,17 @@ class TextMessageTooLongError(LimitExceededError):
         super().__init__(message, actual_length, limit)
 
 class FileCaptionTooLongError(LimitExceededError):
-    """Raised when the caption exceeds TrueConf's allowed length."""
+    """
+    Raised when a file caption exceeds the maximum allowed length.
+
+    The default caption limit is 4096 visible characters. For long captions,
+    use `safe_split_text` from `trueconf.utils` and send the returned chunks
+    separately when appropriate.
+
+    Attributes:
+        actual_value: Actual visible length of the caption.
+        limit: Maximum allowed caption length.
+    """
     def __init__(self, actual_length: int, limit: int = 4096):
         message = (
             f"Bad Request: caption is too long. "
@@ -41,11 +83,22 @@ class FileCaptionTooLongError(LimitExceededError):
         super().__init__(message, actual_length, limit)
 
 class ChatTitleTooLongError(LimitExceededError):
-    """Base error for long chat titles."""
+    """
+    Base exception for chat title length errors.
+
+    This class is inherited by more specific exceptions for group and channel
+    title length validation.
+    """
     pass
 
 class GroupTitleTooLongError(ChatTitleTooLongError):
-    """Raised when the group title exceeds allowed length."""
+    """
+    Raised when a group title exceeds the maximum allowed length.
+
+    Attributes:
+        actual_value: Actual length of the group title.
+        limit: Maximum allowed group title length.
+    """
     def __init__(self, actual_length: int, limit: int = 256):
         message = (
             f"Bad Request: group title is too long. "
@@ -54,7 +107,13 @@ class GroupTitleTooLongError(ChatTitleTooLongError):
         super().__init__(message, actual_length, limit)
 
 class ChannelTitleTooLongError(ChatTitleTooLongError):
-    """Raised when the channel title exceeds allowed length."""
+    """
+    Raised when a channel title exceeds the maximum allowed length.
+
+    Attributes:
+        actual_value: Actual length of the channel title.
+        limit: Maximum allowed channel title length.
+    """
     def __init__(self, actual_length: int, limit: int = 256):
         message = (
             f"Bad Request: channel title is too long. "
@@ -63,10 +122,25 @@ class ChannelTitleTooLongError(ChatTitleTooLongError):
         super().__init__(message, actual_length, limit)
 
 class FileValidationError(TrueConfChatBotError):
-    """Общий класс для всех ошибок валидации файлов."""
+    """
+    Base exception for file validation errors.
+
+    This class is used for errors related to file size limits, extension filters,
+    and other file validation rules received from TrueConf Server.
+    """
     pass
 
 class FileSizeTooLargeError(FileValidationError, LimitExceededError):
+    """
+    Raised when a file exceeds the maximum size allowed by the server.
+
+    File size limits are configured by the TrueConf Server administrator and
+    are checked by the bot before sending a file.
+
+    Attributes:
+        actual_value: Actual file size in bytes.
+        limit: Maximum allowed file size in bytes.
+    """
     def __init__(self, actual_size: int, limit: int):
         actual_mb = round(actual_size / (1024 * 1024), 2)
         limit_mb = round(limit / (1024 * 1024), 2)
@@ -78,6 +152,18 @@ class FileSizeTooLargeError(FileValidationError, LimitExceededError):
 
 
 class InvalidFileExtensionError(FileValidationError):
+    """
+    Raised when a file extension does not satisfy the server extension filter.
+
+    File extension rules are configured by the TrueConf Server administrator.
+    Depending on the filter mode, the extension list can work either as an
+    allow list or as a block list.
+
+    Attributes:
+        extension: File extension that failed validation.
+        extensions: Set of extensions used for validation.
+        mode: Extension filter mode.
+    """
     def __init__(self, extension: str, extensions: set[str] | None = None, mode: str = "allow"):
         self.extension = extension
         self.extensions = extensions or set()
@@ -106,6 +192,17 @@ class InvalidFileExtensionError(FileValidationError):
         super().__init__(message)
 
 class ApiErrorException(TrueConfChatBotError):
+    """
+    Raised when TrueConf Server returns an API error response.
+
+    This exception stores the server error code, human-readable detail, and
+    optional response payload for additional context.
+
+    Attributes:
+        code: Error code returned by the server.
+        detail: Human-readable error description.
+        payload: Raw error payload returned by the server, or an empty dict.
+    """
     def __init__(self, code: int, detail: str, payload: dict | None = None):
         super().__init__(f"[{code}] {detail}")
         self.code = code

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()