Генерация типовых заглушек (автодополнение в IDE)

ErisPulse использует entry-points для динамического обнаружения модулей/адаптеров, и типы пользовательских классов не могут быть определены на статическом уровне.
Команда epsdk types сканирует установленные модули/адаптеры и генерирует файл типовых заглушек, позволяя использовать эти типы в аннотациях переменных и получать автодополнение в IDE.

Основные принципы проектирования

Заглушечные файлы экспортируют только типы, не предоставляя каких-либо экземпляров во время выполнения:

• Все импорты находятся внутри TYPE_CHECKING, без накладных расходов во время выполнения, без изменения поведения
• Имена типов используют PascalCase, соответствующий названию entry-point (например, 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. Сканирование entry-points erispulse.adapter / erispulse.module
2. Инспекция в целевой среде Python через дочерний процесс для сбора информации о фактических классах каждого адаптера/модуля (включая путь модуля и полное имя)
3. Генерация .py файла, в котором:
   • Все from xxx import Yyy as Zzz находятся в TYPE_CHECKING
   • 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']

Параметры командной строки

Когда перегенерировать

• После установки или удаления новых модулей или адаптеров
• После обновления публичного API модуля/адаптера
• Когда автодополнение IDE перестаёт работать или типы устаревают

Отношение к стандартным методам SendDSL

Базовый класс SendDSL уже содержит стандартные методы отправки (Text/Image/Voice/Video/File), и любой полученный экземпляр SendDSL может дополнить эти методы. Команда types в основном используется для дополнения методов, специфичных для платформы (например, Board для Yunhu, Dice для Sandbox) и методов, специфичных для модуля.

Связанные документы

• SendDSL подробно - Инструкции по стандартному методу отправки
• Введение в разработку адаптеров - Создание адаптера