PyMax

Python-библиотека для Max API.

Warning

PyMax использует неофициальный внутренний API Max. API может измениться без предупреждения, а использование библиотеки может нарушать условия сервиса. Вы используете PyMax на свой риск; авторы и контрибьюторы не несут ответственности за блокировки аккаунтов, потерю данных или другие последствия.

Что это

PyMax - асинхронная Python-библиотека для внутреннего API Max. Она умеет авторизоваться в аккаунте, слушать события, отправлять сообщения, работать с чатами, пользователями, файлами, сессиями и доменными типами Max через TCP или WebSocket.

Возможности

• Авторизация по телефону и SMS-коду через Client.
• QR-авторизация web-клиента через WebClient.
• Роутеры, фильтры, on_start, raw-события и typed events.
• Сообщения: отправка и планирование, ответы, реакции, pin, read, delete и история.
• Чаты, группы, участники, invite-ссылки и настройки групп.
• Пользователи, контакты, профиль, папки, активные сессии и 2FA.
• Вложения: Photo, File, Video, Voice, VideoNote.
• Выбор версии mobile-клиента с локальным или обновляемым каталогом fingerprints.
• SQLite-сессии, sync-state, reconnect и debug-логи.
• Pydantic-модели и удобные domain-объекты.

Установка

Требуется Python 3.10 или новее.

pip install -U maxapi-python

Через uv:

uv add -U maxapi-python

Напрямую из репозитория:

pip install git+https://github.com/MaxApiTeam/PyMax.git

Быстрый старт

Client использует TCP-соединение. При первом запуске PyMax попросит SMS-код и сохранит сессию в SQLite-файл; дальше этот файл используется автоматически.

importasynciofrompymaximportClient, Messageclient=Client(
phone="+79990000000",
work_dir="cache",
session_name="main.db",
)
@client.on_start()asyncdefon_start(client: Client) ->None:
print("Клиент запущен")
print("Ваш ID:", client.me.contact.idifclient.meelse"unknown")
@client.on_message()asyncdefon_message(message: Message, client: Client) ->None:
print(message.chat_id, message.sender, message.text)
ifmessage.chat_idisnotNoneandmessage.text:
awaitmessage.answer("Привет от PyMax")
asyncdefmain() ->None:
awaitclient.start()
if__name__=="__main__":
asyncio.run(main())

WebClient

WebClient использует WebSocket и QR-авторизацию:

importasynciofrompymaximportWebClientclient=WebClient(work_dir="cache", session_name="web.db")
@client.on_start()asyncdefon_start(client: WebClient) ->None:
print("Web-клиент запущен")
asyncio.run(client.start())

Роутеры

Обработчики можно регистрировать на клиенте или вынести в отдельный роутер. Handler всегда принимает событие и клиента: (event, client).

frompymaximportClient, ClientRouter, Messagerouter=ClientRouter()
defis_start(message: Message) ->bool:
returnmessage.text=="/start"@router.on_message(is_start)asyncdefstart(message: Message, client: Client) ->None:
awaitmessage.answer("Готово")
client=Client(phone="+79990000000", work_dir="cache")
client.include_router(router)

Куда дальше

• Getting Started - первый запуск и сессии.
• Client - жизненный цикл клиента, reconnect и sync-state.
• Router - роутеры, фильтры и raw events.
• Messages - сообщения, реакции, история и вложения.
• Files - отправка и скачивание файлов.
• FAQ и Troubleshooting - частые проблемы.

Опубликованная документация:

• docs.pymax.org
• DeepWiki

Разработка

uv sync --all-groups
uv run pre-commit install
uv run pre-commit run --all-files
uv run pytest
uv run python -c "import pymax; print(pymax.__all__)"
uv run sphinx-build -b html docs docs/_build/html

Ссылки

• GitHub
• PyPI
• Telegram

Лицензия

Проект распространяется под лицензией MIT. Подробности см. в LICENSE.

Авторы

• ink - основной разработчик, исследование API и документация.
• noxzion - оригинальный автор проекта.