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

maxapi_python-2.3.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.3 → maxapi_python-2.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.1.3
+Version: 2.3.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.3.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.3.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.3.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.3.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.3 → maxapi_python-2.3.0}/docs/api/router.rst

@@ -5,6 +5,12 @@ Router API
    :members:
    :show-inheritance:
 
+.. autoclass:: pymax.dispatch.ErrorScope
+   :members:
+
+.. autoclass:: pymax.dispatch.ErrorContext
+   :members:
+
 .. autodata:: pymax.ClientRouter
 
 .. autodata:: pymax.WebRouter

{maxapi_python-2.1.3 → maxapi_python-2.3.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.3 → maxapi_python-2.3.0}/docs/chats.rst

@@ -142,6 +142,22 @@ login/sync, а также методы для загрузки, создания
 ``leave()`` зависит от типа чата: для группы вызывает выход из группы, для
 канала - выход из канала. Из личного диалога выйти нельзя.
 
+Удалить чат
+-----------
+
+.. code-block:: python
+
+   await client.delete_chat(chat_id=123456)
+
+Через объект ``Chat`` PyMax использует ``chat.last_event_time``:
+
+.. code-block:: python
+
+   chat = await client.get_chat(123456)
+   await chat.delete(for_all=True)
+
+После успешного удаления чат убирается из локального кеша ``client.chats``.
+
 Invite-ссылки
 -------------
 

{maxapi_python-2.1.3 → maxapi_python-2.3.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
 -------------------
 
@@ -162,6 +231,21 @@ PyMax потеряет token и попросит авторизацию снов
 сессии можно удалить файл ``work_dir/session_name``; тогда потребуется новая
 авторизация.
 
+Повторная авторизация
+---------------------
+
+Если нужно сбросить текущую локальную сессию и пройти авторизацию заново,
+используйте ``relogin()``:
+
+.. code-block:: python
+
+   await client.relogin()
+
+``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и
+по умолчанию сразу запускает клиента снова. Если token был передан через
+``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через
+``drop_config_token=False``.
+
 Reconnect
 ---------
 
@@ -173,6 +257,14 @@ Reconnect
 а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
 после каждого успешного reconnect.
 
+Перед повторным подключением можно зарегистрировать ``on_disconnect``:
+
+.. code-block:: python
+
+   @client.on_disconnect()
+   async def disconnected(exc: Exception, reconnect: bool, delay: float) -> None:
+       print("connection lost:", exc, reconnect, delay)
+
 Отключить reconnect:
 
 .. code-block:: python
@@ -214,19 +306,19 @@ Debug-логи показывают handshake, login, входящие собы
 
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,
-   участники, настройки групп и выход из групп/каналов.
+   участники, настройки групп, удаление чатов и выход из групп/каналов.
 
 Пользователи
    ``get_user()``, ``get_users()``, ``fetch_users()``, ``search_by_phone()``,
-   ``add_contact()``, ``remove_contact()`` и ``get_chat_id()``. Подробнее:
-   :doc:`users`.
+   ``add_contact()``, ``remove_contact()``, ``import_contacts()`` и
+   ``get_chat_id()``. Подробнее: :doc:`users`.
 
 Аккаунт
    ``change_profile()``, папки чатов, активные сессии, ``logout()`` и
    ``close_all_sessions()``. Подробнее: :doc:`account`.
 
 Auth
-   ``set_2fa()`` и ``remove_2fa()`` для управления паролем 2FA. Подробнее:
+   ``set_2fa()``, ``remove_2fa()`` и ``authorize_qr_login()``. Подробнее:
    :doc:`auth`.
 
 Частые ошибки

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

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

{maxapi_python-2.1.3 → maxapi_python-2.3.0}/docs/messages.rst

@@ -30,7 +30,28 @@ 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, ...)``.
+Новые вложения передаются через ``attachments``.
 
 Отправлять сообщения
 --------------------
@@ -69,6 +90,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.3.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.3.0/docs/release-2-3-0.rst

@@ -0,0 +1,40 @@
+PyMax 2.3.0
+===========
+
+Изменения относительно ``2.2.0``.
+
+Добавлено
+---------
+
+* Несколько ``on_start``-обработчиков на одном клиенте или роутере. Все
+  зарегистрированные callbacks запускаются после успешного login.
+* ``on_error()`` для централизованной обработки ошибок из handler-ов,
+  фильтров, ``on_start`` и login на этапе запуска.
+* ``ErrorScope.GLOBAL`` и ``ErrorScope.LOCAL`` для выбора области действия
+  error-handler-а.
+* ``on_disconnect()`` для реакции на сетевое отключение перед reconnect. В
+  callback передаются исходная ошибка, флаг reconnect и задержка.
+* ``relogin()`` для удаления текущей локальной сессии и повторной авторизации.
+* ``delete_chat()`` на клиенте и ``Chat.delete()`` на bound-объекте чата.
+* ``import_contacts()`` и ``ContactInfo`` для импорта контактов из телефонной
+  книги.
+* ``SessionStore.delete_all_sessions()`` для очистки встроенного SQLite-store.
+
+Изменилось
+----------
+
+* ``edit_message()`` и ``Message.edit()`` принимают новые вложения только через
+  ``attachments=[...]``.
+* Тип ``attachments`` для отправки и редактирования сообщений теперь принимает
+  любую ``Sequence`` из ``Photo``, ``File`` и ``Video``.
+* Обработанные login-ошибки на этапе ``start`` больше не приводят к запуску
+  ``on_start``.
+
+Миграция
+--------
+
+* В ``edit_message()`` и ``Message.edit()`` используйте ``attachments=[...]``.
+  Параметр ``attachment`` удален.
+* Если error-handler зарегистрирован и успешно отработал, исходная ошибка
+  считается обработанной. Если сам error-handler падает, исходная ошибка
+  продолжает распространяться.