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 возвращает его содержимое напрямую. Если рядом с data есть meta (списки и метод Новый чат), SDK возвращает ответ целиком: data и meta.

# ≤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 попыток). Ошибки сервера 5xx повторяются только у запросов GET, PUT и DELETE: запрос POST сервер мог успеть выполнить, и повтор создал бы дубль. Ответ 504 с кодом timeout (поиск не уложился по времени) не повторяется: тот же запрос, скорее всего, снова не уложится, и его стоит сузить.

Свой 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.7.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.7.0
File	Size	Uploaded	Provenance
pachca_sdk-1.7.0.tar.gz	43.2 kB	Oct 28, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pachca-sdk 1.7.0
File	Interpreter	ABI	Platform	Reset
pachca_sdk-1.7.0-py3-none-any.whl 42.6 kB Oct 28, 2026 Without provenance	Python 3	none	any	Details

Total release size: 85.8 kB

Release files / pachca_sdk-1.7.0.tar.gz

Download URL	pachca_sdk-1.7.0.tar.gz
Size	43.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`937947ff749d362205ce012bcd1b283bb4a1d9124da191fdbcfdd5379b8fb6a1`
BLAKE2b-256 checksum How to use checksums	`00d69b51708009b65a899ab27b186b52d45c9983fec01eedfacf349d6603c9a6`
Upload date	Oct 28, 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.7.0-py3-none-any.whl

Download URL	pachca_sdk-1.7.0-py3-none-any.whl
Size	42.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`639d24e7f4ef480773c55d4e9bcbca3bf978d2849165fbcb368f45f04a9af6c3`
BLAKE2b-256 checksum How to use checksums	`2b0320ec799529abd1d99faca3c26c90ab10c979f5c826bfe88493d524bea09a`
Upload date	Oct 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Security for pachca-sdk 1.7.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.