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

maxapi_python-2.2.0/.github/workflows/tests.yml

@@ -0,0 +1,66 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main, "dev/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checks-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    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: Install development dependencies
+        run: uv sync --group dev
+
+      - name: Check code formatting
+        run: uv run ruff format --check .
+
+      - name: Run Ruff linting
+        run: uv run ruff check .
+
+  tests:
+    name: Tests / Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install development dependencies
+        run: uv sync --group dev
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest \
+            --cov=src/pymax \
+            --cov-report=term-missing:skip-covered \
+            --cov-report=markdown-append:$GITHUB_STEP_SUMMARY

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

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.1.2
+Version: 2.2.0
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
 Project-URL: Issues, https://github.com/MaxApiTeam/PyMax/issues
-Project-URL: Documentation, https://maxapiteam.github.io/PyMax/
+Project-URL: Documentation, https://docs.pymax.org
 Author-email: ink <inkdev@proton.me>
 License-Expression: MIT
 License-File: LICENSE
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: aiofiles>=25.1.0
@@ -30,15 +31,6 @@ Requires-Dist: pydantic>=2.10.0
 Requires-Dist: python-socks[asyncio]>=2.8.1
 Requires-Dist: qrcode>=8.2
 Requires-Dist: websockets>=16.0
-Provides-Extra: docs
-Requires-Dist: furo>=2025.12.19; extra == 'docs'
-Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
-Requires-Dist: sphinx>=8.1.3; extra == 'docs'
-Provides-Extra: test
-Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
-Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
-Requires-Dist: pytest-timeout>=2.1.0; extra == 'test'
-Requires-Dist: pytest>=8.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 # PyMax

maxapi_python-2.2.0/docs/api/client-client.rst

@@ -0,0 +1,18 @@
+Client
+======
+
+.. currentmodule:: pymax
+
+TCP-клиент с SMS-авторизацией. Это основной клиент для long-running
+подключения, обработчиков событий и mobile API Max.
+
+.. note::
+
+   ``Client`` поддерживает ``ExtraConfig.device_type`` со значениями
+   ``ANDROID``, ``IOS`` и ``DESKTOP``. Для :meth:`Client.authorize_qr_login`
+   используйте ``ANDROID`` или ``IOS``: с ``DESKTOP`` подтверждение QR-входа
+   не работает.
+
+.. autoclass:: Client
+   :members:
+   :inherited-members:

maxapi_python-2.2.0/docs/api/client-config.rst

@@ -0,0 +1,14 @@
+Client Config
+=============
+
+.. currentmodule:: pymax
+
+Настройки, которые используются ``Client`` и ``WebClient``.
+
+.. autoclass:: ExtraConfig
+   :members:
+
+.. autoclass:: RegistrationConfig
+   :members:
+
+.. autofunction:: configure_logging

maxapi_python-2.2.0/docs/api/client-web.rst

@@ -0,0 +1,17 @@
+WebClient
+=========
+
+.. currentmodule:: pymax
+
+WebSocket-клиент с QR-авторизацией. Он подходит, когда нужно подключаться как
+web-клиент Max.
+
+.. note::
+
+   В штатной конфигурации ``WebClient`` использует только ``DeviceType.WEB``.
+   Параметр ``ExtraConfig.device_type`` предназначен для ``Client`` и не
+   меняет тип устройства ``WebClient``.
+
+.. autoclass:: WebClient
+   :members:
+   :inherited-members:

maxapi_python-2.2.0/docs/api/client.rst

@@ -0,0 +1,25 @@
+Clients API
+===========
+
+.. currentmodule:: pymax
+
+``Client`` и ``WebClient`` используют общий набор высокоуровневых методов,
+но отличаются транспортом и способом авторизации:
+
+``Client``
+   TCP-клиент с SMS-авторизацией. Поддерживает mobile ``device_type``:
+   ``ANDROID``, ``IOS`` и ``DESKTOP``. Для подтверждения QR-входа через
+   :meth:`Client.authorize_qr_login` используйте ``ANDROID`` или ``IOS``:
+   с ``DESKTOP`` этот метод не работает.
+
+``WebClient``
+   WebSocket-клиент с QR-авторизацией. В штатной конфигурации всегда
+   использует ``DeviceType.WEB``; ``ExtraConfig.device_type`` на него не
+   влияет.
+
+.. toctree::
+   :maxdepth: 1
+
+   client-client
+   client-web
+   client-config

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/docs/auth.rst

@@ -91,7 +91,7 @@ Provider нужен, когда код приходит не из консоли
 Кастомный QR handler
 --------------------
 
-``QrHandler`` не должен подтверждать QR сам. Его задача - показать ссылку
+Обычно ``QrHandler`` не подтверждает QR сам. Его задача - показать ссылку
 пользователю: вывести в терминал, отправить в web UI или положить в лог.
 
 .. code-block:: python
@@ -110,6 +110,33 @@ Provider нужен, когда код приходит не из консоли
        qr_provider=PrintQrUrl(),
    )
 
+Если у вас уже есть запущенный и авторизованный ``Client``, QR-ссылку можно
+подтвердить программно через ``authorize_qr_login()``. Это удобно, когда
+``WebClient`` получает QR, а основной mobile-клиент должен разрешить вход:
+
+.. code-block:: python
+
+   from pymax import Client, WebClient
+
+
+   class ConfirmQrWithClient:
+       def __init__(self, client: Client) -> None:
+           self.client = client
+
+       async def show_qr(self, qr_url: str) -> None:
+           await self.client.authorize_qr_login(qr_url)
+
+
+   mobile_client = Client(phone="+79990000000", work_dir="cache")
+   # mobile_client должен уже пройти start/login в вашей программе.
+   web_client = WebClient(qr_provider=ConfirmQrWithClient(mobile_client))
+
+``mobile_client`` должен быть уже авторизован к моменту вызова
+``show_qr()``. Для такого подтверждения используйте ``Client`` с
+``device_type`` ``ANDROID`` или ``IOS``; при ``DESKTOP`` метод
+``authorize_qr_login()`` не работает. ``WebClient`` в штатной конфигурации
+всегда использует ``WEB``.
+
 Полный кастомный AuthFlow
 -------------------------
 
@@ -146,6 +173,31 @@ Flow должен иметь async-метод ``authenticate(app)`` и верн
 Если вам нужно только передать готовый token, проще использовать
 ``ExtraConfig(token="TOKEN")``. Тогда custom flow не нужен.
 
+Регистрация нового аккаунта
+---------------------------
+
+Если номер ещё не зарегистрирован в Max, после SMS-кода сервер возвращает
+токен регистрации. Чтобы стандартный ``SmsAuthFlow`` завершил создание
+аккаунта, передайте имя через ``RegistrationConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig, RegistrationConfig
+
+   client = Client(
+       phone="+79990000000",
+       extra_config=ExtraConfig(
+           registration_config=RegistrationConfig(
+               first_name="Max",
+               last_name="User",
+           )
+       ),
+   )
+
+Для уже существующего аккаунта эта настройка не используется. Если Max
+вернул токен регистрации, а ``registration_config`` не задан, авторизация
+завершится с ``RuntimeError``.
+
 Управление 2FA
 --------------
 

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/docs/client.rst

@@ -16,9 +16,11 @@ Client
 
 ``Client``
    TCP-клиент с авторизацией по телефону и SMS-коду. Это основной вариант.
+   Поддерживает ``device_type`` ``ANDROID``, ``IOS`` и ``DESKTOP``.
 
 ``WebClient``
-   WebSocket-клиент с QR-авторизацией.
+   WebSocket-клиент с QR-авторизацией. В штатной конфигурации работает как
+   ``WEB``-устройство.
 
 Жизненный цикл
 --------------
@@ -85,6 +87,32 @@ Client
 ``extra_config``
    Настройки соединения, логов, reconnect, token, device/user-agent и sync.
 
+Тип устройства
+---------------
+
+``Client`` по умолчанию использует ``DeviceType.ANDROID``. Если нужно
+поменять тип устройства, передайте ``device_type`` через ``ExtraConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig
+   from pymax.api.session.enums import DeviceType
+
+   client = Client(
+       phone="+79990000000",
+       work_dir="cache",
+       extra_config=ExtraConfig(device_type=DeviceType.IOS),
+   )
+
+Для ``Client`` доступны ``ANDROID``, ``IOS`` и ``DESKTOP``. Практический
+нюанс: ``authorize_qr_login()`` подтверждает QR-вход только из mobile-режима,
+поэтому для него используйте ``ANDROID`` или ``IOS``. С ``DESKTOP`` этот метод
+не работает.
+
+``WebClient`` сам использует ``DeviceType.WEB``. Параметр
+``ExtraConfig.device_type`` относится к ``Client`` и не меняет тип устройства
+``WebClient``.
+
 Авторизация
 -----------
 
@@ -119,6 +147,47 @@ Client
        extra_config=ExtraConfig(token="TOKEN"),
    )
 
+Подтверждение QR-входа
+----------------------
+
+``Client`` может подтверждать QR-вход по ссылке через
+``authorize_qr_login()``. Это полезно, когда QR-ссылку показал другой клиент
+или ваш UI получил ее от ``WebClient``:
+
+.. code-block:: python
+
+   async def confirm_qr(client: Client, qr_link: str) -> None:
+       ok = await client.authorize_qr_login(qr_link)
+       print("QR подтвержден:", ok)
+
+``Client`` для такого подтверждения должен быть уже авторизован. Также
+проверьте ``device_type``: используйте ``ANDROID`` или ``IOS``, не
+``DESKTOP``.
+
+Если QR создает ``WebClient``, ссылку можно перехватить в своем
+``QrHandler`` и подтвердить ее уже запущенным ``Client``:
+
+.. code-block:: python
+
+   from pymax import Client, WebClient
+
+
+   class ConfirmQrWithClient:
+       def __init__(self, client: Client) -> None:
+           self.client = client
+
+       async def show_qr(self, qr_url: str) -> None:
+           await self.client.authorize_qr_login(qr_url)
+
+
+   mobile_client = Client(phone="+79990000000", work_dir="cache")
+   # mobile_client должен уже пройти start/login в вашей программе.
+   web_client = WebClient(
+       work_dir="cache",
+       session_name="web.db",
+       qr_provider=ConfirmQrWithClient(mobile_client),
+   )
+
 Сессия и sync-state
 -------------------
 
@@ -226,7 +295,7 @@ Debug-логи показывают handshake, login, входящие собы
    ``close_all_sessions()``. Подробнее: :doc:`account`.
 
 Auth
-   ``set_2fa()`` и ``remove_2fa()`` для управления паролем 2FA. Подробнее:
+   ``set_2fa()``, ``remove_2fa()`` и ``authorize_qr_login()``. Подробнее:
    :doc:`auth`.
 
 Частые ошибки

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/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.2.0}/docs/index.rst

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

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/docs/messages.rst

@@ -30,7 +30,27 @@ Messages
 
    @client.on_message_delete()
    async def on_delete(event: MessageDeleteEvent, client: Client) -> None:
-       print("deleted in chat:", event.chat.id)
+       print("deleted in chat:", event.chat_id)
+
+Получать и редактировать сообщения
+----------------------------------
+
+.. code-block:: python
+
+   message = await client.get_message(
+       chat_id=123456,
+       message_id=987654,
+   )
+   messages = await client.get_messages(
+       chat_id=123456,
+       message_ids=[987654, 987655],
+   )
+
+   if message is not None:
+       await message.edit("Обновленный текст")
+
+Через клиент то же редактирование доступно как
+``client.edit_message(chat_id, message_id, text, ...)``.
 
 Отправлять сообщения
 --------------------
@@ -69,6 +89,45 @@ Messages
        elif message.text == "/delete":
            await message.delete(for_me=False)
 
+.. note::
+
+   У низкоуровневого ``client.read_message(...)`` есть особенность Max:
+   для отметки прочтения TCP-клиент ожидает ``message_id`` как ``int``, а
+   WebSocket-клиент - как ``str``. Если вызываете метод напрямую, выбирайте
+   тип по клиенту.
+
+Служебные события
+-----------------
+
+В ``2.2.0`` доступны отдельные обработчики набора текста, присутствия,
+прочтения и реакций:
+
+.. code-block:: python
+
+   from pymax import (
+       Client,
+       MessageReadEvent,
+       PresenceEvent,
+       ReactionUpdateEvent,
+       TypingEvent,
+   )
+
+   @client.on_typing()
+   async def typing(event: TypingEvent, client: Client) -> None:
+       print(event.chat_id, event.user_id)
+
+   @client.on_presence()
+   async def presence(event: PresenceEvent, client: Client) -> None:
+       print(event.user_id, event.presence.status)
+
+   @client.on_message_read()
+   async def read(event: MessageReadEvent, client: Client) -> None:
+       print(event.chat_id, event.mark)
+
+   @client.on_reaction_update()
+   async def reactions(event: ReactionUpdateEvent, client: Client) -> None:
+       print(event.message_id, event.total_count)
+
 История сообщений
 -----------------
 

maxapi_python-2.2.0/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.2.0/docs/release-2-2-0.rst

@@ -0,0 +1,57 @@
+PyMax 2.2.0
+===========
+
+Изменения относительно ``2.1.3``.
+
+Добавлено
+---------
+
+* Получение сообщений по ID через ``get_message()`` и ``get_messages()``.
+  Те же операции доступны на bound-объекте ``Chat``.
+* Редактирование сообщений через ``edit_message()`` и ``Message.edit()`` с
+  поддержкой markdown, фото, видео и файлов.
+* События ``TypingEvent``, ``PresenceEvent``, ``MessageReadEvent`` и
+  ``ReactionUpdateEvent`` с обработчиками ``on_typing()``, ``on_presence()``,
+  ``on_message_read()`` и ``on_reaction_update()``.
+* ``join_channel()`` для вступления в канал по полной ссылке или join-токену.
+* Автоматическое завершение SMS-регистрации нового аккаунта через
+  ``RegistrationConfig`` в ``ExtraConfig.registration_config``.
+* Поддержка Python 3.14 в метаданных пакета и CI-матрице.
+
+Исправлено
+----------
+
+* Позиции markdown-элементов теперь корректно считаются в UTF-16 для emoji и
+  других символов вне BMP.
+* Удаление сообщения в ``WebClient`` распознается из события
+  ``NOTIF_MESSAGE`` со статусом ``REMOVED``.
+* ``MessageDeleteEvent`` принимает обе формы payload-а Max и не требует поле
+  ``ttl``.
+* ``PresenceEvent`` принимает частичные обновления, в которых Max присылает
+  ``seen`` без ``status``.
+* ``read_message()`` сохраняет тип ``message_id``: ``int`` для ``Client`` и
+  ``str`` для ``WebClient``.
+* Вложенные ``Message``, ``Chat`` и ``User`` из API-ответов и событий
+  привязываются к сервисам клиента, поэтому их bound-методы работают
+  последовательно.
+
+Изменилось
+----------
+
+* ``MessageDeleteEvent`` всегда содержит ``chat_id``. Поля ``chat`` и
+  ``message`` зависят от формы события и могут быть ``None``.
+* Проверка типов ``pyright`` ограничена релизным пакетом ``src`` и снова
+  проходит без ошибок.
+* Документация клиента разделена на отдельные API-страницы для ``Client``,
+  ``WebClient`` и конфигурации.
+
+Миграция
+--------
+
+* В обработчике удаления используйте ``event.chat_id`` вместо
+  ``event.chat.id``: ``event.chat`` может отсутствовать в ``WebClient``.
+* При прямом вызове ``read_message()`` передавайте ``int`` в ``Client`` и
+  ``str`` в ``WebClient``.
+* Для регистрации нового номера задайте
+  ``ExtraConfig(registration_config=RegistrationConfig(...))``. Для уже
+  существующих аккаунтов настройка не нужна.

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/docs/router.rst

@@ -175,6 +175,18 @@ Raw events
    async def raw(frame: InboundFrame, client: Client) -> None:
        print(frame.opcode, frame.payload)
 
+Другие события
+--------------
+
+Кроме новых и измененных сообщений, доступны специализированные декораторы:
+
+* ``on_message_delete()`` и ``on_message_read()``;
+* ``on_typing()`` и ``on_presence()``;
+* ``on_reaction_update()`` и ``on_chat_update()``.
+
+Все они поддерживают те же sync/async-фильтры и сигнатуру
+``handler(event, client)``.
+
 Частые ошибки
 -------------
 

{maxapi_python-2.1.2 → maxapi_python-2.2.0}/docs/types/index.rst

@@ -85,6 +85,10 @@ API reference
    chat
    message
    message_delete_event
+   message_read_event
+   typing_event
+   presence_event
+   reaction_update_event
    reaction_counter
    reaction_info
    read_state

maxapi_python-2.2.0/docs/types/message_read_event.rst

@@ -0,0 +1,6 @@
+MessageReadEvent
+================
+
+.. autoclass:: pymax.types.events.mark.MessageReadEvent
+   :members:
+   :show-inheritance:

maxapi_python-2.2.0/docs/types/presence_event.rst

@@ -0,0 +1,6 @@
+PresenceEvent
+=============
+
+.. autoclass:: pymax.types.events.presence.PresenceEvent
+   :members:
+   :show-inheritance:

maxapi_python-2.2.0/docs/types/reaction_update_event.rst

@@ -0,0 +1,6 @@
+ReactionUpdateEvent
+===================
+
+.. autoclass:: pymax.types.events.reaction.ReactionUpdateEvent
+   :members:
+   :show-inheritance:

maxapi_python-2.2.0/docs/types/typing_event.rst

@@ -0,0 +1,6 @@
+TypingEvent
+===========
+
+.. autoclass:: pymax.types.events.typing.TypingEvent
+   :members:
+   :show-inheritance: