ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

型スタブ生成(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(...)   # ← プラットフォーム固有のメソッドを補完

動作原理

  1. erispulse.adapter / erispulse.module entry-points のスキャン
  2. サブプロセスを介して、対象の Python 環境内でインスペクションを行い、各アダプタ/モジュールの実際のクラス情報を収集(モジュールパスと限定名を含む)
  3. .py ファイルを生成し、以下を含む:
    • TYPE_CHECKING の下ではすべての from xxx import Yyy as Zzz が有効
    • Zzz は entry-point 名の PascalCase 形式
  4. 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 などの標準メソッドの権威ある説明が載っています
  • 独自のアダプターを開発している場合:アダプター開発入門 からアダプタープロジェクトの作成を始めましょう