Cluster · разработчикам

Agreement

Снимок договора обмена. Передача допустима только при активном договоре и доступных участниках.

Все методы SDK · Типы и ошибки

Получение объекта

agreement = app.exchange.agreement("agreement-id")

agreement ссылается на доступный договор; для передачи договор активен и участники запущены.

__init__

Создаёт Agreement. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(exchange: Exchange, id: str, data: JSON = None) -> None: ...

Аргументы

• exchange: Exchange, обязательный. Служба договоров текущего приложения.
• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.
• data: JSON, по умолчанию None. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.

Результат

None. Создаёт Agreement. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
agreement = app.exchange.agreement("agreement-id")

state

Возвращает состояние из локального снимка договора.

def state() -> str | None: ...

Свойство: читается без скобок и без await.

Аргументы

Нет.

Результат

str | None. Возвращает состояние из локального снимка договора.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

value = agreement.state

load

Обновляет снимок договора из ядра.

async def load() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Обновляет снимок договора из ядра.

Права

Нужны exchange.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await agreement.load()

transfer

Передаёт значение или запрашивает согласованные данные в зависимости от направления договора.

async def transfer(value: JSON = None) -> JSON: ...

Аргументы

• value: JSON, по умолчанию None. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.

Результат

JSON. Передаёт значение или запрашивает согласованные данные в зависимости от направления договора.

Права

Нужны exchange.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await agreement.transfer()

revoke

Отзывает договор и заменяет локальный снимок ответом ядра.

async def revoke() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Отзывает договор и заменяет локальный снимок ответом ядра.

Права

Нужны exchange.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await agreement.revoke()

history

Получает историю действий по договору.

async def history() -> list[dict[str, JSON]]: ...

Аргументы

Нет.

Результат

list[dict[str, JSON]]. Получает историю действий по договору.

Права

Нужны exchange.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await agreement.history()

events

Перебирает события после указанной границы порциями, проверяя продвижение курсора.

async def events(after: int = 0, limit: int = 100) -> AsyncIterator[dict[str, JSON]]: ...

Аргументы

• after: int, по умолчанию 0. Граница событий обмена. after исключает ранее полученные события; before задаёт границу очистки.
• limit: int, по умолчанию 100. Размер порции. Для db.keys: 1..1000; файлов и договоров: 1..100. get_messages: смотри ограничения Telegram-клиента.

Результат

AsyncIterator[dict[str, JSON]]. Перебирает события после указанной границы порциями, проверяя продвижение курсора.

Права

Нужны exchange.request.

Ошибки

• RuntimeError('The exchange cursor did not advance'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

async for value in agreement.events():
    break

clear

Удаляет события по указанную договором границу; уже выполненные передачи не отменяет.

async def clear(before: int) -> dict[str, int]: ...

Аргументы

• before: int, обязательный. Граница событий обмена. after исключает ранее полученные события; before задаёт границу очистки.

Результат

dict[str, int]. Словарь {removed: int} с числом удалённых событий.

Права

Нужны exchange.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await agreement.clear(0)