Введение в разработку модулей
Note
Обязательно к прочтению на уровне L1 — одна из пяти ключевых статей в разделе "Путь чтения" на главной странице. Необходима для разработки модулей.
Следуя этой статье, вы получите запускаемый модуль, который будет отвечать на команду /hello, и узнаете структуру проекта модуля, способ регистрации и обработчики загрузки/выгрузки — все последующие документы по модулям строятся на этой основе.
Структура проекта
Стандартная структура модуля:
MyModule/
├── pyproject.toml
├── README.md
├── LICENSE
└── MyModule/
├── __init__.py
└── Core.py
Конфигурация pyproject.toml
[project]
name = "ErisPulse-MyModule"
version = "1.0.0"
description = "Описание функционала модуля"
readme = "README.md"
requires-python = ">=3.10"
license = { file = "LICENSE" }
authors = [ { name = "yourname", email = "[email protected]" } ]
dependencies = []
[project.urls]
"homepage" = "https://github.com/yourname/MyModule"
[project.entry-points."erispulse.module"]
"MyModule" = "MyModule:Main"
__init__.py
from .Core import Main
Core.py - Базовый модуль
from ErisPulse import sdk
# Рекомендуется корневой импорт (Python 3.10+): часто используемые символы импортируются напрямую из корневого пакета, но и глубокие пути по-прежнему поддерживаются
from ErisPulse import BaseModule, command
class Main(BaseModule):
def __init__(self, sdk):
self.sdk = sdk
self.logger = sdk.logger.get_child("MyModule")
self.storage = sdk.storage
@staticmethod
def get_load_strategy():
"""Возвращает стратегию загрузки модуля"""
from ErisPulse.loaders import ModuleLoadStrategy
return ModuleLoadStrategy(
lazy_load=True,
priority=0,
depends=[], # Необязательно: список модулей, от которых зависит данный модуль
# Необязательно: ленивая активация по событиям — объявите триггеры, модуль автоматически загрузится при первом совпадении события/команды
# activate_on=[{"command": {"name": "hello", "help": "Отправить приветствие"}}],
)
async def on_load(self, event):
"""Вызывается при загрузке модуля"""
@command("hello", help="Отправить приветствие")
async def hello_command(event):
name = event.get_user_nickname() or "друг"
await event.reply(f"Привет, {name}!")
self.logger.info("Модуль загружен")
async def on_unload(self, event):
"""Вызывается при выгрузке модуля"""
self.logger.info("Модуль выгружен")
Чтение конфигурации: в приведённом базовом примере конфигурация не используется. При необходимости чтения конфигурации рекомендуется объявить вложенный класс
ConfigClassи читать данные в реальном времени черезself.cfg(см. Основные концепции модуля). Старый способ — ручной вызов_load_config()— устарел.
Тестирование модуля
Локальное тестирование
# Установите модуль в директории проекта
epsdk install ./MyModule
# Запустите проект
epsdk run main.py --reload
Тестовая команда
Отправьте команду для тестирования:
/hello
Основные концепции
Базовый класс BaseModule
Все модули должны наследоваться от BaseModule, предоставляя следующие методы:
| Метод | Описание | Обязательно |
|---|---|---|
__init__(self, sdk) |
Конструктор (фреймворк передаёт экземпляр sdk) |
Нет |
get_load_strategy() |
Возвращает стратегию загрузки | Нет |
get_meta() |
Возвращает метаинформацию о модуле (необязательно) | Нет |
on_load(self, event) |
Вызывается при загрузке модуля | Да |
on_unload(self, event) |
Вызывается при выгрузке модуля | Да |
Метаинформация модуля
Note
Эта функция доступна начиная с ErisPulse 2.8.0+.
Метаинформация модуля — это описание того, для чего он предназначен, к какой категории относится и т.д. Метаинформация — это общие сведения о модуле, которые используются различными интерфейсами и экосистемными модулями, такими как модуль help, список модулей в Dashboard, магазин модулей и т.д.
Как и в случае с get_load_strategy(), возвращайте экземпляр класса ModuleMeta (с поддержкой типизации и автодополнения в IDE), но также допускается возвращать словарь:
class MyModule(BaseModule):
@staticmethod
def get_meta() -> ModuleMeta:
return ModuleMeta(
name="Погода", # Отображаемое имя (по умолчанию имя регистрации)
description="Получение погоды в городе", # Описание модуля
version="1.0.0",
author="ErisDev",
group="Инструменты", # Категория функционала
tags=["Погода", "Поиск"],
)
Совместимый способ (через словарь):
class MyModule(BaseModule):
@staticmethod
def get_meta() -> dict:
return {
"name": "Погода",
"description": "Получение погоды в городе",
"version": "1.0.0",
"author": "ErisDev",
"group": "Инструменты",
"tags": ["Погода", "Поиск"],
}
module.get_meta("MyModule")читает уже разобранные метаданные (приоритет класса > регистрационной информации, автоматически дополняет имена команд модуля).module.get_commands_overview()объединяет "метаинформацию модуля + зарегистрированные команды (псевдонимы/группы/описания)" и организует обзор всех команд по модулям.- Владелец команды можно получить через
cmd_info["owner"](автоматически вставляется контекстной системой при регистрации).
Поддержка i18n для полей метаинформации
Значения полей метаинформации могут быть простыми строками или словарями i18n {"i18n": "key.path", "default": "текст по умолчанию"} (согласно соглашению для description в конфигурации).
Ключи перевода объявляются через I18nClass, а при чтении module.get_meta() автоматически разрешаются в текст текущего языка:
class MyModule(BaseModule):
class I18nClass(BaseI18n):
meta_description: I18nKey = I18nKey(
default="Weather lookup",
zh_CN="查询城市天气",
en="Weather lookup",
)
@staticmethod
def get_meta() -> ModuleMeta:
return ModuleMeta(
name="Погода",
description={"i18n": "MyModule.meta_description", "default": "Weather lookup"},
)
Объект SDK
Доступ к основным функциям осуществляется через объект sdk:
from ErisPulse import sdk
sdk.storage # Система хранения
sdk.config # Система конфигурации
sdk.logger # Система логирования
sdk.adapter # Система адаптеров
sdk.router # Система маршрутизации
sdk.lifecycle # Система жизненного цикла
Далее
Продолжение пути обучения
- Основные концепции модуля - Глубокое понимание архитектуры модуля
- Подробное объяснение Event-обёртки - Изучение объекта Event
После написания
- Лучшие практики модуля - Разработка высококачественных модулей