butterbot-python 3.1.0.dev1__py3-none-any.whl

butterbot/core/data/base_model.py

@@ -0,0 +1,197 @@
+from typing import ClassVar, Generic, Self, TypeVar
+
+from pydantic import BaseModel, ConfigDict, RootModel, model_validator
+from pydantic._internal._model_construction import ModelMetaclass
+
+from .base_data import BaseDataMixin
+
+
+class MetaDataModel(ModelMetaclass):
+    """pydantic数据模型元类，支持单层和多层继承的 discriminator 注册机制.
+    1. 根类定义 discriminator_field，子类定义 discriminator_value，自动注册到 registry
+    2. 支持属性嵌套
+    3. 完全自动注册和分发
+    """
+
+    def __new__(mcls, name, bases, namespace, **kwargs):
+        cls = super().__new__(mcls, name, bases, namespace, **kwargs)
+
+        # 沿每个直接父类的 MRO 查找最近的分发根。这样既支持
+        # “分发根 → 共享字段基类 → 叶子类型”的间接注册，也不会把
+        # BaseDataModel 的全局 registry 误当作普通 DTO 的分发目标。
+        base_with_registry = None
+        for base in bases:
+            for ancestor in base.__mro__:
+                if (
+                    "discriminator_field" in ancestor.__dict__
+                    and "_registry" in ancestor.__dict__
+                ):
+                    base_with_registry = ancestor
+                    break
+            if base_with_registry is not None:
+                break
+
+        discriminator_value = namespace.get("discriminator_value")
+        discriminator_field = namespace.get("discriminator_field")
+
+        # 如果子类有 discriminator_value，注册到父类的 registry
+        if base_with_registry and discriminator_value is not None:
+            if isinstance(discriminator_value, (list, tuple, set)):
+                for value in discriminator_value:
+                    base_with_registry._registry[value] = cls
+            else:
+                base_with_registry._registry[discriminator_value] = cls
+
+        # 如果当前类定义了 discriminator_field，初始化自己的 registry（用于二级分发）
+        if discriminator_field is not None:
+            cls._registry = {}
+
+        return cls
+
+
+class BaseDataModel(BaseModel, BaseDataMixin, metaclass=MetaDataModel):
+    """
+    基于BaseDataMixin实现的领域模型基类
+    1. 使用pydantic进行数据校验
+    2. 支持单层和多层继承的 discriminator 注册机制
+    3. 根类定义 discriminator_field，子类定义 discriminator_value，自动注册到 registry
+    """
+
+    model_config = ConfigDict(
+        strict=False,  # 强制转换数据
+        frozen=True,  # 实例不可变，自动生成 __hash__
+        extra="ignore",  # 额外字段将被忽略
+    )
+
+    # discriminator_field: ClassVar[str] = "data_type"
+    # 作为分发依据的"键"，必须在根/基类定义
+    # discriminator_value: ClassVar[str] = "group"
+    # 作为分发依据的"值"，子类可选定义，若定义则认为是可直接构造模型，否则则认为是属性嵌套的分发模型
+
+    _registry: ClassVar[dict] = {}
+
+    @classmethod
+    def from_raw(cls, raw: dict) -> Self:
+        """从原始数据构造实例，可实现复杂构造逻辑
+
+        Args:
+            raw: 原始数据字典
+
+        Returns:
+            对应子类的实例
+        """
+        ...
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> Self:
+        """从dict自动构造实例，支持多层分发
+
+        Args:
+            raw: 原始数据字典
+
+        Returns:
+            对应子类的实例
+        """
+        field = getattr(cls, "discriminator_field", None)
+        if field is None:
+            # 没有 discriminator_field，直接构造
+            return cls.model_validate(raw)
+
+        value = raw.get(field)
+        if value is None:
+            raise ValueError("Missing discriminator field: %s" % field)
+
+        subclass = cls._registry.get(value)
+        if subclass is None:
+            raise ValueError("Unknown type value: %s" % value)
+
+        # 递归检查子类是否还有自己的 discriminator_field（多层分发）
+        sub_field = getattr(subclass, "discriminator_field", None)
+        if (
+            sub_field is not None
+            and sub_field != field
+            and hasattr(subclass, "_registry")
+            and subclass._registry
+        ):
+            # 子类有自己的 discriminator_field，继续递归分发
+            return subclass.from_dict(raw)
+        else:
+            # 子类没有 discriminator_field，直接构造
+            return subclass.model_validate(raw)
+
+    @classmethod
+    def from_type(cls, data: dict, type_value: str, raw: bool = True) -> Self:
+        """根据指定的type_value从dict构造实例
+
+        Args:
+            data: 原始数据字典
+            type_value: discriminator_value的值，用于匹配具体子类
+            raw: 是否从model_validate方法构造实例，
+                 否则调用子类的from_raw方法.
+
+        Returns:
+            对应子类的实例
+        """
+        subclass = cls._registry.get(type_value)
+        if subclass is None:
+            raise ValueError("Unknown type value: %s" % type_value)
+        if raw:
+            return subclass.model_validate(data)
+        else:
+            return subclass.from_raw(data)
+
+    def __repr__(self):
+        # 覆盖BaseModel的__repr__，使用BaseDataMixin的实现
+        return BaseDataMixin.__repr__(self)
+
+    def __str__(self):
+        return self.__repr__()
+
+
+BaseDataModelT = TypeVar("BaseDataModelT", bound=BaseDataModel)
+
+
+class AutoDispatchList(RootModel[list[BaseDataModelT]], Generic[BaseDataModelT]):
+    """
+    自动对 list 中的 dict 进行 registry 分发
+    """
+
+    # root: list[BaseDataModelT]
+
+    # 子类必须指定 element_type
+    @classmethod
+    def element_type(cls) -> type[BaseDataModelT]: ...
+
+    @model_validator(mode="before")
+    @classmethod
+    def dispatch_elements(cls, value):
+        if not isinstance(value, list):
+            return value
+
+        result = []
+        for item in value:
+            if isinstance(item, dict):
+                result.append(cls.element_type().from_dict(item))
+            else:
+                result.append(item)
+
+        return result
+
+    # 辅助方法，方便调试和展示
+
+    def __repr__(self):
+        core_properties_str: str = self._get_core_properties_str()
+        return "%s(%s)" % (self.__class__.__name__, core_properties_str)
+
+    def __str__(self):
+        return self.__repr__()
+
+    def _get_core_properties_str(self) -> str:
+        excludes = {"raw_data"}
+        props = {
+            k: v
+            for k, v in vars(self).items()
+            if not k.startswith("_") and k not in excludes
+        }
+        parts = ["%s=%r" % (k, v) for k, v in props.items()]
+        return ", ".join(parts)

butterbot/core/event/README.md

@@ -0,0 +1 @@
+--- 待施工 ---

butterbot/core/event/__init__.py

@@ -0,0 +1,10 @@
+from .event import Event
+from .event_bus import EventBus
+from .subscriber import Subscriber, SubscriberGroup
+
+__all__ = [
+    "Event",
+    "EventBus",
+    "Subscriber",
+    "SubscriberGroup",
+]

butterbot/core/event/event.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass, field
+from typing import Generic
+from uuid import uuid4
+
+from butterbot.core.data import BaseDataT
+from butterbot.core.types import BaseType
+
+
+@dataclass
+class Event(Generic[BaseDataT]):
+    """事件类，包含数据和状态.
+
+    Attributes:
+        data: 事件数据
+        status: 事件状态
+        id: 事件唯一标识符
+    """
+
+    data: BaseDataT
+    status: BaseType
+    id: str = field(default_factory=lambda: str(uuid4()))
+
+    def __repr__(self) -> str:
+        return "Event(data=%s, status=%s)" % (self.data, self.status)
+
+    def __str__(self) -> str:
+        return self.__repr__()

butterbot/core/event/event_bus.py

@@ -0,0 +1,276 @@
+import asyncio
+import inspect
+import re
+from collections.abc import Callable, Coroutine
+from functools import wraps
+from logging import getLogger
+from typing import TYPE_CHECKING, Any, Union
+from uuid import UUID
+
+from .event import Event
+from .subscriber import Subscriber, SubscriberGroup
+
+if TYPE_CHECKING:
+    from butterbot.core.filter import BaseFilter
+    from butterbot.core.types import BaseType
+
+_log = getLogger(__name__)
+
+
+class EventBus:
+    """事件总线，管理事件的订阅和发布."""
+
+    def __init__(self):
+        """初始化事件总线."""
+        # 使用订阅组管理订阅者
+        self._subscriber_group = SubscriberGroup()
+        # 持有 create_task 返回的 Task 强引用，防止 GC 回收未完成的任务
+        self._background_tasks: set[asyncio.Task] = set()
+        # 已关闭的总线不再接受 publish
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        """是否已关闭（关闭后 :meth:`publish` 不再派发事件）."""
+        return self._closed
+
+    @property
+    def pending_callbacks(self) -> int:
+        """当前尚未完成的回调数量."""
+        return sum(1 for task in self._background_tasks if not task.done())
+
+    def _wrap_callback(
+        self,
+        func: Callable,
+        event_filter: "BaseFilter | None" = None,
+    ) -> Callable[[Event], Coroutine[Any, Any, None]]:
+        """检查并包装回调函数.
+
+        验证函数是否为协程函数，并用 @wraps 保留原函数元信息。
+        若提供了 event_filter，将过滤逻辑一并包装到回调中。
+
+        Args:
+            func: 原始回调函数
+            event_filter: 可选的事件内容过滤器
+
+        Returns:
+            包装后的回调函数
+
+        Raises:
+            TypeError: 如果回调函数不是协程函数
+        """
+        if not inspect.iscoroutinefunction(func):
+            raise TypeError("回调函数 '%s' 必须是协程函数" % func.__name__)
+
+        if event_filter is not None:
+
+            @wraps(func)
+            async def wrapper(event: Event) -> None:
+                if event_filter.check(event):
+                    return await func(event)
+                _log.debug("事件%s被过滤器 %s 拦截", event.id, event_filter)
+
+            return wrapper
+
+        @wraps(func)
+        async def wrapper(event: Event) -> None:
+            return await func(event)
+
+        return wrapper
+
+    def add_subscriber(
+        self,
+        uuid: UUID,
+        callback: Callable[[Event], Coroutine[Any, Any, None]],
+        status: Union[str, re.Pattern[str], "BaseType"],
+        supported_types: "type[BaseType] | None" = None,
+        *,
+        event_filter: "BaseFilter | None" = None,
+    ) -> None:
+        """添加订阅者.
+
+        Args:
+            uuid: 发布器的唯一标识符
+            callback: 回调函数，接收 Event 参数
+            status: 状态过滤器（``BaseType`` 枚举或 ``str`` 正则）
+            supported_types: 事件源声明的 ``BaseType`` 枚举类。
+                订阅规则将在注册期编译为具体状态到回调的映射。
+            event_filter: 可选的事件内容过滤器，只有通过过滤器的事件才触发回调。
+        """
+        wrapper = self._wrap_callback(callback, event_filter=event_filter)
+
+        subscriber = Subscriber(
+            callback=wrapper,
+            status_filter=status,
+            event_filter=event_filter,
+        )
+        self._subscriber_group.add(uuid, subscriber, supported_types)
+        _log.debug(
+            "为 '%s' 注册订阅者 callback=%s, status_filter=%s)",
+            uuid,
+            callback.__name__,
+            status,
+        )
+
+    def subscribe(
+        self,
+        uuid: UUID,
+        status: Union[str, re.Pattern[str], "BaseType"],
+        supported_types: "type[BaseType] | None" = None,
+        *,
+        event_filter: "BaseFilter | None" = None,
+    ) -> Callable:
+        """装饰器：订阅事件.
+
+        Args:
+            uuid: 发布器的唯一标识符
+            status: 状态过滤器（``BaseType`` 枚举或 ``str`` 正则）
+            supported_types: 事件源声明的 ``BaseType`` 枚举类
+            event_filter: 可选的事件内容过滤器，只有通过过滤器的事件才触发回调
+
+        Returns:
+            装饰器函数
+
+        Usage:
+            @bus.subscribe(keys=[123456], status=LiveType.OPEN)
+            async def on_open(event: Event):
+                print(event)
+        """
+
+        def decorator(func: Callable[[Event], Coroutine[Any, Any, None]]) -> Callable:
+            self.add_subscriber(
+                uuid, func, status, supported_types, event_filter=event_filter
+            )
+            return func
+
+        return decorator
+
+    def remove_subscribers(self, uuid: UUID) -> int:
+        """移除某个事件源的全部订阅.
+
+        事件源被移除时必须调用，否则派发表中该 uuid 的回调会永久残留。
+
+        Args:
+            uuid: 发布器的唯一标识符
+
+        Returns:
+            被移除的回调数量
+        """
+        return self._subscriber_group.remove(uuid)
+
+    async def close(self, timeout: float = 5.0) -> None:
+        """关闭事件总线：停止接受新事件，并排空正在执行的回调.
+
+        关闭序列：
+
+        1. 置 ``closed`` —— 之后 :meth:`publish` 只记录警告、不再派发；
+        2. 等待所有 in-flight 回调完成，最长 ``timeout`` 秒；
+        3. 超时未完成的回调被 ``cancel()`` 并 ``await`` 到真正结束。
+
+        不做这件事的后果是进程退出时 pending 回调被 GC，
+        Python 会打印 ``Task was destroyed but it is pending!``，
+        且用户回调可能执行到一半被掐断。
+
+        该方法幂等；从回调内部调用时会跳过调用者自身的 task，不会自我等待。
+
+        Args:
+            timeout: 等待回调完成的秒数，超时后强制取消
+        """
+        if self._closed:
+            return
+        self._closed = True
+
+        current = asyncio.current_task()
+        pending = [
+            task
+            for task in self._background_tasks
+            if not task.done() and task is not current
+        ]
+        if not pending:
+            self._background_tasks.clear()
+            _log.debug("EventBus 已关闭（无待完成回调）")
+            return
+
+        _log.info(
+            "EventBus 正在等待 %s 个回调完成（超时 %.1fs）", len(pending), timeout
+        )
+        _, not_done = await asyncio.wait(pending, timeout=timeout)
+
+        if not_done:
+            _log.warning("%s 个回调在 %.1fs 内未完成，强制取消", len(not_done), timeout)
+            for task in not_done:
+                task.cancel()
+            await asyncio.gather(*not_done, return_exceptions=True)
+
+        self._background_tasks.clear()
+        _log.info("EventBus 已关闭")
+
+    def _task_done_callback(
+        self,
+        task: asyncio.Task,
+        uuid: UUID,
+        callback_name: str,
+        status_value: str,
+    ) -> None:
+        """后台任务完成回调，检查并记录异常.
+
+        Args:
+            task: 已完成的 asyncio.Task
+            uuid: 发布器的唯一标识符
+            callback_name: 回调函数名
+            status_value: 事件状态值
+        """
+        self._background_tasks.discard(task)
+
+        try:
+            exc = task.exception()
+        except asyncio.CancelledError:
+            return
+
+        if exc is not None:
+            _log.exception(
+                "订阅者回调执行失败 (uuid=%s, callback=%s, status=%s)",
+                uuid,
+                callback_name,
+                status_value,
+                exc_info=exc,
+            )
+
+    async def publish(self, uuid: UUID, event: Event) -> None:
+        """发布事件.
+
+        发布指定发布器的事件，触发所有匹配的订阅者回调。
+
+        总线已关闭时事件被丢弃（记录警告），避免在关闭排空过程中又派生新回调。
+
+        Args:
+            uuid: 发布器的唯一标识符
+            event: 要发布的事件
+        """
+        if self._closed:
+            _log.warning(
+                "EventBus 已关闭，丢弃事件 (uuid=%s, status=%s)",
+                uuid,
+                event.status.value,
+            )
+            return
+
+        # 查表派发：根据 uuid + 状态值直接获取所有已编译的回调
+        callbacks = self._subscriber_group.get_callbacks(uuid, event.status)
+
+        for callback in callbacks:
+            callback_name = getattr(callback, "__name__", "<lambda>")
+            # 异步执行回调，保留强引用防止 GC 回收
+            task = asyncio.create_task(callback(event))
+            self._background_tasks.add(task)
+            task.add_done_callback(
+                lambda t, u=uuid, cn=callback_name, sv=event.status.value: (
+                    self._task_done_callback(t, u, cn, sv)
+                )
+            )
+            _log.debug(
+                "触发订阅者 (uuid=%s, callback=%s, status=%s)",
+                uuid,
+                callback_name,
+                event.status.value,
+            )

butterbot/core/event/subscriber.py

@@ -0,0 +1,130 @@
+import re
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+from logging import getLogger
+from typing import TYPE_CHECKING, Any, Union
+from uuid import UUID
+
+from butterbot.core.exceptions import SubscriptionError
+from butterbot.core.types import BaseType
+
+if TYPE_CHECKING:
+    from butterbot.core.filter import BaseFilter
+
+from .event import Event
+
+_log = getLogger(__name__)
+
+
+@dataclass
+class Subscriber:
+    """订阅者信息.
+
+    Attributes:
+        callback: 回调函数
+        status_filter: 状态过滤器（``BaseType`` 枚举、``str`` 或 ``re.Pattern[str]`` 正则）
+        event_filter: 事件过滤器（``BaseFilter`` 实例，仅用于调试/内省）
+    """
+
+    callback: Callable[[Event], Coroutine[Any, Any, None]]
+    status_filter: Union[str, re.Pattern[str], "BaseType"]
+    event_filter: "BaseFilter | None" = None
+
+
+class SubscriberGroup:
+    """订阅组类，管理订阅者的注册与派发.
+
+    订阅规则在注册时编译展开：根据事件源的 ``supported_types`` 枚举类，
+    将订阅规则匹配到所有具体的状态值，建立 ``uuid→status_value→callbacks``
+    的派发表。``publish`` 时只需 O(1) 查表，无需运行时遍历和匹配。
+
+    未提供 ``supported_types`` 的调用将抛出 ``TypeError``。
+    """
+
+    def __init__(self):
+        """初始化订阅组."""
+        # 编译派发表：uuid -> concrete_status -> [callback, ...]
+        self._dispatch_table: dict[UUID, dict[BaseType, list[Callable]]] = {}
+
+    def add(
+        self,
+        uuid: UUID,
+        subscriber: Subscriber,
+        supported_types: "type[BaseType] | None" = None,
+    ) -> None:
+        """添加订阅者，将订阅规则编译展开存入派发表.
+
+        Args:
+            uuid: 发布器的唯一标识符
+            subscriber: 订阅者对象
+            supported_types: 事件源声明的 ``BaseType`` 枚举类。
+                为 ``None`` 时抛出 ``TypeError``。
+
+        Raises:
+            TypeError: 未提供 ``supported_types``
+            SubscriptionError: 订阅规则在 ``supported_types`` 中无任何匹配
+        """
+        if supported_types is None:
+            raise TypeError(
+                "订阅规则编译需要事件源声明 supported_types。"
+                "请在事件源类中设置 supported_types = <BaseType 子类>"
+                "（例如 class MySource(BaseSource): supported_types = MyType）。"
+            )
+
+        # 将订阅规则展开到所有匹配的具体状态
+        matched = supported_types.matching_statuses(subscriber.status_filter)
+
+        # 无匹配意味着这个订阅永远不会触发——几乎总是状态值或正则写错了。
+        # 静默丢弃会让用户面对"回调不执行"却无从下手，因此直接报错。
+        if not matched:
+            raise SubscriptionError(
+                "订阅规则 %r 在 %s 中无匹配的具体状态，该订阅永远不会触发。"
+                "可用的状态值：%s"
+                % (
+                    subscriber.status_filter,
+                    supported_types.__name__,
+                    [member.value for member in supported_types],
+                )
+            )
+
+        status_map = self._dispatch_table.setdefault(uuid, {})
+        for status in matched:
+            status_map.setdefault(status, []).append(subscriber.callback)
+
+    def remove(self, uuid: UUID) -> int:
+        """移除某个事件源的全部订阅.
+
+        用于事件源被移除时清理派发表——否则该 uuid 的回调会永久残留，
+        且同一 uuid 的新事件源会意外继承旧订阅。
+
+        Args:
+            uuid: 发布器的唯一标识符
+
+        Returns:
+            被移除的回调数量（含同一回调注册到多个状态的重复计数）
+        """
+        status_map = self._dispatch_table.pop(uuid, None)
+        if not status_map:
+            return 0
+        removed = sum(len(callbacks) for callbacks in status_map.values())
+        _log.debug("移除 '%s' 的 %s 个订阅回调", uuid, removed)
+        return removed
+
+    def get_callbacks(self, uuid: UUID, status: BaseType) -> tuple[Callable, ...]:
+        """获取指定事件源和状态值对应的所有回调函数快照.
+
+        返回不可变元组作为快照，确保 publish 遍历期间不受并发 add 影响。
+
+        Args:
+            uuid: 发布器的唯一标识符
+            status: 事件状态（``BaseType`` 枚举成员）
+
+        Returns:
+            回调函数元组（无匹配时返回空元组）
+        """
+        return tuple(self._dispatch_table.get(uuid, {}).get(status, []))
+
+    @property
+    def uids(self) -> list[UUID]:
+        """获取所有已注册的发布器列表."""
+        return list(self._dispatch_table.keys())