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

Button

Одна кнопка с постоянным key, текстом, обработчиком и признаками видимости и доступности.

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

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

button = app.inline.button("Open", key="open")

Для move() button уже включена в keyboard; key остаётся постоянным при изменении подписи.

__init__

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

def __init__(text: ButtonLabel, callback: str | Callable | None = None, *, key: str | None = None, values: JSON = None, args: JSON | tuple[JSON, ...] | None = None, visible: bool = True, enabled: bool = True, **options: JSON) -> None: ...

Аргументы

• text: ButtonLabel, обязательный. Непустая строка либо callable без аргументов или с Form. Результат может быть awaitable и должен дать непустую строку.
• callback: str | Callable | None, по умолчанию None. ID объявленного обработчика либо метод с соответствующим декоратором loader.
• key: str | None, по умолчанию None. Постоянный уникальный ключ кнопки, не её подпись. None у конструктора генерирует UUID.
• values: JSON, по умолчанию None. Данные выбранной операции. Форма и ограничения описаны ниже; передаваемые JSON-значения копируются.
• args: JSON | tuple[JSON, ...] | None, по умолчанию None. Аргументы обработчика по схеме полей: словарь либо позиционные значения. Для позиционных значений требуется объявленный callable.
• visible: bool, по умолчанию True. Логический переключатель указанного действия.
• enabled: bool, по умолчанию True. Логический переключатель указанного действия.
• options: JSON, произвольные именованные аргументы. Параметры выбранного метода Telegram или Bot API. Для выделенных методов допустимы только перечисленные в TYPES.md поля; полный запрос использует каталог NATIVE.md. Параметры не обходят ограничения прав.

Результат

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

Права

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

Ошибки

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

Пример

# Обычный способ получения объекта:
button = app.inline.button("Open", key="open")

rename

Меняет подпись кнопки локально. Для отправленной формы затем вызови update().

def rename(text: ButtonLabel) -> Self: ...

Аргументы

• text: ButtonLabel, обязательный. Непустая строка либо callable без аргументов или с Form. Результат может быть awaitable и должен дать непустую строку.

Результат

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

Права

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

Ошибки

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

Пример

result = button.rename("Open")

hide

Скрывает кнопку в локальном описании, сохраняя её место и обработчик.

def hide() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Скрывает кнопку в локальном описании, сохраняя её место и обработчик.

Права

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

Ошибки

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

Пример

result = button.hide()

show

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

def show() -> Self: ...

Аргументы

Нет.

Результат

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

Права

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

Ошибки

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

Пример

result = button.show()

disable

Отключает кнопку локально; при обновлении формы ядро не выполняет отключённый обработчик.

def disable() -> Self: ...

Аргументы

Нет.

Результат

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

Права

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

Ошибки

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

Пример

result = button.disable()

enable

Включает кнопку локально.

def enable() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Включает кнопку локально.

Права

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

Ошибки

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

Пример

result = button.enable()

remove

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

def remove() -> Self: ...

Аргументы

Нет.

Результат

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

Права

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

Ошибки

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

Пример

result = button.remove()

move

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

def move(row: int, index: int = 0) -> Self: ...

Аргументы

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

Результат

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

Права

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

Ошибки

• ValueError('The button does not belong to a keyboard'): условие проверяется до продолжения операции.

Пример

result = button.move(0)

render

Вычисляет подпись, при необходимости ожидает её результат, проверяет декоратор callback и собирает JSON-описание кнопки.

async def render(form: Form | None) -> dict[str, JSON]: ...

Аргументы

• form: Form | None, обязательный. Контекст формы для вычисления динамических подписей кнопок.

Результат

dict[str, JSON]. Вычисляет подпись, при необходимости ожидает её результат, проверяет декоратор callback и собирает JSON-описание кнопки.

Права

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

Ошибки

• ValueError('Button text is required'): условие проверяется до продолжения операции.
• ValueError('Use a method declared with loader.callback'): условие проверяется до продолжения операции.
• ValueError('Named callbacks use values instead of positional arguments'): условие проверяется до продолжения операции.
• ValueError('Callback arguments do not match its fields'): условие проверяется до продолжения операции.

Пример

result = await button.render(None)