Pachca Python SDK

Python клиент для Pachca API.

Установка

pip install pachca-sdk

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

from pachca import PachcaClient, MessageCreateRequestMessage

client = PachcaClient("YOUR_TOKEN")

# Создание сообщения
msg = await client.messages.create_message(
    MessageCreateRequestMessage(entity_id=334, content="Hello!")
)

# Получение сообщения
fetched = await client.messages.get_message(msg.id)

# Реакция (≤2 полей — передаются как kwargs)
await client.reactions.add_reaction(msg.id, code="👀")

# Закрепление
await client.messages.pin_message(msg.id)

# Список сообщений чата (с пагинацией)
messages = await client.messages.list_chat_messages(chat_id=198)
print(messages.next_cursor)  # курсор следующей страницы

Конвенции

• Вход: path-параметры и body-поля (если ≤2) разворачиваются в аргументы метода. Иначе — один объект-запрос.
• Выход: если ответ API содержит единственное поле data, SDK возвращает его содержимое напрямую.

# ≤2 поля → развёрнуто в аргументы
await client.reactions.add_reaction(message_id, ReactionRequest(code="👍"))
await client.messages.pin_message(message_id)

# >2 полей → объект-запрос
await client.messages.create_message(MessageCreateRequest(...))

# Ответ: API возвращает {"data": ...}, SDK возвращает объект напрямую
message = await client.messages.create_message(...)  # Message, не {"data": Message}

Пагинация

Для эндпоинтов с курсорной пагинацией SDK генерирует *_all-методы, которые автоматически обходят все страницы:

# Вручную
chats = []
cursor = None
while True:
    response = await client.chats.list_chats(cursor=cursor)
    if not response.data:
        break
    chats.extend(response.data)
    cursor = response.meta.paginate.next_page

# Автоматически
all_chats = await client.chats.list_chats_all()

Доступные методы: list_chats_all, list_users_all, list_tasks_all, list_tags_all, list_members_all, list_chat_messages_all, list_reactions_all, search_chats_all, search_messages_all, search_users_all и др.

Повторные запросы

SDK автоматически повторяет запросы при получении ответа 429 Too Many Requests. Используется заголовок Retry-After для определения задержки, с экспоненциальным backoff (до 3 попыток).

Свой HTTP-клиент

Для настройки прокси, таймаутов и других параметров HTTP используйте PachcaClient.from_client() с готовым httpx.AsyncClient:

import httpx
from pachca import PachcaClient, PACHCA_API_URL

http = httpx.AsyncClient(
    base_url=PACHCA_API_URL,
    headers={"Authorization": f"Bearer {token}"},
    proxy="http://proxy:8080",
)
client = PachcaClient.from_client(http)

Полный пример: ../examples/httpclient.py

Загрузка файлов

Загрузка файла — трёхшаговый процесс:

# 1. Получить параметры загрузки
params = await client.common.get_upload_params()

# 2. Загрузить файл на S3
with open("photo.png", "rb") as f:
    await client.common.upload_file(params, f, "photo.png")

# 3. Прикрепить к сообщению (используя key из params)

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

from pachca import PachcaClient, ApiError, OAuthError

try:
    await client.messages.get_message(999999)
except OAuthError as e:
    print(f"Ошибка авторизации: {e.message}")
except ApiError as e:
    print(f"Ошибка API: {e.errors}")

Тестирование

Для unit-тестов используйте PachcaClient.stub() — создаёт клиент без HTTP-подключения.

Методы без переопределения выбрасывают NotImplementedError("Service.method is not implemented"):

from unittest.mock import AsyncMock
from pachca import PachcaClient, MessagesService, Message

# Мок-сервис
mock_messages = MessagesService()
mock_messages.get_message = AsyncMock(return_value=Message(
    id=1,
    content="Test message",
    entity_id=123
))

# Тест
client = PachcaClient.stub(messages=mock_messages)

message = await client.messages.get_message(1)
assert message.content == "Test message"

Полный пример: ../examples/stub.py