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

maxapi_python-2.1.3/.github/workflows/publish.yml

@@ -0,0 +1,64 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Validate package distributions
+        run: uv run twine check dist/*
+
+      - name: Upload package distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [package]
+
+    environment:
+      name: pypi
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download package distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Publish package to PyPI
+        run: uv publish

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.1.1
+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.1 → 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.1 → maxapi_python-2.1.3}/docs/index.rst

@@ -22,6 +22,8 @@ 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-2.rst

@@ -0,0 +1,32 @@
+PyMax 2.1.2
+===========
+
+Изменения относительно ``2.1.1``.
+
+Добавлено
+---------
+
+* ``get_bot_init_data()`` теперь можно вызвать без ``chat_id`` для сценариев,
+  где Max запускает web app вне конкретного чата.
+
+Исправлено
+----------
+
+* ``ExtraConfig.request_timeout`` снова применяется к API-запросам по
+  умолчанию, а явный ``timeout`` в низкоуровневом вызове сохраняет приоритет.
+* Login-ответ без нового ``token`` больше не ломает запуск клиента и не
+  перезаписывает сохраненный токен пустым значением.
+* ``FolderList`` больше не переопределяет pydantic-итератор и не ломает
+  ``dict(...)`` / стандартную сериализацию модели.
+
+Изменилось
+----------
+
+* Publish workflow упрощен: сборка, проверка дистрибутивов и публикация в PyPI
+  теперь разделены на понятные шаги с artifact handoff.
+
+Миграция
+--------
+
+* Если код итерировал ``FolderList`` напрямую, замените это на
+  ``folder_list.folders``.

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.1 → maxapi_python-2.1.3}/pyproject.toml

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

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

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

{maxapi_python-2.1.1 → maxapi_python-2.1.3}/src/pymax/api/bots/payloads.py

@@ -3,5 +3,5 @@ from pymax.api.models import CamelModel
 
 class RequestInitDataPayload(CamelModel):
     bot_id: int
-    chat_id: int
+    chat_id: int | None = None
     start_param: str | None = None

{maxapi_python-2.1.1 → maxapi_python-2.1.3}/src/pymax/api/bots/service.py

@@ -23,13 +23,9 @@ class BotsService:
     async def get_init_data(
         self,
         bot_id: int,
-        chat_id: int,
+        chat_id: int | None = None,
         start_param: str | None = None,
     ) -> InitData:
-        frame = RequestInitDataPayload(
-            bot_id=bot_id, chat_id=chat_id, start_param=start_param
-        )
-        response = await self.app.invoke(
-            Opcode.WEB_APP_INIT_DATA, frame.to_payload()
-        )
+        frame = RequestInitDataPayload(bot_id=bot_id, chat_id=chat_id, start_param=start_param)
+        response = await self.app.invoke(Opcode.WEB_APP_INIT_DATA, frame.to_payload())
         return require_payload_model(response, InitData)

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

@@ -33,9 +33,7 @@ class App(Generic[ClientT]):
         self.dispatcher: Dispatcher[ClientT] = Dispatcher(self, root_router)
         self.api = ApiFacade(self)
         self.config = config
-        self.store = self.config.store or SessionStore(
-            config.work_dir, config.session_name
-        )
+        self.store = self.config.store or SessionStore(config.work_dir, config.session_name)
         self.auth_flow = auth_flow
 
         self.me: Profile | None = None
@@ -51,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,
@@ -76,18 +75,14 @@ class App(Generic[ClientT]):
             await self.connection.open()
 
             handshake_device_id = (
-                session_data.device_id
-                if session_data
-                else self.config.device.device_id
+                session_data.device_id if session_data else self.config.device.device_id
             )
             logger.debug("running handshake")
             await self.handshake(handshake_device_id)
         except (ConnectionError, EOFError, OSError, TimeoutError) as e:
             logger.exception("failed to connect or handshake")
             await self.connection.close()
-            raise ConnectionError(
-                f"Failed to connect and handshake: {e}"
-            ) from e
+            raise ConnectionError(f"Failed to connect and handshake: {e}") from e
 
         self._ping_task = asyncio.create_task(self._ping_loop())
 
@@ -108,9 +103,7 @@ class App(Generic[ClientT]):
 
                 if not auth_result.token:
                     logger.error("authentication finished without token")
-                    raise RuntimeError(
-                        "Authentication failed: no token received"
-                    )
+                    raise RuntimeError("Authentication failed: no token received")
 
                 await self.store.save_session(
                     session_data := SessionInfo(
@@ -135,7 +128,7 @@ class App(Generic[ClientT]):
             self.config.device.user_agent,
         )
 
-        if response.token != self.session.token:
+        if response.token is not None and response.token != self.session.token:
             await self.store.update_token(self.session.token, response.token)
             self.session.token = response.token
 
@@ -182,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(
@@ -189,7 +183,7 @@ class App(Generic[ClientT]):
         opcode: int,
         payload: dict[str, Any],
         cmd: int = Command.REQUEST,
-        timeout: float | None = 30.0,
+        timeout: float | None = None,
         compress: bool = False,
     ) -> InboundFrame:
         seq = self.connection.next_seq()
@@ -211,10 +205,9 @@ class App(Generic[ClientT]):
             payload_keys,
         )
         logger.debug("Request data=%s", frame.model_dump())
-        response = await self.connection.request(frame, timeout=timeout)
-        response_keys = (
-            sorted(response.payload.keys()) if response.payload else []
-        )
+        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(
             "response opcode=%s cmd=%s seq=%s payload_keys=%s",
             response.opcode,
@@ -238,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.1 → 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.1 → 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.1 → 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.1 → 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())