mirrors/karkas
0
0
Fork 0
mirror of https://gitflic.ru/project/alt-gnome/karkas.git synced 2025-10-05 12:18:28 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Рефакторинг файлов README.md и документации

Browse Source
This commit is contained in:
x1z53
2024-08-25 14:52:07 +03:00
parent 04a4ab4868
commit 5f5e851ecd
21 changed files with 349 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
docs/BLOCKS-SPEC.md Normal file
View File

@@ -0,0 +1,105 @@
# Спецификация блоков
> **Внимание!**
>
> Данная спецификация ещё не закончена и активно разрабатывается.
>
> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).
Каждый блок представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
## Метаданные блока (`info.json`)
Файл `info.json` содержит информацию о блоке в формате JSON. Пример структуры `info.json` приведён ниже:
```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](https://semver.org/) |
| `privileged` | Является ли блок привилегированным (булево значение) |
| `dependencies` | Объект, описывающий зависимости блока от других блоков |
| `dependencies.required` и `dependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — идентификатор блока, значение — версия или объект `DependencyInfo`. |
| `pythonDependencies` | Объект, описывающий зависимости блока от внешних Python пакетов. |
| `pythonDependencies.required` и `pythonDependencies.optional` | Объекты, описывающий обязательные и необязательные зависимости соответственно. Ключ — название пакета, значение — версия. |
### DependencyInfo
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов блока (`uses`). Если `uses` не указан, то доступ к блоку целиком запрещён. Пример объекта `DependencyInfo`:
```json
{
"version": "^1.0.0",
"uses": ["db_api"]
}
```
| Поле | Описание |
| :-------: | ----------------------------------- |
| `version` | Версия блока |
| `uses` | Список используемых атрибутов блока |
## Режимы работы блоков
### Непривилегированный режим (`privileged: false`)
- Исполнение блока происходит в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
- Может импортировать только явно разрешенные блоки, указанные в `pythonDependencies`, а также несколько стандартных блоков, необходимых для работы;
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
### Привилегированный режим (`privileged: true`)
- Блок исполняется без ограничений;
- Имеет полный доступ ко всем пакетам, доступным в окружении;
- Должен использоваться с осторожностью и только для блоков, требующих расширенных прав.
## Жизненный цикл блока
1. Загрузка метаданных из `info.json`;
2. Проверка зависимостей:
- Проверка всех обязательных зависимостей;
- Проверка совместимости версий зависимостей;
- Проверка зависимостей Python;
3. Загрузка кода блока из `__init__.py`;
4. Вызов функции `module_init`, если она есть;
5. После загрузки всех блоков вызывается функция `module_late_init`, если она есть.
## Межблочное взаимодейтвие
Для блоков взаимодействия друг с другом описан [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
предоставляемое системой управления блоками.
Например, можно использовать функцию `get_module` для получения блока или предоставляемых им объекты по идентификатору.

49
docs/DEV.md
View File

@@ -1,39 +1,34 @@
## Настройка рабочего окружения
# Настройка рабочего окружения
Данная инструкция поможет вам настроить рабочее окружение для разработки Karkas.
### Предварительные требования
## Предварительные требования
* **Python 3.12:** Karkas требует Python 3.12.
* **VSCode:** Рекомендуется использовать VSCode для разработки.
* **Git:** У вас должен быть установлен Git для клонирования репозитория.
- **Python** — платформа «Каркас» требует интерпретатор языка Python версии 3.12;
- **VSCode** — рекомендованная среда разработки;
- **Git** — инструмент контроля версий, необходим клонирования репозиториянео.
### Шаги
## Шаги
1. **Клонируйте репозиторий:**
```bash
git clone https://gitflic.ru/project/alt-gnome/karkas.git
```
1. Клонируйте репозиторий с помощью утилиты `git`:
2. **Откройте проект в VSCode:**
* Откройте папку `karkas` в VSCode.
* VSCode автоматически предложит открыть проект как workspace, используя файл `karkas.code-workspace`.
Нажмите "Открыть Workspace", чтобы принять предложение.
```shell
git clone https://gitflic.ru/project/alt-gnome/karkas.git
```
3. **Настройте Poetry:**
* Установите Poetry, следуя инструкциям на официальном сайте: [https://python-poetry.org/docs/](https://python-poetry.org/docs/).
* **Для каждого пакета:**
* Перейдите в папку пакета (например, `src/karkas_core`).
* Выполните команду `poetry install`, чтобы установить зависимости пакета.
* Poetry создаст виртуальное окружение внутри папки пакета (`.venv`).
2. Откройте папку `karkas` в VSCode. Среда разработки автоматически предложит открыть проект как Workspace, используя файл `karkas.code-workspace`. Нажмите `Открыть Workspace`, чтобы принять предложение;
4. **Активируйте виртуальное окружение:**
* Выполните команду `poetry shell` в папке пакета, чтобы активировать виртуальное окружение.
3. Установите инструмент Poetry, следуя инструкциям из [официальной документации](https://python-poetry.org/docs/). Для каждого пакета выполните следующую последовательность действий:
Теперь ваше рабочее окружение настроено, и вы можете начать.
- Перейдите в папку пакета (например, `src/karkas_core`);
- Выполните команду `poetry install`, чтобы установить зависимости пакета. После этого будет создано виртуальное окружене (`.venv`);
### Дополнительная информация
4. Выполните команду `poetry shell` в папке пакета, над которым будут производится работы, чтобы активировать виртуальное окружение.
* Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости.
* Poetry автоматически управляет виртуальными окружениями для каждого пакета.
* Вы можете использовать команду `poetry add <package_name>` для добавления новых зависимостей.
Теперь рабочее окружение настроено!
## Дополнительная информация
- Каждый пакет в монорепозитории имеет свой собственный файл `pyproject.toml`, где указаны его зависимости;
- Poetry автоматически управляет виртуальными окружениями для каждого пакета;
- Вы можете использовать команду `poetry add <package_name>` (где `<package_name>` — имя пакета) для добавления новых зависимостей.

107
docs/MODULES-SPEC.md
View File

@@ -1,107 +0,0 @@
# Спецификация модулей
> **Внимание!**
>
> Данная спецификация еще не закончена и активно разрабатывается.
> Могут быть значительные изменения (breaking changes).
Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.
## Метаинформация о модуле (info.json)
Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже:
```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](https://semver.org/).
- `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
- `dependencies`: Объект, описывающий зависимости модуля от других **Karkas** модулей.
- `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
- `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов.
- `required`: Обязательные зависимости. Ключ - название пакета, значение - версия.
- `optional`: Необязательные зависимости. Ключ - название пакета, значение - версия.
### DependencyInfo
Объект `DependencyInfo` позволяет указать не только версию зависимости, но и список разрешенных к использованию
атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещен.
```json
{
"version": "^1.0.0",
"uses": [
"db_api"
]
}
```
- `version`: Версия модуля.
- `uses`: Список разрешенных атрибутов модуля.
## Режимы выполнения модулей
**Непривилегированный режим** (`privileged: false`):
- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений).
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`,
а также несколько стандартных модулей, необходимых для работы.
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
**Привилегированный режим** (`privileged: true`):
- Модуль выполняется без ограничений.
- Имеет полный доступ ко всем пакетам, доступным в окружении.
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
## Жизненный цикл модуля
1. Загрузка метаданных из `info.json`.
2. Проверка зависимостей:
- Проверяется наличие всех обязательных зависимостей.
- Проверяется совместимость версий зависимостей.
- Проверяется наличие Python зависимостей.
3. Загрузка кода модуля из `__init__.py`.
4. Вызов функции `module_init` (если она есть).
5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть).
## Взаимодействие между модулями
Модули могут взаимодействовать друг с другом через [API](../src/karkas_core/karkas_core/modules_system/public_api/__init__.py),
предоставляемое системой управления модулями.
Например, есть функция `get_module`. Она позволяет получить модуль или предоставляемые им объекты по его
идентификатору.