maxapi-python 2.1.2__tar.gz → 2.1.3__tar.gz

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.1.2
+Version: 2.1.3
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/docs/conf.py

@@ -78,6 +78,7 @@ release = __version__
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
@@ -86,6 +87,8 @@ extensions = [
 
 templates_path = ["_templates"]
 
+autosummary_generate = True
+
 exclude_patterns = [
     "_build",
     "Thumbs.db",
@@ -99,20 +102,24 @@ language = "ru"
 autodoc_default_options = {
     "members": True,
     "undoc-members": False,
-    "show-inheritance": False,
+    "show-inheritance": True,
     "private-members": False,
     "special-members": False,
+    "member-order": "bysource",
     "exclude-members": (
-        "dict,json,parse_obj,parse_raw,schema,model_dump,model_validate,"
-        "model_json_schema,model_construct"
+        "dict,json,parse_obj,parse_raw,schema,schema_json,"
+        "copy,construct,from_orm,update_forward_refs,validate,"
+        "model_dump,model_dump_json,model_validate,model_validate_json,"
+        "model_validate_strings,model_json_schema,model_construct,"
+        "model_copy,model_rebuild,model_post_init,model_parametrized_name"
     ),
 }
 
+
+autodoc_typehints_format = "short"
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"
-autodoc_typehints_format = "short"
 autodoc_class_signature = "separated"
-
 # -- Napoleon ----------------------------------------------------------------
 
 napoleon_google_docstring = True
@@ -131,7 +138,9 @@ intersphinx_mapping = {
 
 # -- HTML --------------------------------------------------------------------
 
+# html_theme = "shibuya"
 html_theme = "furo"
+
 html_title = "PyMax"
 html_static_path = ["_static"]
 

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/docs/index.rst

@@ -22,6 +22,7 @@ PyMax - асинхронная Python-библиотека для Max API. Он
    :maxdepth: 1
    :caption: Новости
 
+   release-2-1-3
    release-2-1-2
    release-2-1-1
    release-2-1-0

maxapi_python-2.1.3/docs/release-2-1-3.rst

@@ -0,0 +1,48 @@
+PyMax 2.1.3
+===========
+
+Изменения относительно ``2.1.2``.
+
+Добавлено
+---------
+
+* ``UnknownAttachment`` для вложений с неизвестным ``_type``. Такие вложения
+  больше не ломают парсинг ``Message`` и сохраняют дополнительные поля
+  payload-а.
+
+Исправлено
+----------
+
+* ``Message`` больше не падает на неизвестных типах вложений вроде
+  ``UNSUPPORTED``.
+* ``AudioAttachment`` принимает payload без ``duration`` и ``audioId``.
+* ``VideoAttachment`` принимает payload без ``duration``.
+* ``ElementAttributes.url`` и ``Element.length`` стали необязательными для
+  элементов, где Max не присылает эти поля.
+* ``Photo(url=...)`` корректно определяет расширение и MIME type, если в URL
+  есть query string.
+* При потере соединения ``App.started`` сбрасывается, ping-task отменяется, а
+  pending API-запросы очищаются без ``Future exception was never retrieved``.
+* Reconnect/close после штатного сетевого обрыва стало меньше шуметь
+  exception-логами.
+
+Изменилось
+----------
+
+* ``configure_logging()`` теперь уважает уже настроенный logging
+  host-приложения: PyMax не очищает чужие handler-ы и не добавляет свой
+  stderr-handler, если logging уже сконфигурирован.
+* Если logging не настроен, PyMax по-прежнему включает pretty-логи из коробки.
+* Для принудительного включения pretty-логов PyMax добавлен аргумент
+  ``configure_logging(..., force=True)``.
+* TCP msgpack decoder стал проще и подробнее логирует payload при ошибках
+  декодирования.
+
+Миграция
+--------
+
+* Код на ``Client`` и ``WebClient`` обычно менять не нужно.
+* Если приложение рассчитывало, что ``configure_logging()`` всегда заменяет
+  существующие handler-ы ``pymax``, передайте ``force=True``.
+* Если код обрабатывал ``ValidationError`` для неизвестных вложений, теперь
+  вместо ошибки придет ``UnknownAttachment``.

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "2.1.2"
+version = "2.1.3"
 description = "Python wrapper для API мессенджера Max"
 readme = "README.md"
 requires-python = ">=3.10"

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.1.2"
+__version__ = "2.1.3"
 
 
 from .auth import (

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/app.py

@@ -49,6 +49,7 @@ class App(Generic[ClientT]):
         self._telemetry = TelemetryService(self) if config.telemetry else None
 
         self.connection.on_event = self.on_event
+        self.connection.on_close = self.on_connection_lost
         logger.debug(
             "app initialized session=%s work_dir=%s auth_flow=%s",
             config.session_name,
@@ -174,6 +175,7 @@ class App(Generic[ClientT]):
         await self.dispatcher.stop_startup_tasks()
         await self.connection.close()
         await self.store.close()
+
         self.started = False
 
     async def invoke(
@@ -203,9 +205,7 @@ class App(Generic[ClientT]):
             payload_keys,
         )
         logger.debug("Request data=%s", frame.model_dump())
-        request_timeout = (
-            self.config.request_timeout if timeout is None else timeout
-        )
+        request_timeout = self.config.request_timeout if timeout is None else timeout
         response = await self.connection.request(frame, timeout=request_timeout)
         response_keys = sorted(response.payload.keys()) if response.payload else []
         logger.debug(
@@ -231,9 +231,23 @@ class App(Generic[ClientT]):
         except asyncio.CancelledError:
             raise
         except Exception as e:
-            logger.exception("ping loop failed; closing transport")
+            logger.warning("ping loop failed; closing transport: %s", e)
             await self.connection.fail(ConnectionError(f"Ping failed: {e}"))
 
+    def on_connection_lost(self, exc: Exception | None = None) -> None:
+        if self.started:
+            logger.warning("connection lost; marking app as stopped: %s", exc)
+
+        self.started = False
+
+        task = self._ping_task
+        if task is None or task.done():
+            return
+
+        current_task = asyncio.current_task()
+        if task is not current_task:
+            task.cancel()
+
     def _build_api_error(self, response: InboundFrame) -> ApiError:
         try:
             error = MaxApiError.model_validate(response.payload)

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/client.py

@@ -66,10 +66,7 @@ class Client(BaseClient["Client"]):
 
         self._config = self._build_config(
             phone=phone,
-            user_agent=(
-                self.extra_config.user_agent
-                or self.extra_config.generate_user_agent()
-            ),
+            user_agent=(self.extra_config.user_agent or self.extra_config.generate_user_agent()),
         )
 
         if auth_flow is None:

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/connection/connection.py

@@ -20,16 +20,19 @@ class ConnectionManager:
         transport: Transport,
         protocol: BaseProtocol,
         on_event: Callable[[InboundFrame], Awaitable[None]] | None = None,
+        on_close: Callable[[Exception | None], None] | None = None,
     ) -> None:
         self.reader = reader
         self.transport = transport
         self.protocol = protocol
         self.on_event = on_event
+        self.on_close = on_close
 
         self.requests = PendingRequests()
 
         self._is_open = False
         self._connection_lost = False
+        self._close_reported = False
         self._seq = -1
 
         self._recv_task: asyncio.Task[None] | None = None
@@ -44,6 +47,7 @@ class ConnectionManager:
         await self.transport.connect()
         self._is_open = True
         self._connection_lost = False
+        self._close_reported = False
 
         self._recv_task = asyncio.create_task(self._recv_loop())
         logger.debug("receive loop started")
@@ -80,7 +84,7 @@ class ConnectionManager:
         self._connection_lost = True
         self.requests.cancel_all(exc=exc)
         await self.transport.close()
-        self._is_open = False
+        self._mark_closed(exc)
 
     async def send(self, frame: OutboundFrame) -> None:
         if not self._is_open:
@@ -116,20 +120,38 @@ class ConnectionManager:
             )
             await self.transport.send(raw)
             return await asyncio.wait_for(future, timeout)
-        except Exception as e:
+        except asyncio.CancelledError:
+            self.requests.discard(frame.seq)
+            raise
+        except (ConnectionError, EOFError, OSError, TimeoutError) as e:
+            logger.warning(
+                "request failed seq=%s opcode=%s error=%s",
+                frame.seq,
+                frame.opcode,
+                e,
+            )
+            self.requests.discard(frame.seq)
+            raise
+        except Exception:
             logger.exception(
                 "request failed seq=%s opcode=%s",
                 frame.seq,
                 frame.opcode,
             )
-            self.requests.reject(frame.seq, e)
+            self.requests.discard(frame.seq)
             raise
 
     async def wait_closed(self) -> None:
         if not self._recv_task:
             return
 
-        await self._recv_task
+        try:
+            await self._recv_task
+        except Exception as e:
+            if self._connection_lost:
+                raise ConnectionError("Connection lost") from e
+            raise
+
         if self._connection_lost:
             raise ConnectionError("Connection lost")
 
@@ -147,27 +169,23 @@ class ConnectionManager:
                 await self._handle_inbound(model)
 
         except EOFError:
+            exc = ConnectionError("Connection closed by the server")
             logger.warning("connection closed by server")
-            self.requests.cancel_all(
-                exc=ConnectionError("Connection closed by the server")
-            )
+            self.requests.cancel_all(exc=exc)
             self._connection_lost = True
-            self._is_open = False
-        except TimeoutError as e:
-            logger.exception("connection timed out")
-            self.requests.cancel_all(
-                exc=ConnectionError("Connection timed out")
-            )
+            self._mark_closed(exc)
+        except (ConnectionError, OSError, TimeoutError) as e:
+            exc = ConnectionError(f"Connection error: {e}")
+            logger.warning("connection closed while reading payload: %s", e)
+            self.requests.cancel_all(exc=exc)
             self._connection_lost = True
-            self._is_open = False
-            raise e
+            self._mark_closed(exc)
         except Exception as e:
+            exc = ConnectionError(f"Connection error: {e}")
             logger.exception("connection receive loop failed")
-            self.requests.cancel_all(
-                exc=ConnectionError(f"Connection error: {e}")
-            )
+            self.requests.cancel_all(exc=exc)
             self._connection_lost = True
-            self._is_open = False
+            self._mark_closed(exc)
             raise e
 
     async def _handle_inbound(self, frame: InboundFrame) -> None:
@@ -210,6 +228,15 @@ class ConnectionManager:
         self._seq = (self._seq + 1) % 0x10000
         return self._seq
 
+    def _mark_closed(self, exc: Exception | None = None) -> None:
+        self._is_open = False
+        if self._close_reported:
+            return
+
+        self._close_reported = True
+        if self.on_close:
+            self.on_close(exc)
+
     @property
     def is_open(self) -> bool:
         return self._is_open

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/files/photo.py

@@ -1,6 +1,7 @@
 import mimetypes
 from collections.abc import AsyncGenerator
 from pathlib import Path
+from urllib.parse import urlsplit
 
 from .base import BaseFile
 from .static import ALLOWED_EXTENSIONS
@@ -66,12 +67,13 @@ class Photo(BaseFile):
                 raise ValueError(msg)
             return (extension[1:], ("image/" + extension[1:]).lower())
         if self.url:
-            extension = Path(self.url).suffix.lower()
+            url_path = urlsplit(self.url).path
+            extension = Path(url_path).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]
+            mime_type = mimetypes.guess_type(url_path)[0]
 
             if not mime_type or not mime_type.startswith("image/"):
                 msg = f"URL does not appear to be an image: {self.url}"

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/logging.py

@@ -4,6 +4,7 @@ import sys
 from typing import TextIO
 
 DATE_FORMAT = "%H:%M:%S"
+PYMAX_HANDLER_ATTR = "_pymax_pretty_handler"
 
 RESET = "\x1b[0m"
 DIM = "\x1b[2m"
@@ -56,17 +57,22 @@ def configure_logging(
     *,
     stream: TextIO | None = None,
     use_colors: bool | None = None,
+    force: bool = False,
 ) -> None:
     """Настраивает pretty-логи для logger-а ``pymax``.
 
     Обычно уровень логов задают через ``ExtraConfig(log_level="DEBUG")``.
-    Вызывайте эту функцию вручную, если хотите управлять stream или цветами.
+    PyMax ставит свой handler только если приложение еще не настроило logging.
+    Вызывайте эту функцию с ``force=True``, если хотите принудительно включить
+    pretty-логи PyMax.
 
     Args:
         level: Уровень логирования: строка вроде ``"DEBUG"`` или число из
             модуля ``logging``.
         stream: Поток для вывода. По умолчанию ``sys.stderr``.
         use_colors: Включить ANSI-цвета. Если ``None``, определяется по TTY.
+        force: Заменить существующие handler-ы logger-а ``pymax`` на pretty
+            handler PyMax.
 
     Returns:
         ``None``.
@@ -84,17 +90,25 @@ def configure_logging(
         use_colors = hasattr(stream, "isatty") and stream.isatty()
 
     logger = logging.getLogger("pymax")
+    level_value = _normalize_level(level)
+    logger.setLevel(level_value)
+
+    if not force and _logging_already_configured(logger):
+        if logging.getLogger().handlers and not _has_non_null_handlers(logger):
+            logger.propagate = True
+        return
+
     logger.handlers.clear()
-    logger.setLevel(_normalize_level(level))
     logger.propagate = False
 
     handler = logging.StreamHandler(stream)
-    handler.setLevel(_normalize_level(level))
+    handler.setLevel(level_value)
     handler.setFormatter(
         PrettyFormatter(
             use_colors=use_colors,
         )
     )
+    setattr(handler, PYMAX_HANDLER_ATTR, True)
 
     logger.addHandler(handler)
 
@@ -126,4 +140,20 @@ def _strip_ansi(text: str) -> str:
     return re.sub(r"\x1b\[[0-9;]*m", "", text)
 
 
+def _logging_already_configured(logger: logging.Logger) -> bool:
+    return bool(logging.getLogger().handlers or _has_external_handlers(logger))
+
+
+def _has_non_null_handlers(logger: logging.Logger) -> bool:
+    return any(not isinstance(handler, logging.NullHandler) for handler in logger.handlers)
+
+
+def _has_external_handlers(logger: logging.Logger) -> bool:
+    return any(
+        not isinstance(handler, logging.NullHandler)
+        and not getattr(handler, PYMAX_HANDLER_ATTR, False)
+        for handler in logger.handlers
+    )
+
+
 logging.getLogger("pymax").addHandler(logging.NullHandler())

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/protocol/tcp/payload.py

@@ -15,10 +15,7 @@ class MsgpackPayloadCodec:
         if isinstance(value, Enum):
             return value.value
         if isinstance(value, dict):
-            return {
-                self._to_msgpack_value(k): self._to_msgpack_value(v)
-                for k, v in value.items()
-            }
+            return {self._to_msgpack_value(k): self._to_msgpack_value(v) for k, v in value.items()}
         if isinstance(value, list):
             return [self._to_msgpack_value(item) for item in value]
         if isinstance(value, tuple):
@@ -28,56 +25,42 @@ class MsgpackPayloadCodec:
     def encode(self, payload: object) -> bytes:
         if payload is None:
             return b""
-        return (
-            msgpack.packb(self._to_msgpack_value(payload), use_bin_type=True)
-            or b""
-        )
+        return msgpack.packb(self._to_msgpack_value(payload), use_bin_type=True) or b""
 
-    def _unpack_stream(self, payload_bytes: bytes, *, raw: bool) -> list[Any]:
+    def _unpack_stream(
+        self, payload_bytes: bytes, *, raw: bool
+    ) -> list[Any]:  # TODO: deprecate? idk
         unpacker = msgpack.Unpacker(raw=raw, strict_map_key=False)
         unpacker.feed(payload_bytes)
         return list(unpacker)
 
-    def decode(self, payload_bytes: bytes) -> dict[Any, Any]:
+    def decode(self, payload_bytes: bytes) -> Any:
         if not payload_bytes:
             return {}
 
         try:
             return msgpack.unpackb(
-                payload_bytes, raw=False, strict_map_key=False
+                payload_bytes,
+                raw=False,
+                strict_map_key=False,
             )
-        except msgpack.exceptions.ExtraData as e:
-            if isinstance(e.unpacked, dict):
-                logger.debug(
-                    "msgpack payload has trailing data unpacked_type=%s extra_bytes=%s extra_head=%s",
-                    type(e.unpacked).__name__,
-                    len(e.extra),
-                    e.extra[:16].hex(),
-                )
-                return e.unpacked
 
-            try:
-                values = self._unpack_stream(payload_bytes, raw=False)
-            except UnicodeDecodeError:
-                values = self._unpack_stream(payload_bytes, raw=True)
+        except msgpack.exceptions.ExtraData as e:
             logger.debug(
-                "msgpack payload has extra data objects=%s extra_bytes=%s",
-                [type(value).__name__ for value in values],
+                "msgpack extra data: unpacked_type=%s extra_len=%s extra_head=%s payload_head=%s",
+                type(e.unpacked).__name__,
                 len(e.extra),
+                e.extra[:64].hex(),
+                payload_bytes[:128].hex(),
             )
-            for value in values:
-                if isinstance(value, dict):
-                    return value
-            raise
-        except UnicodeDecodeError:
-            values = self._unpack_stream(payload_bytes, raw=True)
-            logger.debug(
-                "msgpack payload decoded with raw bytes objects=%s",
-                [type(value).__name__ for value in values],
+            return e.unpacked
+
+        except Exception:
+            logger.exception(
+                "msgpack decode failed: payload_len=%s payload_head=%s",
+                len(payload_bytes),
+                payload_bytes[:128].hex(),
             )
-            for value in values:
-                if isinstance(value, dict):
-                    return value
             raise
 
 
@@ -93,10 +76,7 @@ class TcpPayloadDecoder:
 
     def _normalize_keys(self, obj: Any) -> Any:
         if isinstance(obj, dict):
-            return {
-                self._normalize_key(k): self._normalize_keys(v)
-                for k, v in obj.items()
-            }
+            return {self._normalize_key(k): self._normalize_keys(v) for k, v in obj.items()}
         if isinstance(obj, list):
             return [self._normalize_keys(item) for item in obj]
         if isinstance(obj, tuple):

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/protocol/tcp/protocol.py

@@ -25,11 +25,7 @@ class TcpProtocol(BaseProtocol):
         )
 
     def encode(self, frame: OutboundFrame) -> bytes:
-        payload_bytes = (
-            self.serializer.encode(frame.payload)
-            if frame.payload is not None
-            else b""
-        )
+        payload_bytes = self.serializer.encode(frame.payload) if frame.payload is not None else b""
 
         flags = 0
 
@@ -52,9 +48,7 @@ class TcpProtocol(BaseProtocol):
 
         packed_packet = self.framer.unpack(raw)
         if not packed_packet:
-            return InboundFrame(
-                opcode=0, cmd=0, seq=None, payload=None, raw=None
-            )
+            return InboundFrame(opcode=0, cmd=0, seq=None, payload=None, raw=None)
 
         logger.debug(
             "tcp frame decoded header ver=%s cmd=%s seq=%s opcode=%s flags=%s payload_len=%s",

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/types/domain/attachments/__init__.py

@@ -8,4 +8,5 @@ from .keyboards import InlineKeyboardAttachment
 from .photo import PhotoAttachment
 from .share import ShareAttachment
 from .sticker import StickerAttachment
+from .unknown import UnknownAttachment
 from .video import VideoAttachment, VideoRequest

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/types/domain/attachments/audio.py

@@ -11,9 +11,9 @@ class AudioAttachment(CamelModel):
     """Аудио-вложение сообщения.
 
     :ivar duration: Длительность аудио.
-    :vartype duration: int
+    :vartype duration: int | None
     :ivar audio_id: ID аудио.
-    :vartype audio_id: int
+    :vartype audio_id: int | None
     :ivar wave: Данные waveform.
     :vartype wave: str | None
     :ivar transcription_status: Статус транскрибации.
@@ -26,8 +26,8 @@ class AudioAttachment(CamelModel):
     :vartype token: str | None
     """
 
-    duration: int
-    audio_id: int
+    duration: int | None = None
+    audio_id: int | None = None
     wave: str | None = None
     transcription_status: TranscriptionStatus | None = None
     url: str | None = None

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/types/domain/attachments/enums.py

@@ -14,6 +14,7 @@ class AttachmentType(str, Enum):
     CALL = "CALL"
     SHARE = "SHARE"
     INLINE_KEYBOARD = "INLINE_KEYBOARD"
+    UNKNOWN = "UNKNOWN"
 
 
 class TranscriptionStatus(str, Enum):

maxapi_python-2.1.3/src/pymax/types/domain/attachments/unknown.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from pydantic import Field, model_validator
+
+from pymax.types.domain.base import CamelModel
+
+from .enums import AttachmentType
+
+KNOWN_ATTACHMENT_TYPES = {
+    attachment_type.value
+    for attachment_type in AttachmentType
+    if attachment_type != AttachmentType.UNKNOWN
+}
+
+
+class UnknownAttachment(CamelModel):
+    """Вложение неизвестного типа.
+
+    :ivar type: Тип вложения.
+    :vartype type: str
+    """
+
+    type: str = Field(alias="_type")
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_known_attachment_type(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+
+        attachment_type = value.get("_type", value.get("type"))
+        if attachment_type in KNOWN_ATTACHMENT_TYPES:
+            raise ValueError(
+                "Known attachment type should be parsed by its own model"
+            )
+
+        return value

{maxapi_python-2.1.2 → maxapi_python-2.1.3}/src/pymax/types/domain/attachments/video.py

@@ -31,7 +31,7 @@ class VideoAttachment(CamelModel):
     :ivar video_id: ID видео.
     :vartype video_id: int
     :ivar duration: Длительность видео.
-    :vartype duration: int
+    :vartype duration: int | None
     :ivar preview_data: Данные превью.
     :vartype preview_data: bytes
     :ivar type: Тип вложения.
@@ -47,7 +47,7 @@ class VideoAttachment(CamelModel):
     height: int
     width: int
     video_id: int
-    duration: int
+    duration: int | None = None
     preview_data: bytes
     type: Literal[AttachmentType.VIDEO] = Field(alias="_type")
     thumbnail: str