maxapi-python 1.2.4__py3-none-any.whl → 2.0.0__py3-none-any.whl

pymax/files/__init__.py

@@ -0,0 +1,9 @@
+from .file import File
+from .photo import Photo
+from .video import Video
+
+__all__ = (
+    "File",
+    "Photo",
+    "Video",
+)

pymax/files/base.py

@@ -0,0 +1,82 @@
+import os
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+
+import aiofiles
+import aiohttp
+
+
+class BaseFile(ABC):
+    def __init__(
+        self, raw: bytes | None = None, *, path: str | None, url: str | None, name: str | None
+    ) -> None:
+        self.path = path
+        self.url = url
+        self.raw = raw
+        self.name = name
+
+        if raw is None and not url and not path:
+            raise ValueError("Path or Url or Raw must be provided")
+
+        if raw is not None and not name:
+            raise ValueError("Name must be provided for raw data")
+
+        sources = sum(source is not None for source in (raw, url, path))
+        if sources > 1:
+            raise ValueError("Only one of raw, url or path must be provided.")
+
+    @abstractmethod
+    async def read(self) -> bytes:
+        if self.raw:
+            return self.raw
+
+        if self.path:
+            async with aiofiles.open(self.path, "rb") as f:
+                return await f.read()
+        elif self.url:
+            async with aiohttp.ClientSession() as session:  # noqa: SIM117
+                async with session.get(self.url) as resp:
+                    resp.raise_for_status()
+                    return await resp.read()
+        else:
+            raise ValueError("Path or Url must be provided")
+
+    @abstractmethod
+    async def size(self) -> int:
+        if self.raw:
+            return len(self.raw)
+
+        if self.path:
+            return os.path.getsize(self.path)
+
+        if self.url:
+            async with aiohttp.ClientSession() as session:  # noqa: SIM117
+                async with session.head(self.url) as resp:
+                    return int(resp.headers["Content-Length"])
+        else:
+            raise ValueError("Path or Url must be provided")
+
+    @abstractmethod
+    async def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        if size <= 0:
+            raise ValueError("size must be greater than zero")
+
+        if self.raw:
+            for i in range(0, len(self.raw), size):
+                yield self.raw[i : i + size]
+
+        if self.path:
+            async with aiofiles.open(self.path, "rb") as f:
+                while True:
+                    data = await f.read(size)
+
+                    if not data:
+                        break
+                    yield data
+
+        if self.url:
+            async with aiohttp.ClientSession() as session:  # noqa: SIM117
+                async with session.get(self.url) as resp:
+                    resp.raise_for_status()
+                    async for chunk in resp.content.iter_chunked(size):
+                        yield chunk

pymax/files/file.py

@@ -0,0 +1,76 @@
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from .base import BaseFile
+
+
+class File(BaseFile):
+    """Обычный файл для отправки в сообщение.
+
+    Используйте ``File`` в ``attachments`` у ``send_message``, ``Message.answer``
+    или ``Chat.answer``. Источником может быть ``path``, ``url`` или ``raw``;
+    передавайте только один источник. Для ``raw`` обязательно укажите ``name``.
+
+    Args:
+        raw: Байты файла.
+        url: URL, откуда PyMax скачает файл перед upload.
+        path: Локальный путь к файлу.
+        name: Имя файла, которое будет отправлено Max.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import File
+
+           await client.send_message(
+               chat_id=123,
+               text="Документ",
+               attachments=[File(path="report.pdf")],
+           )
+    """
+
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        url: str | None = None,
+        path: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        self.name: str = name or ""
+        if not self.name and path:
+            self.name = Path(path).name
+        elif not self.name and url:
+            self.name = Path(url).name
+
+        if not self.name:
+            raise ValueError("Either name, url or path must be provided.")
+
+        super().__init__(raw=raw, url=url, path=path, name=self.name)
+
+    async def read(self) -> bytes:
+        """Читает файл целиком в память.
+
+        Returns:
+            Байты файла.
+        """
+        return await super().read()
+
+    async def size(self) -> int:
+        """Возвращает размер файла в байтах.
+
+        Returns:
+            Размер файла.
+        """
+        return await super().size()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        """Итерирует файл чанками.
+
+        Args:
+            size: Размер чанка в байтах.
+
+        Returns:
+            Async generator с байтами.
+        """
+        return super().iter_chunks(size)

pymax/files/photo.py

@@ -0,0 +1,108 @@
+import mimetypes
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from .base import BaseFile
+from .static import ALLOWED_EXTENSIONS
+
+
+class Photo(BaseFile):
+    """Фото для отправки в сообщение.
+
+    ``Photo`` принимает ``path``, ``url`` или ``raw`` и проверяет расширение:
+    ``.jpg``, ``.jpeg``, ``.png``, ``.gif``, ``.webp`` или ``.bmp``.
+
+    Args:
+        raw: Байты изображения.
+        url: URL изображения.
+        path: Локальный путь к изображению.
+        name: Имя файла. Обязательно для ``raw``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Photo
+
+           await client.send_message(
+               chat_id=123,
+               text="Фото",
+               attachments=[Photo(path="image.jpg")],
+           )
+    """
+
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        url: str | None = None,
+        path: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        if path:
+            self.file_name = Path(path).name
+        elif url:
+            self.file_name = Path(url).name
+        elif name:
+            self.file_name = name
+        else:
+            self.file_name = ""
+
+        super().__init__(raw=raw, url=url, path=path, name=name)
+
+    def validate_photo(self) -> tuple[str, str] | None:
+        """Проверяет расширение и MIME-тип фото.
+
+        Returns:
+            ``(extension, mime_type)`` или ``None``, если источник не задан.
+
+        Raises:
+            ValueError: Если расширение или MIME-тип не похожи на изображение.
+        """
+        if self.path or self.raw is not None:
+            source_name = self.path or self.file_name
+            extension = Path(source_name).suffix.lower()
+            if extension not in ALLOWED_EXTENSIONS:
+                msg = f"Invalid photo extension: {extension}. Allowed: {ALLOWED_EXTENSIONS}"
+                raise ValueError(msg)
+            return (extension[1:], ("image/" + extension[1:]).lower())
+        if self.url:
+            extension = Path(self.url).suffix.lower()
+            if extension not in ALLOWED_EXTENSIONS:
+                msg = f"Invalid photo extension: {extension}. Allowed: {ALLOWED_EXTENSIONS}"
+                raise ValueError(msg)
+
+            mime_type = mimetypes.guess_type(self.url)[0]
+
+            if not mime_type or not mime_type.startswith("image/"):
+                msg = f"URL does not appear to be an image: {self.url}"
+                raise ValueError(msg)
+
+            return (extension[1:], mime_type)
+        return None
+
+    async def read(self) -> bytes:
+        """Читает фото целиком в память.
+
+        Returns:
+            Байты изображения.
+        """
+        return await super().read()
+
+    async def size(self) -> int:
+        """Возвращает размер фото в байтах.
+
+        Returns:
+            Размер изображения.
+        """
+        return await super().size()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        """Итерирует фото чанками.
+
+        Args:
+            size: Размер чанка в байтах.
+
+        Returns:
+            Async generator с байтами.
+        """
+        return super().iter_chunks(size)

pymax/files/static.py

@@ -0,0 +1,10 @@
+from typing import Final
+
+ALLOWED_EXTENSIONS: Final[set[str]] = {
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".webp",
+    ".bmp",
+}

pymax/files/video.py

@@ -0,0 +1,74 @@
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from .base import BaseFile
+
+
+class Video(BaseFile):
+    """Видео для отправки в сообщение.
+
+    ``Video`` принимает ``path``, ``url`` или ``raw``. При отправке PyMax
+    загружает видео чанками и ждет от Max событие готовности обработки.
+
+    Args:
+        raw: Байты видео.
+        url: URL видео.
+        path: Локальный путь к видео.
+        name: Имя файла. Обязательно для ``raw``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Video
+
+           await client.send_message(
+               chat_id=123,
+               text="Видео",
+               attachments=[Video(path="clip.mp4")],
+           )
+    """
+
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        url: str | None = None,
+        path: str | None = None,
+        name: str | None = None,
+    ) -> None:
+        self.name: str = name or ""
+        if not self.name and path:
+            self.name = Path(path).name
+        elif not self.name and url:
+            self.name = Path(url).name
+
+        if not self.name:
+            raise ValueError("Either name, url or path must be provided.")
+        super().__init__(raw=raw, url=url, path=path, name=self.name)
+
+    async def read(self) -> bytes:
+        """Читает видео целиком в память.
+
+        Returns:
+            Байты видео.
+        """
+        return await super().read()
+
+    async def size(self) -> int:
+        """Возвращает размер видео в байтах.
+
+        Returns:
+            Размер видео.
+        """
+        return await super().size()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        """Итерирует видео чанками.
+
+        Args:
+            size: Размер чанка в байтах.
+
+        Returns:
+            Async generator с байтами.
+        """
+        return super().iter_chunks(size)

pymax/formatting/markdown.py

@@ -0,0 +1,217 @@
+from pymax.types.domain.element import Element, ElementAttributes
+
+
+class Formatter:
+    MARKERS = {
+        "```": "CODE",
+        "**": "STRONG",
+        "__": "UNDERLINE",
+        "~~": "STRIKETHROUGH",
+        "`": "MONOSPACED",
+        "_": "EMPHASIZED",
+        "*": "EMPHASIZED",
+    }
+
+    MARKER_ORDER = ["```", "**", "__", "~~", "`", "_", "*"]
+
+    @staticmethod
+    def _parse_link(
+        text: str,
+        i: int,
+        clean_pos: int,
+    ) -> tuple[str, str, int] | None:
+        if not text.startswith("[", i):
+            return None
+
+        label_end = text.find("]", i + 1)
+        if label_end == -1:
+            return None
+
+        if label_end + 1 >= len(text) or text[label_end + 1] != "(":
+            return None
+
+        url_start = label_end + 2
+        url_end = text.find(")", url_start)
+        if url_end == -1:
+            return None
+
+        label = text[i + 1 : label_end]
+        url = text[url_start:url_end]
+
+        if not label or not url:
+            return None
+
+        return label, url, url_end + 1
+
+    @staticmethod
+    def format_markdown(text: str) -> tuple[str, list[Element]]:
+        clean_text = ""
+        entities: list[Element] = []
+
+        i = 0
+        clean_pos = 0
+        active: dict[str, int] = {}
+
+        line_start = True
+
+        while i < len(text):
+            handled = False
+
+            # LINK: [text](url)
+            parsed_link = Formatter._parse_link(text, i, clean_pos)
+
+            if parsed_link is not None:
+                label, url, next_i = parsed_link
+
+                start = clean_pos
+
+                clean_text += label
+                clean_pos += len(label)
+
+                entities.append(
+                    Element(
+                        type="LINK",
+                        from_=start,
+                        length=len(label),
+                        attributes=ElementAttributes(url=url),
+                    )
+                )
+
+                i = next_i
+                line_start = False
+                continue
+
+            # HEADING: # Title
+            if line_start and text[i] == "#":
+                start_i = i
+
+                while i < len(text) and text[i] == "#":
+                    i += 1
+
+                if i < len(text) and text[i] == " ":
+                    i += 1
+                    start = clean_pos
+
+                    while i < len(text) and text[i] != "\n":
+                        clean_text += text[i]
+                        i += 1
+                        clean_pos += 1
+
+                    length = clean_pos - start
+
+                    if length > 0:
+                        entities.append(
+                            Element(
+                                type="HEADING",
+                                from_=start,
+                                length=length,
+                            )
+                        )
+
+                    line_start = False
+                    continue
+
+                i = start_i
+
+            # QUOTE: > text
+            if line_start and text[i] == ">":
+                i += 1
+
+                if i < len(text) and text[i] == " ":
+                    i += 1
+
+                start = clean_pos
+
+                while i < len(text) and text[i] != "\n":
+                    clean_text += text[i]
+                    i += 1
+                    clean_pos += 1
+
+                length = clean_pos - start
+
+                if length > 0:
+                    entities.append(
+                        Element(
+                            type="QUOTE",
+                            from_=start,
+                            length=length,
+                        )
+                    )
+
+                line_start = False
+                continue
+
+            for marker in Formatter.MARKER_ORDER:
+                if not text.startswith(marker, i):
+                    continue
+
+                marker_len = len(marker)
+
+                if marker not in active:
+                    if marker == "```":
+                        closing_index = text.find(marker, i + marker_len)
+
+                        if closing_index == -1 or closing_index == i + marker_len:
+                            clean_text += marker
+                            clean_pos += marker_len
+                            i += marker_len
+                            handled = True
+                            break
+
+                        active[marker] = clean_pos
+                        i += marker_len
+
+                        line_end = text.find("\n", i)
+                        if line_end != -1 and line_end < closing_index:
+                            i = line_end + 1
+
+                        handled = True
+                        break
+
+                    end = text.find("\n", i + marker_len)
+                    closing_index = text.find(
+                        marker,
+                        i + marker_len,
+                        None if end == -1 else end,
+                    )
+
+                    if closing_index == -1 or closing_index == i + marker_len:
+                        clean_text += marker
+                        clean_pos += marker_len
+                        i += marker_len
+                        handled = True
+                        break
+
+                    active[marker] = clean_pos
+                    i += marker_len
+                    handled = True
+                    break
+
+                start = active[marker]
+                length = clean_pos - start
+
+                if length > 0:
+                    entities.append(
+                        Element(
+                            type=Formatter.MARKERS[marker],
+                            from_=start,
+                            length=length,
+                        )
+                    )
+
+                del active[marker]
+                i += marker_len
+                handled = True
+                break
+
+            if handled:
+                line_start = False
+                continue
+
+            clean_text += text[i]
+            line_start = text[i] == "\n"
+
+            i += 1
+            clean_pos += 1
+
+        return clean_text, entities

pymax/infra/__init__.py

@@ -0,0 +1 @@
+from .base import BaseMixin

pymax/infra/auth.py

@@ -0,0 +1,55 @@
+from pymax.api.auth.types import MISSING, Missing
+from pymax.auth.providers import EmailCodeProvider
+
+from .protocol import IClientProtocol
+
+
+class AuthMixin(IClientProtocol):
+    """Методы клиента для управления 2FA текущего аккаунта."""
+
+    async def set_2fa(
+        self,
+        password: str,
+        email: str | Missing = MISSING,
+        hint: str | Missing = MISSING,
+        email_code_provider: EmailCodeProvider | None = None,
+    ) -> bool:
+        """Устанавливает пароль 2FA для текущей учетной записи.
+
+        Если ``email`` или ``hint`` не переданы, PyMax не добавляет
+        соответствующую настройку. Если ``email`` передан без
+        ``email_code_provider``, код подтверждения будет запрошен в консоли.
+
+        Args:
+            password: Новый пароль 2FA.
+            email: Адрес электронной почты для 2FA, если требуется.
+            hint: Подсказка пароля, если требуется.
+            email_code_provider: Провайдер кода из электронной почты, если
+                требуется.
+
+        Returns:
+            ``True``, если пароль успешно установлен.
+
+        Raises:
+            RuntimeError: Если установка пароля не удалась.
+        """
+        return await self._app.api.auth.set_2fa(
+            password=password,
+            email=email,
+            hint=hint,
+            email_code_provider=email_code_provider,
+        )
+
+    async def remove_2fa(self, password: str) -> bool:
+        """Удаляет пароль 2FA для текущей учетной записи.
+
+        Args:
+            password: Текущий пароль 2FA.
+
+        Returns:
+            ``True``, если пароль успешно удален.
+
+        Raises:
+            RuntimeError: Если удаление пароля не удалось.
+        """
+        return await self._app.api.auth.remove_2fa(password=password)

pymax/infra/base.py

@@ -0,0 +1,15 @@
+from .auth import AuthMixin
+from .chat import ChatMixin
+from .message import MessageMixin
+from .self import SelfMixin
+from .user import UserMixin
+
+
+class BaseMixin(
+    SelfMixin,
+    UserMixin,
+    ChatMixin,
+    MessageMixin,
+    AuthMixin,
+):
+    """Собирает публичные API-методы клиента."""