pachca-sdk 1.0.12

A client library for accessing Pachca API

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 попыток).

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

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

# 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}")