Module Core Concepts
Note
L1 Core Must-Read — one of the five core documents in the homepage's "Reading Path"; essential for module development.
This document explains the complete lifecycle of a module from loading to unloading, along with how to use declarative configuration and storage — what the framework automatically does for you and what you only need to write, so you'll know exactly where you stand after reading.
Module Lifecycle
Load Strategy
from ErisPulse.Core.Bases import BaseModule
from ErisPulse.loaders import ModuleLoadStrategy
class MyModule(BaseModule):
@staticmethod
def get_load_strategy():
"""Returns the module load strategy"""
return ModuleLoadStrategy(
lazy_load=True, # Lazy load or load immediately
priority=0, # Load priority (higher values load first)
depends=["OtherModule"] # Optional: declare other modules this one depends on
)
If modules declared in
dependsare not registered, the current module will be skipped and a warning logged. The loading order is determined by topological sorting; modules at the same level are sorted in descending order ofpriority.
Note
Cascading Unload / Cascading Reload (ErisPulse 2.8.0+): when unloading a module that other modules depend on, the modules depending on it are cascadingly unloaded first (logs explain the cascade chain); when hot-reloading any module (local plugin / runtime registration / PyPI package), the modules depending on it are likewise cascadingly reloaded, preventing dependents from continuing to run with stale instance references. Declared circular dependencies are rejected with a RuntimeError at load time.
reload means a full reload (ErisPulse 2.11.0+): reload() by default clears the import cache by top-level package name and re-imports dependent code, automatically performs a syntax pre-check before unloading (on failure the unload is rejected and the old instance keeps serving), and verifies code identity after success (fake-reload warning / stale flag); failure details of a failed load can be queried directly via sdk.module.last_error(name) (including the traceback).
The on_load Method
Called when the module is loaded; used to initialize resources and register event handlers:
async def on_load(self, event):
# Register event handlers
@command("hello", help="Greeting command")
async def hello_handler(event):
await event.reply("Hello!")
# Use the SDK's built-in HTTP client (automatically manages the connection pool, no need to manually create a session)
# Send requests via sdk.client
The on_unload Method
Called when the module is unloaded; used to clean up resources:
async def on_unload(self, event):
# Clean up custom resources
# sdk.client is managed by the framework, no need to close it manually
# Cancel event handlers (the framework handles this automatically)
self.logger.info("Module unloaded")
For creating and cleaning up background tasks (
self.spawn()/ framework fallback cancellation), see Lifecycle Management.
The on_before_unload Method
Note
This hook requires ErisPulse 2.11.0+.
An optional hook triggered as the first step of the unload pipeline (before on_unload and resource reclamation) — at this point all of the module's resources are still intact, making it the right place to save state to sdk.storage before unload / dormancy / reload and restore it in the next on_load (state continuation for lazy-load dormancy is based on this):
async def on_before_unload(self, event):
# event["reason"] indicates why the hook is running: unload / reload / disable / cascade / dormant
if event["reason"] in ("reload", "dormant"):
await self.sdk.storage.aset(f"{self._module_name}:state", self.collect_state())
Hook failures only produce a warning and do not block the unload process; modules that do not declare this hook behave unchanged. For dormancy / wake-up semantics, see Lazy-Load Dormancy.
Unload and Complete Unload (purge)
Note
This feature requires ErisPulse 2.8.0+.
By default, unload() only cancels the load (unloads the instance and resources) while keeping the registration stub (module class and metadata) — the module can still be rediscovered by discover and re-instantiated with load(), without needing to register() again.
When you need to completely unload (release the module class reference, clean up sys.modules, so that the plugin and its exclusive dependencies can be garbage collected), pass purge=True:
# Unload only: keeps the registration stub, can be load()ed again at any time
await sdk.module.unload("MyModule")
# Complete unload: deletes the registration stub + cleans up sys.modules (plugin sources)
await sdk.module.unload("MyModule", purge=True)
| Semantics | unload() default |
unload(purge=True) |
|---|---|---|
| Unload instance and resources (events/tasks/routes/lifecycle/i18n) | ✅ | ✅ |
| Keep registration stub (module class and metadata) | ✅ | ❌ Deleted |
Clean up sys.modules (plugin folder sources only) |
❌ | ✅ |
| Module class can be garbage collected | ❌ | ✅ |
| Reload | load() directly available |
Requires register() + load() first |
When
purge=True, dependents unloaded via the cascade are purged as well; after unloading, the framework runsgc.collect()and checks whether the module class/instance is reclaimable, warning in the logs about leftover references (including referrers, DEBUG level).
Lifecycle Overview
Tying the methods above together, here is everything the framework does behind the scenes when loading and unloading a module:
flowchart TD
subgraph Load["Loading (register → load)"]
L1["register: register module class and metadata"] --> L2["Dependency check<br/>skip if missing"]
L2 --> L3["Topological sort (Kahn + priority)"]
L3 --> L4["owner injects current_owner"]
L4 --> L5["Generate config template + register i18n translation keys"]
L5 --> L6["Instantiate module (inject sdk)"]
L6 --> L7["Call on_load()"]
L7 --> L8["Mount onto sdk attribute + emit module.load"]
end
subgraph Unload["Unloading (unload)"]
U1["Call on_unload()"] --> U2["Fallback cancellation of background tasks (self.spawn ownership)"]
U2 --> U3["Clean up i18n translation keys"]
U3 --> U4["Remove routes / commands / event handlers (by owner)"]
U4 --> U5["Clean up lifecycle hooks (by owner)"]
U5 --> U6["Remove SDK attribute + lazy-load proxy"]
U6 --> U7["emit module.unload"]
end
Load --> Unload
What the framework does for you at load time (you only write on_load; everything else is done automatically):
| Step | What the framework does automatically |
|---|---|
| owner injection | During instantiation, the module name is wrapped in owner_scope — commands/events/hooks/background tasks registered in your on_load are automatically attributed to this module, and cleaned up in one go by owner at unload |
| Config template | For modules declaring ConfigClass, the framework automatically generates/fills the ErisPulse.<ModuleName> config section |
| i18n translation keys | For modules declaring I18nClass, translation keys are registered automatically (and unregistered automatically at unload) |
| Dependency topology | Sorted by the depends declarations to ensure depended-on modules load first; circular dependencies are rejected with a RuntimeError |
| SDK mounting | After instantiation the module is mounted at sdk.<ModuleName>, which is what enables access via sdk.MyModule.xxx |
What the framework cleans up for you at unload (corresponding to U1→U7 above): after on_unload finishes, fallback cleanup runs — forced cancellation of background tasks (those created by self.spawn; do graceful shutdown yourself in on_unload), i18n keys, routes, command/event handlers, lifecycle hooks, and finally the SDK attribute is removed. purge=True additionally deletes the registration stub + cleans up sys.modules.
These automatic cleanups are exactly what makes "you only write
on_load/on_unloadand never manually unregister" possible — the framework uses owner attribution to turn "whoever registers it cleans it up" into a one-click affair.
The SDK Object
Accessing Core Modules
from ErisPulse import sdk
# Access all core modules via the sdk object
sdk.logger.info("Log")
sdk.storage.set("key", "value")
config = sdk.config.getConfig("MyModule")
Inter-Module Communication
# Access other modules
other_module = sdk.OtherModule
result = await other_module.some_method()
Adapter Send Method Query
Because the new standard specification requires overriding the __getattr__ method to implement the fallback send mechanism, the hasattr method can no longer be used to check whether a method exists. Starting from 2.3.5, the ability to query send methods has been added.
Listing Supported Send Methods
# List all send methods supported by the platform
methods = sdk.adapter.list_sends("onebot11")
# Returns: ["Text", "Image", "Voice", "Markdown", ...]
Getting Method Details
# Get the details of a method
info = sdk.adapter.send_info("onebot11", "Text")
# Returns:
# {
# "name": "Text",
# "parameters": [
# {"name": "text", "type": "str", "default": null, "annotation": "str"}
# ],
# "return_type": "Awaitable[Any]",
# "docstring": "Send a text message..."
# }
Configuration Management
Declarative Configuration (Recommended)
Since v2.5.2, modules can declare a configuration class via ConfigClass, sharing the same configuration Schema system as adapters. Configuration is read in real time through self.cfg, so changes take effect immediately:
from dataclasses import dataclass, field
from ErisPulse.Core.Bases import BaseModule
from ErisPulse.Core.Bases import BaseConfig
@dataclass
class MyModuleConfig(BaseConfig):
api_key: str = field(
default="",
metadata={
"description": {"i18n": "my_module.api_key", "default": "API Key"},
"required": True,
"secret": True,
"ui": {"widget": "password", "group": "basic", "order": 1},
},
)
timeout: int = field(
default=30,
metadata={
"description": {"i18n": "my_module.timeout", "default": "Timeout (seconds)"},
"ui": {"widget": "number", "group": "advanced", "order": 2},
},
)
class MyModule(BaseModule):
ConfigClass = MyModuleConfig
def __init__(self, sdk):
self.sdk = sdk
self.logger = sdk.logger.get_child("MyModule")
async def on_load(self, event):
self.logger.info("Module loaded")
async def on_unload(self, event):
pass
async def do_something(self):
cfg = self.cfg # Read in real time, type-safe
api_key = cfg.api_key
timeout = cfg.timeout
BaseConfig is a general-purpose configuration base class suitable for adapters, modules, external projects, and any other scenario. Configuration fields support i18n multilingual descriptions (see the i18n documentation for details).
Note
The lifecycle of modules (including adapters) — loading, unloading, enabling/disabling, and so on — is managed uniformly by the framework (the module manager / scope provide query and control APIs). ConfigClass should only carry business parameters; modules do not need to nest logic inside themselves that decides "whether they should start".
The configuration Schema system also supports the following (v2.8.0+, see adapter core-concepts for details):
- Automatic field descriptions from docstrings: when metadata
descriptionis not declared, a fallback is automatically extracted from the docstring's:ivar field: descriptionorAttributes:section - Nested dataclass configuration: when a field's type is a nested dataclass, schema/template/validation are handled recursively, and the WebUI renders it as nested groups
examplenon-persisted fields: fields withmetadata={"example": True}are not written to config.toml and are only recorded inconfig.full.example(suitable for verbose, rarely touched advanced configuration items); once users set them manually, they persist normally
Declarative Translation Keys (v2.7.0+)
Since v2.7.0, modules can also declare translation keys centrally through a nested class I18nClass, just like declaring ConfigClass. The framework automatically registers all declared translation keys at load time — no need to call i18n.register() manually — and registration happens before config template generation, ensuring that i18n keys referenced in configuration descriptions are already available.
from ErisPulse.Core.Bases import BaseConfig, BaseI18n, I18nKey
class MyModule(BaseModule):
# Configuration class (optional)
@dataclass
class ConfigClass(BaseConfig):
welcome_msg: str = field(
default="Welcome",
metadata={
"description": {"i18n": "mymodule.welcome_msg", "default": "Welcome message"},
},
)
# Translation key collection class (optional)
class I18nClass(BaseI18n):
# Attribute names are automatically joined into the full key path: <module name>.<attribute name>
welcome_msg: I18nKey = I18nKey(
default="Welcome Message", # Language-independent fallback
zh_CN="Welcome message",
zh_TW="歡迎訊息",
en="Welcome Message",
ja="ウェルカムメッセージ",
ru="Приветственное сообщение",
)
hello: I18nKey = I18nKey(
default="Hello, {name}!",
zh_CN="Hello, {name}!",
zh_TW="你好,{name}!",
en="Hello, {name}!",
ja="こんにちは、{name}!",
ru="Привет, {name}!",
)
For details, see i18n Recommended Approach.
Reading Configuration Manually (Deprecated)
Deprecated: Please use Declarative Configuration + real-time reading via
self.cfginstead.
class MyModule(BaseModule):
def __init__(self, sdk):
self.sdk = sdk
def _load_config(self):
config = self.sdk.config.getConfig("MyModule")
if not config:
self.sdk.config.setConfig("MyModule", {"api_key": "", "timeout": 30})
return {"api_key": "", "timeout": 30}
return config
Storage System
Basic Usage
# Store data
sdk.storage.set("user:123", {"name": "Zhang San"})
# Get data
user = sdk.storage.get("user:123", {})
# Delete data
sdk.storage.delete("user:123")
Using Transactions
# Use a transaction to ensure data consistency
with sdk.storage.transaction():
sdk.storage.set("key1", "value1")
sdk.storage.set("key2", "value2")
# If any operation fails, all changes are rolled back
Event Handling
Registering Event Handlers
from ErisPulse.Core.Event import command, message
# Register a command
@command("info", help="Get information")
async def info_handler(event):
await event.reply("Here is the information")
# Register a message handler
@message.on_group_message()
async def group_handler(event):
sdk.logger.info(f"Received group message: {event.get_text()}")
Event Handler Lifecycle
The framework automatically manages the registration and unregistration of event handlers; you only need to register them in on_load.
Lazy Loading Mechanism
How It Works
# The module is only initialized on first access
result = await sdk.my_module.some_method()
# ↑ This triggers module initialization
Immediate Loading
For modules that need to be initialized immediately (such as listeners, timers):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=False, # Load immediately
priority=100
)
Error Handling
Catching Exceptions
async def handle_event(self, event):
try:
# Business logic
await self.process_event(event)
except ValueError as e:
self.logger.warning(f"Invalid parameter: {e}")
await event.reply(f"Invalid parameter: {e}")
except Exception as e:
self.logger.error(f"Processing failed: {e}")
raise
Logging
# Use different log levels
self.logger.debug("Debug info") # Detailed debug information
self.logger.info("Running status") # Normal operation information
self.logger.warning("Warning message") # Warning message
self.logger.error("Error message") # Error message
self.logger.critical("Fatal error") # Fatal error
Related Documentation
Continuing the Learning Path
- Event Wrapper Class - Event handling in depth
Going Deeper and Troubleshooting
- Module Best Practices - Developing high-quality modules
- Module Development Getting Started - Review the steps for building your first module