maxapi-sdk 0.12.0__py3-none-any.whl

maxapi/builders/keyboards.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+SPECIAL_ROW_LIMIT_TYPES = {
+    "link",
+    "open_app",
+    "request_contact",
+    "request_geo_location",
+}
+
+
+class InlineKeyboardBuilder:
+    """Builder для MAX inline keyboard."""
+
+    def __init__(self) -> None:
+        self._rows: list[list[dict[str, Any]]] = []
+        self._pending: list[dict[str, Any]] = []
+
+    def add(self, *buttons: dict[str, Any]) -> "InlineKeyboardBuilder":
+        for button in buttons:
+            self._pending.append(_normalize_button(button))
+        return self
+
+    def button(self, *, button_type: str, text: str, **extra: Any) -> "InlineKeyboardBuilder":
+        button = {"type": button_type, "text": text}
+        button.update({key: value for key, value in extra.items() if value is not None})
+        return self.add(button)
+
+    def callback(self, text: str, payload: str | dict[str, Any]) -> "InlineKeyboardBuilder":
+        return self.button(button_type="callback", text=text, payload=payload)
+
+    def link(self, text: str, url: str) -> "InlineKeyboardBuilder":
+        return self.button(button_type="link", text=text, url=url)
+
+    def request_contact(self, text: str) -> "InlineKeyboardBuilder":
+        return self.button(button_type="request_contact", text=text)
+
+    def request_geo_location(self, text: str) -> "InlineKeyboardBuilder":
+        return self.button(button_type="request_geo_location", text=text)
+
+    def open_app(
+        self,
+        text: str,
+        *,
+        url: str | None = None,
+        app_id: str | None = None,
+        payload: str | dict[str, Any] | None = None,
+    ) -> "InlineKeyboardBuilder":
+        return self.button(
+            button_type="open_app",
+            text=text,
+            url=url,
+            app_id=app_id,
+            payload=payload,
+        )
+
+    def message(self, text: str, message_text: str) -> "InlineKeyboardBuilder":
+        return self.button(button_type="message", text=text, message_text=message_text)
+
+    def row(self, *buttons: dict[str, Any]) -> "InlineKeyboardBuilder":
+        normalized = [_normalize_button(button) for button in buttons]
+        if normalized:
+            self._append_row(normalized)
+        elif self._pending:
+            self._append_row(self._consume_pending())
+        return self
+
+    def adjust(self, *sizes: int, repeat: bool = False) -> "InlineKeyboardBuilder":
+        if not self._pending:
+            return self
+        if not sizes:
+            sizes = (7,)
+        index = 0
+        pattern_index = 0
+        while index < len(self._pending):
+            row_size = sizes[pattern_index]
+            row = self._pending[index:index + row_size]
+            self._append_row(row)
+            index += row_size
+            if repeat:
+                pattern_index = (pattern_index + 1) % len(sizes)
+            else:
+                pattern_index = min(pattern_index + 1, len(sizes) - 1)
+        self._pending.clear()
+        return self
+
+    def as_markup(self) -> dict[str, Any]:
+        self._flush_pending()
+        return {"type": "inline_keyboard", "payload": {"buttons": self._rows}}
+
+    def as_attachment(self) -> dict[str, Any]:
+        return self.as_markup()
+
+    def export(self) -> list[list[dict[str, Any]]]:
+        self._flush_pending()
+        return [[dict(button) for button in row] for row in self._rows]
+
+    def _consume_pending(self) -> list[dict[str, Any]]:
+        items = list(self._pending)
+        self._pending.clear()
+        return items
+
+    def _flush_pending(self) -> None:
+        if not self._pending:
+            return
+        self.adjust(7, repeat=True)
+
+    def _append_row(self, row: Iterable[dict[str, Any]]) -> None:
+        normalized = [dict(item) for item in row]
+        if not normalized:
+            return
+        if len(normalized) > 7:
+            raise ValueError("В одном ряду MAX inline keyboard может быть не более 7 кнопок.")
+        if any(item.get("type") in SPECIAL_ROW_LIMIT_TYPES for item in normalized) and len(normalized) > 3:
+            raise ValueError(
+                "Ряд с кнопками link/open_app/request_contact/request_geo_location "
+                "может содержать не более 3 кнопок."
+            )
+        if len(self._rows) >= 30:
+            raise ValueError("MAX inline keyboard поддерживает не более 30 рядов.")
+        total_buttons = sum(len(existing_row) for existing_row in self._rows) + len(normalized)
+        if total_buttons > 210:
+            raise ValueError("MAX inline keyboard поддерживает не более 210 кнопок.")
+        self._rows.append(normalized)
+
+
+def _normalize_button(button: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(button, dict):
+        raise TypeError(f"Кнопка должна быть dict, получено: {button!r}")
+    if "type" not in button or "text" not in button:
+        raise ValueError("Кнопка должна содержать поля 'type' и 'text'.")
+    return {key: value for key, value in button.items() if value is not None}

maxapi/builders/media.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+
+def make_attachment(attachment_type: str, payload: dict[str, Any]) -> dict[str, Any]:
+    return {"type": attachment_type, "payload": payload}
+
+
+def image_attachment(*, token: str | None = None, url: str | None = None, **extra: Any) -> dict[str, Any]:
+    payload = _build_payload(token=token, url=url, extra=extra)
+    return make_attachment("image", payload)
+
+
+def video_attachment(*, token: str | None = None, url: str | None = None, **extra: Any) -> dict[str, Any]:
+    payload = _build_payload(token=token, url=url, extra=extra)
+    return make_attachment("video", payload)
+
+
+def audio_attachment(*, token: str | None = None, url: str | None = None, **extra: Any) -> dict[str, Any]:
+    payload = _build_payload(token=token, url=url, extra=extra)
+    return make_attachment("audio", payload)
+
+
+def file_attachment(*, token: str | None = None, url: str | None = None, **extra: Any) -> dict[str, Any]:
+    payload = _build_payload(token=token, url=url, extra=extra)
+    return make_attachment("file", payload)
+
+
+def normalize_attachment(item: Any) -> dict[str, Any]:
+    if item is None:
+        raise TypeError("Attachment не может быть None.")
+    if isinstance(item, dict):
+        return item
+    if hasattr(item, "as_attachment"):
+        return item.as_attachment()
+    if hasattr(item, "model_dump"):
+        return item.model_dump(by_alias=True, exclude_none=True)
+    raise TypeError(f"Неподдерживаемый attachment: {item!r}")
+
+
+def normalize_attachments(
+    attachments: Iterable[Any] | None = None,
+    *,
+    keyboard: Any | None = None,
+) -> list[dict[str, Any]] | None:
+    normalized: list[dict[str, Any]] = []
+    if attachments is not None:
+        for item in attachments:
+            normalized.append(normalize_attachment(item))
+    if keyboard is not None:
+        normalized.append(normalize_attachment(keyboard))
+    if not normalized:
+        return None
+    return normalized
+
+
+def build_uploaded_attachment(
+    *,
+    upload_type: str,
+    upload_response_token: str | None,
+    uploaded_payload: dict[str, Any],
+) -> dict[str, Any]:
+    payload = dict(uploaded_payload)
+    if payload.get("token") is None and upload_response_token is not None:
+        payload["token"] = upload_response_token
+    return make_attachment(upload_type, payload)
+
+
+def _build_payload(
+    *,
+    token: str | None,
+    url: str | None,
+    extra: dict[str, Any],
+) -> dict[str, Any]:
+    payload = dict(extra)
+    if token is not None:
+        payload["token"] = token
+    if url is not None:
+        payload["url"] = url
+    return payload

maxapi/callback_schema.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+from typing import Any, ClassVar, TypeVar, get_origin
+from urllib.parse import quote, unquote
+
+from pydantic import TypeAdapter
+
+from .types import ApiModel
+
+PayloadSchemaType = TypeVar("PayloadSchemaType", bound="CallbackPayloadSchema")
+
+
+class CallbackPayloadError(ValueError):
+    """Ошибка сериализации или десериализации callback payload."""
+
+
+class CallbackPayloadSchema(ApiModel):
+    """Структурированная схема callback payload.
+
+    Пример:
+
+        class AdminAction(CallbackPayloadSchema):
+            prefix = "admin"
+            action: str
+            user_id: int
+
+        payload = AdminAction(action="ban", user_id=42).pack()
+        parsed = AdminAction.unpack(payload)
+    """
+
+    prefix: ClassVar[str] = ""
+    sep: ClassVar[str] = ":"
+
+    def pack(self) -> str:
+        field_names = list(type(self).model_fields)
+        values = [self.prefix or type(self).__name__.lower()]
+        for field_name in field_names:
+            values.append(_encode_component(getattr(self, field_name)))
+        return self.sep.join(values)
+
+    @classmethod
+    def unpack(cls, payload: Any) -> PayloadSchemaType:
+        payload_text = extract_callback_value(payload)
+        if payload_text is None:
+            raise CallbackPayloadError("Не удалось извлечь текстовый callback payload.")
+        parts = payload_text.split(cls.sep)
+        expected_prefix = cls.prefix or cls.__name__.lower()
+        if not parts or parts[0] != expected_prefix:
+            raise CallbackPayloadError(
+                f"Некорректный prefix callback payload: ожидался {expected_prefix!r}."
+            )
+        field_names = list(cls.model_fields)
+        raw_values = parts[1:]
+        if len(raw_values) != len(field_names):
+            raise CallbackPayloadError(
+                "Количество значений callback payload не совпадает с количеством полей схемы."
+            )
+        converted: dict[str, Any] = {}
+        for index, field_name in enumerate(field_names):
+            field_info = cls.model_fields[field_name]
+            converted[field_name] = _convert_component(
+                unquote(raw_values[index]),
+                field_info.annotation,
+            )
+        return cls(**converted)
+
+    @classmethod
+    def filter(cls, **conditions: Any):
+        return CallbackSchemaFilter(cls, **conditions)
+
+
+class CallbackSchemaFilter:
+    def __init__(self, schema: type[CallbackPayloadSchema], **conditions: Any) -> None:
+        self.schema = schema
+        self.conditions = conditions
+
+    async def __call__(self, event: Any) -> bool:
+        update = getattr(event, "update", None)
+        callback = getattr(update, "callback", None)
+        payload = getattr(callback, "payload", None)
+        try:
+            parsed = self.schema.unpack(payload)
+        except CallbackPayloadError:
+            return False
+        for key, expected_value in self.conditions.items():
+            if getattr(parsed, key, None) != expected_value:
+                return False
+        return True
+
+
+def extract_callback_value(payload: Any) -> str | None:
+    if payload is None:
+        return None
+    if isinstance(payload, str):
+        return payload
+    if isinstance(payload, dict):
+        for key in ("data", "payload", "value"):
+            item = payload.get(key)
+            if isinstance(item, str):
+                return item
+        return None
+    return None
+
+
+def extract_callback_mapping(payload: Any) -> dict[str, Any] | None:
+    if payload is None:
+        return None
+    if isinstance(payload, dict):
+        return dict(payload)
+    if isinstance(payload, str):
+        try:
+            parsed = json.loads(payload)
+        except json.JSONDecodeError:
+            return None
+        if isinstance(parsed, dict):
+            return parsed
+    return None
+
+
+def _encode_component(value: Any) -> str:
+    if isinstance(value, (dict, list)):
+        serialized = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    else:
+        serialized = str(value)
+    return quote(serialized, safe="")
+
+
+def _convert_component(raw_value: str, annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    candidate: Any = raw_value
+    if annotation is Any:
+        return raw_value
+    if annotation in {dict, list} or origin in {dict, list, tuple, set}:
+        try:
+            candidate = json.loads(raw_value)
+        except json.JSONDecodeError:
+            candidate = raw_value
+    adapter = TypeAdapter(annotation)
+    return adapter.validate_python(candidate)

maxapi/client/__init__.py

@@ -0,0 +1,3 @@
+from .default import DefaultConnectionProperties
+
+__all__ = ["DefaultConnectionProperties"]

maxapi/client/default.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from aiohttp import ClientTimeout
+
+
+@dataclass(slots=True)
+class DefaultConnectionProperties:
+    """Расширенная конфигурация HTTP-соединения."""
+
+    timeout_seconds: float = 150.0
+    sock_connect: float = 30.0
+    sock_read: float = 60.0
+    connector_limit: int = 100
+    connector_limit_per_host: int = 30
+    trust_env: bool = False
+    auto_decompress: bool = True
+    raise_for_status: bool = False
+    request_retries: int = 5
+    request_retry_delay: float = 0.5
+    request_retry_backoff: float = 2.0
+    request_retry_max_delay: float = 8.0
+    respect_retry_after: bool = True
+    retry_statuses: tuple[int, ...] = (408, 425, 429, 500, 502, 503, 504)
+    retry_methods: tuple[str, ...] = (
+        "DELETE",
+        "GET",
+        "HEAD",
+        "OPTIONS",
+        "PATCH",
+        "POST",
+        "PUT",
+    )
+    timeout: ClientTimeout = field(init=False)
+    kwargs: dict[str, Any] = field(default_factory=dict)
+
+    def __init__(
+        self,
+        timeout: float = 150.0,
+        sock_connect: float = 30.0,
+        sock_read: float = 60.0,
+        connector_limit: int = 100,
+        connector_limit_per_host: int = 30,
+        trust_env: bool = False,
+        auto_decompress: bool = True,
+        raise_for_status: bool = False,
+        request_retries: int = 5,
+        request_retry_delay: float = 0.5,
+        request_retry_backoff: float = 2.0,
+        request_retry_max_delay: float = 8.0,
+        respect_retry_after: bool = True,
+        retry_statuses: tuple[int, ...] | None = None,
+        retry_methods: tuple[str, ...] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.timeout_seconds = timeout
+        self.sock_connect = sock_connect
+        self.sock_read = sock_read
+        self.connector_limit = connector_limit
+        self.connector_limit_per_host = connector_limit_per_host
+        self.trust_env = trust_env
+        self.auto_decompress = auto_decompress
+        self.raise_for_status = raise_for_status
+        self.request_retries = request_retries
+        self.request_retry_delay = request_retry_delay
+        self.request_retry_backoff = request_retry_backoff
+        self.request_retry_max_delay = request_retry_max_delay
+        self.respect_retry_after = respect_retry_after
+        self.retry_statuses = retry_statuses or (408, 425, 429, 500, 502, 503, 504)
+        self.retry_methods = retry_methods or (
+            "DELETE",
+            "GET",
+            "HEAD",
+            "OPTIONS",
+            "PATCH",
+            "POST",
+            "PUT",
+        )
+        self.timeout = ClientTimeout(
+            total=timeout,
+            sock_connect=sock_connect,
+            sock_read=sock_read,
+        )
+        self.kwargs = dict(kwargs)
+        self.kwargs.setdefault("trust_env", trust_env)
+        self.kwargs.setdefault("auto_decompress", auto_decompress)
+        self.kwargs.setdefault("raise_for_status", raise_for_status)

maxapi/compat/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from ..bot import Bot as LegacyBot
+from ..builders import InlineKeyboardBuilder as Keyboard
+from ..dispatcher import Dispatcher as LegacyDispatcher
+from ..dispatcher import Router as LegacyRouter
+from ..types import MessageBody as NewMessageBody
+
+__all__ = [
+    "Keyboard",
+    "LegacyBot",
+    "LegacyDispatcher",
+    "LegacyRouter",
+    "NewMessageBody",
+]

maxapi/connection/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseConnection
+
+__all__ = ["BaseConnection"]

maxapi/connection/base.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import aiofiles
+from aiohttp import FormData
+
+from ..transport import MaxApiTransport, TransportConfig
+from ..types.bot_mixin import BotMixin
+
+if TYPE_CHECKING:
+    from aiohttp import ClientSession
+
+
+class BaseConnection(BotMixin):
+    """Базовый класс transport-aware соединения."""
+
+    API_URL = "https://platform-api.max.ru"
+
+    def __init__(self) -> None:
+        self.bot = None
+        self.session: ClientSession | None = None
+        self.api_url = self.API_URL
+        self._transport: MaxApiTransport | None = None
+
+    def set_api_url(self, url: str) -> None:
+        self.api_url = url.rstrip("/")
+        if self.bot is not None:
+            self.bot.api_url = self.api_url
+        self._transport = None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        model: Any = None,
+        *,
+        is_return_raw: bool = False,
+        **kwargs: Any,
+    ) -> Any:
+        bot = self._ensure_bot()
+        transport = self._ensure_transport(bot)
+        response = await transport.request(method=method, path=path, model=model, **kwargs)
+        if is_return_raw:
+            return response.raw
+        parsed = response.parsed
+        self._bind_bot(bot=bot, payload=parsed)
+        return parsed
+
+    async def upload_file(self, url: str, path: str, upload_type: str) -> Any:
+        async with aiofiles.open(path, "rb") as file_object:
+            file_data = await file_object.read()
+        filename = Path(path).name
+        return await self.upload_file_buffer(
+            filename=filename,
+            url=url,
+            buffer=file_data,
+            upload_type=upload_type,
+        )
+
+    async def upload_file_buffer(
+        self,
+        *,
+        filename: str,
+        url: str,
+        buffer: bytes,
+        upload_type: str,
+    ) -> Any:
+        ext = Path(filename).suffix
+        if not ext:
+            guessed_ext = mimetypes.guess_extension(f"{upload_type}/*") or ""
+            ext = guessed_ext
+        content_type = mimetypes.guess_type(filename)[0] or f"{upload_type}/*"
+        form = FormData(quote_fields=False)
+        form.add_field(
+            name="data",
+            value=buffer,
+            filename=f"{Path(filename).stem}{ext}",
+            content_type=content_type,
+        )
+        transport = self._ensure_transport(self._ensure_bot())
+        payload_text = await transport.upload(url=url, data=form)
+        try:
+            return json.loads(payload_text)
+        except json.JSONDecodeError:
+            return {"text": payload_text}
+
+    def _ensure_transport(self, bot: Any) -> MaxApiTransport:
+        if self._transport is not None:
+            return self._transport
+        config = TransportConfig.from_default_connection(bot.default_connection)
+        config.session_kwargs.setdefault(
+            "connector_limit",
+            getattr(bot.default_connection, "connector_limit", 100),
+        )
+        config.session_kwargs.setdefault(
+            "connector_limit_per_host",
+            getattr(bot.default_connection, "connector_limit_per_host", 30),
+        )
+        self._transport = MaxApiTransport(
+            base_url=bot.api_url,
+            headers=dict(getattr(bot, "headers", {})),
+            config=config,
+            session=getattr(bot, "session", None),
+        )
+        if self._transport.session is not None:
+            bot.session = self._transport.session
+            self.session = self._transport.session
+        return self._transport
+
+    def _bind_bot(self, *, bot: Any, payload: Any) -> None:
+        if payload is None:
+            return
+        if hasattr(payload, "bind_bot"):
+            payload.bind_bot(bot)
+        if hasattr(payload, "message") and getattr(payload, "message") is not None:
+            message = getattr(payload, "message")
+            if hasattr(message, "bind_bot"):
+                message.bind_bot(bot)
+        if hasattr(payload, "messages"):
+            for message in getattr(payload, "messages") or []:
+                if hasattr(message, "bind_bot"):
+                    message.bind_bot(bot)
+        if hasattr(payload, "updates"):
+            for update in getattr(payload, "updates") or []:
+                message = getattr(update, "message", None)
+                if message is not None and hasattr(message, "bind_bot"):
+                    message.bind_bot(bot)
+                callback = getattr(update, "callback", None)
+                if callback is not None and getattr(callback, "message", None) is not None:
+                    callback_message = callback.message
+                    if hasattr(callback_message, "bind_bot"):
+                        callback_message.bind_bot(bot)