Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
3eaf39e
fix: preserve intraword markdown markers
kocaemre Sep 3, 2026
884ace5
fix: keep intraword asterisk emphasis
kocaemre Sep 6, 2026
7186a30
feat: add callback and message link support
ink-developer Aug 5, 2026
e11d91d
feat: add composable event filters
ink-developer Aug 5, 2026
d0f9bfd
feat: add channel comments support
ink-developer Sep 21, 2026
899e7d9
fix: parse inline keyboard buttons as rows
ink-developer Sep 25, 2026
90316a5
fix: allow null comments info in updates
ink-developer Sep 25, 2026
190e391
fix: comments info model fix
ink-developer Sep 25, 2026
6625579
fix: normalize reaction updates and route self reactions
ink-developer Oct 17, 2026
e31682e
fix: dispatch raw frames when typed dispatch fails
ink-developer Oct 17, 2026
91aea44
refactor: align filter typing and test usage
ink-developer Oct 17, 2026
141ec84
chore: update Android device profiles
ink-developer Oct 17, 2026
9cab675
chore: clean up model examples and typing annotations
ink-developer Oct 17, 2026
aaf6f9f
fix: read photo upload ids from photos URL parameter
ink-developer Oct 17, 2026
10d6c93
refactor: use integer ids for read_message
ink-developer Oct 17, 2026
192a8e7
fix: accept full LZ4 compression factor range
ink-developer Oct 23, 2026
9008f88
fix: support photo upload URL variants
ink-developer Oct 23, 2026
c0b8f67
fix: stop repeated authentication after token revocation
ink-developer Oct 23, 2026
d818071
feat: expose client middleware registration and execution chain
ink-developer Oct 23, 2026
70f2277
Merge pull request #101 from kocaemre/fix/markdown-in-word-markers
ink-developer Oct 23, 2026
993ea68
fix: preserve literal content inside Markdown code
ink-developer Oct 25, 2026
de76842
fix: preserve API context for comments and callbacks
ink-developer Oct 25, 2026
c43ea8d
fix: respect QR two-factor password attempt limits
ink-developer Oct 25, 2026
bb2f4c9
feat: add FSM and handler dependency injection
ink-developer Oct 25, 2026
f4bb718
feat: add stories API and update notifications
ink-developer Oct 25, 2026
846fce8
chore: update Android fingerprints and default to 26.37.1
ink-developer Oct 25, 2026
b73aa38
test: align expectations with current message and event models
ink-developer Oct 25, 2026
dd3b717
docs: document 2.5.0 public APIs and migration
ink-developer Oct 25, 2026
91c394d
chore: prepare 2.5.0 release metadata
ink-developer Oct 25, 2026
02f167f
test: exclude unsupported post_id magic filter selector
ink-developer Oct 25, 2026
ee75cf9
fix: preserve session store during reconnect and relogin
ink-developer Oct 25, 2026
ca26c02
fix: handle whitespace-only text in Command filter
ink-developer Oct 25, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 14 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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",
Expand All @@ -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)

Expand All @@ -92,6 +96,8 @@ if __name__ == "__main__":
asyncio.run(main())
```

Отправьте `/start`, чтобы вызвать обработчик.

## WebClient

`WebClient` использует WebSocket и QR-авторизацию:
Expand Down Expand Up @@ -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("Готово")

Expand All @@ -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) - частые
проблемы.
Expand Down
13 changes: 7 additions & 6 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
25 changes: 25 additions & 0 deletions docs/api/router.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,28 @@ Router API
.. 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
32 changes: 21 additions & 11 deletions docs/client.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -361,7 +362,7 @@ number всегда берутся из конфигурации текущег

await client.relogin()

``relogin()`` удаляет загруженную сессию из store, закрывает текущий runtime и
``relogin()`` удаляет загруженную локальную сессию, закрывает соединение и
по умолчанию сразу запускает клиента снова. Если token был передан через
``ExtraConfig(token=...)``, он тоже сбрасывается; это можно отключить через
``drop_config_token=False``.
Expand All @@ -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``:

Expand Down Expand Up @@ -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-ссылки,
участники, назначение администраторов, настройки групп, удаление чатов и
Expand Down
144 changes: 144 additions & 0 deletions docs/di.rst
Original file line number Diff line number Diff line change
@@ -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
17 changes: 5 additions & 12 deletions docs/examples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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}")
Expand Down
2 changes: 2 additions & 0 deletions docs/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ FAQ
``@client.on_message()``;
* handler принимает один аргумент вместо ``(event, client)``;
* фильтр вернул ``False`` или упал с ошибкой;
* вместо экземпляра ``Filter`` передана обычная функция;
* более ранний обработчик этого роутера уже подошел под событие;
* событие другого типа;
* payload не прошел Pydantic-валидацию.

Expand Down
Loading
Loading