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

app

Точка входа в SDK. Содержит службы ядра и фабрики объектов.

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

text = app.text("Cluster")

document

Создаёт независимый документ JSON в памяти; чтение и изменения не обращаются к базе.

def document(value: JSON = None) -> Document: ...

Аргументы

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

Результат

Document. Создаёт независимый документ JSON в памяти; чтение и изменения не обращаются к базе.

Права

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

Ошибки

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

Пример

result = app.document()

stream

Создаёт поток с буфером и счётчиком потерянных событий. Получение начинается при next() или переборе.

def stream(kind: str = 'telegram') -> EventStream: ...

Аргументы

kind: str, по умолчанию 'telegram'. Источник telegram или bot. Другой kind ядро отклоняет.

Результат

EventStream. Создаёт поток с буфером и счётчиком потерянных событий. Получение начинается при next() или переборе.

Права

Ошибки

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

Пример

result = app.stream()

message

Создаёт сообщение с выбранным источником, текстом, вложением и клавиатурой. Для отправки вызови send().

def message(context: Event | int | None = None, **data: JSON) -> Message: ...

Аргументы

context: Event | int | None, по умолчанию None. Текущее событие либо числовой чат. None допустимо, если чат будет передан позже.
data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: source, text, media, keyboard. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

Message. Создаёт сообщение с выбранным источником, текстом, вложением и клавиатурой. Для отправки вызови send().

Права

Ошибки

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

Пример

result = app.message(text="Ready")

media

Описывает вложение из ID файла Cluster или байтов. Байты загружаются при первом использовании.

def media(file: str | bytes, kind: str = 'document', **data: JSON) -> Media: ...

Аргументы

file: str | bytes, обязательный. ID готового файла Cluster либо байты с обязательным filename. File передавай через file.id.
kind: str, по умолчанию 'document'. Тип photo, video, animation, audio, document, voice или video_note. gif является алиасом animation.
data: JSON, произвольные именованные аргументы. Допустимые именованные параметры: caption, filename и параметры выбранного вложения. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

Media. Описывает вложение из ID файла Cluster или байтов. Байты загружаются при первом использовании.

Права

Ошибки

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

Пример

result = app.media(b"Example", filename="note.txt")

album

Создаёт альбом. Добавь от 2 до 10 совместимых вложений перед отправкой.

def album(context: Event | int | None = None, source: str | None = None) -> Album: ...

Аргументы

context: Event | int | None, по умолчанию None. Текущее событие либо числовой чат. None допустимо, если чат будет передан позже.
source: str | None, по умолчанию None. Источник telegram или bot; None наследует контекст у конструкторов сообщений.

Результат

Album. Создаёт альбом. Добавь от 2 до 10 совместимых вложений перед отправкой.

Права

Ошибки

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

Пример

result = app.album()

text

Создаёт текст с HTML-форматированием и отдельным представлением без разметки.

def text(value: object = '') -> Text: ...

Аргументы

value: object, по умолчанию ''. Значение преобразуется в строку с экранированием либо добавляется как Text. У code/pre всегда используется строковое представление.

Результат

Text. Создаёт текст с HTML-форматированием и отдельным представлением без разметки.

Права

Ошибки

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

Пример

result = app.text()

init

Создаёт App. Объект app уже передан ядром; не создавай второй экземпляр в рабочем модуле.

def __init__() -> None: ...

Аргументы

Нет.

Результат

None. Создаёт App. Объект app уже передан ядром; не создавай второй экземпляр в рабочем модуле.

Права

Ошибки

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

Пример

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

events

Последовательно получает события ядра порциями и выдаёт каждое событие словарём. Это асинхронный генератор, его перебирают через async for.

async def events(kind: str = 'telegram') -> AsyncIterator[EventData]: ...

Аргументы

kind: str, по умолчанию 'telegram'. Источник telegram или bot. Другой kind ядро отклоняет.

Результат

AsyncIterator[EventData]. Последовательно получает события ядра порциями и выдаёт каждое событие словарём. Это асинхронный генератор, его перебирают через async for.

Права

Нужны telegram.read для telegram; bot.read для bot; доступ зависит от kind.

Ошибки

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

Пример

async for value in app.events():
    break

request

Вызывает операцию ядра через канал процесса модуля. Контекст текущего события прикладывается автоматически. Не используй print() в этот канал.

async def request(path: str, /, **data: JSON) -> JSON: ...

Аргументы

path: str, обязательный. Путь операции ядра из ROUTES.md. Параметр только позиционный. Неизвестные операции не обходят права.
data: JSON, произвольные именованные аргументы. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.

Результат

JSON. Вызывает операцию ядра через канал процесса модуля. Контекст текущего события прикладывается автоматически. Не используй print() в этот канал.

Права

Определяются выбранной операцией, см. ROUTES.md и PERMISSIONS.md; общий канал не обходит проверки.

Ошибки

ValueError('Request is too large'): условие проверяется до продолжения операции.
asyncio.CancelledError: условие проверяется до продолжения операции.
RuntimeError('The connection to the core was lost'): условие проверяется до продолжения операции.
resources.error(result.get('error', 'error')): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

info = await app.request("core/info")

stop

Отмечает модуль для завершения основного цикла. Не завершает процесс немедленно и не отменяет уже выполняющиеся корутины.

def stop() -> None: ...

Аргументы

Нет.

Результат

None. Отмечает модуль для завершения основного цикла. Не завершает процесс немедленно и не отменяет уже выполняющиеся корутины.

Права

Ошибки

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

Пример

result = app.stop()