🚀 Руководство по MaxClient¶

📋 Содержание¶

Установка и Настройка
Основные Возможности
Управление Подключением
Работа с Данными
Лучшие Практики

⚙️ Установка и настройка¶

Инициализация Клиента¶

MaxClient

Основной класс для взаимодействия с WebSocket API сервиса Max.

client = MaxClient(
    phone: str,
    uri: str = Constants.WEBSOCKET_URI.value,
    headers: dict[str, Any] | None = Constants.DEFAULT_USER_AGENT.value,
    token: str | None = None,
    send_fake_telemetry: bool = True,
    host: str = Constants.HOST.value,
    port: int = Constants.PORT.value,
    work_dir: str = ".",
    logger: logging.Logger | None = None,
)

Параметры конфигурации

Параметр	Тип	Описание	По умолчанию
`phone`	`str`	Номер телефона для авторизации	-
`uri`	`str`	URI WebSocket сервера	`Constants.WEBSOCKET_URI.value`
`headers`	`dict[str, Any] \\| None`	Заголовки для соединения	`Constants.DEFAULT_USER_AGENT.value`
`token`	`str \\| None`	Токен авторизации	`None`
`send_fake_telemetry`	`bool`	Отправка телеметрии	`True`
`host`	`str`	Хост API сервера	`Constants.HOST.value`
`port`	`int`	Порт API сервера	`Constants.PORT.value`
`work_dir`	`str`	Директория для БД	`"."`
`logger`	`logging.Logger \\| None`	Пользовательский логгер	`None`

Пример базовой инициализации

from pymax import MaxClient

client = MaxClient(
    phone="+79001234567",
    work_dir="./data"
)

Пример расширенной конфигурации

import logging

# Настройка логгера
logger = logging.getLogger("max_bot")
logger.setLevel(logging.DEBUG)

# Инициализация с дополнительными параметрами
client = MaxClient(
    phone="+79001234567",
    token="your_saved_token",  # Если есть сохраненный токен
    work_dir="./data",
    logger=logger,
    send_fake_telemetry=False
)

🔑 Основные возможности¶

Свойства Клиента¶

Аутентификация и Подключение¶

Статус и авторизация

Свойство	Тип	Описание
`is_connected`	`bool`	Статус подключения
`phone`	`str`	Номер телефона
`me`	`Me \\| None`	Информация о пользователе

Доступ к Данным¶

Чаты и пользователи

Свойство	Тип	Описание
`chats`	`list[Chat]`	Все чаты
`dialogs`	`list[Dialog]`	Личные диалоги
`channels`	`list[Channel]`	Каналы

🔌 Управление подключением¶

Запуск и Остановка¶

async def start() -> None

Запуск клиента

Метод выполняет: 1. Подключение к WebSocket 2. Авторизацию пользователя 3. Инициализацию фоновых задач 4. Синхронизацию данных

Пример использования

async def main():
    client = MaxClient(phone="+79001234567")
    try:
        await client.start()
        print("Клиент успешно запущен")
    except Exception as e:
        print(f"Ошибка запуска: {e}")

asyncio.run(main())

async def close() -> None

Закрытие клиента

Метод выполняет: 1. Остановку фоновых задач 2. Закрытие WebSocket соединения 3. Очистку ресурсов

Пример корректного закрытия

async def main():
    async with MaxClient(phone="+79001234567") as client:
        await client.start()
        # Ваш код здесь
    # Клиент автоматически закроется

📨 Работа с Сообщениями¶

Обработка Сообщений¶

Регистрация обработчиков

@client.on_message()
async def handle_message(message: Message):
    print(f"Получено сообщение: {message.text}")

    if message.attaches:
        print("Есть вложения!")

    if message.sender:
        user = await client.get_user(message.sender)
        if user:
            print(f"От: {user.names[0].name}")

Фильтрация Сообщений¶

Примеры фильтров

# Только текстовые сообщения
@client.on_message(Filter(chat_id=0))
async def handle_text(message: Message):
    print(f"Текст: {message.text}")

💾 Работа с данными¶

Доступ к Чатам¶

Типы чатов

# Все чаты
for chat in client.chats:
    print(f"Чат: {chat.title}")

# Личные диалоги
for dialog in client.dialogs:
    user = await client.get_user(dialog.owner)
    if user:
        print(f"Диалог с {user.names[0].name}")

# Каналы
for channel in client.channels:
    print(f"Канал: {channel.title}")

Информация о Пользователе¶

Работа с текущим пользователем

me = client.me
if me:
    name = me.names[0] if me.names else None
    print(f"Авторизован как: {name.name if name else me.phone}")
    print(f"ID: {me.id}")
    print(f"Статус: {me.account_status}")

💽 Хранение Данных¶

База Данных¶

Локальное хранилище

Расположение: {work_dir}/session.db
Хранит:
- Токены авторизации
- Информацию об устройстве
- Данные сессии
Особенности:
- Автоматическое управление
- Персистентное хранение
- Безопасное сохранение токенов

📚 Лучшие практики¶

Безопасное Использование¶

Контекстный менеджер

async def main():
    async with MaxClient(phone="+79001234567") as client:
        await client.start()
        # Ваш код здесь
    # Клиент автоматически закроется

Обработка Ошибок¶

Обработка исключений

try:
    await client.start()
except WebSocketNotConnectedError:
    print("Ошибка подключения")
except Exception as e:
    print(f"Непредвиденная ошибка: {e}")

Оптимизация¶

Советы по оптимизации

Используйте фильтры сообщений для снижения нагрузки
Применяйте кэширование пользователей через get_cached_user
Группируйте операции с сообщениями
Правильно закрывайте ресурсы

Структура Бота¶

Рекомендуемая структура

from pymax import MaxClient

class MyBot:
    def __init__(self, phone: str):
        self.client = MaxClient(phone=phone)

    async def setup(self):
        # Регистрация обработчиков
        @self.client.on_message()
        async def handle_message(message: Message):
            await self.process_message(message)

        @self.client.on_start()
        async def handle_start():
            await self.on_ready()

    async def process_message(self, message: Message):
        # Ваша логика обработки сообщений
        pass

    async def on_ready(self):
        print("Бот готов к работе!")

    async def run(self):
        await self.client.start()

# Использование
bot = MyBot(phone="+79001234567")
asyncio.run(bot.run())