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

Type Stub Generation (IDE Completion)

Tip

When to read this: If IDE completion doesn't surface an adapter's platform-specific methods (such as Yunhu's Board) or a module's custom methods, simply run the epsdk types command to generate type stubs; otherwise, skip this.

ErisPulse dynamically discovers modules/adapters via entry-points, so the concrete types of user classes cannot be known statically from entry points. The epsdk types command scans installed modules/adapters and generates a type stub file, allowing users to use these types as variable annotations and thereby get IDE completion.

Core Design Principles

Stub files export only types and provide no runtime instances:

  • All imports are under TYPE_CHECKING, zero runtime overhead, no behavior changes
  • Type names use PascalCase form of entry-point names (e.g., yunhu → Yunhu), matching the names passed to sdk.adapter.get() / sdk.module.get()
  • Users use sdk.module.get(...) / sdk.adapter.get(...) as usual to get instances in their code, only using imported types for variable annotations

Basic Usage

Run the following command in the project root directory:

epsdk types

This will generate _ep_types.py in the current directory, containing types for all installed modules/adapters.

Using in Code

from _ep_types import MyModule, Yunhu
from ErisPulse import sdk

# By using the imported types as variable annotations, IDE will provide completion for the class's methods
my_mod: MyModule = sdk.module.get("MyModule")
my_mod.hello()                  # ← IDE completes hello

my_adapter: Yunhu = sdk.adapter.get("yunhu")
await my_adapter.Send.To("group", "123").Board(...)   # ← Completes platform-specific methods

How It Works

  1. Scan erispulse.adapter / erispulse.module entry-points
  2. Inspect each adapter/module's actual class information (including module path and qualified name) within the target Python environment via a subprocess
  3. Generate a .py file, where:
    • All from xxx import Yyy as Zzz statements are included under TYPE_CHECKING
    • Zzz is the PascalCase form of the entry-point name
  4. The IDE reads the TYPE_CHECKING section to provide code completion; no code is executed at runtime

Example of generated stubs:

# _ep_types.py (auto-generated)
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    # Adapters
    from MyAdapter.Core import MyAdapter as MyAdapter
    from YunhuAdapter.Core import YunhuAdapter as Yunhu

    # Modules
    from MyModule.Core import Main as MyModule

    __all__ = ['MyAdapter', 'Yunhu', 'MyModule']

Command Options

Option Description
-o, --output PATH Specify the output file path (default: ./_ep_types.py)
--force Overwrite existing stub files
--adapters-only Scan only adapters
--modules-only Scan only modules

When to Regenerate

  • After installing/uninstalling new modules or adapters
  • After modules/adapters update their public APIs
  • When IDE auto-completion fails or types are outdated

Relationship with SendDSL Standard Methods

The SendDSL base class already has built-in standard sending methods (Text/Image/Voice/Video/File), and any instance of SendDSL obtained through any method can complete these methods.
The types command is mainly used to complete platform-specific methods (such as Board for Yunhu, Dice for Sandbox) and module-specific methods.

Next Steps