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

Справочник SDK

Здесь описаны публичные методы, свойства, конструкторы и протоколы объектов Cluster. Сигнатуры сверяются с исходниками. Для каждого метода указаны аргументы, результат, права, ошибки и пример.

Первый модуль · Типы и ошибки · Bot API и Telethon

Как читать справочник

app и loader передаются модулю при загрузке. Не создавай второй App: он использует тот же канал связи с ядром. Код с await выполняется внутри асинхронного обработчика. В примерах ctx является текущим Event; остальные необходимые объекты названы перед вызовом.

Сигнатуры описывают допустимые значения на уровне SDK; они не добавляют новые импорты или проверки типов в сам Python-код. JSON, Path, FileInfo и другие обозначения раскрыты в разделе типов. Результат Self означает тот же объект. Изменения локального объекта отправляются только вызовом, у которого указаны права ядра.

Вызовы ядра дополнительно проверяют состояние юзербота, подписку, ограничения ресурсов, доступ действующего пользователя и всю цепочку вызовов модулей. Указанное право должно быть объявлено и выдано. Права с окончанием .full могут заменять частные права в своей группе, но не отменяют остальные проверки.

Объекты

• app.db: Короткие запросы к данным и фабрики разделов, записей и транзакционных пакетов.
• app.web: HTTPS и WSS через сетевую службу ядра. Настройки профиля и ограничения разделены по экземплярам модулей.
• app.client: Методы подключённого Telegram-аккаунта. Ответы проходят сериализацию ядра; это не живые объекты Telethon.
• app.bot: Методы личного бота юзербота. Для общих вызовов используй bot.api или invoke(); токен остаётся в ядре.
• app.inline: Формы с зарегистрированными кнопками и локальные конструкторы клавиатуры.
• app.core: Сведения о юзерботе, настройки ядра, конфигурация и алиасы команд экземпляров.
• app.config: Чтение собственной конфигурации и объявление её полей.
• app.ui: Объявление элементов страницы модуля и чтение или запись их значений.
• app.files: Хранилище файлов экземпляра и загрузка частями. Путь на сервере не раскрывается.
• app.tasks: Постановка задач своего экземпляра и управление их выполнением.
• app.modules: Вызовы объявленных функций и сигналов зависимостей. Полный доступ вызывающего не передаётся автоматически.
• app.exchange: Договоры обмена между профилями юзерботов. Запрос должен быть одобрен получателем и активирован работающими экземплярами.
• app.requests: Адреса входящих HTTP-запросов к обработчикам loader.request. Bearer-токен является секретом.
• app.logs: Запись событий в журнал. Дополнительные JSON-поля добавляются к сообщению.
• app.images: Фабрика сцен и клиент модуля Image Generator. Сам SDK не содержит растровый движок.
• app: Точка входа в SDK. Содержит службы ядра и фабрики объектов.
• Namespace: Динамические имена Bot API и TL-схемы. Все параметры сгенерированных методов передаются по имени.
• Layer: Один слой сцены. Изменения применяются локально; полная проверка геометрии и стилей происходит в Canvas.build().
• Container: Общие операции холста и группы. Порядок layers задаёт наложение, координаты элементов относительны контейнеру.
• Group: Слой, который одновременно является контейнером дочерних слоёв. Геометрия группы хранится в её описании.
• Canvas: Корневая сцена: размеры 1..2048, не более двух миллионов пикселей, 128 слоёв и 6 уровней вложенности.
• Form: Отправленная форма с текстом, медиа, зарегистрированными кнопками и локальным состоянием. Изменения отдельных кнопок сразу обновляют сообщение.
• Pages: Локальная пагинация списка. Создаёт данные и клавиатуру, но сама ничего не отправляет.
• Button: Одна кнопка с постоянным key, текстом, обработчиком и признаками видимости и доступности.
• Keyboard: Упорядоченные строки кнопок: не более 16 строк и 8 кнопок в каждой. Ключи кнопок уникальны.
• Media: Вложение из файла Cluster или bytes. Поддерживает photo, video, animation, audio, document, voice и video_note; gif нормализуется в animation.
• Album: Альбом из 2..10 элементов. Можно сочетать фото и видео либо отправить только аудио или только документы.
• Message: Сообщение с текстом, вложением и клавиатурой. Отслеживает ID, источник и состояние отправки.
• Text: HTML-текст с экранированием обычных значений и подсчётом длины в UTF-16.
• loader: Декораторы объявляют интерфейс класса Module. Само объявление не выдаёт прав ядра.
• Record: Версионированная запись базы. load() получает исходное состояние; save() и delete() сверяют ревизию.
• Batch: Атомарная запись нескольких ключей своего раздела. Один ключ разрешено включить только один раз.
• Scope: Раздел базы с префиксом и выбранным экземпляром. Префикс добавляется к ключу без разделителя.
• SDKError: Базовая ошибка SDK. code содержит машинный код, retry_after задержку при flood либо None.
• AccessDenied: Ошибка доступа: право не выдано или действие выходит за ограничения.
• Conflict: Ревизия или состояние изменились одновременно с другим действием.
• InvalidInput: Неверные аргументы запроса ядра.
• InvalidState: Действие недоступно при текущем состоянии объекта или службы.
• QuotaExceeded: Превышена квота юзербота или модуля.
• Unavailable: Запрошенная служба или участник сейчас недоступны.
• FloodWait: Ограничение частоты Telegram. retry_after содержит задержку, если она известна.
• error(): Фабрика исключений app.errors.error(value). Возвращает исключение, но сама его не выбрасывает.
• File: Готовый или загружаемый файл Cluster. Методы с побочным эффектом выполняются через ядро.
• Writer: Поток загрузки. open() резервирует размер; finish() проверяет записанный объём и контрольную сумму.
• Asset: Временный ресурс изображения в выбранном генераторе. Это не файл Cluster.
• Drawing: Передача ресурсов и растеризация сцены через установленный модуль Image Generator.
• Journal: Запись событий в журнал. Дополнительные JSON-поля добавляются к сообщению.
• Timer: Измерение длительности блока и запись в журнал. elapsed доступен после выхода.
• EventStream: Чтение событий с локальным буфером. dropped накапливает число событий, потерянных в очереди ядра.
• Call: Подготовленный вызов функции другого модуля. Не повторяет отправку после неизвестного результата запуска.
• Module: Выбранная зависимость и профиль её экземпляра. Функции и сигналы должны быть объявлены получателем.
• Agreement: Снимок договора обмена. Передача допустима только при активном договоре и доступных участниках.
• ExchangeRequest: Подготовленный запрос обмена конкретным ресурсом. Не даёт доступ до одобрения получателем.
• Endpoint: Входящий HTTP-адрес обработчика. Токен не сохраняй в публичных сообщениях и журнале.
• Element: Описание элемента страницы. Данные страницы хранятся отдельно от описания.
• PageDefinition: Объявление страницы модуля с упорядоченными элементами, не более 64.
• Table: Локальное редактирование таблицы Page. Для сохранения изменений вызови page.save().
• Page: Значения объявленной страницы. save() отправляет весь снимок с проверкой ревизии.
• Field: Описание одного поля конфигурации. Окончательная проверка описания выполняется в build().
• Fields: Упорядоченная схема конфигурации, не более 64 полей.
• Settings: Редактируемый снимок настроек ядра, конфигурации или алиасов. secret и file через этот объект не изменяются.
• ConfigView: Снимок доступных значений собственной конфигурации. Унаследованные изменения Document остаются локальными.
• Schedule: Подготовка задачи. Время выбирается через at() либо after(); повторение и повторы при ошибке задаются отдельно.
• Task: Состояние и управление созданной задачей. Изменения параметров сверяют ревизию.
• Document: Изолированная JSON-копия с вложенными путями. Методы изменения возвращают тот же объект, сохранение не выполняется.
• Response: HTTP-ответ с кодом, заголовками и телом. 4xx и 5xx доступны без исключения до raise_for_status().
• Request: Подготовленный HTTP-запрос. Изменения локальные; send(), download() и upload() обращаются к ядру.
• Session: Базовый URL и общие заголовки запросов. Объект не является отдельным сетевым профилем ядра.
• Socket: Объект WSS-соединения. Перед отправкой и получением вызови open() или используй async with.
• Event: Контекст команды, кнопки, задачи или другого обработчика. Поля зависят от источника события.

Покрытие

Описано классов: 69; отдельно описана фабрика ошибок. Собственных методов, свойств и протоколов: 521. Унаследованные методы ведут к описанию класса, где они определены.

python scripts/sdk_reference.py --check
python scripts/check_docs.py

Проверка сравнивает состав классов и методов, параметры, реализацию, полноту полей справочника, синтаксис примеров и совместимость вызовов с сигнатурами. Она также проверяет, что страницы собраны из актуальных описаний. При изменении поведения нужно пересмотреть соответствующую запись contracts.json, затем пересобрать справочник. Прохождение проверки не заменяет тестирование поведения и ручную проверку смысла описаний.