mirror of
https://gitflic.ru/project/alt-gnome/karkas.git
synced 2025-10-05 20:37:39 +03:00
Дополнительный рефакторинг документации
This commit is contained in:
x1z53
@@ -1,4 +1,4 @@
|
||||
# Спецификация модулей
|
||||
# Спецификация блоков
|
||||
|
||||
> **Внимание!**
|
||||
>
|
||||
@@ -6,17 +6,17 @@
|
||||
>
|
||||
> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).
|
||||
|
||||
Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
|
||||
Каждый блок представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
|
||||
|
||||
## Метаданные модуля (`info.json`)
|
||||
## Метаданные блока (`info.json`)
|
||||
|
||||
Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже:
|
||||
Файл `info.json` содержит информацию о блоке в формате JSON. Пример структуры `info.json` приведён ниже:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "standard.info",
|
||||
"name": "Info",
|
||||
"description": "Модуль с информацией",
|
||||
"description": "Блок с информацией",
|
||||
"author": "Karkas Team",
|
||||
"version": "1.0.0",
|
||||
"privileged": false,
|
||||
@@ -43,22 +43,22 @@
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
| :-----------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Уникальный идентификатор модуля |
|
||||
| `name` | Название модуля |
|
||||
| `description` | Описание функциональности модуля |
|
||||
| `author` | Автор модуля |
|
||||
| `version` | Версия модуля в формате [SemVer](https://semver.org/) |
|
||||
| `privileged` | Является ли модуль привилегированным (булево значение) |
|
||||
| `dependencies` | Объект, описывающий зависимости модуля от других модулей |
|
||||
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор модуля, значение — версия или объект `DependencyInfo`. |
|
||||
| `pythonDependencies` | Объект, описывающий зависимости модуля от внешних Python пакетов. |
|
||||
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
|
||||
| Поле | Описание |
|
||||
| :-----------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Уникальный идентификатор блока |
|
||||
| `name` | Название блока |
|
||||
| `description` | Описание функциональности блока |
|
||||
| `author` | Автор блока |
|
||||
| `version` | Версия блока в формате [SemVer](https://semver.org/) |
|
||||
| `privileged` | Является ли блок привилегированным (булево значение) |
|
||||
| `dependencies` | Объект, описывающий зависимости блока от других блоков |
|
||||
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект `DependencyInfo`. |
|
||||
| `pythonDependencies` | Объект, описывающий зависимости блока от внешних Python пакетов. |
|
||||
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
|
||||
|
||||
### DependencyInfo
|
||||
|
||||
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`:
|
||||
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов блока (`uses`). Если `uses` не указан, то доступ к блоку целиком запрещён. Пример объекта `DependencyInfo`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -67,39 +67,39 @@
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Описание |
|
||||
| :-------: | ------------------------------------ |
|
||||
| `version` | Версия модуля |
|
||||
| `uses` | Список используемых атрибутов модуля |
|
||||
| Поле | Описание |
|
||||
| :-------: | ----------------------------------- |
|
||||
| `version` | Версия блока |
|
||||
| `uses` | Список используемых атрибутов блока |
|
||||
|
||||
## Режимы работы модулей
|
||||
## Режимы работы блоков
|
||||
|
||||
### Непривилегированный режим (`privileged: false`)
|
||||
|
||||
- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
|
||||
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы;
|
||||
- Исполнение блока происходит в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
|
||||
- Может импортировать только явно разрешенные блоки, указанные в `pythonDependencies`, а также несколько стандартных блоков, необходимых для работы;
|
||||
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
|
||||
|
||||
### Привилегированный режим (`privileged: true`)
|
||||
|
||||
- Модуль выполняется без ограничений;
|
||||
- Блок исполняется без ограничений;
|
||||
- Имеет полный доступ ко всем пакетам, доступным в окружении;
|
||||
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
|
||||
- Должен использоваться с осторожностью и только для блоков, требующих расширенных прав.
|
||||
|
||||
## Жизненный цикл модуля
|
||||
## Жизненный цикл блока
|
||||
|
||||
1. Загрузка метаданных из `info.json`;
|
||||
2. Проверка зависимостей:
|
||||
- Проверка всех обязательных зависимостей;
|
||||
- Проверка совместимости версий зависимостей;
|
||||
- Проверка зависимостей Python;
|
||||
3. Загрузка кода модуля из `__init__.py`;
|
||||
3. Загрузка кода блока из `__init__.py`;
|
||||
4. Вызов функции `module_init`, если она есть;
|
||||
5. После загрузки всех модулей вызывается функция `module_late_init`, если она есть.
|
||||
5. После загрузки всех блоков вызывается функция `module_late_init`, если она есть.
|
||||
|
||||
## Межмодульное взаимодейтвие
|
||||
## Межблочное взаимодейтвие
|
||||
|
||||
Для взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
|
||||
предоставляемое системой управления модулями.
|
||||
Для блоков взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
|
||||
предоставляемое системой управления блоками.
|
||||
|
||||
Например, можно использовать функцию `get_module` для получения модуля или предоставляемых им объекты по идентификатору.
|
||||
Например, можно использовать функцию `get_module` для получения блока или предоставляемых им объекты по идентификатору.
|
||||
Reference in New Issue
Block a user