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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxapi-python
-Version: 2.3.1
+Version: 2.4.0
 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

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

@@ -53,6 +53,16 @@ Account
        photo_token="PHOTO_TOKEN",
    )
 
+Статус присутствия
+------------------
+
+``set_presence()`` меняет статус, который будет использован при следующем
+login или ping:
+
+.. code-block:: python
+
+   client.set_presence(online=True)
+
 Папки чатов
 -----------
 

{maxapi_python-2.3.1 → maxapi_python-2.4.0}/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.0}/docs/chats.rst

@@ -90,6 +90,40 @@ 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,
+       ],
+   )
+
 Настройки и профиль группы
 --------------------------
 

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

@@ -33,6 +33,18 @@ Client
 6. Вызывается ``on_start``.
 7. Клиент слушает события до закрытия соединения или отмены задачи.
 
+Если ``start()`` запущен отдельной задачей, ``stop()`` штатно закрывает
+соединение и завершает эту задачу без ``CancelledError``:
+
+.. code-block:: python
+
+   import asyncio
+
+   task = asyncio.create_task(client.start())
+   # ... работа приложения ...
+   await client.stop()
+   await task
+
 Данные после login
 ------------------
 
@@ -54,6 +66,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("Для выбранной версии приложения доступно обновление")
+
 Создание клиента
 ----------------
 
@@ -300,13 +321,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.4.0/docs/files.rst

@@ -0,0 +1,174 @@
+Files
+=====
+
+Что это
+-------
+
+Для отправки вложений PyMax использует пять основных классов:
+
+``Photo``
+   Фото. Проверяет расширение и MIME-тип.
+
+``Video``
+   Видео. Загружается чанками и ждет событие готовности от Max.
+
+``File``
+   Обычный файл. Тоже загружается чанками и ждет событие готовности.
+
+``Voice``
+   Голосовое сообщение. Поддерживается только формат OGG; PyMax не
+   конвертирует другие аудиоформаты.
+
+``VideoNote``
+   Круглое видеосообщение. Можно передать длительность вручную или установить
+   extra ``video`` для автоматического определения.
+
+Как отправить файл
+------------------
+
+.. code-block:: python
+
+   import asyncio
+
+   from pymax import Client, File, Photo, Video, VideoNote, Voice
+
+   client = Client(phone="+79990000000", work_dir="cache")
+
+
+   @client.on_start()
+   async def send_files(client: Client) -> None:
+       chat = await client.get_chat(123456)
+
+       await chat.answer(
+           text="Фото",
+           attachments=[Photo(path="image.jpg")],
+       )
+
+       await chat.answer(
+           text="Документ",
+           attachments=[File(path="report.pdf")],
+       )
+
+       await chat.answer(
+           text="Видео",
+           attachments=[Video(path="clip.mp4")],
+       )
+
+       await chat.answer(attachments=[Voice(path="voice.ogg")])
+       await chat.answer(
+           attachments=[VideoNote(path="circle.mp4", duration=4200)]
+       )
+
+
+   asyncio.run(client.start())
+
+Источники данных
+----------------
+
+Можно передать ровно один источник:
+
+.. code-block:: python
+
+   Photo(path="image.jpg")
+   File(url="https://example.com/report.pdf")
+   Video(raw=b"...", name="clip.mp4")
+   Voice(path="voice.ogg")
+   VideoNote(path="circle.mp4", duration=4200)
+
+Для ``raw`` обязательно указывайте ``name``. Для ``File``, ``Video``,
+``Voice`` и ``VideoNote`` имя берется из ``path`` или ``url``, если не
+передано явно.
+
+Если длительность ``VideoNote`` не передана, установите дополнительную
+зависимость:
+
+.. code-block:: console
+
+   uv add "maxapi-python[video]"
+
+Формат Voice и VideoNote
+------------------------
+
+Для ``Voice`` используйте готовый OGG-файл. Простого переименования MP3, WAV
+или другого аудиофайла в ``.ogg`` недостаточно: PyMax загружает исходные байты
+без перекодирования.
+
+``VideoNote`` также не перекодирует видео. Для совместимости с официальным
+клиентом 26.21.1 рекомендуется следующий формат:
+
+* контейнер MP4;
+* видео H.264/AVC, 480x480, 30 FPS и bitrate около 1 024 000 bit/s;
+* pixel format ``yuv420p`` при подготовке через FFmpeg;
+* ключевой кадр примерно раз в секунду, то есть GOP около 30 кадров;
+* аудио AAC в том же MP4-контейнере;
+* длительность до 60 секунд.
+
+Официальный клиент задает квадратное разрешение, фиксированные 30 FPS и
+максимальную длительность через server config. Нижняя граница в одну секунду
+не является подтвержденным ограничением upload API, поэтому PyMax ее не
+проверяет.
+
+Поворот лучше физически применить при перекодировании и убрать rotation
+metadata: так файл меньше зависит от того, как конкретный клиент обработает
+orientation hint. H.264 profile и level специально фиксировать не требуется.
+``faststart`` официальный recorder явно не включает; при самостоятельной
+подготовке файла его можно использовать, но для PyMax это не обязательное
+условие.
+
+Как работает upload
+-------------------
+
+1. PyMax запрашивает у Max временный upload URL.
+2. Читает файл из ``path``, ``url`` или ``raw``.
+3. Загружает данные HTTP-запросом.
+4. Для ``File``, ``Video``, ``Voice`` и ``VideoNote`` ждет служебное событие
+   готовности до 60 секунд.
+5. Подставляет token/file_id/video_id в отправляемое сообщение.
+
+Фото проходит проще: после HTTP-upload PyMax сразу достает token из ответа.
+
+Скачать входящий файл
+---------------------
+
+``FileAttachment`` содержит ID, но для скачивания нужен временный URL:
+
+.. code-block:: python
+
+   from pymax import Client, Message
+   from pymax.types.domain import FileAttachment
+
+   @client.on_message()
+   async def on_message(message: Message, client: Client) -> None:
+       if message.chat_id is None:
+           return
+
+       for attach in message.attaches:
+           if isinstance(attach, FileAttachment):
+               info = await client.get_file_by_id(
+                   chat_id=message.chat_id,
+                   message_id=message.id,
+                   file_id=attach.file_id,
+               )
+               print(info.url if info else "URL не получен")
+
+Частые ошибки
+-------------
+
+``ValueError: Only one of raw, url or path must be provided``
+   Передайте только один источник файла.
+
+``ValueError: Name must be provided for raw data``
+   Для bytes укажите имя: ``File(raw=data, name="file.bin")``.
+
+``Invalid photo extension``
+   ``Photo`` принимает ``.jpg``, ``.jpeg``, ``.png``, ``.gif``, ``.webp`` и
+   ``.bmp``.
+
+``UploadError``
+   Upload-сервис не получил нужный ответ от Max. Включите ``DEBUG``-логи:
+   часто причина в недоступном URL, неверном размере файла, timeout или в том,
+   что событие готовности файла не пришло за 60 секунд.
+
+``Automatic video duration detection requires the 'video' extra``
+   Передайте ``duration`` в миллисекундах или установите
+   ``maxapi-python[video]``.

{maxapi_python-2.3.1 → maxapi_python-2.4.0}/docs/index.rst

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

{maxapi_python-2.3.1 → maxapi_python-2.4.0}/docs/messages.rst

@@ -83,6 +83,57 @@ Messages
        source_chat_id=123456,
    )
 
+Опросы
+------
+
+Опрос можно отправить без текста. Настройки объединяются оператором ``|``:
+
+.. code-block:: python
+
+   from pymax.types import Poll, PollAnswer, PollFlags
+
+   await client.send_message(
+       chat_id=123456,
+       attachments=[
+           Poll(
+               title="Какой вариант выбрать?",
+               answers=[
+                   PollAnswer(text="Первый"),
+                   PollAnswer(text="Второй"),
+               ],
+               settings=(
+                   PollFlags.FLAG_SETTINGS_ANONYMOUS
+                   | PollFlags.FLAG_SETTINGS_REVOTE
+               ),
+           )
+       ],
+   )
+
+Для голосования нужны ID сообщения, опроса и вариантов из входящего
+``PollAttachment``:
+
+.. code-block:: python
+
+   from pymax import Message
+   from pymax.types import PollAttachment
+
+   @client.on_message()
+   async def vote(message: Message, client: Client) -> None:
+       if message.chat_id is None:
+           return
+
+       for attach in message.attaches:
+           if isinstance(attach, PollAttachment):
+               answer_id = attach.answers[0].answer_id
+               if answer_id is not None:
+                   state = await client.vote_poll(
+                       chat_id=message.chat_id,
+                       message_id=message.id,
+                       poll_id=attach.poll_id,
+                       answer_ids=[answer_id],
+                   )
+                   print(state.total)
+
 Ответ, реакции, удаление и прочтение
 ----------------------------------------
 
@@ -147,7 +198,7 @@ Messages
 .. code-block:: python
 
    history = await client.fetch_history(chat_id=123456, backward=50)
-   for message in history or []:
+   for message in history:
        print(message.id, message.text)
 
 ``fetch_history()`` принимает ``item_type``. По умолчанию используются обычные
@@ -178,8 +229,8 @@ Max присылает разные формы событий. Некоторы
 --------
 
 Входящие вложения лежат в ``message.attaches``. Тип вложения определяется по
-полю ``type``: фото, видео, файл, стикер, аудио, контакт, звонок, share или
-inline-клавиатура.
+полю ``type``: фото, видео, файл, стикер, аудио, опрос, контакт, звонок, share
+или inline-клавиатура.
 
 .. code-block:: python
 

maxapi_python-2.4.0/docs/release-2-4-0.rst

@@ -0,0 +1,210 @@
+PyMax 2.4.0
+===========
+
+Версия 2.4.0 добавляет опросы, голосовые сообщения, кружки, настройки
+приватности и новые методы управления чатами. Одновременно уточнены контракты
+существующих методов и исправлены проблемы с lifecycle клиента, повторной
+авторизацией и WebSocket.
+
+Ниже перечислены изменения относительно ``2.3.1``, которые важны при
+использовании библиотеки и обновлении существующего кода.
+
+Новый публичный API
+-------------------
+
+Опросы
+~~~~~~
+
+Добавлены модели ``Poll``, ``PollAnswer`` и ``PollFlags`` для создания
+опросов. Опрос отправляется обычным ``send_message()`` и может быть
+единственным вложением без текста:
+
+.. code-block:: python
+
+   from pymax.types import Poll, PollAnswer, PollFlags
+
+   message = await client.send_message(
+       chat_id=123456,
+       attachments=[
+           Poll(
+               title="Выберите вариант",
+               answers=[
+                   PollAnswer(text="Первый"),
+                   PollAnswer(text="Второй"),
+               ],
+               settings=PollFlags.FLAG_SETTINGS_REVOTE,
+           )
+       ],
+   )
+
+Для голосования добавлен метод:
+
+``await client.vote_poll(chat_id, message_id, poll_id, answer_ids) -> PollState``
+
+Входящий опрос представлен моделью ``PollAttachment``. Она содержит
+``poll_id``, варианты ответа и текущее состояние ``PollState`` с
+типизированными результатами и голосами.
+
+Голосовые сообщения и кружки
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Добавлены два типа отправляемых вложений:
+
+``Voice``
+   Голосовое сообщение. Принимает только готовый OGG-файл. PyMax не
+   перекодирует MP3, WAV и другие форматы.
+
+``VideoNote``
+   Круглое видеосообщение. Рекомендуемый формат — MP4 с H.264-видео 480x480,
+   30 FPS и AAC-аудио. Длительность передается в миллисекундах через
+   ``duration``.
+
+Оба класса экспортируются из ``pymax`` и передаются в ``attachments``:
+
+.. code-block:: python
+
+   from pymax import VideoNote, Voice
+
+   await client.send_message(
+       chat_id=123456,
+       attachments=[Voice(path="voice.ogg")],
+   )
+   await client.send_message(
+       chat_id=123456,
+       attachments=[VideoNote(path="circle.mp4", duration=4200)],
+   )
+
+Если ``duration`` для ``VideoNote`` не указан, PyMax может определить его
+автоматически с необязательной зависимостью ``video``::
+
+   uv add "maxapi-python[video]"
+
+Чаты и состояние аккаунта
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Новые методы
+   :header-rows: 1
+   :widths: 35 40 25
+
+   * - Метод
+     - Назначение
+     - Результат
+   * - ``get_chat_members(chat_id, marker=None, count=50)``
+     - Получить страницу участников чата. Ненулевой ``marker`` передается в
+       следующий вызов.
+     - ``tuple[list[Member], int]``
+   * - ``add_admin(chat_id, user_id, permissions)``
+     - Назначить администратора канала с явным списком
+       ``ChannelPermissions``.
+     - ``None``
+   * - ``set_presence(online=...)``
+     - Изменить статус, используемый при следующем login или ping.
+     - ``None``
+   * - ``is_update_available()``
+     - Проверить флаг обновления, полученный при handshake.
+     - ``bool``
+
+Настройки приватности
+~~~~~~~~~~~~~~~~~~~~~
+
+Добавлен метод
+``await client.change_profile_settings(settings) -> bool``. Он принимает
+``PrivacySettingsUpdate`` и изменяет только заполненные поля:
+
+.. code-block:: python
+
+   from pymax import PrivacyAccess, PrivacySettingsUpdate
+
+   await client.change_profile_settings(
+       PrivacySettingsUpdate(
+           search_by_phone=PrivacyAccess.CONTACTS,
+           incoming_calls=PrivacyAccess.ALL,
+           chat_invites=PrivacyAccess.NOBODY,
+           phone_number_visibility=PrivacyAccess.CONTACTS,
+           hide_online_status=True,
+           safe_content_only=True,
+       )
+   )
+
+Для настроек доступа используются ``PrivacyAccess.ALL``,
+``PrivacyAccess.CONTACTS`` и ``PrivacyAccess.NOBODY``. После успешного запроса
+PyMax сохраняет новый ``config_hash`` в текущей сессии, поэтому следующая
+авторизация продолжает синхронизацию с актуального состояния.
+
+Изменения существующего API
+---------------------------
+
+.. list-table:: Изменившиеся контракты
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - API
+     - Было в 2.3.1
+     - Стало в 2.4.0
+   * - ``send_message()`` и ``forward_message()``
+     - Возвращаемый тип допускал ``Message | None``.
+     - Возвращают ``Message``. Если сервер не прислал обязательный объект
+       сообщения, вызов завершается ошибкой.
+   * - ``Message.reply()``, ``Message.answer()``, ``Message.forward()`` и
+       ``Chat.answer()``
+     - Bound-методы также имели необязательный возвращаемый тип.
+     - Возвращают ``Message`` без лишней проверки на ``None``.
+   * - ``send_message()``, ``edit_message()``, ``Message.reply()``,
+       ``Message.answer()`` и ``Chat.answer()``
+     - Для type checker требовался текст.
+     - ``text`` может быть ``None``, если переданы вложения. Если нет ни
+       текста, ни вложений, выбрасывается ``ValueError``.
+   * - ``fetch_history()``
+     - При отсутствии сообщений мог вернуть ``None``.
+     - Всегда возвращает ``list[Message]``; пустая история — ``[]``.
+   * - ``get_bot_init_data()``
+     - ``chat_id`` был обязательным.
+     - ``chat_id`` необязателен, поэтому метод можно вызвать вне чата.
+   * - ``change_profile()``
+     - ``photo`` был типизирован как ``Any``.
+     - ``photo`` принимает ``Photo | None``.
+
+Также исправлены типы частичных моделей протокола. В частности,
+``StickerAttachment.set_id`` теперь имеет тип ``int | None``, а поля неполных
+событий реакций больше не считаются безусловно заполненными.
+
+Breaking changes
+----------------
+
+Методы и классы из 2.3.1 не удалялись и не переименовывались. Проверить перед
+обновлением нужно два наблюдаемых изменения поведения:
+
+* Код, который отличал ``None`` от пустого списка после ``fetch_history()``,
+  должен проверять пустоту списка: ``if not history``.
+* Попытка отправить или отредактировать сообщение без текста и без вложений
+  теперь сразу завершается ``ValueError``. Сообщения только с вложением
+  поддерживаются штатно.
+
+Изменения ``Message | None`` на ``Message`` у методов отправки и пересылки —
+уточнение публичного контракта, а не новое успешное значение в runtime.
+Пользователи mypy или Pyright могут удалить лишние проверки результата на
+``None``. При работе со ``StickerAttachment.set_id`` проверка на ``None``,
+наоборот, теперь требуется.
+
+Исправления стабильности и совместимости
+----------------------------------------
+
+* Если текущую сессию отозвали с другого устройства, ответы
+  ``FAIL_LOGIN_TOKEN`` и ``FAIL_LOGOUT_ALL`` больше не оставляют клиент в
+  цикле переподключений. PyMax удаляет недействительный локальный token и
+  запускает авторизацию заново. Закрытие TLS-соединения ограничено timeout,
+  поэтому зависший shutdown не блокирует клиент бесконечно.
+* ``stop()`` штатно завершает ожидающий ``start()``. Внешняя отмена задачи при
+  этом не поглощается и продолжает распространяться вызывающему коду.
+* WebSocket-клиент использует актуальный endpoint и корректно обрабатывает
+  бинарные protocol frames.
+* Mobile login поддерживает двухэтапный LOGIN/LOGIN2. Fingerprint устройства
+  выбирается автоматически из данных Android-версий от 26.9.1 до 26.25.0.
+* Handshake без обязательного ``callsSeed`` завершается контролируемой ошибкой,
+  а не оставляет клиент в частично инициализированном состоянии.
+* Исправлены очистка ожиданий при ошибках upload, выбор MP4 URL по качеству и
+  разбор частичных событий реакций и голосов в опросах.
+
+Базовый набор зависимостей не изменился. Extra ``video`` нужен только для
+автоматического определения длительности ``VideoNote``; при явном
+``duration`` он не требуется.

{maxapi_python-2.3.1 → maxapi_python-2.4.0}/docs/types/enums.rst

@@ -19,6 +19,15 @@ Domain enums
 .. autoclass:: pymax.types.domain.attachments.enums.TranscriptionStatus
    :members:
 
+.. autoclass:: pymax.types.domain.attachments.enums.PollFlags
+   :members:
+
+Chat API enums
+--------------
+
+.. autoclass:: pymax.api.chats.ChannelPermissions
+   :members:
+
 Client config enums
 -------------------
 

{maxapi_python-2.3.1 → maxapi_python-2.4.0}/docs/types/index.rst

@@ -40,7 +40,7 @@ Types
 ``ContactInfo``
    Контакт телефонной книги для ``import_contacts()``.
 
-``PhotoAttachment``, ``VideoAttachment``, ``FileAttachment`` и другие
+``PhotoAttachment``, ``VideoAttachment``, ``FileAttachment``, ``PollAttachment`` и другие
    Входящие вложения в ``message.attaches``.
 
 ``SyncState`` и ``SyncOverrides``
@@ -112,6 +112,8 @@ API reference
    control_attachment
    file_attachment
    photo_attachment
+   poll
+   poll_attachment
    share_attachment
    sticker_attachment
    video_attachment

maxapi_python-2.4.0/docs/types/poll.rst

@@ -0,0 +1,22 @@
+Poll
+====
+
+.. autoclass:: pymax.types.domain.attachments.poll.Poll
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.types.domain.attachments.poll.PollAnswer
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.types.domain.attachments.poll.PollState
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.types.domain.attachments.poll.PollResult
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.types.domain.attachments.poll.PollVote
+   :members:
+   :show-inheritance:

maxapi_python-2.4.0/docs/types/poll_attachment.rst

@@ -0,0 +1,6 @@
+PollAttachment
+==============
+
+.. autoclass:: pymax.types.domain.attachments.poll.PollAttachment
+   :members:
+   :show-inheritance: