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

Form

Отправленная форма с текстом, медиа, зарегистрированными кнопками и локальным состоянием. Изменения отдельных кнопок сразу обновляют сообщение.

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

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

form = app.inline(ctx)

Для load() у form уже есть ID; для edit/update/close и изменения кнопок форма уже отправлена. Для методов кнопок существует key="open".

init

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

def __init__(inline: Inline, context: Event | int | None = None, id: str | None = None) -> None: ...

Аргументы

inline: Inline, обязательный. Служба форм текущего приложения.
context: Event | int | None, по умолчанию None. Текущее событие либо числовой чат. None допустимо, если чат будет передан позже.
id: str | None, по умолчанию None. Идентификатор объекта, полученный при его создании. Не путь сервера.

Результат

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

Права

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

Ошибки

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

Пример

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

message_id

Возвращает ID сообщения из локальных данных либо None до отправки или загрузки.

def message_id() -> int | None: ...

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

Аргументы

Нет.

Результат

int | None. Возвращает ID сообщения из локальных данных либо None до отправки или загрузки.

Права

Ошибки

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

Пример

value = form.message_id

button

Возвращает кнопку по key; перед доступом к существующей неизвестной форме нужен load().

def button(key: str) -> Button: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

Button. Возвращает кнопку по key; перед доступом к существующей неизвестной форме нужен load().

Права

Ошибки

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

Пример

result = form.button("open")

load

Загружает текст, медиа, кнопки, параметры и ID сообщения существующей формы.

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

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Загружает текст, медиа, кнопки, параметры и ID сообщения существующей формы.

Права

Нужны bot.send; telegram.send дополнительно для отправки через via="inline". files.read при медиа; ограничения chats/users и доступ callback продолжают действовать. Для чужих файлов своего юзербота дополнительно files.full либо отдельное разрешение конфигурационного файла на чтение.

Ошибки

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

Пример

result = await form.load()

form

Отправляет новую форму один раз, сохраняет ID и помещает её в локальный кэш inline.units.

async def form(data: JSON = None, **kwargs: JSON) -> Self: ...

Аргументы

data: JSON, по умолчанию None. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.
kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: chat, text, keyboard/buttons, media, ttl, users, receiver, replace, method, options, via и параметры отправки. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

Self. Тот же объект после успешной операции. Отправляет новую форму один раз, сохраняет ID и помещает её в локальный кэш inline.units.

Права

Ошибки

ValueError('The form has already been sent'): условие проверяется до продолжения операции.
ValueError('A form chat is required'): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await form.form(text="Ready", chat=ctx.chat_id)

edit

Обновляет текст, клавиатуру, медиа и параметры активной формы. Превратить форму с медиа в текстовую этим методом нельзя.

async def edit(data: JSON = None, **kwargs: JSON) -> Self: ...

Аргументы

data: JSON, по умолчанию None. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.
kwargs: JSON, произвольные именованные аргументы. Допустимые именованные параметры: text, keyboard/buttons, media, options и параметры редактирования. Точные типы и исходные значения низкоуровневых операций приведены в разделе типов и ROUTES.md.

Результат

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

Права

Ошибки

ValueError('The form is not active'): условие проверяется до продолжения операции.
ValueError('A media form cannot be changed into a text form; create another form'): условие проверяется до продолжения операции.
error(result['error']): условие проверяется до продолжения операции.
Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await form.edit(text="Updated")

update

Отправляет текущее локальное состояние активной формы.

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

Аргументы

Нет.

Результат

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

Права

Ошибки

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

Пример

result = await form.update()

close

Удаляет активную форму и убирает её из локального кэша.

async def close() -> bool: ...

Аргументы

Нет.

Результат

bool. Удаляет активную форму и убирает её из локального кэша.

Права

Ошибки

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

Пример

result = await form.close()

drop_button

Удаляет кнопку по key и сразу обновляет форму.

async def drop_button(key: str) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

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

Права

Ошибки

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

Пример

result = await form.drop_button("open")

rename_button

Меняет подпись кнопки по key и сразу обновляет форму.

async def rename_button(key: str, text: str | Text) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.
text: str | Text, обязательный. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).

Результат

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

Права

Ошибки

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

Пример

result = await form.rename_button("open", "Ready")

hide_button

Скрывает кнопку по key и сразу обновляет форму.

async def hide_button(key: str) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

Self. Тот же объект после успешной операции. Скрывает кнопку по key и сразу обновляет форму.

Права

Ошибки

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

Пример

result = await form.hide_button("open")

show_button

Показывает кнопку по key и сразу обновляет форму.

async def show_button(key: str) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

Self. Тот же объект после успешной операции. Показывает кнопку по key и сразу обновляет форму.

Права

Ошибки

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

Пример

result = await form.show_button("open")

disable_button

Отключает кнопку по key и сразу обновляет форму.

async def disable_button(key: str) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

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

Права

Ошибки

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

Пример

result = await form.disable_button("open")

enable_button

Включает кнопку по key и сразу обновляет форму.

async def enable_button(key: str) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.

Результат

Self. Тот же объект после успешной операции. Включает кнопку по key и сразу обновляет форму.

Права

Ошибки

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

Пример

result = await form.enable_button("open")

move_button

Перемещает кнопку по key в выбранную строку и сразу обновляет форму.

async def move_button(key: str, row: int, index: int = 0) -> Self: ...

Аргументы

key: str, обязательный. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.
row: int, обязательный. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.
index: int, по умолчанию 0. Позиция от нуля в указанном списке или строке. Допустимые границы проверяются методом.

Результат

Self. Тот же объект после успешной операции. Перемещает кнопку по key в выбранную строку и сразу обновляет форму.

Права

Ошибки

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

Пример

result = await form.move_button("open", 0)

sort_buttons

Сортирует кнопки и сразу обновляет форму; параметры соответствуют Keyboard.sort().

async def sort_buttons(key: Callable | None = None, reverse: bool = False, per_row: bool = False) -> Self: ...

Аргументы

key: Callable | None, по умолчанию None. Синхронный ключ сортировки. None использует правило класса; вызывается для каждого элемента.
reverse: bool, по умолчанию False. Логический переключатель указанного действия.
per_row: bool, по умолчанию False. Логический переключатель указанного действия.

Результат

Self. Тот же объект после успешной операции. Сортирует кнопки и сразу обновляет форму; параметры соответствуют Keyboard.sort().

Права

Ошибки

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

Пример

result = await form.sort_buttons()

answer

Передаёт ответ на callback через сохранённый контекст события.

async def answer(text: str | Text = '', alert: bool = False) -> JSON: ...

Аргументы

text: str | Text, по умолчанию ''. Текст или собранный Text там, где поддерживается преобразование. В короткие методы клиента передавай str(Text).
alert: bool, по умолчанию False. Логический переключатель указанного действия.

Результат

JSON. Передаёт ответ на callback через сохранённый контекст события.

Права

Контекст действующего callback; полномочия кнопки и её отправителя проверяет ядро.

Ошибки

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

Пример

result = await form.answer()