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

butterbot/core/exceptions.py

@@ -0,0 +1,90 @@
+"""框架异常层级.
+
+框架主动抛出的异常都继承 :class:`ButterError`，用户代码既可以用一个
+``except ButterError`` 兜住框架内部的全部错误，也可以按子类精确区分错误来源::
+
+    from butterbot.app import ButterError, ConfigError
+
+    try:
+        app = BotApp()
+        app.run()
+    except ConfigError as e:
+        print("配置有问题:", e)
+    except ButterError as e:
+        print("框架错误:", e)
+
+部分异常同时继承内置异常（如 :class:`ConfigError` 继承 ``ValueError``），
+这样既能被新的类型精确捕获，也不会让原本 ``except ValueError`` 的调用方漏掉。
+"""
+
+from collections.abc import Mapping
+
+
+class ButterError(Exception):
+    """butterbot 所有框架异常的基类."""
+
+
+class ConfigError(ButterError, ValueError):
+    """配置错误.
+
+    触发场景：配置文件格式非法、配置项构建失败、
+    以及事件源/API 所需的配置键缺失。
+    """
+
+
+class LifecycleError(ButterError, RuntimeError):
+    """生命周期状态错误.
+
+    触发场景：在已关闭的 ``SourceManager`` 上添加事件源、
+    在已关闭的 ``EventBus`` 上发布事件等。
+    """
+
+
+class SourceError(ButterError):
+    """事件源相关错误的基类."""
+
+
+class SourceStartError(SourceError):
+    """一个或多个事件源启动失败.
+
+    由 ``SourceManager.start()`` 在批量启动结束后抛出。抛出前所有已成功启动的
+    事件源都已被回滚（stop），因此捕获到该异常时应用处于"未启动"状态。
+
+    Attributes:
+        failures: ``{事件源描述: 原始异常}``，保留每个失败源的真实异常对象
+    """
+
+    def __init__(self, failures: Mapping[str, BaseException]) -> None:
+        """初始化.
+
+        Args:
+            failures: 事件源描述到原始异常的映射
+        """
+        self.failures: dict[str, BaseException] = dict(failures)
+        detail = "; ".join(
+            "%s: %s" % (name, exc) for name, exc in self.failures.items()
+        )
+        super().__init__("以下事件源启动失败: %s" % detail)
+
+
+class ApiError(ButterError):
+    """API 构建或调用错误."""
+
+
+class SubscriptionError(ButterError, ValueError):
+    """订阅注册错误.
+
+    触发场景：订阅规则在事件源声明的 ``supported_types`` 中无任何匹配的具体状态
+    —— 这种订阅永远不会被触发，绝大多数情况下是状态值或正则写错了。
+    """
+
+
+__all__ = [
+    "ApiError",
+    "ButterError",
+    "ConfigError",
+    "LifecycleError",
+    "SourceError",
+    "SourceStartError",
+    "SubscriptionError",
+]

butterbot/core/filter/__init__.py

@@ -0,0 +1,11 @@
+from .base_filter import (
+    AndFilter,
+    BaseFilter,
+    OrFilter,
+)
+
+__all__ = [
+    "AndFilter",
+    "BaseFilter",
+    "OrFilter",
+]

butterbot/core/filter/base_filter.py

@@ -0,0 +1,74 @@
+from abc import ABC, abstractmethod
+from logging import getLogger
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from butterbot.core.event import Event
+
+_log = getLogger(__name__)
+
+
+class BaseFilter(ABC):
+    """过滤器基类."""
+
+    filters: Any
+
+    @abstractmethod
+    def check(self, event: "Event") -> bool:
+        """检查事件是否通过过滤器
+
+        Args:
+            event: 消息事件
+
+        Returns:
+            bool: True 表示通过过滤器，False 表示被拦截
+        """
+        pass
+
+    def __repr__(self) -> str:
+        return "<%s filters=%s>" % (self.__class__.__name__, self.filters)
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __and__(self, other: "BaseFilter") -> "BaseFilter":
+        """使用 & 合并过滤器, 并支持链式调用, 处理顺序为传入顺序."""
+        return AndFilter(self, other)
+
+    def __or__(self, other: "BaseFilter") -> "BaseFilter":
+        """使用 | 合并过滤器, 并支持链式调用, 处理顺序为传入顺序."""
+        return OrFilter(self, other)
+
+
+class AndFilter(BaseFilter):
+    """与过滤器."""
+
+    def __init__(self, *filters: BaseFilter):
+        self.filters = list(filters)
+
+    def check(self, event: "Event") -> bool:
+        """检查事件是否通过所有过滤器."""
+        for f in self.filters:
+            if not f.check(event):
+                _log.debug(
+                    "事件%s被过滤器参数 %s 拦截, 不再继续检查", event.id, f.filters
+                )
+                return False
+        _log.debug("事件%s通过所有%s与过滤器", event.id, self)
+        return True
+
+
+class OrFilter(BaseFilter):
+    """或过滤器."""
+
+    def __init__(self, *filters: BaseFilter):
+        self.filters = list(filters)
+
+    def check(self, event: "Event") -> bool:
+        """检查事件是否通过任一过滤器."""
+        for f in self.filters:
+            if f.check(event):
+                _log.debug("事件%s通过过滤器参数 %s, 不再继续检查", event.id, f.filters)
+                return True
+        _log.debug("事件%s未通过%s或过滤器", event.id, self)
+        return False

butterbot/core/source/README.md

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

butterbot/core/source/__init__.py

@@ -0,0 +1,9 @@
+from .base_source import (
+    BaseSource,
+    BaseSourceT,
+)
+
+__all__ = [
+    "BaseSource",
+    "BaseSourceT",
+]

butterbot/core/source/base_source.py

@@ -0,0 +1,134 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, ClassVar, TypeVar
+from uuid import UUID, uuid4
+
+if TYPE_CHECKING:
+    from butterbot.core.context import AppContext
+    from butterbot.core.types import BaseType
+
+
+class BaseSource(ABC):
+    """事件源基类.
+
+    Source 负责：
+    - 产生事件数据
+    - 通过 EventBus 发布事件
+    - 管理自己的生命周期（start/stop）
+
+    子类只需实现 :meth:`on_start` 和 :meth:`on_stop`，
+    无需手动管理 ``self.running`` 状态——
+    :meth:`start` 和 :meth:`stop` 已自动处理。
+
+    Attributes:
+        uuid: 唯一标识符，由 SourceManager 内部管理
+        running: 运行状态（由 start/stop 自动管理，子类不应直接修改）
+        config_key: 配置键，子类可覆盖此类属性作为默认值
+        supported_types: 事件源支持的 ``BaseType`` 枚举类，用于订阅规则编译
+    """
+
+    config_key: str = ""
+
+    # 事件源支持的 BaseType 枚举类。子类必须覆盖此属性，
+    # 例如 supported_types = DynamicType。
+    # 未声明时订阅将抛出 TypeError。
+    supported_types: ClassVar[type["BaseType"] | None] = None
+
+    def __init_subclass__(cls) -> None:
+        """子类初始化检查."""
+        super().__init_subclass__()
+
+        if cls.__name__ == "BaseSource":
+            return
+
+        if not hasattr(cls, "supported_types"):
+            raise TypeError(f"{cls.__name__} must define supported_types")
+
+    def __init__(
+        self,
+        uuid: UUID | None = None,
+        *,
+        config_key: str | None = None,
+    ) -> None:
+        """初始化事件源.
+
+        Args:
+            uuid: 可选，指定 UUID，默认自动生成
+            config_key: 可选，覆盖类级默认配置键
+        """
+        self.uuid: UUID = uuid or uuid4()
+        self.running: bool = False
+        self._ctx: "AppContext | None" = None
+        if config_key is not None:
+            self.config_key = config_key
+
+    async def start(self) -> None:
+        """启动事件源（模板方法）.
+
+        自动管理 ``running`` 状态，然后委托给 :meth:`on_start`。
+        子类不应重写此方法，应实现 :meth:`on_start`。
+
+        :meth:`on_start` 抛出异常（含 ``CancelledError``）时，
+        ``running`` 会回滚为 ``False`` 后再向上传播——否则启动失败的事件源
+        会以"运行中"的假象留在应用里，而它的资源其实从未建立起来。
+
+        Raises:
+            Exception: :meth:`on_start` 抛出的任何异常，原样向上传播
+        """
+        if self.running:
+            return
+        self.running = True
+        try:
+            await self.on_start()
+        except BaseException:
+            self.running = False
+            raise
+
+    async def stop(self) -> None:
+        """停止事件源（模板方法）.
+
+        自动管理 ``running`` 状态，然后委托给 :meth:`on_stop`。
+        子类不应重写此方法，应实现 :meth:`on_stop`。
+        """
+        if not self.running:
+            return
+        self.running = False
+        await self.on_stop()
+
+    @abstractmethod
+    async def on_start(self) -> None:
+        """子类实现：事件源启动逻辑.
+
+        在 :meth:`start` 中被调用，此时 ``self.running`` 已为 ``True``。
+        """
+
+    @abstractmethod
+    async def on_stop(self) -> None:
+        """子类实现：事件源停止逻辑.
+
+        在 :meth:`stop` 中被调用，此时 ``self.running`` 已为 ``False``。
+        """
+
+    def bind(self, ctx: "AppContext") -> None:
+        """绑定应用上下文.
+
+        由 SourceManager 在启动时调用，注入依赖。
+
+        Args:
+            ctx: 应用上下文
+        """
+        self._ctx = ctx
+
+    @property
+    def ctx(self) -> "AppContext":
+        """获取应用上下文."""
+        if self._ctx is None:
+            raise RuntimeError("Source 尚未绑定上下文，请先调用 bind()")
+        return self._ctx
+
+    @property
+    def is_running(self) -> bool:
+        """检查是否正在运行."""
+        return self.running
+
+
+BaseSourceT = TypeVar("BaseSourceT", bound=BaseSource)

butterbot/core/types/__init__.py

@@ -0,0 +1,9 @@
+from .base_type import (
+    BaseType,
+    BaseTypeT,
+)
+
+__all__ = [
+    "BaseType",
+    "BaseTypeT",
+]

butterbot/core/types/base_type.py

@@ -0,0 +1,74 @@
+import re
+from enum import Enum
+from typing import TypeVar, Union
+
+_BaseTypeSelf = Union[str, re.Pattern[str], "BaseType"]
+
+
+class BaseType(str, Enum):
+    """标签枚举基类，提供通用的匹配方法."""
+
+    @property
+    def scope(self) -> str:
+        """返回标签的作用域."""
+        return self.value.split(".", 1)[0]
+
+    @property
+    def state(self) -> str:
+        """返回标签的状态."""
+        return self.value.split(".", 1)[1]
+
+    def matches(self, rule: _BaseTypeSelf) -> bool:
+        """判断状态是否匹配.
+
+        支持三种匹配方式：
+
+        - ``BaseType``: 按枚举类型匹配（需同 type、同 scope）
+          - state 为 "all" 时通配同 scope 下所有状态
+          - 支持层级匹配：父状态匹配子状态（如 "message" 匹配 "message.group"）
+        - ``str``: 作为正则表达式，用 ``re.fullmatch`` 与 ``self.value`` 匹配
+        - ``re.Pattern[str]``: 编译好的正则对象，直接调用其 ``fullmatch`` 方法
+
+        Args:
+            rule: 状态过滤器（``BaseType`` 枚举，``str`` 正则，或编译好的 ``re.Pattern``）
+
+        Returns:
+            bool: 匹配结果
+        """
+        if isinstance(rule, BaseType):
+            # 枚举匹配：需同 type、同 scope；state="all" 通配；层级父匹配子
+            if type(self) is type(rule):
+                if self.scope == rule.scope:
+                    if (
+                        self.state == rule.state
+                        or rule.state == "all"
+                        or self.state.startswith(rule.state + ".")
+                    ):
+                        return True
+                    return False
+                return False
+            return False
+
+        if isinstance(rule, re.Pattern):
+            return bool(rule.fullmatch(self.value))
+
+        # str 正则匹配：直接与 self.value 全量匹配
+        return bool(re.fullmatch(rule, self.value))
+
+    @classmethod
+    def matching_statuses(cls, rule: _BaseTypeSelf) -> list["BaseType"]:
+        """返回当前枚举类中所有匹配给定规则的成员.
+
+        遍历当前枚举类的所有成员，筛掉通配标签（state="all"），
+        返回余下成员中能通过 ``matches(rule)`` 的元素列表。
+
+        Args:
+            rule: 状态过滤器（``BaseType`` 枚举、``str`` 或 ``re.Pattern`` 正则）
+
+        Returns:
+            匹配的枚举成员列表（不含 state="all" 的通配成员）
+        """
+        return [m for m in cls if m.state != "all" and m.matches(rule)]
+
+
+BaseTypeT = TypeVar("BaseTypeT", bound=BaseType)

butterbot/sources/__init__.py

@@ -0,0 +1 @@
+"""事件源实现包：每个子包适配一个外部平台（napcat、bilibili 等）."""

butterbot/sources/bilibili/README.md

@@ -0,0 +1,10 @@
+# Bilibili 适配文档
+
+Bilibili 的使用与 API 文档已迁移到统一文档站：
+
+- [Bilibili 功能指南](../../../docs/features/bilibili.md)
+- [内置事件源 API](../../../docs/api/builtin-sources.md)
+- [Bilibili 示例](../../../docs/examples/bilibili.md)
+
+本文件保留用于兼容仓库旧链接。新文档以当前三个 Source、`BilibiliApi`、类型、
+测试和示例为准。

butterbot/sources/bilibili/__init__.py

@@ -0,0 +1,20 @@
+from .api import BilibiliApi
+from .source import (
+    BiliDanmakuSource,
+    BiliDynamicSource,
+    BiliLiveSource,
+)
+from .types import DanmakuType, DynamicType, LiveType
+
+__all__ = [
+    "BiliDanmakuSource",
+    # 事件源类
+    "BiliDynamicSource",
+    "BiliLiveSource",
+    # API类
+    "BilibiliApi",
+    # 数据类型类
+    "DanmakuType",
+    "DynamicType",
+    "LiveType",
+]

butterbot/sources/bilibili/api/__init__.py

@@ -0,0 +1,5 @@
+from .bili_api import BilibiliApi
+
+__all__ = [
+    "BilibiliApi",
+]

butterbot/sources/bilibili/api/bili_api.py

@@ -0,0 +1,123 @@
+from logging import getLogger
+from typing import TYPE_CHECKING
+
+from bilibili_api import Credential
+from bilibili_api.dynamic import get_dynamic_page_info
+from bilibili_api.live import LiveDanmaku, LiveRoom
+from bilibili_api.user import User
+
+from butterbot.core.api import BaseApi
+
+from ..data import DynamicData, LiveRoomData, get_max_id
+from ..data.dto import DynamicDTO, LiveRoomDTO
+
+if TYPE_CHECKING:
+    from butterbot.core.context import ApiRegistry
+
+_log = getLogger("BilibiliApi")
+
+
+class BilibiliApi(BaseApi):
+    def __init__(self, credential: Credential | None) -> None:
+        """初始化BilibiliApi客户端
+        Args:
+            credential: Optional[Credential]: B站用户凭证
+        """
+        self._credential = credential
+
+    @classmethod
+    def create(cls, ctx: "ApiRegistry", config_key: str = "bilibili") -> "BilibiliApi":
+        """
+        从上下文创建 BilibiliApi 实例
+        Args:
+            ctx: API 上下文
+            config_key: 配置键
+        """
+        return cls(ctx.config.get_config(config_key))
+
+    @property
+    def credential(self) -> Credential | None:
+        """获取B站用户凭证
+        Returns:
+            Optional[Credential]: B站用户凭证对象，如果未配置则返回None
+        """
+        return self._credential
+
+    async def get_all_dynamic(self, uid: int, offset: str = "") -> list[DynamicData]:
+        """
+        获取单页动态
+        Args:
+            uid (int): 用户uid
+            offset (str): 分页偏移参数
+        Returns:
+            list[DynamicData]: 动态信息对象
+        """
+        user = User(credential=self._credential, uid=uid)
+        dict_info = await user.get_dynamics_new(offset=offset)
+        if dict_info.get("items", None) is None or not dict_info.get("items"):
+            raise ValueError("未获取到动态数据或者动态数据为不完整")
+        info_dto = DynamicDTO.from_list(dict_info["items"])
+        info = [DynamicData.from_dto(dto) for dto in info_dto if dto is not None]
+        return info
+
+    async def get_new_dynamic(self, uid: int) -> DynamicData:
+        """
+        获取最新的一条动态
+        Args:
+            uid (int): 用户uid
+        Returns:
+            DynamicData: 动态信息对象
+        """
+        user = User(credential=self._credential, uid=uid)
+        dict_info = await user.get_dynamics_new()
+        max_id = get_max_id(dict_info)
+        _log.debug("获取到最大时间戳的索引为'%s'", max_id)
+        if max_id is None:
+            raise ValueError("未获取到动态数据或者动态数据为不完整")
+        dynamic_info = dict_info["items"][max_id]
+        dto = DynamicDTO.from_raw(dynamic_info)
+        if not dto:
+            raise ValueError("构造 %s 用户动态DTO对象失败" % uid)
+        info = DynamicData.from_dto(dto)
+        return info
+
+    async def get_new_dynamic_list(self) -> list[DynamicData]:
+        """获取动态主页的动态列表
+        Returns:
+            list[DynamicData]: 动态信息对象
+        """
+        if self._credential is None:  # pyright: ignore
+            raise ValueError("获取动态主页需要 B 站凭证，请配置 credential")
+        dynamic_info = await get_dynamic_page_info(self._credential)
+        if dynamic_info.get("items", None) is None or not dynamic_info.get("items"):
+            raise ValueError("未获取到动态数据或者动态数据为不完整")
+        info_dto = DynamicDTO.from_list(dynamic_info["items"])
+        info = [DynamicData.from_dto(dto) for dto in info_dto if dto is not None]
+        return info
+
+    async def get_room_info(self, room_id: int) -> LiveRoomData:
+        """
+        获取直播间信息
+        Args:
+            room_id (int): 直播间ID
+        Returns:
+            LiveRoomData: 直播间信息对象
+        """
+        live_room = LiveRoom(credential=self._credential, room_display_id=room_id)
+        live = await live_room.get_room_info()
+        dto = LiveRoomDTO.from_raw(live)
+        if dto is None:
+            raise ValueError("构造直播间 %s DTO对象失败" % room_id)
+        info = LiveRoomData.from_dto(dto)
+        return info
+
+    def get_live_danmaku(self, room_id: int) -> LiveDanmaku:
+        """
+        获取直播间弹幕对象
+        Args:
+            room_id (int): 直播间ID
+        Returns:
+            LiveDanmaku: 直播间弹幕对象
+        """
+        live_danmaku = LiveDanmaku(credential=self._credential, room_display_id=room_id)
+        return live_danmaku

butterbot/sources/bilibili/data/__init__.py

@@ -0,0 +1,52 @@
+from .danmaku_gift_data import (
+    BlindGiftData,
+    DanmakuGiftData,
+    GiftMedalData,
+)
+from .danmaku_guard_data import (
+    DanmakuGuardData,
+)
+from .danmaku_msg_data import DanmakuMsgData, MedalData
+from .dynamic_data import (
+    ArticleData,
+    AuthorData,
+    DynamicData,
+    LiveRcmdData,
+    MusicData,
+    StatData,
+    VideoData,
+    get_max_id,
+)
+from .live_room_data import (
+    AnchorInfoData,
+    LiveRoomData,
+    NoticeBoardData,
+    RoomInfoData,
+    WatchedShowData,
+)
+from .video_part import (
+    VideoPartData,
+)
+
+__all__ = [
+    "AnchorInfoData",
+    "ArticleData",
+    "AuthorData",
+    "BlindGiftData",
+    "DanmakuGiftData",
+    "DanmakuGuardData",
+    "DanmakuMsgData",
+    "DynamicData",
+    "GiftMedalData",
+    "LiveRcmdData",
+    "LiveRoomData",
+    "MedalData",
+    "MusicData",
+    "NoticeBoardData",
+    "RoomInfoData",
+    "StatData",
+    "VideoData",
+    "VideoPartData",
+    "WatchedShowData",
+    "get_max_id",
+]