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

app.exchange

Договоры обмена между профилями юзерботов. Запрос должен быть одобрен получателем и активирован работающими экземплярами.

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

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

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

__init__

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

def __init__(app: App) -> None: ...

Аргументы

• app: App, обязательный. Переданный ядром объект app. Второй App в модуле создавать не нужно.

Результат

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

Права

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

Ошибки

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

Пример

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

__call__

Готовит запрос договора для выбранного юзербота и экземпляра.

def __call__(peer: str, module: str | None, slot: str | None = 'main') -> ExchangeRequest: ...

Аргументы

• peer: str, обязательный. ID профиля юзербота получателя договора, не Telegram ID.
• module: str | None, обязательный. ID публикации модуля. None выбирает текущий раздел там, где это предусмотрено.
• slot: str | None, по умолчанию 'main'. Имя профиля экземпляра. None использует выбор зависимости или текущий профиль.

Результат

ExchangeRequest. Готовит запрос договора для выбранного юзербота и экземпляра.

Права

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

Ошибки

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

Пример

result = app.exchange("peer-id", "dependency-id")

agreement

Создаёт объект договора по его ID.

def agreement(id: str) -> Agreement: ...

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

Agreement. Создаёт объект договора по его ID.

Права

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

Ошибки

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

Пример

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

iter

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

async def iter(limit: int = 100) -> AsyncIterator[Agreement]: ...

Аргументы

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

Результат

AsyncIterator[Agreement]. Перебирает доступные договоры порциями с проверкой продвижения курсора.

Права

Нужны exchange.request.

Ошибки

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

Пример

async for value in app.exchange.iter():
    break

request

Отправляет запрос договора на конкретный ресурс. Одобрение не проверяет наличие данных заранее.

async def request(peer: str, module: str | None, slot: str | None, resource: dict[str, JSON], **data: JSON) -> AgreementInfo: ...

Аргументы

• peer: str, обязательный. ID профиля юзербота получателя договора, не Telegram ID.
• module: str | None, обязательный. ID публикации модуля. None выбирает текущий раздел там, где это предусмотрено.
• slot: str | None, обязательный. Имя профиля экземпляра. None использует выбор зависимости или текущий профиль.
• resource: dict[str, JSON], обязательный. Ресурс договора с kind и key. Наличие данных проверяется после одобрения.
• data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: fields, mode, direction, group. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

AgreementInfo. Отправляет запрос договора на конкретный ресурс. Одобрение не проверяет наличие данных заранее.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.request("peer-id", "dependency-id", "main", {"kind": "data", "key": "notes"}, mode="permanent")

get

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

async def get(id: str) -> AgreementInfo: ...

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

AgreementInfo. Получает доступное состояние договора.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.get("object-id")

list

Получает порцию договоров после указанного ID.

async def list(**data: JSON) -> list[AgreementInfo]: ...

Аргументы

• data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: after, limit. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

list[AgreementInfo]. Получает порцию договоров после указанного ID.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.list(limit=20)

transfer

Выполняет согласованную передачу по активному договору.

async def transfer(id: str, **data: JSON) -> JSON: ...

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.
• data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: value. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

JSON. Выполняет согласованную передачу по активному договору.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.transfer("object-id", value=None)

revoke

Отзывает договор. Завершённые и уже выполняющиеся действия не откатываются.

async def revoke(id: str) -> AgreementInfo: ...

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

AgreementInfo. Отзывает договор. Завершённые и уже выполняющиеся действия не откатываются.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.revoke("object-id")

history

Возвращает историю действий по договору.

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

Аргументы

• id: str, обязательный. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

list[dict[str, JSON]]. Возвращает историю действий по договору.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.history("object-id")

events

Получает порцию событий обмена после указанного номера.

async def events(id: str, after: int = 0, limit: int = 100) -> ExchangePage: ...

Аргументы

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

Результат

ExchangePage. Получает порцию событий обмена после указанного номера.

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.events("object-id")

clear

Удаляет сохранённые события до указанной границы по правилам договора.

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

Аргументы

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

Результат

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

Права

Нужны exchange.request.

Ошибки

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

Пример

result = await app.exchange.clear("object-id", 0)