ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

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

Tip


Когда следует читать эту статью: если IDE не предлагает дополнение для методов платформы, специфичных для адаптера (например, Board в Yunhu), или для пользовательских методов модуля, выполните команду epsdk types, чтобы сгенерировать файл типовых заглушек; если не нужно, пропустите.

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']

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

Параметр Описание
-o, --output PATH Указывает путь к выходному файлу (по умолчанию ./_ep_types.py)
--force Перезаписывает существующие файлы-заглушки
--adapters-only Сканирует только адаптеры
--modules-only Сканирует только модули

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

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

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

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

Далее

  • Хотите узнать, какие методы отправки универсальны для всех платформ?: ознакомьтесь с подробным руководством по SendDSL, где содержится официальное описание стандартных методов, таких как Text / Image / Voice
  • Разрабатываете собственный адаптер?: начните с введения в разработку адаптеров, чтобы создать проект адаптера