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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: maxapi-python
-Version: 2.4.1
+Version: 2.5.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: dishka
+Requires-Dist: dishka>=1.10.1; extra == 'dishka'
 Provides-Extra: video
 Requires-Dist: tinytag>=2.2.1; extra == 'video'
 Description-Content-Type: text/markdown
@@ -62,8 +64,11 @@ WebSocket.
 
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
-- Роутеры, фильтры, `on_start`, raw-события и typed events.
+- Роутеры, составные фильтры, middleware, `on_start`, raw-события и typed events.
+- FSM для диалогов и необязательная интеграция с Dishka.
 - Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
+- Комментарии к постам каналов и нажатия inline-кнопок ботов.
+- Сторис: фото и видео, лента, реакции и статистика просмотров.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
 - Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
@@ -100,6 +105,7 @@ pip install git+https://github.com/MaxApiTeam/PyMax.git
 import asyncio
 
 from pymax import Client, Message
+from pymax.filters import Command
 
 client = Client(
     phone="+79990000000",
@@ -114,7 +120,7 @@ async def on_start(client: Client) -> None:
     print("Ваш ID:", client.me.contact.id if client.me else "unknown")
 
 
-@client.on_message()
+@client.on_message(Command("start"))
 async def on_message(message: Message, client: Client) -> None:
     print(message.chat_id, message.sender, message.text)
 
@@ -130,6 +136,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Отправьте `/start`, чтобы вызвать обработчик.
+
 ## WebClient
 
 `WebClient` использует WebSocket и QR-авторизацию:
@@ -157,15 +165,12 @@ Handler всегда принимает событие и клиента: `(even
 
 ```python
 from pymax import Client, ClientRouter, Message
+from pymax.filters import Command
 
 router = ClientRouter()
 
 
-def is_start(message: Message) -> bool:
-    return message.text == "/start"
-
-
-@router.on_message(is_start)
+@router.on_message(Command("start"))
 async def start(message: Message, client: Client) -> None:
     await message.answer("Готово")
 
@@ -178,8 +183,11 @@ client.include_router(router)
 
 - [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
 - [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
-- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Router](docs/router.rst) - роутеры, фильтры, middleware и raw events.
+- [FSM](docs/fsm.rst) - состояния и данные диалога.
+- [DI и Dishka](docs/di.rst) - зависимости обработчиков.
 - [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Stories](docs/stories.rst) - публикация и чтение сторис.
 - [Files](docs/files.rst) - отправка и скачивание файлов.
 - [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
   проблемы.

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

@@ -24,8 +24,11 @@ WebSocket.
 
 - Авторизация по телефону и SMS-коду через `Client`.
 - QR-авторизация web-клиента через `WebClient`.
-- Роутеры, фильтры, `on_start`, raw-события и typed events.
+- Роутеры, составные фильтры, middleware, `on_start`, raw-события и typed events.
+- FSM для диалогов и необязательная интеграция с Dishka.
 - Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
+- Комментарии к постам каналов и нажатия inline-кнопок ботов.
+- Сторис: фото и видео, лента, реакции и статистика просмотров.
 - Чаты, группы, участники, invite-ссылки и настройки групп.
 - Пользователи, контакты, профиль, папки, активные сессии и 2FA.
 - Вложения: `Photo`, `File`, `Video`, `Voice`, `VideoNote`.
@@ -62,6 +65,7 @@ pip install git+https://github.com/MaxApiTeam/PyMax.git
 import asyncio
 
 from pymax import Client, Message
+from pymax.filters import Command
 
 client = Client(
     phone="+79990000000",
@@ -76,7 +80,7 @@ async def on_start(client: Client) -> None:
     print("Ваш ID:", client.me.contact.id if client.me else "unknown")
 
 
-@client.on_message()
+@client.on_message(Command("start"))
 async def on_message(message: Message, client: Client) -> None:
     print(message.chat_id, message.sender, message.text)
 
@@ -92,6 +96,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+Отправьте `/start`, чтобы вызвать обработчик.
+
 ## WebClient
 
 `WebClient` использует WebSocket и QR-авторизацию:
@@ -119,15 +125,12 @@ Handler всегда принимает событие и клиента: `(even
 
 ```python
 from pymax import Client, ClientRouter, Message
+from pymax.filters import Command
 
 router = ClientRouter()
 
 
-def is_start(message: Message) -> bool:
-    return message.text == "/start"
-
-
-@router.on_message(is_start)
+@router.on_message(Command("start"))
 async def start(message: Message, client: Client) -> None:
     await message.answer("Готово")
 
@@ -140,8 +143,11 @@ client.include_router(router)
 
 - [Getting Started](docs/getting-started.rst) - первый запуск и сессии.
 - [Client](docs/client.rst) - жизненный цикл клиента, reconnect и sync-state.
-- [Router](docs/router.rst) - роутеры, фильтры и raw events.
+- [Router](docs/router.rst) - роутеры, фильтры, middleware и raw events.
+- [FSM](docs/fsm.rst) - состояния и данные диалога.
+- [DI и Dishka](docs/di.rst) - зависимости обработчиков.
 - [Messages](docs/messages.rst) - сообщения, реакции, история и вложения.
+- [Stories](docs/stories.rst) - публикация и чтение сторис.
 - [Files](docs/files.rst) - отправка и скачивание файлов.
 - [FAQ](docs/faq.rst) и [Troubleshooting](docs/troubleshooting.rst) - частые
   проблемы.

{maxapi_python-2.4.1 → maxapi_python-2.5.0}/TODO.md

@@ -28,17 +28,18 @@ Format:
 # 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/messages/payloads.py:40: enum?
+- [ ] src/pymax/api/messages/service.py:137: 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/uploads/service.py:85: enum maybe?
+- [ ] src/pymax/api/uploads/service.py:291: 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/dispatch/dispatcher.py:79: make better comparison or just remove it
+- [ ] src/pymax/dispatch/dispatcher.py:204: 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
+- [ ] src/pymax/versions/catalog.py:88: msg

maxapi_python-2.5.0/docs/api/router.rst

@@ -0,0 +1,41 @@
+Router API
+==========
+
+.. autoclass:: pymax.Router
+   :members:
+   :show-inheritance:
+
+.. autoclass:: pymax.dispatch.ErrorScope
+   :members:
+
+.. autoclass:: pymax.dispatch.ErrorContext
+   :members:
+
+.. autodata:: pymax.ClientRouter
+
+.. autodata:: pymax.WebRouter
+
+Фильтры
+-------
+
+Примеры регистрации и объединения фильтров приведены в :doc:`/router`.
+
+.. autoclass:: pymax.filters.Filter
+   :exclude-members: resolve_filter_result
+
+.. autoclass:: pymax.filters.Command
+
+.. autoclass:: pymax.filters.Reply
+
+.. autoclass:: pymax.filters.Forwarded
+
+.. autoclass:: pymax.filters.FromMe
+
+.. autoclass:: pymax.filters.HasAttachment
+
+Middleware
+----------
+
+.. autoclass:: pymax.dispatch.Middleware
+
+.. autodata:: pymax.dispatch.MiddlewareNext

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

@@ -36,10 +36,11 @@ Client
 ``start()`` - long-running режим с автоматическим reconnect. Метод не
 возвращается, пока соединение не закрыто штатно или задача не отменена.
 
-``connect()`` выполняет один цикл подключения, login и ``on_start``, после
-чего возвращается, оставляя соединение открытым. Он не запускает reconnect
-loop: приложение само выполняет работу и затем вызывает ``stop()`` или
-``close()``.
+``connect()`` выполняет один цикл подключения и login, запускает
+``on_start``-обработчики и возвращается, оставляя соединение открытым.
+Обработчики выполняются в отдельных задачах: возврат из ``connect()`` не
+означает, что они уже завершились. Приложение само выполняет работу и затем
+вызывает ``stop()`` или ``close()``; reconnect loop этот метод не запускает.
 
 .. code-block:: python
 
@@ -361,7 +362,7 @@ number всегда берутся из конфигурации текущег
 
    await client.relogin()
 
-``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и
+``relogin()`` удаляет загруженную локальную сессию, закрывает соединение и
 по умолчанию сразу запускает клиента снова. Если token был передан через
 ``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через
 ``drop_config_token=False``.
@@ -370,16 +371,17 @@ Reconnect
 ---------
 
 По умолчанию reconnect включен. Если соединение падает из-за сетевой ошибки,
-клиент закрывает текущий runtime, ждет ``reconnect_delay`` секунд, заново
-создает соединение и app, затем снова выполняет start/login.
+``start()`` закрывает соединение, ждет ``reconnect_delay`` секунд и повторяет
+подключение с login.
 
-Роутеры после reconnect не теряются: корневой ``Router`` хранится на клиенте,
-а новый ``App`` снова получает тот же root router. ``on_start`` вызывается
-после каждого успешного reconnect.
+Регистрации обработчиков и middleware, а также данные FSM в памяти
+сохраняются при reconnect того же клиента. ``on_start`` вызывается после
+каждого успешного подключения. Завершение процесса очищает FSM в памяти.
 
 Если сервер отозвал login token, ``ExtraConfig(relogin=True)`` по умолчанию
 сбрасывает текущую сессию и запускает авторизацию заново. Значение ``False``
-отключает этот автоматический сброс.
+отключает этот автоматический сброс. Если новый token тоже отклонен, ошибка
+передается вызывающему коду без повторного автоматического запроса авторизации.
 
 Перед повторным подключением можно зарегистрировать ``on_disconnect``:
 
@@ -428,6 +430,14 @@ Debug-логи показывают handshake, login, входящие собы
    ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и
    получение URL для входящих файлов/видео.
 
+Комментарии
+   ``send_comment()``, ``fetch_comments()``, редактирование, удаление,
+   реакции и подписка на ветку поста. Подробнее: :doc:`messages`.
+
+Сторис
+   ``send_story()``, ``get_stories_feed()``, ``get_stories()``, просмотр,
+   реакции и подробная статистика. Подробнее: :doc:`stories`.
+
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,
    участники, назначение администраторов, настройки групп, удаление чатов и

maxapi_python-2.5.0/docs/di.rst

@@ -0,0 +1,144 @@
+Внедрение зависимостей
+======================
+
+Встроенная передача ``FSMContext`` описана в разделе :doc:`fsm` и работает без
+дополнительных пакетов. Для собственных сервисов и других зависимостей
+можно подключить Dishka.
+
+Установка
+---------
+
+.. code-block:: bash
+
+   pip install -U 'maxapi-python[dishka]'
+
+или через uv:
+
+.. code-block:: bash
+
+   uv add 'maxapi-python[dishka]'
+
+Подключение Dishka
+------------------
+
+Создайте ``AsyncContainer`` и свяжите его с клиентом через
+``setup_dishka(container, client)``. Параметры, которые должен заполнить
+контейнер, помечаются ``FromDishka[T]``. Событие и клиент остаются первыми
+двумя аргументами обработчика.
+
+.. code-block:: python
+
+   import asyncio
+
+   from dishka import FromDishka, Provider, Scope, make_async_container, provide
+
+   from pymax import Client, ClientRouter, Message
+   from pymax.filters import Command
+   from pymax.integrations.dishka import inject, setup_dishka
+
+
+   class GreetingService:
+       def text(self) -> str:
+           return "Привет от сервиса!"
+
+
+   class AppProvider(Provider):
+       @provide(scope=Scope.APP)
+       def greetings(self) -> GreetingService:
+           return GreetingService()
+
+
+   router = ClientRouter()
+
+
+   @router.on_message(Command("hello"))
+   @inject
+   async def hello(
+       message: Message,
+       client: Client,
+       greetings: FromDishka[GreetingService],
+   ) -> None:
+       await message.answer(greetings.text())
+
+
+   async def main() -> None:
+       container = make_async_container(AppProvider())
+       client = Client(phone="+79990000000", work_dir="cache")
+       client.include_router(router)
+       setup_dishka(container, client)
+
+       try:
+           await client.start()
+       finally:
+           await container.close()
+
+
+   if __name__ == "__main__":
+       asyncio.run(main())
+
+``@inject`` находится под ``@router.on_message(...)``: сначала создается
+обертка Dishka, затем роутер регистрирует ее. Одна аннотация
+``GreetingService`` без ``FromDishka`` не включает внедрение зависимости.
+
+В примере сервис имеет ``Scope.APP`` и повторно используется в пределах
+созданного контейнера. Контейнер привязан к конкретному экземпляру клиента.
+Если один роутер подключен к нескольким клиентам, вызовите ``setup_dishka``
+для каждого из них с нужным контейнером.
+
+Автоматическое оборачивание обработчиков
+----------------------------------------
+
+Вместо ``@inject`` у каждого обработчика можно включить ``auto_inject``:
+
+.. code-block:: python
+
+   client.include_router(router)
+   setup_dishka(container, client, auto_inject=True)
+
+Сначала зарегистрируйте обработчики и подключите роутеры, затем вызовите
+``setup_dishka``. Интеграция обойдет текущее дерево роутеров клиента и обернет
+уже зарегистрированные обработчики событий. Обработчики, у которых уже есть
+``@inject``, повторно не оборачиваются.
+
+Если нужно обернуть только отдельный роутер и его детей, используйте
+``inject_router``:
+
+.. code-block:: python
+
+   from pymax.integrations.dishka import inject_router
+
+   inject_router(router)
+
+Этот вызов не заменяет ``setup_dishka``: контейнер по-прежнему нужно связать
+с клиентом. Оба способа оборачивают только существующие регистрации; новые
+обработчики и позже подключенные роутеры автоматически не обрабатываются.
+Для них используйте ``@inject`` или повторите оборачивание после регистрации.
+
+Автоматическое оборачивание относится к обработчикам событий, например
+``on_message`` и ``on_raw``. Оно не затрагивает ``on_start``, ``on_error``
+и ``on_disconnect``.
+
+Scope и завершение работы
+-------------------------
+
+Интеграция получает зависимости непосредственно из контейнера, переданного
+в ``setup_dishka``. Отдельный ``Scope.REQUEST`` для каждого события не
+открывается. При обычном контейнере со ``Scope.APP`` зависимости уровня
+``Scope.REQUEST`` автоматически недоступны.
+
+PyMax также не добавляет ``Message``, ``Client`` или ``FSMContext`` в контекст
+Dishka. Событие и клиент передаются самим PyMax, а ``FSMContext`` можно
+добавить отдельным обязательным параметром с этой аннотацией.
+
+Созданием, выбором scope и закрытием контейнера управляет приложение.
+``client.close()`` не закрывает контейнер Dishka. В примере это делает
+``await container.close()`` в ``finally`` после завершения работы клиента.
+
+API reference
+-------------
+
+.. autofunction:: pymax.integrations.dishka.inject
+
+.. autofunction:: pymax.integrations.dishka.inject_router
+
+.. autofunction:: pymax.integrations.dishka.setup_dishka

{maxapi_python-2.4.1 → maxapi_python-2.5.0}/docs/examples.rst

@@ -9,11 +9,12 @@ Examples
    import asyncio
 
    from pymax import Client, Message
+   from pymax.filters import FromMe
 
    client = Client(phone="+79990000000", work_dir="cache")
 
 
-   @client.on_message()
+   @client.on_message(~FromMe())
    async def echo(message: Message, client: Client) -> None:
        if message.chat_id is None or not message.text:
            return
@@ -28,26 +29,18 @@ Examples
 
 .. code-block:: python
 
-   from collections.abc import Callable
-
    from pymax import Client, ClientRouter, Message
+   from pymax.filters import Command
 
    router = ClientRouter()
 
 
-   def command(name: str) -> Callable[[Message], bool]:
-       def filter_message(message: Message) -> bool:
-           return message.text == f"/{name}"
-
-       return filter_message
-
-
-   @router.on_message(command("start"))
+   @router.on_message(Command("start"))
    async def start(message: Message, client: Client) -> None:
        await message.answer("Привет")
 
 
-   @router.on_message(command("me"))
+   @router.on_message(Command("me"))
    async def me(message: Message, client: Client) -> None:
        if client.me:
            await message.answer(f"Ваш ID: {client.me.contact.id}")

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

@@ -26,6 +26,8 @@ FAQ
   ``@client.on_message()``;
 * handler принимает один аргумент вместо ``(event, client)``;
 * фильтр вернул ``False`` или упал с ошибкой;
+* вместо экземпляра ``Filter`` передана обычная функция;
+* более ранний обработчик этого роутера уже подошел под событие;
 * событие другого типа;
 * payload не прошел Pydantic-валидацию.
 

{maxapi_python-2.4.1 → maxapi_python-2.5.0}/docs/files.rst

@@ -95,6 +95,15 @@ Files
 или другого аудиофайла в ``.ogg`` недостаточно: PyMax загружает исходные байты
 без перекодирования.
 
+Пример подготовки Ogg/Opus из видео или аудиофайла:
+
+.. code-block:: console
+
+   ffmpeg -i input.mp4 -vn -c:a libopus -ac 1 -ar 48000 -b:a 32k -f ogg voice.ogg
+
+Команда создает монофайл Opus с частотой 48 кГц. PyMax загружает уже
+подготовленный файл; FFmpeg не требуется во время отправки.
+
 ``VideoNote`` также не перекодирует видео. Для совместимости с официальным
 клиентом 26.21.1 рекомендуется следующий формат:
 

{maxapi_python-2.4.1 → maxapi_python-2.5.0}/docs/formatting.rst

@@ -2,7 +2,8 @@ Text Formatting
 ===============
 
 PyMax поддерживает базовое Markdown-подобное форматирование при отправке
-сообщений. Форматирование применяется автоматически в ``send_message()``,
+сообщений. Форматирование применяется автоматически при отправке и
+редактировании сообщений и комментариев, в том числе через
 ``Message.answer()``, ``Message.reply()`` и ``Chat.answer()``: библиотека
 удаляет служебные маркеры из текста и передает Max список ``Element``.
 
@@ -67,6 +68,10 @@ PyMax поддерживает базовое Markdown-подобное форм
 Этот фрагмент будет отправлен как текст ``print("hello")`` с элементом
 ``CODE``.
 
+Содержимое inline-кода и блоков кода передается буквально: звёздочки,
+подчёркивания, ссылки, заголовки и цитаты внутри них не разбираются как
+дополнительная разметка.
+
 Ограничения
 -----------
 
@@ -79,3 +84,7 @@ PyMax поддерживает базовое Markdown-подобное форм
 
 Экранирование служебных символов обратным слешем пока не обрабатывается.
 
+Одиночное подчёркивание между буквами или цифрами сохраняется, поэтому
+``snake_case_name`` и URL с такими подчёркиваниями остаются целыми.
+Для звёздочки это правило не действует: ``foo*bar*baz`` содержит выделение.
+