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

Внимание!

Данная спецификация еще не закончена и активно разрабатывается. Могут быть значительные изменения (breaking changes).

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

Метаинформация о модуле (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: Объект, описывающий зависимости модуля от других Karkas модулей.
- required: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект DependencyInfo.
- optional: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект DependencyInfo.
pythonDependencies: Объект, описывающий зависимости модуля от внешних Python пакетов.
- required: Обязательные зависимости. Ключ - название пакета, значение - версия.
- optional: Необязательные зависимости. Ключ - название пакета, значение - версия.

DependencyInfo

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

{
  "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. Она позволяет получить модуль или предоставляемые им объекты по его идентификатору.

5.4 KiB Raw Blame History Unescape Escape