型スタブ生成(IDE 補完)
Tip
このドキュメントを読むべきケース:IDE の補完にアダプターのプラットフォーム固有メソッド(例:云湖の Board)やモジュールのカスタムメソッドが表示されない場合は、epsdk types コマンドを 1 回実行して型スタブを生成すれば解決します。不要であれば読み飛ばしてください。
ErisPulse は entry-points を通じてモジュール/アダプターを動的に検出するため、エントリーポイントからは静的な段階でユーザークラスの具体的な型を知ることができません。
epsdk types コマンドは、インストール済みのモジュール/アダプターをスキャンして型スタブファイルを生成します。これにより、ユーザーはこれらの型を変数アノテーションとして使用できるようになり、IDE 補完を受けられます。
核心設計原則
スタブファイルは型のみをエクスポートし、実行時のインスタンスは一切提供しません。
- すべてのインポートは
TYPE_CHECKINGの下で行われ、実行時のオーバーヘッドはゼロ、動作の変更も一切ありません - クラス名はエントリーポイント名の PascalCase 形式を採用します(例:
yunhu→Yunhu)。これはsdk.adapter.get()/sdk.module.get()に渡す名前に対応しています - ユーザーはコード内で通常通り
sdk.module.get(...)/sdk.adapter.get(...)を使用してインスタンスを取得しますが、インポートされた型は変数の型注釈にのみ使用します
基本的な使い方
プロジェクトのルートディレクトリで実行します:
epsdk types
現在のディレクトリに _ep_types.py が生成され、インストール済みのすべてのモジュール/アダプタの型が含まれます。
コード内での使用方法
from _ep_types import MyModule, Yunhu
from ErisPulse import sdk
# 導入された型を変数の型ヒントとして使用することで、IDE がそのクラスのメソッドを補完します
my_mod: MyModule = sdk.module.get("MyModule")
my_mod.hello() # ← IDE が hello を補完
my_adapter: Yunhu = sdk.adapter.get("yunhu")
await my_adapter.Send.To("group", "123").Board(...) # ← プラットフォーム固有のメソッドを補完
動作原理
erispulse.adapter/erispulse.moduleentry-points のスキャン- サブプロセスを介して、対象の Python 環境内でインスペクションを行い、各アダプタ/モジュールの実際のクラス情報を収集(モジュールパスと限定名を含む)
.pyファイルを生成し、以下を含む:TYPE_CHECKINGの下ではすべてのfrom xxx import Yyy as Zzzが有効Zzzは entry-point 名の PascalCase 形式
- IDE は
TYPE_CHECKING部分を読み取り、補完を提供する。実行時にはコードは一切実行されない
生成されたスタブの例:
# _ep_types.py(自動生成)
from typing import TYPE_CHECKING
if TYPE_CHECKING:
# アダプタ
from MyAdapter.Core import MyAdapter as MyAdapter
from YunhuAdapter.Core import YunhuAdapter as Yunhu
# モジュール
from MyModule.Core import Main as MyModule
__all__ = ['MyAdapter', 'Yunhu', 'MyModule']
コマンドオプション
| オプション | 説明 |
|---|---|
-o, --output PATH |
出力ファイルのパスを指定します(デフォルト: ./_ep_types.py) |
--force |
既存のスタブファイルを上書きします |
--adapters-only |
アダプターのみをスキャンします |
--modules-only |
モジュールのみをスキャンします |
再生成のタイミング
- 新しいモジュールやアダプターをインストール/アンインストールした後
- モジュール/アダプターが公開 API を更新した後
- IDEの補完が機能しない、または型が期限切れになった場合
SendDSL 標準メソッドとの関係
SendDSL 基底クラスには、標準の送信メソッド(Text/Image/Voice/Video/File)が既に組み込まれており、どのような方法で取得した SendDSL インスタンスでも、これらのメソッドが補完されます。types コマンドは主に、プラットフォーム固有のメソッド(例:雲湖の Board、沙盒の Dice)およびモジュール固有のメソッドを補完するために使用されます。
次のステップ
- どの送信メソッドがすべてのプラットフォームで共通して使えるか知りたい:SendDSL 詳解 をご覧ください。Text / Image / Voice などの標準メソッドの権威ある説明が載っています
- 独自のアダプターを開発している場合:アダプター開発入門 からアダプタープロジェクトの作成を始めましょう