API основных модулей
Tip
Когда следует читать эту статью: когда вам нужно использовать основные возможности, такие как хранилище, конфигурация, логирование, управление модулями, маршрутизация, HTTP-клиент и т.д., и вы не помните точные сигнатуры методов, обратитесь к этой статье для быстрого ознакомления. Если не нужно, пропустите.
Документация предоставляет быструю справочную информацию по API основных модулей ErisPulse, включая сигнатуры методов и краткие пояснения. Для подробного использования и примеров щелкните по ссылкам "Полная документация" для каждого модуля.
Модуль Storage
Система хранения пар ключ-значение на основе настраиваемого бэкенда (SQLite/MySQL/PostgreSQL), поддерживающая общие SQL-цепные запросы, бэкенд можно переключить одним кликом, подробнее см. Хранилище бэкендов.
Основные операции
from ErisPulse import sdk
sdk.storage.set("key", "value")
value = sdk.storage.get("key", default_value)
keys = sdk.storage.keys()
sdk.storage.delete("key")
Пакетные операции
sdk.storage.set_multi({"key1": "val1", "key2": "val2"})
values = sdk.storage.get_multi(["key1", "key2"])
sdk.storage.delete_multi(["key1", "key2"])
Транзакционные операции
with sdk.storage.transaction():
sdk.storage.set("key1", "value1")
sdk.storage.set("key2", "value2")
Доступ по свойствам
sdk.storage.my_key # эквивалентно sdk.storage.get("my_key")
sdk.storage.my_key = "val" # эквивалентно sdk.storage.set("my_key", "val")
SQL-цепные запросы
Модуль Storage предоставляет гибкий API для построения SQL-запросов в стиле цепных вызовов, поддерживающий CRUD-операции для пользовательских таблиц.
sdk.storage.CreateTable("users", {
"id": "INTEGER PRIMARY KEY AUTOINCREMENT",
"name": "TEXT NOT NULL",
})
sdk.storage.Table("users").Insert({"name": "Alice"}).Execute()
rows = sdk.storage.Table("users").Select("name").Where("id > ?", 0).Execute()
Полный API цепных SQL-запросов (Select/Insert/Update/Delete/Where/OrderBy/Limit, AlterTable, транзакции и т.д.) см. в SQL-построителе запросов.
Абстракция хранилища бэкендов
StorageManager наследуется от абстрактного базового класса BaseStorage, поддерживает расширение другими хранилищами (Redis, MySQL и т.д.).
from ErisPulse.Core.Bases.storage import BaseStorage, BaseQueryBuilder
Асинхронный интерфейс
Модули Storage и Config предоставляют асинхронные методы (префикс a): асинхронные методы являются основными, синхронные методы являются совместимыми слоем (внутренне мостятся к фоновому циклу событий для выполнения). Существующий синхронный код не требует изменений; новые коды в асинхронных обработчиках следует использовать асинхронные методы.
# Асинхронное хранилище
value = await sdk.storage.aget("key")
await sdk.storage.aset("key", "value")
await sdk.storage.adelete("key")
keys = await sdk.storage.aget_all_keys()
await sdk.storage.aclear()
# Асинхронные пакетные операции
values = await sdk.storage.aget_multi(["k1", "k2"])
await sdk.storage.aset_multi({"k1": "v1", "k2": "v2"})
await sdk.storage.adelete_multi(["k1", "k2"])
# Асинхронная конфигурация
value = await sdk.config.agetConfig("MyModule.key")
await sdk.config.asetConfig("MyModule.key", "value")
await sdk.config.aforce_save()
await sdk.config.areload()
Модуль Config
Управление конфигурационными файлами в формате TOML, поддерживает ключевые пути с разделением точками.
Обзор API
| Метод | Описание |
|---|---|
getConfig(key, default) |
Чтение конфигурации, поддерживает пути с точками, например "MyModule.subkey" |
getAllConfig() |
Полный снимок конфигурации (глубокая копия, включая незаписанные значения) |
setConfig(key, value, immediate=False) |
Запись конфигурации. immediate=True немедленно сохраняет в файл |
delConfig(key, immediate=False) |
Удаление ключа конфигурации (в отличие от установки в пустое значение), удаляет из файла; вызывает событие config.set (new_value=None) |
force_save() |
Принудительное сохранение конфигурации из памяти в файл |
reload() |
Перезагрузка конфигурации из файла |
agetConfig(key, default) |
Асинхронное чтение конфигурации |
agetAllConfig() |
Асинхронный получение полного снимка конфигурации |
asetConfig(key, value, immediate) |
Асинхронная запись конфигурации |
adelConfig(key, immediate) |
Асинхронное удаление ключа конфигурации (поведение аналогично delConfig) |
aforce_save() |
Асинхронное принудительное сохранение |
areload() |
Асинхронная перезагрузка |
Примеры
config = sdk.config.getConfig("MyModule", {})
value = sdk.config.getConfig("MyModule.timeout", 30)
snapshot = sdk.config.getAllConfig() # Полный снимок (глубокая копия)
sdk.config.delConfig("MyModule.deprecated") # Удаление ключа (отложенная запись)
sdk.config.setConfig("MyModule", {"key": "value"})
sdk.config.setConfig("MyModule.timeout", 60, immediate=True)
# Асинхронный интерфейс (в асинхронных обработчиках предпочтительно использовать)
snapshot = await sdk.config.agetAllConfig()
await sdk.config.adelConfig("MyModule.deprecated") # Асинхронное удаление ключа
setConfigпо умолчанию использует отложенную запись (каждые 5 секунд пакетное сохранение), установкаimmediate=Trueнемедленно сохраняет в конфигурационный файл. Изменения конфигурации вызывают событие жизненного циклаconfig.set.deleteтакже поддерживает отложенную запись и событиеconfig.set(new_value=None), существующие слушателиon_config_updateбез изменений могут обнаруживать удаление.
Модуль Logger
Модульная система логирования, основанная на Rich, поддерживает под-логгеры и контроль на уровне модуля.
Основное использование
sdk.logger.debug("Отладочная информация")
sdk.logger.info("Информация о работе")
sdk.logger.warning("Предупреждение")
sdk.logger.error("Ошибка")
sdk.logger.critical("Критическая ошибка")
Под-логгеры
child_logger = sdk.logger.get_child("MyModule")
child_logger.info("Лог под-модуля")
child_logger.get_child("utils") # Поддержка вложенности
Управление уровнем логирования
sdk.logger.set_level("DEBUG") # Глобальный уровень
sdk.logger.set_module_level("MyModule", "DEBUG") # Уровень на уровне модуля
# Поддерживаемые уровни (от низкого к высокому):
# TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
# TRACE - самый низкий уровень, выводит подробную отладочную информацию (распределение событий, регистрация маршрутов и т.д.)
sdk.logger.set_level("TRACE") # Включить все логи
Подписка на логи (режим push)
Для модулей, таких как Dashboard, для получения структурированных логов в реальном времени, поддерживаются фильтрация по уровню и историческое восстановление.
Явная подписка на низкий уровень логирования: подписчик может иметь
min_levelниже глобального уровня логирования. В этом случае логи низкого уровня отправляются только соответствующему подписчику, не выводятся в консоль и не записываются в память, чтобы избежать загрязнения основного потока логов.# Глобально INFO, но можно отдельно подписаться на DEBUG логи @sdk.logger.handler("debug-tracer", min_level="DEBUG") def on_debug(log_data: dict): ...
# Способ декоратора
@sdk.logger.handler("my-handler", min_level="INFO")
def on_log(log_data: dict):
# log_data = {
# "timestamp": "2026-06-29T22:00:00.123456",
# "level": "WARNING", "level_num": 30,
# "module": "ErisPulse.Core.adapter",
# "message": "Строгий режим:...",
# }
pass
# Прямой вызов
sdk.logger.handler("my-handler", min_level="INFO")(on_log)
sdk.logger.remove_handler("my-handler")
| Метод | Описание |
|---|---|
handler(id, *, min_level)(func) |
Декоратор/прямой вызов. id пустой, берется имя функции. min_level может быть ниже глобального уровня (логи низкого уровня отправляются только подписчику, не идут в консоль/память). При регистрации автоматически восстанавливает исторические логи |
remove_handler(id) |
Удалить подписчика |
Управление выводом
sdk.logger.set_output_file("app.log")
sdk.logger.save_logs("log.txt")
sdk.logger.get_logs("MyModule")
sdk.logger.set_memory_limit(1000)
Модуль Adapter
Менеджер адаптеров, управляет регистрацией, запуском и остановкой адаптеров для различных платформ.
Обзор API
| Метод | Описание |
|---|---|
get(platform) |
Получить экземпляр адаптера |
exists(platform) |
Проверить, зарегистрирован ли адаптер |
enable(platform) / disable(platform) |
Включить/выключить адаптер |
is_enabled(platform) |
Проверить, включен ли |
startup(platforms) / shutdown(platforms) |
Запустить/остановить адаптеры |
is_running(platform) |
Проверить, запущен ли адаптер |
list_running() |
Перечислить все запущенные адаптеры |
platforms |
Получить список всех платформ |
get_info(platform) |
Информация о зарегистрированном адаптере (json-safe: meta + имя класса) |
get_meta(platform, resolve_i18n=True) |
Метаинформация адаптера (согласование с module.get_meta, поддержка i18n解析) |
События адаптера
@sdk.adapter.on("message")
async def handle_message(event):
pass
@sdk.adapter.on("message", platform="yunhu")
async def handle_yunhu_message(event):
pass
Запрос статуса бота
sdk.adapter.get_bot_info("telegram", "123456")
sdk.adapter.list_bots("telegram")
sdk.adapter.is_bot_online("telegram", "123456")
sdk.adapter.get_status_summary()
Полный API управления адаптерами см. в API системы адаптеров.
Модуль Module
Менеджер модулей, управляет регистрацией, загрузкой и выгрузкой плагинов.
Обзор API
| Метод | Описание |
|---|---|
get(name) |
Получить экземпляр модуля или ленивый загрузочный прокси (при регистрации, но не загрузке, возвращается прокси) |
exists(name) |
Проверить, зарегистрирован ли |
is_loaded(name) |
Проверить, загружен ли |
is_enabled(name) |
Проверить, включен ли |
enable(name) / disable(name) |
Включить/выключить модуль |
load(name) / unload(name) |
Загрузить/выгрузить модуль |
call(module, method, *args, timeout=None, **kwargs) |
Вызов метода сервиса другого модуля (протоколизированный RPC) |
list_registered() |
Перечислить зарегистрированные модули |
list_loaded() |
Перечислить загруженные модули |
get_info(name) |
Получить информацию о модуле |
get_status_summary() |
Получить сводку состояния модуля |
Доступ по свойствам
module = sdk.module.get("ModuleName")
module = sdk.module.ModuleName
module = sdk.ModuleName # Эквивалентный сокращенный способ
Вызов между модулями (RPC)
# Протоколизированный вызов: типизированные ошибки / ленивые модули автоматически пробуждаются / owner присваивается / семантика таймаута
result = await sdk.module.call("Chat", "get_history", session_id, n=20)
Различия между module.call() и прямым доступом к свойству:
module.call() |
Прямой доступ к свойству | |
|---|---|---|
| Цель не зарегистрирована/не включена | Выбрасывает ModuleNotAvailableError |
Выбрасывает AttributeError |
| Ленивая загрузка модуля | Автоматически пробуждается | Асинхронная инициализация модуля выбрасывает RuntimeError |
current_owner |
Присваивается к целевому модулю | Сохраняется вызывающий модуль |
| Таймаут | По умолчанию 30 секунд, можно перекрыть | Нет |
| Проверка scope | actions.<вызывающий модуль>.call |
Нет |
Сервисный контракт (meta.services)
Сервисная сторона в get_meta() в поле services объявляет белый список для внешнего доступа (симметрично commands), после объявления доступ к вызову сужается:
class ChatModule(BaseModule):
@staticmethod
def get_meta() -> ModuleMeta:
return ModuleMeta(services=["get_history", "translate"])
async def get_history(self, session_id, n=20): ...
- По умолчанию = для разработчика незаметно: если не объявлен
services, доступны любые публичные методы (для обратной совместимости), методы с подчеркиванием всегда запрещены; основной контроль доступа находится в настройках scope пользователя - После объявления: доступны только методы из белого списка, при выходе за пределы выбрасывается
ServiceNotProvidedError - Ограничение вызывающей стороны:
scope.set_action("CallerModule", "call", deny="Chat.get_history")
Описание сервиса (description): services поддерживает словарную форму для описания каждого сервиса (поддерживает чистую строку или словарь i18n), для каталога сервисов / потребления описания точек вызова AI:
return ModuleMeta(
services=[
"get_history", # Простая форма: описание автоматически берется из первой строки docstring метода
{"name": "translate", "description": "Перевести текст на указанный язык"},
{"name": "summarize", "description": {"i18n": "Chat.meta.svc.summarize", "default": "Суммаризировать диалог"}},
],
)
Приоритет разбора описания: явное описание (i18n разбирается на текущий язык) > первая строка docstring метода > пустая строка.
Каталог сервисов (services)
sdk.module.services()
# {'Chat': [{'name': 'get_history', 'signature': '(session_id, n=20)',
# 'description': 'Получить историю сессии'}]}
sdk.module.services("Chat") # Получить только для указанного модуля
Перечисляются только модули с явно объявленным meta.services; каждый сервис сопровождается строкой сигнатуры метода и описанием текста, что обеспечивает данные для MCP (экспозиция точек вызова для AI).
Направленная отправка событий относится к уровню жизненного цикла:
lifecycle.emit(event, data, to="ModuleName"), подробнее см. Взаимодействие между модулями.
Модуль Lifecycle
Система управления жизненным циклом на основе событий, предоставляет функции отправки и прослушивания событий.
Обзор API
| Метод | Описание |
|---|---|
on(event, priority=0) |
Декоратор для регистрации обработчика событий, поддерживает точечные совпадения и подстановочные знаки * |
register(event, handler, priority=0) |
Функциональная регистрация обработчика |
unregister(event, handler=None) |
Удаление обработчика |
emit(event, data, to=None) |
Асинхронная отправка события; to указывает на владельца, если направлена отправка |
emit_sync(event, data, to=None) |
Синхронная отправка события (в асинхронных обработчиках с помощью create_task) |
submit_event(event_type, msg, data, source, to=None) |
Подача стандартного события (совместимость со старыми версиями) |
start_timer(id) / stop_timer(id) |
Таймер производительности |
Примеры
@sdk.lifecycle.on("module.init")
async def handle_module_init(event_data):
print(f"Инициализация модуля: {event_data}")
@sdk.lifecycle.on("module")
async def handle_any_module_event(event_data):
print(f"Событие модуля: {event_data}")
await sdk.lifecycle.emit("custom.event", {"key": "value"})
# Направленная отправка: отправка только обработчикам, зарегистрированным в модуле Chat
await sdk.lifecycle.emit("message_received", {"text": "hi"}, to="Chat")
Полный список стандартных событий и подробное использование см. в Управление жизненным циклом.
Модуль Router
Менеджер маршрутизации HTTP/WebSocket, на основе FastAPI + Uvicorn, поддерживает маршрутизацию с декораторами, промежуточные обработчики, группировку, ограничение скорости, CORS.
Полная документация API маршрутизатора (маршрутизация с декораторами, WebSocket, промежуточные обработчики, ограничение скорости, CORS, заголовки безопасности и т.д.) см. в Менеджер маршрутизации.
Краткий справочник
# HTTP маршрутизация
@sdk.router.get("MyModule", "/api")
async def handler(request: HttpRequest):
return {"status": "ok"}
# WebSocket маршрутизация
@sdk.router.ws("MyModule", "/ws")
async def ws_handler(ws: WebSocketConnection):
async for text in ws.iter_text():
await ws.send_text(f"Echo: {text}")
# Группировка маршрутов
group = sdk.router.group("MyModule", prefix="/v1")
@group.get("/users")
async def list_users(request: HttpRequest):
return {"users": []}
Модуль HTTP Client
Единый клиент для сетевых запросов, объединяет HTTP-запросы, WebSocket-соединения, управление пула соединений, автоматические повторные попытки, статистику запросов и интеграцию событий жизненного цикла.
Полная документация сетевого клиента (методы запросов, объекты ответов, WebSocket-клиент, иерархия исключений и т.д.) см. в Сетевой клиент.
Краткий справочник
from ErisPulse.Core import client
# HTTP запрос
resp = await client.get("https://api.example.com/users")
data = await resp.json()
# WebSocket
ws = await client.ws_connect("wss://example.com/ws")
async for text in ws.iter_text():
await ws.send_text(f"Echo: {text}")
SDK отладка
dump_state()
Экспорт снимка текущего состояния работы фреймворка, используется для отладки и диагностики.
import json
state = sdk.dump_state()
print(json.dumps(state, indent=2, ensure_ascii=False, default=str))
Возвращаемая структура содержит состояние следующих подсистем:
| Поле | Описание |
|---|---|
sdk |
Состояние инициализации SDK, версия Python, платформа, временная метка |
adapters |
Список зарегистрированных/запущенных адаптеров, статус онлайн-бота каждой платформы |
modules |
Список зарегистрированных/включенных/отключенных/лениво загружаемых модулей |
events |
Количество обработчиков различных типов событий (message/notice/request/meta/commands) |
router |
Статус сервера, количество HTTP/WebSocket маршрутов |
Note
Добавлено в ErisPulse 2.5.2+
Взаимодействие (Interaction)
Управление ожиданием wait_reply и сеансовыми взаимосвязями (sdk.interaction).
Основные методы
# Таймер напоминания сеанса: если нет ответа в течение 5 минут, напомнить, ответ пользователя автоматически отменяет
reminder = event.remind(300, "Еще здесь?")
reminder.cancel() # Ручная отмена
# Превышение таймаута: обязательно срабатывает по истечении времени (не отменяется ответом)
event.escalate(1800, lambda e: notify_master("Не обработано 30 минут"))
# Ожидание нескольких путей: первый, кто ответит, побеждает
which, reply = await event.select(
event.expect(pattern="同意*", user="A"),
event.expect(pattern="拒绝*", user="B"),
timeout=60,
)
# Сеансовое ожидание: любой ответ в группе может быть принят
reply = await event.wait_reply(session=True, prompt="Кто-нибудь может помочь ответить?")
# Запрос текущего владельца сеанса (кто взаимодействует с пользователем)
owner = sdk.interaction.get_owner_of(event)
# Заявление сеансового взаимосвязи (если занято, возвращает None)
lease = sdk.interaction.acquire(event)
if lease:
try:
... # Исключительное взаимодействие
finally:
lease.release()
# Форма контекстного менеджера (если занято, выбрасывается SessionOccupiedError)
with sdk.interaction.hold(event) as lease:
...
# Статистика сеансов
sdk.interaction.counts() # {'waits': 2, 'leases': 1, 'timers': 3, 'owners': {'Chat': 3}}
При выгрузке модуля/остановке адаптера ожидания и таймеры автоматически отменяются (ожидание немедленно возвращает None), при срабатывании ответа автоматически проверяется разрешение scope (если пользователь исключен/модуль отключен, ожидание прекращается).
Note
Функциональность в этом разделе добавлена в ErisPulse 2.8.0+
Транскрипт (Transcript)
Автоматическая запись и запрос последних сообщений для каждого сеанса (sdk.transcript), используется как база для модулей контекстной памяти, таких как AI-диалоги и предотвращение повторений.
Основные методы
# Удобный запрос (рекомендуется): последние 20 сообщений текущего сеанса (включая пользователя и бота, по возрастанию времени)
messages = await event.history(20)
for m in messages:
print(m["role"], ":", m["text"])
# Методы менеджера
sdk.transcript.append(event, "user", "Текст")
sdk.transcript.get(event, n=20)
sdk.transcript.clear(event)
Конфигурация (ErisPulse.transcript): enabled (по умолчанию включено), max_per_session (максимум на сеанс, по умолчанию 50), ttl_hours (время жизни по умолчанию, по умолчанию 168 часов). Данные хранятся в отдельной таблице SQLite, при превышении лимита или истечении срока удаляются лениво.
Note
Функциональность в этом разделе добавлена в ErisPulse 2.8.0+
Связанные документы
Продолжить изучение API:
- API системы событий - API модуля Event
- API системы адаптеров - API управления адаптерами
Глубокое изучение документации по подсистемам:
- SQL-построитель запросов - Полная документация SQL-цепных запросов
- Менеджер маршрутизации - Полная документация менеджера маршрутизации
- Сетевой клиент - Полная документация сетевого клиента
- Управление жизненным циклом - Полная документация жизненного цикла