aiogram-max 1.1.1__py3-none-any.whl

aiogram_max/__init__.py

@@ -0,0 +1,39 @@
+"""aiogram-max: запускает aiogram-бота в мессенджере MAX.
+
+Код бота не меняется — подменяется только транспорт::
+
+    from aiogram import Dispatcher
+    from aiogram_max import make_bot
+
+    bot = make_bot(max_token="...")
+    await Dispatcher().start_polling(bot)
+"""
+
+from aiogram_max.bot import create_bot, make_bot
+from aiogram_max.errors import (
+    AiogramMaxError,
+    MaxApiError,
+    NotImplementedYet,
+    UnsupportedByMax,
+)
+from aiogram_max.markup import MarkupPolicy
+from aiogram_max.session import (
+    MAX_API_URL,
+    NOT_IMPLEMENTED_PR_WELCOME,
+    MaxSession,
+    UnsupportedPolicy,
+)
+
+__all__ = [
+    "MAX_API_URL",
+    "NOT_IMPLEMENTED_PR_WELCOME",
+    "AiogramMaxError",
+    "MarkupPolicy",
+    "MaxApiError",
+    "MaxSession",
+    "NotImplementedYet",
+    "UnsupportedByMax",
+    "UnsupportedPolicy",
+    "create_bot",
+    "make_bot",
+]

aiogram_max/bot.py

@@ -0,0 +1,75 @@
+"""Сборка aiogram-бота, говорящего в MAX."""
+
+from __future__ import annotations
+
+import httpx
+from aiogram import Bot
+
+from aiogram_max.markup import MarkupPolicy
+from aiogram_max.session import MAX_API_URL, MaxSession, UnsupportedPolicy
+
+# aiogram проверяет форму токена: "<цифры>:<непустая строка>", а Bot.id парсит
+# из левой части. Токен MAX такой формы не имеет, поэтому левую часть
+# подставляем сами — туда идёт настоящий id бота. Сам токен уходит в
+# MaxSession и дальше в заголовок Authorization.
+_UNKNOWN_BOT_ID = 0
+
+
+def make_bot(
+    max_token: str,
+    *,
+    bot_id: int = _UNKNOWN_BOT_ID,
+    api_url: str = MAX_API_URL,
+    unsupported: UnsupportedPolicy = UnsupportedPolicy.WARN,
+    markup: MarkupPolicy = MarkupPolicy.CONVERT,
+    client: httpx.AsyncClient | None = None,
+    **bot_kwargs: object,
+) -> Bot:
+    """Вернуть обычный ``aiogram.Bot``, ходящий в MAX вместо Telegram.
+
+    Всё, что выше транспорта — Dispatcher, роутеры, фильтры, FSM, типы —
+    остаётся стандартным aiogram.
+
+    ``bot_id`` нужен, только если важен ``bot.id`` (мультиботовые сценарии,
+    ключи в логах). Не знаете id — берите :func:`create_bot`, он спросит
+    его у MAX сам.
+    """
+    session = MaxSession(
+        max_token,
+        api_url=api_url,
+        unsupported=unsupported,
+        markup=markup,
+        client=client,
+    )
+    return Bot(token=f"{bot_id}:max", session=session, **bot_kwargs)  # type: ignore[arg-type]
+
+
+async def create_bot(
+    max_token: str,
+    *,
+    api_url: str = MAX_API_URL,
+    unsupported: UnsupportedPolicy = UnsupportedPolicy.WARN,
+    markup: MarkupPolicy = MarkupPolicy.CONVERT,
+    client: httpx.AsyncClient | None = None,
+    **bot_kwargs: object,
+) -> Bot:
+    """То же, что :func:`make_bot`, но с настоящим ``bot.id`` из ``GET /me``.
+
+    Один лишний запрос на старте — зато ``bot.id`` не ноль, а username
+    доезжает до фильтра ``Command``, который разбирает ``/start@bot``.
+    """
+    probe = make_bot(max_token, api_url=api_url, unsupported=unsupported, client=client)
+    try:
+        me = await probe.get_me()
+    finally:
+        await probe.session.close()
+
+    return make_bot(
+        max_token,
+        bot_id=me.id,
+        api_url=api_url,
+        unsupported=unsupported,
+        markup=markup,
+        client=client,
+        **bot_kwargs,
+    )

aiogram_max/converters.py

@@ -0,0 +1,279 @@
+"""Перевод между моделями MAX и aiogram.
+
+Это единственное место, где живут знания о форме payload'ов MAX. Всё
+остальное работает в терминах aiogram-типов.
+
+Схемы MAX сверены с моделями библиотеки maxapi 1.2.1:
+* update: {update_type, timestamp, ...}
+* message: {sender: User, recipient: {user_id, chat_id, chat_type},
+            timestamp, body: {mid, seq, text, attachments}}
+* user: {user_id, first_name, last_name, username, is_bot}
+* callback: {timestamp, callback_id, payload, user}
+"""
+
+from collections.abc import Callable
+from datetime import UTC, datetime
+from typing import Any
+
+from aiogram.types import (
+    AcceptedGiftTypes,
+    CallbackQuery,
+    Chat,
+    ChatFullInfo,
+    ChatMemberAdministrator,
+    ChatMemberMember,
+    ChatMemberOwner,
+    Document,
+    InlineKeyboardMarkup,
+    Message,
+    PhotoSize,
+    Update,
+    User,
+)
+
+# MAX различает диалог с ботом и групповой чат; Telegram — private/group/channel.
+_CHAT_TYPE = {"dialog": "private", "chat": "group", "channel": "channel"}
+
+
+def chat_type(max_type: str | None) -> str:
+    return _CHAT_TYPE.get(max_type or "dialog", "private")
+
+
+def to_user(raw: dict[str, Any] | None) -> User | None:
+    """MAX user → aiogram User."""
+    if not raw:
+        return None
+    return User(
+        id=raw["user_id"],
+        is_bot=bool(raw.get("is_bot", False)),
+        # first_name в Telegram обязателен, в MAX может не прийти.
+        first_name=raw.get("first_name") or raw.get("name") or "MAX user",
+        last_name=raw.get("last_name"),
+        username=raw.get("username"),
+    )
+
+
+def to_chat(recipient: dict[str, Any], sender: dict[str, Any] | None) -> Chat:
+    """MAX recipient → aiogram Chat.
+
+    ``recipient.user_id`` в запасной путь НЕ годится: на живых событиях видно,
+    что это получатель конкретного сообщения, а не собеседник. В сообщении от
+    юзера боту там лежит id бота, в сообщении бота юзеру — id юзера. Если
+    подставить его как chat_id, бот в какой-то момент начнёт отвечать сам
+    себе, причём молча. Поэтому запасной путь только через отправителя.
+    """
+    cid = recipient.get("chat_id")
+    if cid is None and sender and not sender.get("is_bot"):
+        cid = sender.get("user_id")
+    return Chat(id=int(cid or 0), type=chat_type(recipient.get("chat_type")))
+
+
+def to_attachments(
+    raw_attachments: list[dict[str, Any]] | None,
+) -> dict[str, Any]:
+    """MAX attachments → поля aiogram Message (document / photo).
+
+    У MAX нет file_id и метода getFile: вложение приходит готовым URL внутри
+    payload. Кладём этот URL в ``file_id`` — сессия отдаёт его обратно как
+    ``file_path``, и ``bot.download`` скачивает по прямой ссылке.
+    """
+    fields: dict[str, Any] = {}
+    for att in raw_attachments or []:
+        payload = att.get("payload") or {}
+        url = payload.get("url")
+        if not url:
+            continue
+        kind = att.get("type")
+        if kind == "image" and "photo" not in fields:
+            fields["photo"] = [
+                PhotoSize(file_id=url, file_unique_id=url, width=0, height=0)
+            ]
+        elif kind in {"file", "audio", "video"} and "document" not in fields:
+            fields["document"] = Document(
+                file_id=url,
+                file_unique_id=url,
+                file_name=att.get("filename"),
+                file_size=att.get("size"),
+            )
+    return fields
+
+
+def to_message(raw: dict[str, Any]) -> Message:
+    """MAX message → aiogram Message.
+
+    ``message_id`` берём из body.seq: он целочисленный и монотонный внутри
+    чата, тогда как MAX-идентификатор ``mid`` — строка. Соответствие
+    seq → mid держит сессия, оно нужно для правки и удаления.
+    """
+    body = raw.get("body") or {}
+    sender = raw.get("sender")
+    recipient = raw.get("recipient") or {}
+    return Message(
+        message_id=int(body.get("seq") or 0),
+        date=datetime.fromtimestamp(int(raw.get("timestamp", 0)) / 1000, tz=UTC),
+        chat=to_chat(recipient, sender),
+        from_user=to_user(sender),
+        text=body.get("text"),
+        **to_attachments(body.get("attachments")),
+    )
+
+
+def to_update(raw: dict[str, Any], update_id: int) -> Update | None:
+    """MAX update → aiogram Update. None — если тип события нам не нужен."""
+    kind = raw.get("update_type")
+
+    if kind == "message_created":
+        return Update(update_id=update_id, message=to_message(raw["message"]))
+
+    if kind == "message_callback":
+        cb = raw["callback"]
+        message = raw.get("message")
+        clicker = to_user(cb.get("user"))
+        if clicker is None:
+            # Кто нажал — обязательное поле CallbackQuery в aiogram, и без него
+            # событие всё равно некуда роутить. Пропускаем как неизвестный тип,
+            # а не падаем: иначе один кривой апдейт застопорит весь polling.
+            return None
+        return Update(
+            update_id=update_id,
+            callback_query=CallbackQuery(
+                id=cb["callback_id"],
+                from_user=clicker,
+                # chat_instance в Telegram обязателен и используется только
+                # как ключ группировки; MAX аналога не имеет.
+                chat_instance=str(cb.get("callback_id")),
+                data=cb.get("payload"),
+                message=to_message(message) if message else None,
+            ),
+        )
+
+    if kind == "bot_started":
+        # Нажатие «Начать» в MAX — ближайший аналог /start в Telegram.
+        return Update(
+            update_id=update_id,
+            message=Message(
+                message_id=0,
+                date=datetime.fromtimestamp(int(raw.get("timestamp", 0)) / 1000, tz=UTC),
+                chat=Chat(id=int(raw.get("chat_id") or 0), type="private"),
+                from_user=to_user(raw.get("user")),
+                text="/start",
+            ),
+        )
+
+    return None
+
+
+# Telegram HTML/Markdown → MAX format. MarkdownV2 у MAX аналога не имеет,
+# ближайшее — markdown (CommonMark), о расхождении предупреждает вызывающий.
+_PARSE_MODE = {"HTML": "html", "Markdown": "markdown", "MarkdownV2": "markdown"}
+
+
+def parse_mode_to_format(parse_mode: str | None) -> str | None:
+    """aiogram parse_mode → MAX format."""
+    if parse_mode is None:
+        return None
+    return _PARSE_MODE.get(str(parse_mode))
+
+
+def keyboard_to_attachment(
+    markup: InlineKeyboardMarkup | None,
+    degrade: Callable[[str, str], None] | None = None,
+) -> dict[str, Any] | None:
+    """aiogram InlineKeyboardMarkup → MAX attachment inline_keyboard.
+
+    MAX знает только callback-кнопки и ссылки. Кнопку, которой нет аналога,
+    отбрасываем — показать пользователю кнопку, которая ничего не делает,
+    хуже. Но не молча: сообщаем через ``degrade``.
+    """
+    if markup is None:
+        return None
+    rows: list[list[dict[str, Any]]] = []
+    for row in markup.inline_keyboard:
+        buttons: list[dict[str, Any]] = []
+        for btn in row:
+            if btn.callback_data is not None:
+                buttons.append(
+                    {"type": "callback", "text": btn.text, "payload": btn.callback_data}
+                )
+            elif btn.url is not None:
+                buttons.append({"type": "link", "text": btn.text, "url": btn.url})
+            elif degrade is not None:
+                kind = next(
+                    (
+                        name
+                        for name in (
+                            "web_app",
+                            "login_url",
+                            "switch_inline_query",
+                            "switch_inline_query_current_chat",
+                            "callback_game",
+                            "pay",
+                            "copy_text",
+                        )
+                        if getattr(btn, name, None) is not None
+                    ),
+                    "кнопка неизвестного типа",
+                )
+                degrade(f"InlineKeyboardButton.{kind}", f"текст кнопки: {btn.text!r}")
+        if buttons:
+            rows.append(buttons)
+    if not rows:
+        return None
+    return {"type": "inline_keyboard", "payload": {"buttons": rows}}
+
+
+# MAX-тип чата → телеграмный. «dialog» — личка, «chat» — группа.
+_CHAT_TYPES = {"dialog": "private", "chat": "group", "channel": "channel"}
+
+
+def to_chat_full_info(raw: dict[str, Any]) -> ChatFullInfo:
+    """MAX chat → aiogram ChatFullInfo (её возвращает getChat)."""
+    return ChatFullInfo(
+        id=raw["chat_id"],
+        type=_CHAT_TYPES.get(str(raw.get("type")), "group"),
+        title=raw.get("title"),
+        description=raw.get("description"),
+        invite_link=raw.get("link"),
+        accent_color_id=0,
+        max_reaction_count=0,
+        # Полей про подарки у MAX нет; aiogram требует объект — отдаём пустой.
+        accepted_gift_types=AcceptedGiftTypes(
+            unlimited_gifts=False,
+            limited_gifts=False,
+            unique_gifts=False,
+            premium_subscription=False,
+            gifts_from_channels=False,
+        ),
+    )
+
+
+def to_chat_member(
+    raw: dict[str, Any],
+) -> ChatMemberOwner | ChatMemberAdministrator | ChatMemberMember:
+    """MAX participant → aiogram ChatMember.
+
+    Прав администратора MAX по отдельности не отдаёт — только флаг is_admin.
+    Поэтому телеграмные can_* проставляем в False: соврать «может всё»
+    опаснее, чем занизить, бот на это ориентируется в проверках доступа.
+    """
+    user = to_user(raw)
+    assert user is not None
+    if raw.get("is_owner"):
+        return ChatMemberOwner(user=user, is_anonymous=False)
+    if raw.get("is_admin"):
+        return ChatMemberAdministrator(
+            user=user,
+            can_be_edited=False,
+            is_anonymous=False,
+            can_manage_chat=True,
+            can_delete_messages=False,
+            can_manage_video_chats=False,
+            can_restrict_members=False,
+            can_promote_members=False,
+            can_change_info=False,
+            can_invite_users=False,
+            can_post_stories=False,
+            can_edit_stories=False,
+            can_delete_stories=False,
+        )
+    return ChatMemberMember(user=user)

aiogram_max/errors.py

@@ -0,0 +1,44 @@
+"""Ошибки слоя совместимости."""
+
+
+class AiogramMaxError(Exception):
+    """Базовая ошибка библиотеки."""
+
+
+class UnsupportedByMax(AiogramMaxError):
+    """У метода Telegram нет аналога в MAX — и не появится с нашей стороны.
+
+    Поднимается в строгом режиме. В режиме WARN метод логируется и
+    превращается в no-op: см. ``UnsupportedPolicy``.
+    """
+
+    def __init__(self, method_name: str) -> None:
+        super().__init__(
+            f"{method_name} не поддерживается MAX Bot API. "
+            "Уберите вызов или переключите MaxSession в режим WARN."
+        )
+        self.method_name = method_name
+
+
+class NotImplementedYet(AiogramMaxError):
+    """Аналог в MAX есть, но мы его ещё не написали.
+
+    Отличать это от ``UnsupportedByMax`` важно: первое — предложение прислать
+    PR, второе — свойство самой платформы, и PR тут не поможет.
+    """
+
+    def __init__(self, method_name: str, hint: str = "") -> None:
+        super().__init__(
+            f"{method_name}: в MAX аналог есть, в aiogram-max ещё не написан. "
+            f"PR welcome! {hint}".strip()
+        )
+        self.method_name = method_name
+
+
+class MaxApiError(AiogramMaxError):
+    """MAX вернул не-2xx ответ."""
+
+    def __init__(self, status: int, body: str) -> None:
+        super().__init__(f"MAX API вернул {status}: {body[:500]}")
+        self.status = status
+        self.body = body

aiogram_max/markup.py

@@ -0,0 +1,251 @@
+"""Перевод разметки Telegram в разметку MAX.
+
+Цель — html, а не CommonMark, и это не вкусовщина. Проверка на живом API
+(таблица в README) показала: тип ``underline`` MAX отдаёт только за ``<u>``.
+Через markdown подчёркивание недостижимо в принципе — телеграмное
+``__текст__`` в CommonMark означает жирный, так что конверсия в markdown
+молча превратила бы подчёркнутое в жирное. Плюс html не требует правил
+экранирования, которых в MarkdownV2 полтора десятка, да ещё и разных внутри
+кодовых спанов.
+
+Входа два, и оба сходятся в html:
+
+* ``entities`` — смещения, а не грамматика. Точный перевод, рендер берём
+  готовый из aiogram.
+* ``parse_mode=MarkdownV2`` — нужен разбор текста, этим занят ``_Scanner``.
+
+Чего у MAX нет вовсе — спойлер, цитата, кастомные эмодзи — уходит в
+``degrade``: текст сохраняется, оформление теряется, в лог пишется что
+именно. Молча не теряем ничего.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from enum import StrEnum
+
+from aiogram.types import MessageEntity
+from aiogram.utils.text_decorations import html_decoration
+
+Degrade = Callable[[str, str], None]
+
+
+class MarkupPolicy(StrEnum):
+    """Что делать с разметкой по дороге в MAX."""
+
+    # Перевести в html, понятный MAX. По умолчанию.
+    CONVERT = "convert"
+
+    # Отдать текст как есть, только проставить format. Для тех, кто
+    # форматирует сам и не хочет посредника.
+    RAW = "raw"
+
+
+# Проверено на живом MAX (см. README): эти теги он превращает в разметку.
+# blockquote и tg-spoiler не распознаются, поэтому соответствующие entity
+# отбрасываем до рендера, а не после.
+_SUPPORTED_ENTITIES = frozenset(
+    {
+        "bold",
+        "italic",
+        "underline",
+        "strikethrough",
+        "code",
+        "pre",
+        "text_link",
+        "url",
+        "text_mention",
+        "mention",
+    }
+)
+
+_ENTITY_LOSS = {
+    "spoiler": "у MAX нет спойлера",
+    "blockquote": "у MAX нет цитаты",
+    "expandable_blockquote": "у MAX нет цитаты",
+    "custom_emoji": "у MAX нет кастомных эмодзи",
+}
+
+
+def entities_to_html(
+    text: str, entities: Iterable[MessageEntity] | None, degrade: Degrade
+) -> str:
+    """``text`` + ``entities`` → html для MAX.
+
+    Неподдерживаемые entity выбрасываются до рендера: их текст остаётся,
+    оформление теряется. Рендер — ``html_decoration`` из aiogram, там уже
+    решён вопрос смещений в UTF-16.
+    """
+    kept: list[MessageEntity] = []
+    for entity in entities or []:
+        loss = _ENTITY_LOSS.get(entity.type)
+        if loss is not None:
+            degrade(f"entity {entity.type}", f"{loss}, отправлено без оформления")
+            continue
+        if entity.type in _SUPPORTED_ENTITIES:
+            kept.append(entity)
+        else:
+            degrade(f"entity {entity.type}", "нет аналога в MAX")
+    return html_decoration.unparse(text, kept)
+
+
+def markdown_to_html(text: str, degrade: Degrade) -> str:
+    """MarkdownV2 (и legacy Markdown) → html для MAX."""
+    return _Scanner(text, degrade).run()
+
+
+_ESCAPABLE = set("_*[]()~`>#+-=|{}.!\\")
+
+# Двухсимвольные раньше односимвольных: иначе ``__`` съедается как два ``_``.
+_DELIMITERS: tuple[tuple[str, str], ...] = (
+    ("||", "spoiler"),
+    ("__", "u"),
+    ("*", "b"),
+    ("_", "i"),
+    ("~", "s"),
+)
+
+
+def _escape(chunk: str) -> str:
+    return chunk.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+class _Scanner:
+    """Однопроходный разбор MarkdownV2 с выдачей html.
+
+    Промежуточных entity нет намеренно: они считаются в смещениях UTF-16, а
+    здесь эта бухгалтерия не нужна ни для чего.
+
+    Порядок важен: сначала снимается экранирование и вырезаются кодовые
+    спаны (внутри них разметки нет), и только потом разбираются эмфазы.
+    """
+
+    def __init__(self, text: str, degrade: Degrade) -> None:
+        self._text = text
+        self._degrade = degrade
+        self._out: list[str] = []
+        self._open: list[str] = []
+        self._pos = 0
+
+    def run(self) -> str:
+        text = self._text
+        while self._pos < len(text):
+            if self._take_escape():
+                continue
+            if self._take_pre():
+                continue
+            if self._take_code():
+                continue
+            if self._take_link():
+                continue
+            if self._take_delimiter():
+                continue
+            if self._take_quote_marker():
+                continue
+            self._out.append(_escape(text[self._pos]))
+            self._pos += 1
+
+        # Незакрытый разделитель — ошибка в исходном тексте: Telegram на нём
+        # отвечает 400. Закрываем сами, потому что оборванный тег испортил бы
+        # всё сообщение целиком.
+        while self._open:
+            self._out.append(f"</{self._open.pop()}>")
+        return "".join(self._out)
+
+    def _take_escape(self) -> bool:
+        text = self._text
+        if text[self._pos] != "\\" or self._pos + 1 >= len(text):
+            return False
+        nxt = text[self._pos + 1]
+        if nxt not in _ESCAPABLE:
+            return False
+        self._out.append(_escape(nxt))
+        self._pos += 2
+        return True
+
+    def _take_pre(self) -> bool:
+        text = self._text
+        if not text.startswith("```", self._pos):
+            return False
+        end = text.find("```", self._pos + 3)
+        if end == -1:
+            return False
+        body = text[self._pos + 3 : end]
+        # Первая строка после ``` — либо язык (в MAX ему места нет), либо
+        # пусто. В обоих случаях в тело кода она не входит.
+        if "\n" in body:
+            first, rest = body.split("\n", 1)
+            head = first.strip()
+            if not head or " " not in head:
+                body = rest
+        self._out.append(f"<pre>{_escape(body)}</pre>")
+        self._pos = end + 3
+        return True
+
+    def _take_code(self) -> bool:
+        text = self._text
+        if text[self._pos] != "`":
+            return False
+        end = text.find("`", self._pos + 1)
+        if end == -1:
+            return False
+        body = text[self._pos + 1 : end].replace("\\`", "`").replace("\\\\", "\\")
+        self._out.append(f"<code>{_escape(body)}</code>")
+        self._pos = end + 1
+        return True
+
+    def _take_link(self) -> bool:
+        text = self._text
+        emoji = text.startswith("![", self._pos)
+        start = self._pos + 2 if emoji else self._pos + 1
+        if not emoji and text[self._pos] != "[":
+            return False
+        close = text.find("](", start)
+        if close == -1:
+            return False
+        end = text.find(")", close + 2)
+        if end == -1:
+            return False
+        label = text[start:close]
+        url = text[close + 2 : end]
+        self._pos = end + 1
+        if emoji or url.startswith("tg://emoji"):
+            self._degrade(
+                "custom_emoji", "у MAX нет кастомных эмодзи, оставлен только текст"
+            )
+            self._out.append(_escape(label))
+            return True
+        self._out.append(f'<a href="{_escape(url)}">{_escape(label)}</a>')
+        return True
+
+    def _take_delimiter(self) -> bool:
+        text = self._text
+        for delim, tag in _DELIMITERS:
+            if not text.startswith(delim, self._pos):
+                continue
+            self._pos += len(delim)
+            if tag == "spoiler":
+                # Открывающий и закрывающий || просто исчезают: текст между
+                # ними остаётся видимым и неформатированным.
+                self._degrade("spoiler", "у MAX нет спойлера, текст оставлен открытым")
+                return True
+            if self._open and self._open[-1] == tag:
+                self._out.append(f"</{self._open.pop()}>")
+            else:
+                self._open.append(tag)
+                self._out.append(f"<{tag}>")
+            return True
+        return False
+
+    def _take_quote_marker(self) -> bool:
+        text = self._text
+        if text[self._pos] != ">":
+            return False
+        at_line_start = self._pos == 0 or text[self._pos - 1] == "\n"
+        if not at_line_start:
+            return False
+        self._degrade("blockquote", "у MAX нет цитаты, отправлено обычным текстом")
+        self._pos += 1
+        if self._pos < len(text) and text[self._pos] == " ":
+            self._pos += 1
+        return True