PyMax
Python-библиотека для Max API.
Что это
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-файл; дальше этот файл используется автоматически.
import asyncio
from pymax import Client, Message
client = Client(
phone="+79990000000",
work_dir="cache",
session_name="main.db",
)
@client.on_start()
async def on_start(client: Client) -> None:
print("Клиент запущен")
print("Ваш ID:", client.me.contact.id if client.me else "unknown")
@client.on_message()
async def on_message(message: Message, client: Client) -> None:
print(message.chat_id, message.sender, message.text)
if message.chat_id is not None and message.text:
await message.answer("Привет от PyMax")
async def main() -> None:
await client.start()
if __name__ == "__main__":
asyncio.run(main())
WebClient
WebClient использует WebSocket и QR-авторизацию:
import asyncio
from pymax import WebClient
client = WebClient(work_dir="cache", session_name="web.db")
@client.on_start()
async def on_start(client: WebClient) -> None:
print("Web-клиент запущен")
asyncio.run(client.start())
Роутеры
Обработчики можно регистрировать на клиенте или вынести в отдельный роутер.
Handler всегда принимает событие и клиента: (event, client).
from pymax import Client, ClientRouter, Message
router = ClientRouter()
def is_start(message: Message) -> bool:
return message.text == "/start"
@router.on_message(is_start)
async def start(message: Message, client: Client) -> None:
await message.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 - частые проблемы.
Опубликованная документация:
Разработка
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
Ссылки
Лицензия
Проект распространяется под лицензией MIT. Подробности см. в LICENSE.
Авторы
1 maintainer
Metadata
1 maintainer
Release files for maxapi-python 2.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| maxapi_python-2.4.1.tar.gz | 338.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| maxapi_python-2.4.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 502.3 kB
Release files / maxapi_python-2.4.1.tar.gz
| Download URL | maxapi_python-2.4.1.tar.gz |
|---|---|
| Size | 338.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c68a642845b6794170c84251058b218773f88416b04f689cce837f49b59bf31a
|
|
BLAKE2b-256 checksum How to use checksums |
90a677a04168c570bd44f0066760649317482148b3c9849ab266661454b38f52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / maxapi_python-2.4.1-py3-none-any.whl
| Download URL | maxapi_python-2.4.1-py3-none-any.whl |
|---|---|
| Size | 163.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49c996cebebdcd490b8fc1424c84faad3c33d0b75eff4bb86cf1de9d968d76ea
|
|
BLAKE2b-256 checksum How to use checksums |
42f678e8c997cbdd6ff58096305472e308167e91ab9f5f901705a58a02bad783
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
