python-trueconf-bot 1.0.0__py3-none-any.whl

trueconf/client/context_controller.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .bot import Bot
+
+@dataclass
+class BoundToBot:
+    __slots__ = ('_bot',)
+
+    def __init__(self) -> None:
+        self._bot = None
+
+    def bind(self, bot: "Bot"):
+        self._bot = bot
+        return self
+
+    if TYPE_CHECKING:
+        @property
+        def bot(self) -> "Bot": ...
+    else:
+        @property
+        def bot(self) :
+            if not self._bot  or self._bot is None:
+                raise RuntimeError("Object isn’t bound to ChatBot. Bind via bind(bot) before using shortcuts.")
+            return self._bot

trueconf/client/session.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Awaitable, Callable, Optional
+
+logger = logging.getLogger("chat_bot")
+
+
+class WebSocketSession:
+    """
+    Владеет объектом ws, поднимает фоновый listener и
+    пробрасывает сырые сообщения в callback on_message(raw: str).
+    """
+    def __init__(self, on_message: Optional[Callable[[str], Awaitable[None]]] = None):
+        self.ws = None
+        self._listener_task: Optional[asyncio.Task] = None
+        self._on_message = on_message
+
+    def attach(self, ws) -> None:
+        """Подключить актуальный ws и запустить фонового listener-а."""
+        self.ws = ws
+        if self._listener_task and not self._listener_task.done():
+            self._listener_task.cancel()
+        self._listener_task = asyncio.create_task(self._listener())
+
+    async def detach(self) -> None:
+        """Остановить listener (ws остаётся под управлением ChatBot/connect loop)."""
+        if self._listener_task:
+            try:
+                self._listener_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await self._listener_task
+            finally:
+                self._listener_task = None
+        self.ws = None
+
+    async def close(self) -> None:
+        """Закрыть ws и listener."""
+        if self.ws:
+            await self.ws.close()
+        await self.detach()
+
+    async def send_json(self, message: dict) -> None:
+        if not self.ws:
+            raise RuntimeError("WS is not attached")
+        await self.ws.send(json.dumps(message))
+
+    async def _listener(self):
+        try:
+            async for raw in self.ws:
+                if self._on_message:
+                    try:
+                        await self._on_message(raw)
+                    except Exception as e:
+                        logger.error(f"on_message callback error: {e}")
+        except Exception as e:
+            # Закрытие/обрыв — это нормально, верхний цикл переподключит
+            logger.debug(f"Session listener stopped: {type(e).__name__}: {e}")

trueconf/dispatcher/dispatcher.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+from typing import List
+from trueconf.filters.base import Event
+from trueconf.dispatcher.router import Router
+
+
+class Dispatcher:
+    """
+        Central event dispatcher for processing and routing incoming events.
+
+        The `Dispatcher` aggregates one or more `Router` instances and feeds each
+        incoming event through them. The routers are traversed recursively via their
+        `subrouters` (using `_iter_all()`), and each event is passed to `_feed()` of
+        each router in order until it is handled.
+
+        Typical usage includes registering routers with handlers and then calling
+        `feed_update()` with incoming events.
+
+        Examples:
+            >>> dispatcher = Dispatcher()
+            >>> dispatcher.include_router(my_router)
+
+        Attributes:
+            routers (List[Router]): List of root routers included in the dispatcher.
+
+        """
+
+    def __init__(self):
+        """Initializes an empty dispatcher with no routers."""
+        self.routers: List[Router] = []
+
+    def include_router(self, router: Router):
+        """
+            Includes a router to be used by the dispatcher.
+
+            Args:
+                router (Router): A `Router` instance to include.
+        """
+        self.routers.append(router)
+
+    async def _feed_update(self, event: Event):
+        """
+            Feeds an event to all routers and subrouters in order,
+            stopping at the first one that handles it.
+
+            Args:
+                event (Event): The event to be processed.
+
+            Returns:
+                None
+        """
+        for root in self.routers:
+            for r in root._iter_all():
+                handled = await r._feed(event)
+                if handled:
+                    return

trueconf/dispatcher/router.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+import asyncio
+import logging
+import inspect
+from typing import Callable, Awaitable, List, Tuple, Any, Union
+from magic_filter import MagicFilter
+from trueconf.filters.base import Event
+from trueconf.filters.base import Filter
+from trueconf.filters.instance_of import InstanceOfFilter
+from trueconf.filters.method import MethodFilter
+from trueconf.types.message import Message
+from trueconf.types.requests.added_chat_participant import AddedChatParticipant
+from trueconf.types.requests.created_channel import CreatedChannel
+from trueconf.types.requests.created_group_chat import CreatedGroupChat
+from trueconf.types.requests.created_personal_chat import CreatedPersonalChat
+from trueconf.types.requests.edited_message import EditedMessage
+from trueconf.types.requests.removed_chat import RemovedChat
+from trueconf.types.requests.removed_chat_participant import RemovedChatParticipant
+from trueconf.types.requests.removed_message import RemovedMessage
+from trueconf.types.requests.uploading_progress import UploadingProgress
+
+logger = logging.getLogger("chat_bot")
+
+Handler = Callable[[Event], Awaitable[None]]
+FilterLike = Union[Filter, MagicFilter, Callable[[Event], bool], Callable[[Event], Awaitable[bool]], Any]
+
+
+class Router:
+    """
+        Event router for handling incoming events in a structured and extensible way.
+
+        A `Router` allows you to register event handlers with specific filters,
+        such as message types, chat events, or custom logic.
+
+        You can also include nested routers using `include_router()` to build modular and reusable event structures.
+
+        Handlers can be registered for:
+
+        - Messages (`@<router>.message(...)`)
+        - Chat creation events (`@<router>.created_personal_chat()`, `@<router>.created_group_chat()`, `@<router>.created_channel()`)
+        - Participant events (`@<router>.added_chat_participant()`, `@<router>.removed_chat_participant()`)
+        - Message lifecycle events (`@<router>.edited_message()`, `@<router>.removed_message()`)
+        - File upload events (`@<router>.uploading_progress()`)
+        - Removed chats (`@<router>.removed_chat()`)
+
+        Example:
+
+        ```python
+        router = Router()
+
+        @router.message(F.text == "hello")
+        async def handle_hello(msg: Message):
+            await msg.answer("Hi there!")
+        ```
+
+        If you have multiple routers, use `.include_router()` to add them to a parent router.
+        """
+
+    def __init__(self, name: str | None = None, stop_on_first: bool = True):
+
+        self.name = name or hex(id(self))
+        self.stop_on_first = stop_on_first
+        self._handlers: List[Tuple[Tuple[FilterLike, ...], Handler]] = []
+        self._subrouters: List["Router"] = []
+
+    def include_router(self, router: "Router") -> None:
+        """Include a child router for hierarchical event routing."""
+        self._subrouters.append(router)
+
+    def _iter_all(self) -> List["Router"]:
+        """Return a list of this router and all nested subrouters recursively."""
+        out = [self]
+        for child in self._subrouters:
+            out.extend(child._iter_all())
+        return out
+
+    def event(self, method: str, *filters: FilterLike):
+        """
+            Register a handler for a generic event type, filtered by method name.
+
+            Examples:
+                >>> @r.event(F.method == "SendMessage")
+                >>> async def handle_message(msg: Message): ...
+
+        """
+        mf = MethodFilter(method)
+        return self._register((mf, *filters))
+
+    def message(self, *filters: FilterLike):
+        """Register a handler for incoming `Message` events."""
+        return self._register((InstanceOfFilter(Message), *filters))
+
+    def uploading_progress(self, *filters: FilterLike):
+        """Register a handler for file uploading progress events."""
+        return self._register((InstanceOfFilter(UploadingProgress), *filters))
+
+    def created_personal_chat(self, *filters: FilterLike):
+        """Register a handler for personal chat creation events."""
+        return self._register((InstanceOfFilter(CreatedPersonalChat), *filters))
+
+    def created_group_chat(self, *filters: FilterLike):
+        """Register a handler for group chat creation events."""
+        return self._register((InstanceOfFilter(CreatedGroupChat), *filters))
+
+    def created_channel(self, *filters: FilterLike):
+        """Register a handler for channel creation events."""
+        return self._register((InstanceOfFilter(CreatedChannel), *filters))
+
+    def added_chat_participant(self, *filters: FilterLike):
+        """Register a handler when a participant is added to a chat."""
+        return self._register((InstanceOfFilter(AddedChatParticipant), *filters))
+
+    def removed_chat_participant(self, *filters: FilterLike):
+        """Register a handler when a participant is removed from a chat."""
+        return self._register((InstanceOfFilter(RemovedChatParticipant), *filters))
+
+    def removed_chat(self, *filters: FilterLike):
+        """Register a handler when a chat is removed."""
+        return self._register((InstanceOfFilter(RemovedChat), *filters))
+
+    def edited_message(self, *filters: FilterLike):
+        """Register a handler for message edit events."""
+        return self._register((InstanceOfFilter(EditedMessage), *filters))
+
+    def removed_message(self, *filters: FilterLike):
+        """Register a handler for message deletion events."""
+        return self._register((InstanceOfFilter(RemovedMessage), *filters))
+
+    def _register(self, filters: Tuple[FilterLike, ...]):
+        """Internal decorator for registering handlers with filters."""
+
+        def decorator(func: Handler):
+            if not asyncio.iscoroutinefunction(func):
+                async def async_wrapper(evt: Event):
+                    return func(evt)
+
+                self._handlers.append((filters, async_wrapper))
+                return func
+            self._handlers.append((filters, func))
+            return func
+
+        return decorator
+
+    async def _feed(self, event: Event) -> bool:
+        """Feed an incoming event to the router and invoke the first matching handler."""
+        logger.info(f"📥 Incoming event: {event}")
+        for flts, handler in self._handlers:
+
+            if not flts:
+                self._spawn(handler, event, "<none>")
+                return True
+
+            matched = True
+            for f in flts:
+                try:
+                    if not await self._apply_filter(f, event):
+                        matched = False
+                        break
+                except Exception as e:
+                    logger.exception(f"Filter {type(f).__name__} error: {e}")
+                    matched = False
+                    break
+
+            if matched:
+                filters_str = ", ".join(
+                    getattr(f, "__name__", type(f).__name__) if callable(f) else type(f).__name__
+                    for f in flts
+                )
+                self._spawn(handler, event, filters_str)
+                return True
+        return False
+
+    def _spawn(self, handler: Handler, event: Event, filters_str: str):
+        """Internal method to spawn a task for executing the matched handler."""
+        name = getattr(handler, "__name__", "<handler>")
+        logger.info(f"[router:{self.name}] matched handler={name} filters=[{filters_str}]")
+
+        async def _run():
+            try:
+                await handler(event)
+            except Exception as e:
+                logger.exception(f"Handler {name} failed: {e}")
+
+        asyncio.create_task(_run())
+
+    async def _apply_filter(self, f: Filter | Any, event: Event) -> bool:
+        """Evaluate a filter (sync or async) against the event."""
+        if isinstance(f, MagicFilter):
+            try:
+                return bool(f.resolve(event))
+            except Exception:
+                return False
+
+        try:
+            res = f(event)
+        except Exception:
+            return False
+
+        if inspect.isawaitable(res):
+            try:
+                res = await res
+            except Exception:
+                return False
+
+        if isinstance(res, bool):
+            return res
+        return bool(res)

trueconf/enums/__init__.py

@@ -0,0 +1,23 @@
+from .aouth_error import OAuthError
+from .chat_participant_role import ChatParticipantRole
+from .chat_type import ChatType
+from .envelope_author_type import EnvelopeAuthorType
+from .message_type import MessageType
+from .file_ready_state import FileReadyState
+from .incoming_update_method import IncomingUpdateMethod
+from .update_type import UpdateType
+from .parse_mode import ParseMode
+from .survey_type import SurveyType
+
+__all__ = [
+    'UpdateType',
+    'FileReadyState',
+    'ParseMode',
+    'ChatType',
+    'ChatParticipantRole',
+    'OAuthError',
+    'MessageType',
+    'EnvelopeAuthorType',
+    'SurveyType',
+    'IncomingUpdateMethod',
+]

trueconf/enums/aouth_error.py

@@ -0,0 +1,15 @@
+from enum import Enum
+
+
+class OAuthError(str, Enum):
+    """
+    Error codes, according to the OAuth 2.0 specification, are presented as ASCII strings from the list specified in the specification.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#oauth-error
+    """
+
+    INVALID_REQUEST = "invalid_request"
+    INVALID_CLIENT = "invalid_client"
+    INVALID_GRANT = "invalid_grant"
+    UNSUPORTED_GRANT_TYPE = "unsupported_grant_type"

trueconf/enums/chat_participant_role.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class ChatParticipantRole(str, Enum):
+    """
+    This object represents a possible participant role in a chat.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#chatparticipantroleenum
+    """
+
+    OWNER = "owner"
+    ADMIN = "admin"
+    USER = "user"
+    CONF_OWNER = "conf_owner"
+    CONF_MODERATOR = "conf_moderator"
+    FAVORITES_OWNER = "favorites_owner"
+    WRITER = "writer"

trueconf/enums/chat_type.py

@@ -0,0 +1,17 @@
+from enum import Enum
+
+
+class ChatType(int, Enum):
+    """
+    The enumeration contains possible chat types.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#chattypeenum
+    """
+
+    UNDEF = 0
+    P2P = 1
+    GROUP = 2
+    SYSTEM = 3
+    FAVORITES = 5
+    CHANNEL = 6

trueconf/enums/envelope_author_type.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class EnvelopeAuthorType(int, Enum):
+    """
+    The enumeration contains possible author types.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#envelopeauthortypeenum
+    """
+
+    SYSTEM = 0
+    USER = 1

trueconf/enums/file_ready_state.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class FileReadyState(int, Enum):
+    """
+    This enumeration is used to indicate the status of a file on the server.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#filereadystateenum
+    """
+
+    NOT_AVAILABLE = 0
+    UPLOADING = 1
+    READY = 2

trueconf/enums/incoming_update_method.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class IncomingUpdateMethod(str, Enum):
+    ADDED_CHAT_PARTICIPANT = "addChatParticipant"
+    CREATED_CHANNEL = "createChannel"
+    CREATED_GROUP_CHAT = "createGroupChat"
+    CREATED_PERSONAL_CHAT = "createP2PChat"
+    EDITED_MESSAGE = "editMessage"
+    REMOVED_CHAT_PARTICIPANT = "removeChatParticipant"
+    REMOVED_MESSAGE = "removeMessage"
+    MESSAGE = "sendMessage"
+    UPLOADING_PROGRESS = "uploadFileProgress"
+    REMOVED_CHAT = "removeChat"

trueconf/enums/message_type.py

@@ -0,0 +1,27 @@
+from enum import Enum
+from typing import Any
+
+
+class MessageType(int, Enum):
+    """
+    The enumeration contains the message type.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#envelopetypeenum
+    """
+
+    ADD_PARTICIPANT = 1
+    REMOVE_PARTICIPANT = 2
+    PARTICIPANT_ROLE = 110
+    PLAIN_MESSAGE = 200
+    FORWARDED_MESSAGE = 201
+    ATTACHMENT = 202
+    SURVEY = 204
+
+    async def __call__(self, event: Any) -> bool:
+        if getattr(event, "type", None) is None:
+            return False
+        try:
+            return int(getattr(event, "type")) == int(self)
+        except Exception:
+            return False

trueconf/enums/parse_mode.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class ParseMode(str, Enum):
+    """
+    Formatting options
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/messages/#message-formatting
+    """
+
+    TEXT = "text"
+    MARKDOWN = "markdown"
+    HTML = "html"

trueconf/enums/survey_type.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class SurveyType(str, Enum):
+    NON_ANONYMOUS = "{{Survey}}"
+    ANONYMOUS = "{{Anonymous survey}}"

trueconf/enums/update_type.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class UpdateType(int, Enum):
+    """
+    There are three types of messages. Only REQUEST and RESPONSE are applicable.
+
+    Source:
+        https://trueconf.com/docs/chatbot-connector/en/objects/#message-type
+    """
+
+    RESERVED = 0
+    REQUEST = 1
+    RESPONSE = 2

trueconf/exceptions.py

@@ -0,0 +1,17 @@
+
+
+
+class TrueConfChatBotError(Exception):
+    """
+    Base exception for all TrueConf ChatBot Connector errors.
+    """
+
+class TokenValidationError(TrueConfChatBotError):
+    pass
+
+class InvalidGrantError(TrueConfChatBotError):
+    pass
+
+
+class ApiError(TrueConfChatBotError):
+    pass

trueconf/filters/__init__.py

@@ -0,0 +1,11 @@
+from .base import Filter, Event
+from .command import Command
+from .instance_of import InstanceOfFilter
+from .method import MethodFilter
+
+__all__ = [
+    'Command',
+    'Filter',
+    'MethodFilter',
+    'InstanceOfFilter',
+]

trueconf/filters/base.py

@@ -0,0 +1,8 @@
+from typing import Any
+from typing import Protocol, runtime_checkable
+
+Event = Any
+
+@runtime_checkable
+class Filter(Protocol):
+    async def __call__(self, event: Event) -> bool: ...

trueconf/filters/command.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from typing import Any
+from trueconf.enums.message_type import MessageType
+from trueconf.types.message import Message
+
+Event = Any  # позже можно заменить на типизированные модели
+
+class Command:
+    """
+    /start, /help, /echo hi
+    Command("start")   == Command("/start")  # оба варианта валидны
+    Command(("start", "join")) — строго '/start join'
+    Command("echo", with_param=True) — '/echo <любой текст>'
+    """
+
+    def __init__(self, cmd: str, with_param: bool = False):
+        self.cmd = cmd[1:] if cmd.startswith("/") else cmd
+        self.with_param = with_param
+
+    async def __call__(self, event: Event) -> bool:
+        if not isinstance(event, Message):
+            return False
+        if event.type != MessageType.PLAIN_MESSAGE:
+            return False
+        text = (event.content.text or "")
+        if not text.startswith("/"):
+            return False
+        no_slash = text[1:]
+        parts = no_slash.split(maxsplit=1)
+        if not parts or parts[0] != self.cmd:
+            return False
+        return (len(parts) == 2 and bool(parts[1].strip())) if self.with_param else True

trueconf/filters/instance_of.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+from typing import Type
+from trueconf.filters.base import Event
+
+
+class InstanceOfFilter:
+    def __init__(self, cls: Type[object]):
+        self.cls = cls
+
+    async def __call__(self, event: Event) -> bool:
+        return isinstance(event, self.cls)

trueconf/filters/message.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+from trueconf.enums.message_type import MessageType
+from trueconf.types.message import Message
+
+
+class MessageFilter:
+    """Фильтр по payload.type (= EnvelopeType)."""
+
+    def __init__(self, *types: MessageType):
+        self.types = frozenset(int(t) for t in types)
+
+    async def __call__(self, event: Message) -> bool:
+        if not isinstance(event, Message):
+            return False
+        return int(event.type) in self.types

trueconf/filters/method.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+from trueconf.filters.base import Event
+
+
+class MethodFilter:
+    def __init__(self, method: str):
+        self.method = method
+
+    async def __call__(self, event: Event) -> bool:
+        if isinstance(event, dict):
+            return event.get("method") == self.method
+        return getattr(event, "method", None) == self.method

trueconf/loggers.py

@@ -0,0 +1,4 @@
+import logging
+
+dispatcher = logging.getLogger("trueconf.dispatcher")
+chatbot = logging.getLogger("trueconf.client.chatbot")