Спецификация блоков

Внимание!

Данная спецификация ещё не закончена и активно разрабатывается.

Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).

Каждый блок представлен в виде папки, содержащей два обязательных файла: info.json и __init__.py.

Метаданные блока (`info.json`)

Файл info.json содержит информацию о блоке в формате JSON. Пример структуры info.json приведён ниже:

{
  "id": "standard.info",
  "name": "Info",
  "description": "Блок с информацией",
  "author": "Karkas Team",
  "version": "1.0.0",
  "privileged": false,
  "dependencies": {
    "required": {
      "standard.roles": "^1.0.0",
      "standard.database": {
        "version": "^1.0.0",
        "uses": ["db_api"]
      }
    },
    "optional": {
      "external.yandexgpt": "*"
    }
  },
  "pythonDependencies": {
    "required": {
      "some_package": "^1.2.3"
    },
    "optional": {
      "another_package": "*"
    }
  }
}

Поле	Описание
`id`	Уникальный идентификатор блока
`name`	Название блока
`description`	Описание функциональности блока
`author`	Автор блока
`version`	Версия блока в формате SemVer
`privileged`	Является ли блок привилегированным (булево значение)
`dependencies`	Объект, описывающий зависимости блока от других блоков
`dependencies.required` и `dependencies.optional`	Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект `DependencyInfo`.
`pythonDependencies`	Объект, описывающий зависимости блока от внешних Python пакетов.
`pythonDependencies.required` и `pythonDependencies.optional`	Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия.

DependencyInfo

Объект DependencyInfo позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов блока (uses). Если uses не указан, то доступ к блоку целиком запрещён. Пример объекта DependencyInfo:

{
  "version": "^1.0.0",
  "uses": ["db_api"]
}

Поле	Описание
`version`	Версия блока
`uses`	Список используемых атрибутов блока

Режимы работы блоков

Непривилегированный режим (`privileged: false`)

Исполнение блока происходит в доверенной среде на основе RestrictedPython, что накладывает ряд ограничений;
Может импортировать только явно разрешенные блоки, указанные в pythonDependencies, а также несколько стандартных блоков, необходимых для работы;
Имеет доступ к пакету karkas_core.modules_system.public_api для взаимодействия с ботом.

Привилегированный режим (`privileged: true`)

Блок исполняется без ограничений;
Имеет полный доступ ко всем пакетам, доступным в окружении;
Должен использоваться с осторожностью и только для блоков, требующих расширенных прав.

Жизненный цикл блока

Загрузка метаданных из info.json;
Проверка зависимостей:
- Проверка всех обязательных зависимостей;
- Проверка совместимости версий зависимостей;
- Проверка зависимостей Python;
Загрузка кода блока из __init__.py;
Вызов функции module_init, если она есть;
После загрузки всех блоков вызывается функция module_late_init, если она есть.

Межблочное взаимодейтвие

Для блоков взаимодействия друг с другом описан API, предоставляемое системой управления блоками.

Например, можно использовать функцию get_module для получения блока или предоставляемых им объекты по идентификатору.

7.2 KiB Raw Permalink Blame History Unescape Escape

Спецификация блоков

Метаданные блока (info.json)