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

butterbot/sources/bilibili/source/base_polling_source.py

@@ -0,0 +1,130 @@
+"""Bilibili 轮询事件源的共享生命周期与调度实现."""
+
+import asyncio
+from abc import ABC, abstractmethod
+from logging import Logger, getLogger
+from uuid import UUID
+
+from butterbot.core.source import BaseSource
+
+
+class BasePollingSource(BaseSource, ABC):
+    """按轮次轮询整数目标列表的内部基类.
+
+    领域数据获取与事件构造仍由子类负责；本类只持有生命周期任务、目标集合、
+    间隔更新，以及“每轮只等待一次”的调度契约。
+    """
+
+    _log: Logger = getLogger(__name__)
+    _source_name = "轮询监控"
+    _target_name = "目标"
+    _empty_wait = 5.0
+
+    def __init__(
+        self,
+        poll_interval: float | int,
+        watch_targets: list[int] | None = None,
+        *,
+        uuid: UUID | None = None,
+        config_key: str | None = None,
+    ) -> None:
+        super().__init__(uuid=uuid, config_key=config_key)
+        self.poll_interval: float | int = poll_interval
+        self._watch_targets: list[int] = []
+        self._poll_num = 0
+        self._task: asyncio.Task[None] | None = None
+        if watch_targets is not None:
+            self.add_members(watch_targets)
+
+    async def on_start(self) -> None:
+        """启动本事件源持有的监控任务."""
+        self._task = asyncio.create_task(self._monitor_loop())
+        self._log.info("%s已启动", self._source_name)
+
+    async def on_stop(self) -> None:
+        """取消并等待本事件源持有的监控任务."""
+        task = self._task
+        self._task = None
+        if task is not None and not task.done():
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+        self._log.info("%s已停止", self._source_name)
+
+    def add_members(self, keys: list[int]) -> None:
+        """按插入顺序添加不重复的轮询目标."""
+        for key in keys:
+            if key not in self._watch_targets:
+                self._watch_targets.append(key)
+                self._log.debug("添加%s '%s' 到监控列表", self._target_name, key)
+            else:
+                self._log.warning("%s '%s' 已存在于监控列表中", self._target_name, key)
+
+    def remove_members(self, keys: list[int]) -> None:
+        """移除轮询目标."""
+        for key in keys:
+            if key in self._watch_targets:
+                self._watch_targets.remove(key)
+                self._log.debug("从监控列表移除%s '%s'", self._target_name, key)
+            else:
+                self._log.warning("%s '%s' 不存在于监控列表中", self._target_name, key)
+
+    def set_poll_interval(self, interval: float | int) -> None:
+        """更新每轮轮询间隔."""
+        if interval <= 0:
+            self._log.error("非法参数，轮询间隔时间不可小于或等于0")
+            return
+        if interval <= 30:
+            self._log.warning("将轮询间隔时间设置为30s及以下，可能导致请求频率过高")
+        self.poll_interval = interval
+        self._log.info("轮询间隔时间已设置为 %s 秒", self.poll_interval)
+
+    @property
+    def watch_targets(self) -> list[int]:
+        """返回当前监控目标的快照."""
+        return list(self._watch_targets)
+
+    @property
+    def poll_num(self) -> int:
+        """已完成的轮询轮数."""
+        return self._poll_num
+
+    @abstractmethod
+    async def _poll_target(self, target: int) -> None:
+        """轮询单个目标并发布产生的事件."""
+
+    async def _monitor_loop(self) -> None:
+        """轮询当前全部目标，然后只等待一次再进入下一轮."""
+        self._log.info("%s循环已启动", self._source_name)
+        try:
+            while self.running:
+                targets = list(self._watch_targets)
+                if not targets:
+                    await asyncio.sleep(self._empty_wait)
+                    continue
+
+                for target in targets:
+                    if not self.running:
+                        break
+                    try:
+                        await self._poll_target(target)
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception:
+                        self._log.exception(
+                            "轮询%s '%s' 时出错", self._target_name, target
+                        )
+
+                self._poll_num += 1
+                self._log.debug("完成第 %s 轮%s", self._poll_num, self._source_name)
+                if not self.running:
+                    break
+                await asyncio.sleep(self.poll_interval)
+        except asyncio.CancelledError:
+            self._log.debug("%s循环被取消", self._source_name)
+        except Exception:
+            self._log.exception("%s循环异常", self._source_name)
+        finally:
+            self._log.info("%s循环已停止", self._source_name)

butterbot/sources/bilibili/source/bili_danmaku_source.py

@@ -0,0 +1,230 @@
+import asyncio
+import threading
+from logging import DEBUG, INFO, getLogger
+from typing import TYPE_CHECKING, TypeVar
+from uuid import UUID
+
+from butterbot.core.data import BaseDataMixin
+from butterbot.core.event import Event
+from butterbot.core.source import BaseSource
+
+from ..api import BilibiliApi
+from ..data import DanmakuGiftData, DanmakuGuardData, DanmakuMsgData
+from ..data.dto import DanmakuGiftDTO, DanmakuGuardDTO, DanmakuMsgDTO
+from ..types import DanmakuType
+
+if TYPE_CHECKING:
+    from bilibili_api.live import LiveDanmaku
+
+_log = getLogger("BiliDanmakuSource")
+_EventDataT = TypeVar("_EventDataT", bound=BaseDataMixin)
+
+
+class BiliDanmakuSource(BaseSource):
+    """B站直播弹幕事件源.
+
+    负责轮询B站直播间弹幕并发布事件。
+    """
+
+    supported_types = DanmakuType
+    config_key = "bilibili"
+
+    def __init__(
+        self,
+        room_id: list[int] | None = None,
+        debug: bool = False,
+        *,
+        watch_targets: list[int] | None = None,
+        uuid: UUID | None = None,
+        config_key: str | None = None,
+    ) -> None:
+        """初始化B站弹幕源
+
+        Args:
+            room_id: 房间号列表（兼容旧参数）
+            debug: 是否开启调试
+            watch_targets: 房间号列表，与另外两个 Bilibili source 的命名一致
+            uuid: 可选事件源 UUID
+            config_key: 可选配置键
+        """
+        if room_id is not None and watch_targets is not None:
+            raise TypeError("room_id 与 watch_targets 不能同时提供")
+        targets = room_id if room_id is not None else watch_targets
+        if targets is None:
+            raise TypeError("必须提供 room_id 或 watch_targets")
+
+        super().__init__(uuid=uuid, config_key=config_key)
+        self.room_id: list[int] = list(targets)
+        self.danmaku_list: dict[int, LiveDanmaku] = {}
+        self.debug = debug
+        self._loops: dict[int, asyncio.AbstractEventLoop] = {}
+        self._threads: dict[int, threading.Thread] = {}
+        self._main_loop: asyncio.AbstractEventLoop | None = None  # 主事件循环引用
+
+    def _run_room_thread(
+        self, room_id: int, danmaku: "LiveDanmaku", ready: threading.Event
+    ) -> None:
+        """线程入口：为该房间创建独立事件循环，以 task 方式运行弹幕连接，loop.run_forever() 驱动。"""
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        self._loops[room_id] = loop
+
+        async def _connect():
+            @danmaku.on("VERIFICATION_SUCCESSFUL")
+            async def _on_connected(_):
+                ready.set()
+                if danmaku.get_status() == 2:
+                    _log.info("房间 %s 的弹幕姬已连接", room_id)
+
+            try:
+                asyncio.get_event_loop().create_task(danmaku.connect())
+                _log.debug("等待房间 %d 的弹幕姬连接成功...", room_id)
+            except Exception as e:
+                _log.error("房间 %s 弹幕姬异常退出: %s", room_id, e)
+            finally:
+                ready.set()  # 防止异常时 ready 永远不被 set
+
+        loop.create_task(_connect())
+        loop.run_forever()
+
+    def _start_room_thread(self, room_id: int, danmaku: "LiveDanmaku") -> None:
+        """为已有的 danmaku 对象启动独立线程并等待连接建立."""
+        if room_id in self._threads and self._threads[room_id].is_alive():
+            _log.warning("房间 %s 的弹幕姬已在运行中", room_id)
+            return
+        name = "LiveDanmaku(%s)" % room_id
+        danmaku.logger = getLogger(name)
+        danmaku.logger.setLevel(DEBUG if self.debug else INFO)
+        ready = threading.Event()
+        t = threading.Thread(
+            target=self._run_room_thread,
+            args=(room_id, danmaku, ready),
+            name=name,
+            daemon=True,
+        )
+        self._threads[room_id] = t
+        _log.debug("正在为房间 %s 启动弹幕姬线程...", room_id)
+        t.start()
+
+    def start_room(self, room_id: int) -> None:
+        """启动已有的房间监控（stop_room 后可重新启动）."""
+        danmaku = self.danmaku_list.get(room_id)
+        if danmaku is None:
+            _log.warning("房间 %s 不存在，请先调用 add_new_room", room_id)
+            return
+        self._start_room_thread(room_id, danmaku)
+
+    def add_new_room(self, room_id: int) -> None:
+        """新建房间监控并在独立线程中启动."""
+        if room_id in self.danmaku_list:
+            _log.warning("房间 %s 已存在，如需重启请调用 start_room", room_id)
+            return
+        danmaku = self.api.get_live_danmaku(room_id)
+        danmaku.add_event_listener("LIVE", self.on_live)
+        danmaku.add_event_listener("DANMU_MSG", self.on_danmaku)
+        danmaku.add_event_listener("SEND_GIFT", self.on_gift)
+        danmaku.add_event_listener("GUARD_BUY", self.on_guard)
+        self.danmaku_list[room_id] = danmaku
+        _log.debug("新建了房间 %s 的弹幕姬对象，正在启动线程...", room_id)
+        self._start_room_thread(room_id, danmaku)
+
+    def stop_room(self, room_id: int) -> None:
+        """断开房间连接并等待线程真正退出（保留 danmaku 对象，可通过 start_room 重启）."""
+        danmaku = self.danmaku_list.get(room_id)
+        loop = self._loops.get(room_id)
+        if danmaku is None or loop is None:
+            _log.warning("未找到房间 %s 的弹幕姬或其事件循环", room_id)
+            return
+        # 先在房间线程的事件循环中调用 disconnect，等待其完成
+        future = asyncio.run_coroutine_threadsafe(danmaku.disconnect(), loop)
+        try:
+            future.result(timeout=10)
+        except Exception as e:
+            _log.error("停止房间 %s 时出错: %s", room_id, e)
+        # disconnect 完成后，通知 loop.run_forever() 退出，线程自然结束
+        loop.call_soon_threadsafe(loop.stop)
+        # 等待线程真正退出，确保连接已完全断开
+        t = self._threads.get(room_id)
+        if t and t.is_alive():
+            t.join(timeout=15)
+            if t.is_alive():
+                _log.warning(
+                    "房间 %s 的线程未能在超时内退出，连接可能未完全断开", room_id
+                )
+            else:
+                _log.info("房间 %s 的弹幕姬已暂停", room_id)
+        self._threads.pop(room_id, None)
+
+    def remove_room(self, room_id: int) -> None:
+        """停止并彻底移除房间监控（同时清理 danmaku 对象）."""
+        self.stop_room(room_id)  # 断开连接并等待线程退出
+        self.danmaku_list.pop(room_id, None)
+        _log.info("房间 %s 的弹幕姬已移除", room_id)
+
+    async def on_start(self) -> None:
+        """启动弹幕监控."""
+        if not self.ctx.config.get_config(self.config_key):
+            raise RuntimeError("未找到Credential配置")
+        self._main_loop = asyncio.get_running_loop()  # 保存主事件循环
+        for rid in self.room_id:
+            self.add_new_room(rid)
+        _log.info("B站弹幕姬已启动")
+
+    async def on_stop(self) -> None:
+        """停止所有房间监控."""
+        for rid in list(self._threads.keys()):
+            self.remove_room(rid)
+
+    def _publish_to_main(self, event: Event[_EventDataT]) -> None:
+        """将事件发布调度到主事件循环（线程安全）."""
+        if self._main_loop is None:
+            _log.error("主事件循环未初始化，无法发布事件")
+            raise RuntimeError("主事件循环未初始化")
+        asyncio.run_coroutine_threadsafe(
+            self.ctx.bus.publish(self.uuid, event), self._main_loop
+        )
+
+    @property
+    def api(self) -> BilibiliApi:
+        """获取 Bilibili API 实例."""
+        return self.ctx.api_ctx.get(BilibiliApi, self.config_key)
+
+    async def on_live(self, msg: dict) -> None:
+        # 开播事件
+        if not msg.get("data", {}).get("live_time", 0):
+            # data.live_time不存在时不认为是开播事件
+            _log.debug("跳过不存在live_time字段的LIVE事件")
+            return
+        raw_room_id = msg.get("room_display_id")
+        if raw_room_id is None:
+            _log.warning("消息中缺少 room_display_id，跳过开播事件")
+            return
+        room_id = int(raw_room_id)
+        info = await self.api.get_room_info(room_id)
+        event = Event(data=info, status=DanmakuType.OPEN)
+        self._publish_to_main(event)
+
+    async def on_danmaku(self, msg: dict) -> None:
+        # 弹幕事件
+        dto_data = DanmakuMsgDTO.from_raw(msg)
+        if dto_data is not None:
+            danmaku_data = DanmakuMsgData.from_dto(dto_data)
+            event = Event(data=danmaku_data, status=DanmakuType.DANMAKU)
+            self._publish_to_main(event)
+
+    async def on_gift(self, msg: dict) -> None:
+        # 礼物事件
+        dto_data = DanmakuGiftDTO.from_raw(msg)
+        if dto_data is not None:
+            danmaku_data = DanmakuGiftData.from_dto(dto_data)
+            event = Event(data=danmaku_data, status=DanmakuType.GIFT)
+            self._publish_to_main(event)
+
+    async def on_guard(self, msg: dict) -> None:
+        # 上舰事件
+        dto_data = DanmakuGuardDTO.from_raw(msg)
+        if dto_data is not None:
+            danmaku_data = DanmakuGuardData.from_dto(dto_data)
+            event = Event(data=danmaku_data, status=DanmakuType.GUARD)
+            self._publish_to_main(event)

butterbot/sources/bilibili/source/bili_dynamic_source.py

@@ -0,0 +1,135 @@
+import traceback
+from logging import getLogger
+from uuid import UUID
+
+from butterbot.core.event import Event
+from butterbot.utils import DataPair
+
+from ..api import BilibiliApi
+from ..data import DynamicData
+from ..types import DynamicType
+from .base_polling_source import BasePollingSource
+
+_log = getLogger("BiliDynamicSource")
+
+
+class BiliDynamicSource(BasePollingSource):
+    """B站动态事件源.
+
+    负责轮询B站动态并发布事件。
+    """
+
+    supported_types = DynamicType
+    config_key = "bilibili"
+    _log = _log
+    _source_name = "B站动态监控"
+    _target_name = "UID"
+
+    def __init__(
+        self,
+        poll_interval: float | int = 60,
+        watch_targets: list[int] | None = None,
+        *,
+        uuid: UUID | None = None,
+        config_key: str | None = None,
+    ) -> None:
+        """初始化动态事件源.
+        Args:
+            poll_interval: 轮询间隔时间（秒）
+            watch_targets: 监听用户列表
+        """
+        super().__init__(
+            poll_interval,
+            watch_targets,
+            uuid=uuid,
+            config_key=config_key,
+        )
+        self._dynamic_data: dict[int, DataPair[DynamicData]] = {}
+
+    @property
+    def api(self) -> BilibiliApi:
+        """获取 Bilibili API 实例."""
+        return self.ctx.api_ctx.get(BilibiliApi, self.config_key)
+
+    @property
+    def members(self) -> list[int]:
+        """获取监控成员列表."""
+        return self.watch_targets
+
+    async def _poll_data(self, uid: int) -> DynamicData | None:
+        """获取并更新动态数据.
+
+        Args:
+            uid: 用户UID
+
+        Returns:
+            新获取的动态数据
+        """
+        try:
+            new_data = await self.api.get_new_dynamic(uid)
+
+            if uid not in self._dynamic_data:
+                self._dynamic_data[uid] = DataPair()
+                _log.info("初始化 '%s' 的动态数据", uid)
+
+            self._dynamic_data[uid].update(new_data)
+            return new_data
+
+        except Exception as e:
+            _log.error("获取 '%s' 动态数据时出错: %s", uid, e)
+            raise
+
+    def _get_dynamic_status(self, uid: int) -> DynamicType:
+        """判断动态状态.
+
+        Args:
+            uid: 用户UID
+
+        Returns:
+            当前的动态状态
+        """
+        old_data = self._dynamic_data[uid].old
+        new_data = self._dynamic_data[uid].new
+        if old_data is None or new_data is None:
+            return DynamicType.NULL
+
+        old_timestamp = old_data.pub_ts
+        new_timestamp = new_data.pub_ts
+
+        if new_timestamp > old_timestamp:
+            return DynamicType.NEW
+        elif new_timestamp < old_timestamp:
+            return DynamicType.DELETED
+        else:
+            return DynamicType.NULL
+
+    async def _poll_dynamic(self, uid: int) -> None:
+        """轮询单个用户的动态.
+
+        Args:
+            uid: 用户UID
+        """
+        try:
+            new_data = await self._poll_data(uid=uid)
+
+            if new_data is None:
+                _log.warning("获取 %s 动态数据失败", uid)
+                return
+
+            status = self._get_dynamic_status(uid)
+
+            # 根据状态决定传递哪个数据
+            if status == DynamicType.DELETED:
+                data = self._dynamic_data[uid].get_data("old")
+            else:
+                data = new_data
+
+            event: Event[DynamicData] = Event(data=data, status=status)
+            await self.ctx.bus.publish(self.uuid, event)
+
+        except Exception as e:
+            _log.error("轮询 UID '%s' 动态数据时出错: %s", uid, e)
+            _log.error(traceback.format_exc())
+
+    async def _poll_target(self, target: int) -> None:
+        await self._poll_dynamic(target)

butterbot/sources/bilibili/source/bili_live_source.py

@@ -0,0 +1,137 @@
+import traceback
+from logging import getLogger
+from uuid import UUID
+
+from butterbot.core.event import Event
+from butterbot.utils import DataPair
+
+from ..api import BilibiliApi
+from ..data import LiveRoomData
+from ..types import LiveType
+from .base_polling_source import BasePollingSource
+
+_log = getLogger("BiliLiveSource")
+
+
+class BiliLiveSource(BasePollingSource):
+    """B站直播事件源.
+
+    负责轮询B站直播状态并发布事件。
+    """
+
+    supported_types = LiveType
+    config_key = "bilibili"
+    _log = _log
+    _source_name = "B站直播监控"
+    _target_name = "房间"
+
+    def __init__(
+        self,
+        poll_interval: float | int = 20,
+        watch_targets: list[int] | None = None,
+        *,
+        uuid: UUID | None = None,
+        config_key: str | None = None,
+    ) -> None:
+        """初始化直播事件源.
+        Args:
+            poll_interval: 轮询间隔时间（秒）
+            watch_targets: 监听用户列表
+        """
+        super().__init__(
+            poll_interval,
+            watch_targets,
+            uuid=uuid,
+            config_key=config_key,
+        )
+        self._live_data: dict[int, DataPair[LiveRoomData]] = {}
+
+    @property
+    def api(self) -> BilibiliApi:
+        """获取 Bilibili API 实例."""
+        return self.ctx.api_ctx.get(BilibiliApi, self.config_key)
+
+    @property
+    def rooms(self) -> list[int]:
+        """获取监控房间列表."""
+        return self.watch_targets
+
+    async def _poll_data(self, room_id: int) -> LiveRoomData | None:
+        """获取并更新直播数据.
+
+        Args:
+            room_id: 直播间ID
+
+        Returns:
+            新获取的直播数据
+        """
+        try:
+            new_data = await self.api.get_room_info(room_id)
+
+            if room_id not in self._live_data:
+                self._live_data[room_id] = DataPair()
+                _log.info("初始化房间 '%s' 的直播数据", room_id)
+
+            self._live_data[room_id].update(new_data)
+            return new_data
+
+        except Exception as e:
+            _log.error("获取房间 '%s' 直播数据时出错: %s", room_id, e)
+            raise
+
+    async def _poll_live(self, room_id: int) -> None:
+        """轮询单个房间的直播状态.
+
+        Args:
+            room_id: 直播间ID
+        """
+        try:
+            new_data = await self._poll_data(room_id=room_id)
+
+            if new_data is None:
+                _log.warning("获取房间 %s 直播数据失败", room_id)
+                return
+
+            status = self._get_live_status(room_id)
+
+            event: Event[LiveRoomData] = Event(data=new_data, status=status)
+            await self.ctx.bus.publish(self.uuid, event)
+
+        except Exception as e:
+            _log.error("轮询房间 '%s' 直播数据时出错: %s", room_id, e)
+            _log.error(traceback.format_exc())
+
+    def _get_live_status(
+        self,
+        room_id: int,
+    ) -> LiveType:
+        """判断直播状态.
+        Args:
+            room_id: 直播间ID
+
+        Returns:
+            LiveType: 当前的直播状态
+        """
+        data_pair = self._live_data[room_id]
+        old_data = data_pair.old
+        new_data = data_pair.new
+        if old_data is None or new_data is None:
+            return LiveType.NULL
+
+        old_status = old_data.room_info.live_status
+        new_status = new_data.room_info.live_status
+        # 刚开播：旧状态不是直播中(0或2)，新状态是直播中(1)
+        if old_status != 1 and new_status == 1:
+            return LiveType.OPEN
+        # 刚下播：旧状态是直播中(1)，新状态不是直播中(0或2)
+        elif old_status == 1 and new_status != 1:
+            return LiveType.CLOSE
+        # 直播中：新旧状态都是直播中(1)
+        elif old_status == 1 and new_status == 1:
+            return LiveType.ONLINE
+        # 未开播：其他情况(包括一直未开播、轮播等状态)
+        else:
+            return LiveType.OFFLINE
+
+    async def _poll_target(self, target: int) -> None:
+        await self._poll_live(target)

butterbot/sources/bilibili/types/__init__.py

@@ -0,0 +1,11 @@
+from .bili_type import (
+    DanmakuType,
+    DynamicType,
+    LiveType,
+)
+
+__all__ = [
+    "DanmakuType",
+    "DynamicType",
+    "LiveType",
+]

butterbot/sources/bilibili/types/bili_type.py

@@ -0,0 +1,32 @@
+from butterbot.core.types import BaseType
+
+
+class DynamicType(BaseType):
+    """动态状态枚举."""
+
+    ALL = "dynamic.all"  # 表示所有状态，用作通配符
+    NEW = "dynamic.new"  # 新动态
+    DELETED = "dynamic.deleted"  # 删除的动态
+    NULL = "dynamic.null"  # 无变化
+
+
+class LiveType(BaseType):
+    """直播状态枚举."""
+
+    ALL = "live.all"  # 表示所有状态，用作通配符
+    ONLINE = "live.online"  # 在线
+    OFFLINE = "live.offline"  # 离线
+    OPEN = "live.open"  # 开播
+    CLOSE = "live.close"  # 下播
+    NULL = "live.null"  # 无变化
+
+
+class DanmakuType(BaseType):
+    """弹幕状态枚举."""
+
+    ALL = "danmaku.all"  # 表示所有状态，用作通配符
+    DANMAKU = "danmaku.msg"  # 新弹幕
+    GIFT = "danmaku.gift"  # 礼物
+    GUARD = "danmaku.guard"  # 舰长
+    OPEN = "danmaku.live_open"  # 开播
+    OFFLINE = "danmaku.offline"  # 下播

butterbot/sources/napcat/README.md

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