ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

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 depends are 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 of priority.

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 runs gc.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_unload and 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

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 description is not declared, a fallback is automatically extracted from the docstring's :ivar field: description or Attributes: 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
  • example non-persisted fields: fields with metadata={"example": True} are not written to config.toml and are only recorded in config.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.cfg instead.

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

Continuing the Learning Path

Going Deeper and Troubleshooting