ErisPulse 2.6.3.dev0__tar.gz → 2.7.0.dev0__tar.gz

{erispulse-2.6.3.dev0 → erispulse-2.7.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.6.3.dev0
+Version: 2.7.0.dev0
 Summary: Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署
 Project-URL: Homepage, https://github.com/ErisPulse/ErisPulse
 Project-URL: Documentation, https://www.erisdev.com#docs

{erispulse-2.6.3.dev0 → erispulse-2.7.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.6.3-dev.0"
+version = "2.7.0-dev0"
 description = "Event-driven modular async bot framework — write once, deploy to any platform | 事件驱动的模块化异步机器人框架，一次编写，多平台部署"
 readme = "README.pypi.md"
 requires-python = ">=3.10"

{erispulse-2.6.3.dev0 → erispulse-2.7.0.dev0}/src/ErisPulse/CLI/commands/create.py

@@ -63,9 +63,8 @@ _MODULE_INIT = """from .Core import Main
 """
 
 _MODULE_CORE = """from dataclasses import dataclass, field
-from ErisPulse.Core.Bases import BaseModule
+from ErisPulse.Core.Bases import BaseConfig, BaseI18n, BaseModule, I18nKey
 from ErisPulse.Core.Event import command, message, notice
-from ErisPulse.runtime.config_schema import BaseConfig
 
 
 @dataclass
@@ -79,6 +78,20 @@ class {name}Config(BaseConfig):
     )
 
 
+class {name}I18n(BaseI18n):
+    \"\"\"{name} 模块翻译键声明
+
+    声明的翻译键会被框架自动注册到 i18n 系统。
+    键路径自动生成为: <模块名>.<属性名>
+    \"\"\"
+    # 示例：取消注释并修改以启用
+    # welcome: I18nKey = I18nKey(
+    #     default="Welcome to {name}!",
+    #     zh_CN="欢迎使用 {name}！",
+    #     en="Welcome to {name}!",
+    # )
+
+
 class Main(BaseModule):
     \"\"\"
     {name}模块
@@ -87,6 +100,7 @@ class Main(BaseModule):
     \"\"\"
 
     ConfigClass = {name}Config
+    I18nClass = {name}I18n
 
     def __init__(self, sdk=None):
         from ErisPulse import sdk as _sdk
@@ -179,7 +193,7 @@ _ADAPTER_CORE = """import asyncio
 import json
 from dataclasses import dataclass, field
 from ErisPulse.Core import BaseAdapter
-from ErisPulse.runtime.config_schema import BaseConfig
+from ErisPulse.Core.Bases import BaseConfig, I18nKey, I18nKeys
 from ErisPulse.Core import router
 
 
@@ -205,6 +219,31 @@ class {name}Config(BaseConfig):
     )
 
 
+class {name}I18n(BaseI18n):
+    \"\"\"{name} 适配器翻译键声明
+
+    声明的翻译键会被框架自动注册到 i18n 系统。
+    这里集中管理适配器用到的所有翻译键（含配置描述引用的键）。
+    \"\"\"
+    # 注册配置描述中引用的 i18n 键的多语言译文
+    endpoint: I18nKey = I18nKey(
+        default="Platform API Endpoint",
+        zh_CN="平台 API 地址",
+        en="Platform API Endpoint",
+        ja="APIアドレス",
+        ru="API адрес",
+        zh_TW="API 位址",
+    )
+    token: I18nKey = I18nKey(
+        default="Platform Token",
+        zh_CN="平台 Token",
+        en="Platform Token",
+        ja="トークン",
+        ru="Токен",
+        zh_TW="權杖",
+    )
+
+
 class {name}(BaseAdapter):
     \"\"\"
     {name} 适配器
@@ -214,6 +253,7 @@ class {name}(BaseAdapter):
     \"\"\"
 
     ConfigClass = {name}Config
+    I18nClass = {name}I18n
 
     def __init__(self, sdk=None):
         super().__init__()

{erispulse-2.6.3.dev0 → erispulse-2.7.0.dev0}/src/ErisPulse/Core/Bases/__init__.py

@@ -23,21 +23,41 @@ from .websocket import WebSocketConnectionBase, WSMessage
 from .router import HttpRequest, WebSocketConnection, SseEmitter
 from .client import BaseHttpClient, BaseHttpResponse, BaseClientWebSocket
 
+# 配置 / i18n Schema 类型
+from .config_schema import (
+    AdapterConfig,
+    BaseConfig,
+    BotAccountConfig,
+)
+from .i18n_schema import (
+    BaseI18n,
+    I18nKey,
+    key,
+)
+
 __all__ = [
+    # 配置 Schema 别名（= BaseConfig）
+    "AdapterConfig",
     "BaseAdapter",
     "BaseClientWebSocket",
+    "BaseConfig",
     "BaseHttpClient",
     "BaseHttpResponse",
+    # i18n 键声明 Schema 基类（命名对齐 BaseConfig）
+    "BaseI18n",
     "BaseModule",
     "BaseQueryBuilder",
     "BaseStorage",
     "BatchContext",
+    "BotAccountConfig",
     "ClientConnectionError",
     "ClientError",
     "ClientTimeoutError",
     "ErisPulseError",
     "HTTPStatusError",
     "HttpRequest",
+    # i18n 单键声明
+    "I18nKey",
     "KVQueryBuilder",
     "RequestDSL",
     "SendBuilder",

{erispulse-2.6.3.dev0 → erispulse-2.7.0.dev0}/src/ErisPulse/Core/Bases/adapter.py

@@ -965,11 +965,14 @@ class BaseAdapter(ABC):
     7. 通过 self.cfg / self.accounts 访问类型安全的配置对象（实时读取）
     8. 通过 self.emit_meta() 发送 meta 事件
     9. 通过 self.make_response() / self.make_error() 构造标准化响应
+    10. 通过 I18nClass 声明翻译键集合，框架自动注册到 i18n 系统
     {!--< /tips >!--}
     """
 
     ConfigClass: type | None = None
     AccountConfigClass: type | None = None
+    I18nClass: type | None = None
+    EventMixin: type | None = None
 
     _platform: str = ""
     _sdk: Any = None
@@ -1105,6 +1108,10 @@ class BaseAdapter(ABC):
         self._config_instance = None
         self._accounts_data = None
 
+        # 注册 I18nClass 中声明的翻译键（在生成配置之前）
+        self._ensure_i18n_registered()
+        # EventMixin 的注册由 AdapterManager 在注入 _platform 后调用
+
         # 初始化时确保配置模板存在
         if self.ConfigClass is not None:
             self._ensure_config_exists()
@@ -1196,8 +1203,11 @@ class BaseAdapter(ABC):
                 "未声明 ConfigClass，请设置 MyAdapter.ConfigClass = MyConfig"
             )
 
-        from ...runtime.config_schema import dict_to_dataclass
         from ..config import config as config_mgr
+        from .config_schema import dict_to_dataclass
+
+        # 适配器的 EventMixin 在 AdapterManager.register() 注入 _platform 后注册
+        # __init__ 阶段 _platform 尚未注入，因此不在此处调用
 
         data = config_mgr.getConfig(self._get_config_key())
         if data is None:
@@ -1248,8 +1258,8 @@ class BaseAdapter(ABC):
                 "未声明 AccountConfigClass，请设置 MyAdapter.AccountConfigClass = MyBotConfig"
             )
 
-        from ...runtime.config_schema import dict_to_dataclass, validate_config
         from ..config import config as config_mgr
+        from .config_schema import dict_to_dataclass, validate_config
 
         key = f"{self._get_config_key()}.accounts"
         data = config_mgr.getConfig(key)
@@ -1334,15 +1344,20 @@ class BaseAdapter(ABC):
         确保全局配置模板存在，不存在则生成默认配置
 
         {!--< internal-use >!--}
+        会先行调用 _ensure_i18n_registered() 注册声明的翻译键，
+        确保配置描述引用的 i18n 键在生成模板时已可用。
         {!--< /internal-use >!--}
         """
+        # 先行注册 i18n 键（在生成配置之前），保证配置描述中的 i18n 键可用
+        self._ensure_i18n_registered()
+
         if self.ConfigClass is None:
             return
-        from ...runtime.config_schema import (
+        from ..config import config as config_mgr
+        from .config_schema import (
             dataclass_to_defaults_dict,
             dataclass_to_toml_with_comments,
         )
-        from ..config import config as config_mgr
 
         key = self._get_config_key()
         data = config_mgr.getConfig(key)
@@ -1353,6 +1368,63 @@ class BaseAdapter(ABC):
             config_mgr.setConfig(key, data, immediate=True)
             self._get_logger().info(f"已生成 {key} 默认配置模板:\n{toml_str}")
 
+    def _ensure_i18n_registered(self):
+        """
+        注册 I18nClass 中声明的翻译键到 i18n 系统
+
+        使用适配器配置键名（默认为类名）作为键名前缀和 domain，便于统一卸载。
+        方法是幂等的，多次调用不会产生副作用（重复注册会覆盖旧值）。
+
+        {!--< internal-use >!--}
+        由 __init__() 在生成配置之前隐式调用。
+        {!--< /internal-use >!--}
+        """
+        if self.I18nClass is None:
+            return
+        from .i18n_schema import BaseI18n
+
+        if not isinstance(self.I18nClass, type) or not issubclass(self.I18nClass, BaseI18n):
+            # 非法声明静默跳过（避免影响适配器初始化流程）
+            return
+
+        prefix = f"{self._get_config_key()}."
+        domain = self._get_config_key()
+        try:
+            self.I18nClass.register(prefix=prefix, domain=domain)
+        except Exception:
+            # i18n 注册失败不应中断适配器初始化
+            self._get_logger().debug(
+                f"{self.__class__.__name__}.I18nClass.register() 失败",
+                exc_info=True,
+            )
+
+    def _ensure_event_mixin_registered(self):
+        """
+        注册 EventMixin 中声明的事件扩展方法
+
+        适配器声明 ``EventMixin`` 时，框架自动将其注册到适配器的平台
+        （即 ``self._platform``），而不是通配符。
+
+        {!--< internal-use >!--}
+        由 __init__() 隐式调用。
+        {!--< /internal-use >!--}
+        """
+        if self.EventMixin is None:
+            return
+        if not isinstance(self.EventMixin, type):
+            return
+
+        from ..Event import register_event_mixin
+
+        platform = self._platform or "*"
+        try:
+            register_event_mixin(platform, self.EventMixin)
+        except Exception:
+            self._get_logger().debug(
+                f"{self.__class__.__name__}.EventMixin 注册失败",
+                exc_info=True,
+            )
+
     def _ensure_accounts_exist(self):
         """
         确保多账户配置模板存在，不存在则生成默认账户配置
@@ -1362,8 +1434,8 @@ class BaseAdapter(ABC):
         """
         if self.AccountConfigClass is None:
             return
-        from ...runtime.config_schema import dataclass_to_defaults_dict
         from ..config import config as config_mgr
+        from .config_schema import dataclass_to_defaults_dict
 
         key = f"{self._get_config_key()}.accounts"
         data = config_mgr.getConfig(key)

{erispulse-2.6.3.dev0/src/ErisPulse/runtime → erispulse-2.7.0.dev0/src/ErisPulse/Core/Bases}/config_schema.py

@@ -78,7 +78,15 @@ def _get_ui_meta(meta: Mapping | None) -> dict:
 
 
 def _type_default(type_hint) -> object:
-    """根据类型注解返回合理的默认值"""
+    """
+    根据类型注解返回合理的默认值
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param type_hint: Python 类型注解
+    :return: 对应类型的默认值（int→0, float→0.0, bool→False, list→[], dict→{}, str→""）
+    """
     type_str = str(type_hint).lower()
     if "int" in type_str:
         return 0
@@ -94,7 +102,15 @@ def _type_default(type_hint) -> object:
 
 
 def _python_type_to_toml_type(type_hint) -> str:
-    """将 Python 类型注解转为 TOML 类型字符串"""
+    """
+    将 Python 类型注解转为 TOML 类型字符串
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param type_hint: Python 类型注解
+    :return: TOML 类型名（integer/float/boolean/array/table/string）
+    """
     type_str = str(type_hint).lower()
     if "int" in type_str:
         return "integer"
@@ -110,7 +126,15 @@ def _python_type_to_toml_type(type_hint) -> str:
 
 
 def _format_toml_value(value) -> str:
-    """将 Python 值格式化为 TOML 值字符串"""
+    """
+    将 Python 值格式化为 TOML 值字符串
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param value: Python 值（str/int/float/bool/list/dict 等）
+    :return: TOML 格式的字符串
+    """
     if isinstance(value, bool):
         return "true" if value else "false"
     if isinstance(value, int):
@@ -129,7 +153,15 @@ def _format_toml_value(value) -> str:
 
 
 def _get_field_default(f):
-    """获取字段的默认值"""
+    """
+    获取 dataclass 字段的默认值
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param f: dataclass Field 对象
+    :return: 字段的默认值（优先 default，其次 default_factory，最后根据类型推断）
+    """
     if f.default is not MISSING:
         return f.default
     if f.default_factory is not MISSING:
@@ -138,7 +170,15 @@ def _get_field_default(f):
 
 
 def _is_empty(value) -> bool:
-    """判断值是否为空"""
+    """
+    判断值是否为空（None / 空字符串 / 空列表 / 空字典）
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param value: 任意值
+    :return: 是否为空
+    """
     if value is None:
         return True
     if isinstance(value, str) and value.strip() == "":
@@ -147,7 +187,16 @@ def _is_empty(value) -> bool:
 
 
 def _coerce_value(value, type_hint):
-    """将值强制转换为目标类型"""
+    """
+    将值强制转换为目标类型（如 str→int、str→bool）
+
+    {!--< internal-use >!--}
+    {!--< /internal-use >!--}
+
+    :param value: 原始值
+    :param type_hint: 目标类型注解
+    :return: 转换后的值（转换失败时返回原值）
+    """
     if value is None:
         return value
 
@@ -465,27 +514,24 @@ def register_config_i18n(
     调用 i18n.register() 注册翻译。
 
     两种用法：
-    1. 自动模式（translations=None）：将字段 description.default 作为 zh-CN 翻译注册
+    1. 自动模式（translations=None）：将字段 description.default 注册到指定 lang
+       （description.default 是语言无关的兜底文本，调用者自行决定注册到哪种语言）
     2. 手动模式：提供 translations 字典（{i18n_key: translated_text}）
 
     使用示例::
 
-        # 自动注册默认值作为中文翻译
+        # 将默认文本注册为中文翻译
         register_config_i18n(MyAdapterConfig, "zh-CN")
 
-        # 手动注册英文翻译
+        # 将默认文本注册为英文翻译
+        register_config_i18n(MyAdapterConfig, "en")
+
+        # 手动提供英文翻译（覆盖默认文本）
         register_config_i18n(MyAdapterConfig, "en", {
             "my_adapter.endpoint": "API Endpoint",
             "my_adapter.token": "Platform Token",
         })
 
-        # 多账户配置同理
-        register_config_i18n(MyBotConfig, "zh-CN")
-        register_config_i18n(MyBotConfig, "en", {
-            "my_adapter.bot_id": "Bot ID",
-            "my_adapter.bot_token": "Bot Token",
-        })
-
     :param config_class: dataclass 配置类
     :param lang: 语言代码（如 "zh-CN", "en"）
     :param translations: 手动提供的翻译字典，None 则自动提取

erispulse-2.7.0.dev0/src/ErisPulse/Core/Bases/i18n_schema.py

@@ -0,0 +1,239 @@
+"""
+ErisPulse i18n 键声明 Schema 模块
+
+提供基于类属性的 i18n 翻译键声明，支持框架自动注册。
+适用于适配器、模块、外部项目等任何需要批量声明翻译键的场景。
+
+{!--< tips >!--}
+1. 继承 BaseI18n 基类，通过类属性声明翻译键（命名与 BaseConfig 对齐）
+2. 每个属性对应一个翻译键，属性名（加模块前缀）作为键路径
+3. 也可通过 I18nKey(key=...) 显式指定完整键路径
+4. 框架在加载模块/适配器时自动注册所有声明的翻译键
+5. 配合 BaseModule.I18nClass / BaseAdapter.I18nClass 使用，无需手动调用 i18n.register()
+6. ``default`` 是语言无关的兜底文本，不会注册到任何语言；
+   要让翻译生效，必须显式传入至少一个语言参数（``zh_CN=`` / ``en=`` 等）
+{!--< /tips >!--}
+"""
+
+
+class I18nKey:
+    """
+    单个 i18n 翻译键的声明
+
+    :param default: 兜底文本（语言无关）。当所有已注册语言均未覆盖此键时，
+                    作为最后的显示文本。**不会注册到任何语言**。
+                    各国开发者可使用自己母语填写此字段，框架不做任何假设。
+    :param key: 完整的翻译键路径（如 ``"mymodule.welcome"``）。
+                省略时使用属性名 + 调用方提供的前缀自动生成。
+    :param zh_CN: 简体中文翻译
+    :param zh_TW: 繁体中文翻译
+    :param en: 英文翻译
+    :param ja: 日文翻译
+    :param ru: 俄文翻译
+
+    使用示例::
+
+        from ErisPulse.Core.Bases import BaseI18n, I18nKey
+
+        class MyModule(BaseModule):
+            class I18nClass(BaseI18n):
+                # 自动生成键: mymodule.welcome
+                welcome: I18nKey = I18nKey(
+                    default="Welcome",        # 语言无关的兜底
+                    zh_CN="欢迎",
+                    zh_TW="歡迎",
+                    en="Welcome",
+                    ja="ようこそ",
+                    ru="Добро пожаловать",
+                )
+
+                # 显式指定键路径
+                deep: I18nKey = I18nKey(
+                    key="mymodule.deep.nested.key",
+                    default="Default text",
+                    zh_CN="默认文本",
+                    zh_TW="預設文本",
+                    en="Default text",
+                    ja="デフォルトテキスト",
+                    ru="Текст по умолчанию",
+                )
+    """
+
+    __slots__ = ("_key", "default", "translations")
+
+    def __init__(
+        self,
+        default: str,
+        *,
+        key: str | None = None,
+        zh_CN: str | None = None,
+        zh_TW: str | None = None,
+        en: str | None = None,
+        ja: str | None = None,
+        ru: str | None = None,
+    ):
+        if not default:
+            raise ValueError("default 是必填项（语言无关的兜底文本）")
+
+        self._key = key
+        self.default = default
+        # translations 只包含显式声明的语言翻译
+        # default 不注册到任何语言
+        self.translations: dict[str, str] = {}
+        if zh_CN is not None:
+            self.translations["zh-CN"] = zh_CN
+        if zh_TW is not None:
+            self.translations["zh-TW"] = zh_TW
+        if en is not None:
+            self.translations["en"] = en
+        if ja is not None:
+            self.translations["ja"] = ja
+        if ru is not None:
+            self.translations["ru"] = ru
+
+    @property
+    def explicit_key(self) -> str | None:
+        """
+        获取显式指定的键路径（如有）
+
+        :return: 显式键名字符串，或 None 表示使用前缀+属性名自动生成
+        """
+        return self._key
+
+    def __repr__(self) -> str:
+        return (
+            f"I18nKey(key={self._key!r}, default={self.default!r}, "
+            f"langs={sorted(self.translations.keys())})"
+        )
+
+
+# 模块级别名，方便在类定义中使用更短的名称
+# 使用示例::
+#     class MyKeys(BaseI18n):
+#         hello = key(default="Hello", en="Hello", zh_CN="你好")
+key = I18nKey
+
+
+class BaseI18n:
+    """
+    i18n 键声明集合的基类
+
+    命名与 :class:`BaseConfig` 对齐：用户通过嵌套类继承此类声明翻译键，
+    框架会在模块/适配器加载时自动调用 :meth:`register` 将所有声明的翻译键
+    注册到 i18n 系统。
+
+    {!--< tips >!--}
+    1. 类属性必须是 :class:`I18nKey` 实例，否则被忽略
+    2. 属性名以下划线开头的会被忽略（视为私有/内部）
+    3. 自动生成的键路径为 ``<前缀><属性名>``，前缀通常是模块名 + ``.``
+    4. 通过 :class:`I18nKey` 的 ``key=`` 参数可显式指定完整键路径
+    5. 同一 domain 可被多次注册，键值会被覆盖更新
+    6. ``I18nKey.default`` 是语言无关的兜底文本，不参与注册；
+       实际翻译必须通过 ``zh_CN=`` / ``en=`` 等参数显式声明
+    {!--< /tips >!--}
+
+    使用示例::
+
+        from ErisPulse.Core.Bases import BaseModule, BaseI18n, I18nKey
+
+        class MyModule(BaseModule):
+            class I18nClass(BaseI18n):
+                welcome: I18nKey = I18nKey(
+                    default="Welcome",
+                    zh_CN="欢迎",
+                    zh_TW="歡迎",
+                    en="Welcome",
+                    ja="ようこそ",
+                    ru="Добро пожаловать",
+                )
+                goodbye: I18nKey = I18nKey(
+                    default="Bye",
+                    zh_CN="再见",
+                    zh_TW="再見",
+                    en="Goodbye",
+                    ja="さようなら",
+                    ru="До свидания",
+                )
+
+    也可独立使用（手动注册）::
+
+        class MyKeys(BaseI18n):
+            hello: I18nKey = I18nKey(
+                default="Hello",
+                zh_CN="你好",
+                zh_TW="你好",
+                en="Hello",
+                ja="こんにちは",
+                ru="Привет",
+            )
+
+        MyKeys.register(prefix="myapp.", domain="myapp")
+    """
+
+    @classmethod
+    def _collect_keys(cls) -> dict[str, I18nKey]:
+        """
+        收集类中所有声明的 I18nKey
+
+        遍历 MRO（含父类继承），收集所有非下划线开头的 I18nKey 类属性。
+        子类同名属性会覆盖父类（与 Python 属性查找语义一致）。
+
+        :return: ``{属性名: I18nKey 实例}`` 字典
+        """
+        keys: dict[str, I18nKey] = {}
+        # 反向遍历 MRO，让子类覆盖父类
+        for klass in reversed(cls.__mro__):
+            for name, value in vars(klass).items():
+                if name.startswith("_"):
+                    continue
+                if isinstance(value, I18nKey):
+                    keys[name] = value
+        return keys
+
+    @classmethod
+    def register(cls, prefix: str = "", domain: str = "app") -> int:
+        """
+        注册所有翻译键到 i18n 系统
+
+        仅注册 :class:`I18nKey` 中显式声明的语言翻译。
+        ``default`` 字段是语言无关的兜底文本，不参与注册。
+
+        :param prefix: 键名前缀（通常是模块名 + ``.``，如 ``"mymodule."``）。
+                      仅对未显式指定 ``key`` 的翻译键生效。
+        :param domain: i18n 域标识，用于卸载时按域统一清理。
+                      建议使用模块名。
+        :return: 注册的翻译条目总数
+
+        :example:
+        >>> class MyKeys(BaseI18n):
+        ...     hello: I18nKey = I18nKey(
+        ...         default="Hello",
+        ...         zh_CN="你好",
+        ...         en="Hello",
+        ...     )
+        >>> MyKeys.register(prefix="myapp.", domain="myapp")
+        2  # zh-CN + en
+        """
+        from ..i18n import i18n
+
+        count = 0
+        for attr_name, i18n_key in cls._collect_keys().items():
+            # 决定最终的 key 路径：显式 key > 前缀 + 属性名
+            final_key = i18n_key.explicit_key or f"{prefix}{attr_name}"
+
+            for lang, text in i18n_key.translations.items():
+                i18n.register(lang, {final_key: text}, domain=domain)
+                count += 1
+
+        return count
+
+
+# ---------------------------------------------------------------------------
+# 导出
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "BaseI18n",
+    "I18nKey",
+    "key",
+]