maxapi-python 2.3.1__tar.gz → 2.4.1__tar.gz

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: maxapi-python
-Version: 2.3.1
+Version: 2.4.1
 Summary: Python wrapper для API мессенджера Max
 Project-URL: Homepage, https://github.com/MaxApiTeam/PyMax
 Project-URL: Repository, https://github.com/MaxApiTeam/PyMax
@@ -32,6 +32,8 @@ Requires-Dist: python-socks[asyncio]>=2.8.1
 Requires-Dist: qrcode>=8.2
 Requires-Dist: websockets>=16.0
 Requires-Dist: zstandard>=0.25.0
+Provides-Extra: video
+Requires-Dist: tinytag>=2.2.1; extra == 'video'
 Description-Content-Type: text/markdown
 
 # PyMax
@@ -41,6 +43,7 @@ Python-библиотека для Max API.
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/maxapi-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/maxapi-python)
 
 > [!WARNING]
 > PyMax использует неофициальный внутренний API Max. API может измениться без
@@ -60,10 +63,11 @@ WebSocket.
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
 - Роутеры, фильтры, `on_start`, raw-события и typed events.
-- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
-- Вложения: `Photo`, `File`, `Video`.
+- Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
+- Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
 - SQLite-сессии, sync-state, reconnect и debug-логи.
 - Pydantic-модели и удобные domain-объекты.
 

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/README.md

@@ -5,6 +5,7 @@ Python-библиотека для Max API.
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Package](https://img.shields.io/badge/package-maxapi--python-orange.svg)](https://pypi.org/project/maxapi-python/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/maxapi-python?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/maxapi-python)
 
 > [!WARNING]
 > PyMax использует неофициальный внутренний API Max. API может измениться без
@@ -24,10 +25,11 @@ WebSocket.
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
 - Роутеры, фильтры, `on_start`, raw-события и typed events.
-- Сообщения: отправка, ответы, reply, реакции, pin, read, delete и история.
+- Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
-- Вложения: `Photo`, `File`, `Video`.
+- Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
+- Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
 - SQLite-сессии, sync-state, reconnect и debug-логи.
 - Pydantic-модели и удобные domain-объекты.
 

maxapi_python-2.4.1/TODO.md

@@ -0,0 +1,44 @@
+# PyMax TODO :3
+
+> [!NOTE]
+> This file is maintained by the project owner. Please do not edit it in pull requests.
+
+Format:
+- Refactoring / Bugs: `TEXT. PATH. PRIORITY`
+- Features: `TEXT. TARGET. PRIORITY`
+
+## Refactoring
+
+- [ ] Перевести все аргументы, связанные со временем, на `DateTimeUnion`. `api/messages/service.py:65`. P: 50
+- [ ] Перенести часть общих типов в `common`, например `SendAttachments`. -. P: 40
+- [ ] Пересмотреть систему типов, возможно разбить её на более мелкие части. -. P: 70
+
+## Bugs
+
+- [X] Исправить голосовые/кружки. `api/upload/service.py`. P: 100
+- [X] Исправить генерацию device_id. `src/pymax/base.py:111`. P: 80
+
+## Features
+
+- [ ] FSM. Почти готово. `2.5.0`. P: 80
+- [ ] DI. `2.5.0`. P: 75
+- [ ] Улучшенная система фильтров. Почти готово. `2.5.0`. P: 90
+
+
+# Autogenerated TODO. Please, dont touch it
+- [ ] src/pymax/api/chats/payloads.py:100: ENUMM!!!
+- [ ] src/pymax/api/chats/payloads.py:123: ENUMM!!!
+- [ ] src/pymax/api/messages/payloads.py:32: enum?
+- [ ] src/pymax/api/messages/service.py:94: TypeAlias
+- [ ] src/pymax/api/uploads/service.py:68: ENUM!!!!
+- [ ] src/pymax/api/uploads/service.py:286: Error handing (yes, with 200 status 💔)
+- [ ] src/pymax/api/users/service.py:133: maybe also return phone mapping?
+- [ ] src/pymax/base.py:226: maybe impl it better way
+- [ ] src/pymax/config.py:52: delete maybe
+- [ ] src/pymax/dispatch/dispatcher.py:190: create iter_on_start_handlers
+- [ ] src/pymax/protocol/tcp/payload.py:34: deprecate? idk
+- [ ] src/pymax/transport/websocket.py:28: origin should be configurable
+- [ ] src/pymax/types/domain/attachments/video.py:70: idk maybe | None = None better
+- [ ] src/pymax/types/domain/user.py:14: move to another file
+- [ ] src/pymax/types/events/message.py:49: impl it in the better way maybe
+- [ ] src/pymax/versions/catalog.py:56: msg

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/account.rst

@@ -53,6 +53,16 @@ Account
        photo_token="PHOTO_TOKEN",
    )
 
+Статус присутствия
+------------------
+
+``set_presence()`` меняет статус, который будет использован при следующем
+login или ping:
+
+.. code-block:: python
+
+   client.set_presence(online=True)
+
 Папки чатов
 -----------
 
@@ -119,9 +129,8 @@ Account
 -------------
 
 ``client.me`` равен ``None``
-   Login еще не завершился или клиент не запущен. Читайте профиль внутри
-   ``on_start`` или после успешного ``await client.start()`` в собственном
-   lifecycle.
+   Login еще не завершился. Читайте профиль внутри ``on_start`` или после
+   успешного ``await client.connect()``.
 
 Фото профиля не обновилось
    Если переданы и ``photo``, и ``photo_token``, PyMax загрузит ``photo`` и

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/api/auth.rst

@@ -33,3 +33,5 @@ Auth API
 
 .. autoclass:: pymax.ConsoleQrHandler
    :members:
+
+.. autoclass:: pymax.PasswordAttemptsExceededError

maxapi_python-2.4.1/docs/api/client-session.rst

@@ -0,0 +1,20 @@
+Session storage
+===============
+
+.. currentmodule:: pymax.session
+
+``Client`` и ``WebClient`` используют этот контракт для token,
+device/user-agent и sync-state. Выбор и lifecycle хранилища описаны в разделе
+:ref:`client-session-guide`.
+
+.. autoclass:: SessionInfo
+   :members:
+
+.. autoclass:: StoreProtocol
+   :members:
+
+.. autoclass:: SessionStore
+   :members:
+
+.. autoclass:: InMemoryStore
+   :members:

maxapi_python-2.4.1/docs/api/client-versions.rst

@@ -0,0 +1,12 @@
+Version Catalog
+===============
+
+.. currentmodule:: pymax.versions
+
+``VersionCatalog`` связывает версию Android-клиента с build number и
+fingerprint, которые использует ``Client``.
+
+.. autoclass:: VersionCatalog
+   :members:
+
+.. autoclass:: VersionNotFoundError

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/api/client.rst

@@ -23,3 +23,5 @@ Clients API
    client-client
    client-web
    client-config
+   client-session
+   client-versions

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/api/files.rst

@@ -12,3 +12,11 @@ Files API
 .. autoclass:: pymax.Video
    :members:
    :show-inheritance:
+
+.. autoclass:: pymax.VideoNote
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.Voice
+   :members:
+   :show-inheritance:

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/auth.rst

@@ -88,6 +88,30 @@ Provider нужен, когда код приходит не из консоли
 Если provider вернет пустую строку или Max отклонит пароль, ``SmsAuthFlow``
 попросит пароль снова.
 
+Количество попыток можно ограничить через ``ExtraConfig``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig, PasswordAttemptsExceededError
+
+   client = Client(
+       phone="+79990000000",
+       password_provider=EnvPasswordProvider(),
+       extra_config=ExtraConfig(password_max_attempts=3),
+   )
+
+   try:
+       await client.connect()
+   except PasswordAttemptsExceededError:
+       print("Пароль 2FA не принят")
+
+``password_max_attempts=None`` означает неограниченное число попыток и
+сохраняет прежнее поведение. Пустой пароль, ``ApiError``, ошибка в ответе Max
+и ответ без login token расходуют одну попытку. При ``0`` или отрицательном
+значении provider не вызывается, а ``PasswordAttemptsExceededError``
+возникает сразу. Исключение наследуется напрямую от ``Exception``, поэтому
+его нужно перехватывать отдельно от ``PyMaxError``.
+
 Кастомный QR handler
 --------------------
 

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/chats.rst

@@ -90,15 +90,52 @@ login/sync, а также методы для загрузки, создания
 ``invite()`` работает только для групп и каналов. Для личного диалога тип чата
 не подходит, и метод завершится ошибкой.
 
+Участники и администраторы канала
+---------------------------------
+
+``get_chat_members()`` возвращает одну страницу участников и маркер следующей:
+
+.. code-block:: python
+
+   members, marker = await client.get_chat_members(chat_id=123456, count=50)
+   for member in members:
+       print(member.contact.id)
+
+   if marker:
+       next_members, marker = await client.get_chat_members(
+           chat_id=123456,
+           marker=marker,
+           count=50,
+       )
+
+Назначить администратора канала можно с явным набором прав:
+
+.. code-block:: python
+
+   from pymax.api.chats import ChannelPermissions
+
+   await client.add_admin(
+       chat_id=123456,
+       user_id=111,
+       permissions=[
+           ChannelPermissions.POST_MESSAGE,
+           ChannelPermissions.EDIT_MESSAGE,
+           ChannelPermissions.DELETE_MESSAGE,
+       ],
+   )
+
 Настройки и профиль группы
 --------------------------
 
 .. code-block:: python
 
+   from pymax import Photo
+
    await client.change_group_profile(
        chat_id=123456,
        name="Новый заголовок",
        description="Описание группы",
+       photo=Photo(path="group.jpg"),
    )
 
    await client.change_group_settings(
@@ -107,6 +144,11 @@ login/sync, а также методы для загрузки, создания
        only_admin_can_call=True,
    )
 
+``name``, ``description`` и ``photo`` независимы: передавайте только поля,
+которые нужно изменить. Значение ``None`` исключает поле из запроса. Перед
+обновлением профиля PyMax автоматически загружает ``Photo`` и отправляет Max
+полученный photo token.
+
 Через объект ``Chat`` можно менять настройки и перевыпускать invite-ссылку:
 
 .. code-block:: python

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/client.rst

@@ -7,9 +7,9 @@ Client
 ``Client`` и ``WebClient`` - главные объекты библиотеки. Они держат соединение,
 авторизацию, локальную сессию, кеш профиля/чатов и методы для API Max.
 
-``Client`` не является обычным HTTP-wrapper-ом на один запрос. После
-``await client.start()`` он остается подключенным, слушает события Max,
-отвечает на ping и вызывает ваши handler-ы.
+``Client`` не является обычным HTTP-wrapper-ом на один запрос. После запуска
+он остается подключенным, слушает события Max, отвечает на ping и вызывает
+ваши handler-ы.
 
 Как выбрать клиента
 -------------------
@@ -27,19 +27,50 @@ Client
 
 1. Вы создаете ``Client`` или ``WebClient``.
 2. Регистрируете handler-ы и подключаете роутеры.
-3. Вызываете ``await client.start()``.
+3. Вызываете ``await client.start()`` или ``await client.connect()``.
 4. PyMax открывает соединение, делает handshake и login.
 5. После login доступны ``client.me`` и ``client.chats``.
 6. Вызывается ``on_start``.
 7. Клиент слушает события до закрытия соединения или отмены задачи.
 
+``start()`` - long-running режим с автоматическим reconnect. Метод не
+возвращается, пока соединение не закрыто штатно или задача не отменена.
+
+``connect()`` выполняет один цикл подключения, login и ``on_start``, после
+чего возвращается, оставляя соединение открытым. Он не запускает reconnect
+loop: приложение само выполняет работу и затем вызывает ``stop()`` или
+``close()``.
+
+.. code-block:: python
+
+   await client.connect()
+   try:
+       await client.send_message(chat_id=123456, text="Готово")
+   finally:
+       await client.close()
+
+После успешного запуска состояние соединения доступно через
+``client.is_connected``.
+
+Если ``start()`` запущен отдельной задачей, ``stop()`` штатно закрывает
+соединение и завершает эту задачу без ``CancelledError``:
+
+.. code-block:: python
+
+   import asyncio
+
+   task = asyncio.create_task(client.start())
+   # ... работа приложения ...
+   await client.stop()
+   await task
+
 Данные после login
 ------------------
 
 После успешного login клиент хранит несколько кешей, которые пришли от Max:
 
 ``client.me``
-   Профиль текущего аккаунта или ``None``, если login еще не завершился.
+   Профиль текущего аккаунта.
 
 ``client.chats``
    Чаты из login/sync. Это не гарантированно полный список всех чатов.
@@ -54,6 +85,15 @@ Client
 Для актуализации используйте явные методы: ``fetch_chats()``, ``get_chat()``,
 ``get_users()``, ``fetch_users()`` и ``fetch_history()``.
 
+После handshake можно проверить, требует ли Max обновления версии приложения:
+
+.. code-block:: python
+
+   @client.on_start()
+   async def on_start(client: Client) -> None:
+       if client.is_update_available():
+           print("Для выбранной версии приложения доступно обновление")
+
 Создание клиента
 ----------------
 
@@ -85,7 +125,46 @@ Client
    Имя файла сессии внутри ``work_dir``.
 
 ``extra_config``
-   Настройки соединения, логов, reconnect, token, device/user-agent и sync.
+   Настройки соединения, логов, reconnect, token, хранения сессии,
+   device/user-agent и sync.
+
+``app_version``
+   Версия Android-клиента, которую ``Client`` использует для user-agent и
+   fingerprint. По умолчанию - версия, возвращаемая
+   ``VersionCatalog.recommended()``.
+
+``catalog``
+   Каталог fingerprints для ``app_version``. По умолчанию используется
+   встроенный каталог.
+
+Версия mobile-клиента
+---------------------
+
+``Client`` связывает выбранную ``app_version`` с соответствующими build number
+и fingerprint. Разрешение версии происходит при ``connect()`` или ``start()``,
+а не при создании объекта клиента.
+
+.. code-block:: python
+
+   from pymax import Client
+   from pymax.versions import VersionCatalog
+
+   client = Client(
+       phone="+79990000000",
+       app_version="26.28.0",
+       catalog=VersionCatalog(remote=True),
+   )
+
+Обычный ``VersionCatalog()`` использует только данные, поставляемые вместе с
+PyMax. При ``remote=True`` метод ``load()`` загружает свежий каталог с
+``hashes.pymax.org`` и добавляет его записи поверх встроенных. Сетевые,
+HTTP- и validation-ошибки удаленного каталога не скрываются и возникают во
+время ``connect()``/``start()``.
+
+Если выбранной версии нет в итоговом каталоге, PyMax выбрасывает
+``VersionNotFoundError``. Пользовательский ``ExtraConfig.user_agent`` не
+отменяет проверку ``app_version``: fingerprint для версии всё равно должен
+существовать.
 
 Тип устройства
 ---------------
@@ -188,6 +267,8 @@ Client
        qr_provider=ConfirmQrWithClient(mobile_client),
    )
 
+.. _client-session-guide:
+
 Сессия и sync-state
 -------------------
 
@@ -197,6 +278,7 @@ Client
 * ``device_id``;
 * телефон;
 * ``mt_instance_id``;
+* device/user-agent;
 * sync-маркеры ``chats_sync``, ``contacts_sync``, ``drafts_sync``,
   ``presence_sync`` и ``config_hash``.
 
@@ -204,11 +286,49 @@ Client
 ``session_name="account.db"`` это будет ``cache/account.db``. Если файл удалить,
 PyMax потеряет token и попросит авторизацию снова.
 
+Для автоматически создаваемого user-agent PyMax восстанавливает из сессии
+модель устройства, версию ОС, экран, locale и timezone. ``app_version`` и build
+number всегда берутся из конфигурации текущего запуска, поэтому смена версии
+клиента не сбрасывает сохраненный профиль устройства. Явный
+``ExtraConfig.user_agent`` имеет приоритет и заменяет значение из сессии.
+
+Старый SQLite-файл обновляется автоматически: PyMax добавляет nullable-колонку
+``user_agent`` и при первом успешном login сохраняет в нее текущий payload.
+
 При login PyMax отправляет сохраненные маркеры серверу. Если маркер актуален,
 сервер может вернуть только изменения. Поэтому повторный запуск отличается от
 первого: первый запуск обычно использует ``-1`` и получает начальный sync,
 а последующие запуски продолжают с сохраненного состояния.
 
+Пользовательский ``StoreProtocol`` может возвращать
+``SessionInfo.user_agent=None`` для совместимости, но тогда профиль устройства
+не сохраняется между запусками. Чтобы получить стандартное поведение, храните и
+возвращайте это необязательное поле вместе с остальными данными сессии.
+
+Сессия только в памяти
+----------------------
+
+Чтобы не создавать и не обновлять SQLite-файл, передайте
+``persist_session=False``:
+
+.. code-block:: python
+
+   from pymax import Client, ExtraConfig
+
+   client = Client(
+       phone="+79990000000",
+       extra_config=ExtraConfig(
+           persist_session=False,
+           reconnect=False,
+       ),
+   )
+
+В этом режиме PyMax использует отдельный ``InMemoryStore``. Переданный
+``ExtraConfig.store`` игнорируется. Сессия доступна только текущему runtime и
+теряется при его пересоздании; reconnect без ``ExtraConfig.token`` поэтому снова
+запускает SMS- или QR-авторизацию. Если автоматический reconnect в таком режиме
+не нужен, отключите его как в примере.
+
 Принудительный sync
 -------------------
 
@@ -257,6 +377,10 @@ Reconnect
 а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
 после каждого успешного reconnect.
 
+Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию
+сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False``
+отключает этот автоматический сброс.
+
 Перед повторным подключением можно зарегистрировать ``on_disconnect``:
 
 .. code-block:: python
@@ -300,13 +424,14 @@ Debug-логи показывают handshake, login, входящие собы
 Клиент собирает несколько API-направлений:
 
 Сообщения
-   ``send_message()``, ``forward_message()``, ``fetch_history()``,
+   ``send_message()``, ``forward_message()``, ``fetch_history()``, ``vote_poll()``,
    ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и
    получение URL для входящих файлов/видео.
 
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,
-   участники, настройки групп, удаление чатов и выход из групп/каналов.
+   участники, назначение администраторов, настройки групп, удаление чатов и
+   выход из групп/каналов.
 
 Пользователи
    ``get_user()``, ``get_users()``, ``fetch_users()``, ``search_by_phone()``,

{maxapi_python-2.3.1 → maxapi_python-2.4.1}/docs/faq.rst

@@ -93,6 +93,8 @@ Max не всегда присылает полный объект сообще
 Что делать при Pydantic validation error?
 -----------------------------------------
 
-Max мог прислать новый или неполный формат payload. Включите ``DEBUG``, снимите
-raw payload через ``on_raw`` и обновите PyMax. Если ошибка повторяется, заведите
-issue с очищенным payload без token, телефонов и приватных URL.
+Неизвестный тип вложения сохраняется как ``UnknownAttachment`` и сам по себе не
+должен ломать сообщение. Validation error обычно означает неполный или
+измененный payload уже известной модели. Включите ``DEBUG``, снимите raw payload
+через ``on_raw`` и обновите PyMax. Если ошибка повторяется, заведите issue с
+очищенным payload без token, телефонов и приватных URL.