mirror of
https://gitflic.ru/project/alt-gnome/karkas.git
synced 2025-10-05 20:37:39 +03:00
Рефакторинг файлов README.md и документации
This commit is contained in:
x1z53
49
docs/DEV.md
49
docs/DEV.md
@@ -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>` — имя пакета) для добавления новых зависимостей.
|
||||
|
||||
@@ -2,14 +2,15 @@
|
||||
|
||||
> **Внимание!**
|
||||
>
|
||||
> Данная спецификация еще не закончена и активно разрабатывается.
|
||||
> Могут быть значительные изменения (breaking changes).
|
||||
> Данная спецификация ещё не закончена и активно разрабатывается.
|
||||
>
|
||||
> Могут возникнуть изменения, которые не будут обратно совместимы (breaking changes).
|
||||
|
||||
Каждый модуль представлен в виде папки, содержащей два обязательных файла: info.json и `__init__.py`.
|
||||
Каждый модуль представлен в виде папки, содержащей два обязательных файла: `info.json` и `__init__.py`.
|
||||
|
||||
## Метаинформация о модуле (info.json)
|
||||
## Метаданные модуля (`info.json`)
|
||||
|
||||
Этот файл содержит метаинформацию о модуле в формате JSON. Пример структуры info.json приведен ниже:
|
||||
Файл `info.json` содержит информацию о модуле в формате JSON. Пример структуры `info.json` приведён ниже:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -24,9 +25,7 @@
|
||||
"standard.roles": "^1.0.0",
|
||||
"standard.database": {
|
||||
"version": "^1.0.0",
|
||||
"uses": [
|
||||
"db_api"
|
||||
]
|
||||
"uses": ["db_api"]
|
||||
}
|
||||
},
|
||||
"optional": {
|
||||
@@ -44,64 +43,63 @@
|
||||
}
|
||||
```
|
||||
|
||||
- `id`: Уникальный идентификатор модуля.
|
||||
- `name`: Название модуля.
|
||||
- `description`: Описание функциональности модуля.
|
||||
- `author`: Автор модуля.
|
||||
- `version`: Версия модуля в формате [SemVer](https://semver.org/).
|
||||
- `privileged`: Булево значение, указывающее, является ли модуль привилегированным.
|
||||
- `dependencies`: Объект, описывающий зависимости модуля от других **Karkas** модулей.
|
||||
- `required`: Обязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
|
||||
- `optional`: Необязательные зависимости. Ключ - идентификатор модуля, значение - версия или объект `DependencyInfo`.
|
||||
- `pythonDependencies`: Объект, описывающий зависимости модуля от внешних Python пакетов.
|
||||
- `required`: Обязательные зависимости. Ключ - название пакета, значение - версия.
|
||||
- `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` позволяет указать не только версию зависимости, но и список доступных к использованию атрибутов модуля (`uses`). Если `uses` не указан, то доступ к модулю целиком запрещён. Пример объекта `DependencyInfo`:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "^1.0.0",
|
||||
"uses": [
|
||||
"db_api"
|
||||
]
|
||||
"uses": ["db_api"]
|
||||
}
|
||||
```
|
||||
|
||||
- `version`: Версия модуля.
|
||||
- `uses`: Список разрешенных атрибутов модуля.
|
||||
| Поле | Описание |
|
||||
| :-------: | ------------------------------------ |
|
||||
| `version` | Версия модуля |
|
||||
| `uses` | Список используемых атрибутов модуля |
|
||||
|
||||
## Режимы выполнения модулей
|
||||
## Режимы работы модулей
|
||||
|
||||
**Непривилегированный режим** (`privileged: false`):
|
||||
- Модуль выполняется в доверенной среде на основе RestrictedPython (это накладывает ряд ограничений).
|
||||
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`,
|
||||
а также несколько стандартных модулей, необходимых для работы.
|
||||
### Непривилегированный режим (`privileged: false`)
|
||||
|
||||
- Модуль выполняется в доверенной среде на основе `RestrictedPython`, что накладывает ряд ограничений;
|
||||
- Может импортировать только явно разрешенные модули, указанные в `pythonDependencies`, а также несколько стандартных модулей, необходимых для работы;
|
||||
- Имеет доступ к пакету `karkas_core.modules_system.public_api` для взаимодействия с ботом.
|
||||
|
||||
**Привилегированный режим** (`privileged: true`):
|
||||
- Модуль выполняется без ограничений.
|
||||
- Имеет полный доступ ко всем пакетам, доступным в окружении.
|
||||
### Привилегированный режим (`privileged: true`)
|
||||
|
||||
- Модуль выполняется без ограничений;
|
||||
- Имеет полный доступ ко всем пакетам, доступным в окружении;
|
||||
- Должен использоваться с осторожностью и только для модулей, требующих расширенных прав.
|
||||
|
||||
## Жизненный цикл модуля
|
||||
|
||||
1. Загрузка метаданных из `info.json`.
|
||||
1. Загрузка метаданных из `info.json`;
|
||||
2. Проверка зависимостей:
|
||||
- Проверяется наличие всех обязательных зависимостей.
|
||||
- Проверяется совместимость версий зависимостей.
|
||||
- Проверяется наличие Python зависимостей.
|
||||
3. Загрузка кода модуля из `__init__.py`.
|
||||
4. Вызов функции `module_init` (если она есть).
|
||||
5. После загрузки всех модулей вызывается функция `module_late_init` (если она есть).
|
||||
- Проверка всех обязательных зависимостей;
|
||||
- Проверка совместимости версий зависимостей;
|
||||
- Проверка зависимостей Python;
|
||||
3. Загрузка кода модуля из `__init__.py`;
|
||||
4. Вызов функции `module_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