Спецификация модулей

Внимание!

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

Могут возникнуть изменения, которые не будут обратно совместимы (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.3 KiB Raw Blame History Unescape Escape

Спецификация модулей

Метаданные модуля (info.json)