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

Metadata

Release files for pachca-sdk 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pachca-sdk 1.5.0
File	Size	Uploaded
pachca_sdk-1.5.0.tar.gz	38.1 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pachca-sdk 1.5.0
File	Interpreter	ABI	Platform	Reset
pachca_sdk-1.5.0-py3-none-any.whl 37.8 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 75.8 kB

Release files / pachca_sdk-1.5.0.tar.gz

Download URL	pachca_sdk-1.5.0.tar.gz
Size	38.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`8c3804c801cf9b23c05b752cd724f5c3381db2efc467848c8134ed57461e10f6`
BLAKE2b-256 checksum How to use checksums	`8eb92baebbdf5207f5103223f66ddd46dc440d8d0b78396bf82092119bed822e`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / pachca_sdk-1.5.0-py3-none-any.whl

Download URL	pachca_sdk-1.5.0-py3-none-any.whl
Size	37.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c33a5208b9a2eaa1cb4294e3a660f2c9c77e5606a161e5fe1290b91b6ecac50e`
BLAKE2b-256 checksum How to use checksums	`b1d3b1913ecc8f856239f1e0cc3452633e90191578997a2734f7742caab304ee`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`