kotonebot 0.3.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

kotonebot/backend/flow_controller.py

@@ -1,197 +1,197 @@
-import time
-import logging
-import threading
-from typing import Literal
-
-logger = logging.getLogger(__name__)
-
-class FlowController:
-    """
-    一个用于控制任务执行流程（如停止、暂停、恢复）的类。
-
-    这个类是线程安全的，提供了以下功能：
-
-    * 停止任务执行（通过中断信号）
-    * 暂停/恢复任务执行
-    * 可中断和可暂停的 sleep 功能
-    * 流程状态检查
-
-    使用方法::
-
-        controller = FlowController()
-
-        # 在任务的关键路径上调用检查
-        controller.check()
-
-        # 使用可控制的 sleep
-        controller.sleep(1.0)
-
-        # 外部控制
-        controller.request_pause()  # 暂停
-        controller.request_resume()  # 恢复
-        controller.request_stop()   # 停止
-    """
-    
-    def __init__(self):
-        self.interrupt_event: threading.Event = threading.Event()
-        """中断事件，用于停止任务"""
-
-        self.paused: bool = False
-        """暂停标志"""
-
-        self.pause_condition: threading.Condition = threading.Condition()
-        """暂停条件变量，用于线程间同步"""
-    
-    def check(self) -> None:
-        """
-        检查当前流程状态。
-
-        如果收到停止请求，则抛出 KeyboardInterrupt 异常。
-        如果收到暂停请求，则阻塞直到恢复。
-
-        这是核心的检查点方法，应在任务的关键路径上（如循环或等待前）调用。
-
-        :raises KeyboardInterrupt: 当收到停止请求时
-        """
-        # 优先检查中断信号
-        if self.interrupt_event.is_set():
-            raise KeyboardInterrupt("User requested interrupt.")
-        
-        # 检查暂停状态
-        with self.pause_condition:
-            while self.paused:
-                self.pause_condition.wait()
-    
-    def sleep(self, seconds: float) -> None:
-        """
-        一个可被中断和暂停的 sleep 方法。
-
-        与标准的 time.sleep() 不同，这个方法会响应停止和暂停请求。
-        在暂停状态下，计时器会暂停，恢复后继续计时。
-
-        :param seconds: 睡眠时间（秒）
-        :raises KeyboardInterrupt: 当收到停止请求时
-        """
-        with self.pause_condition:
-            end_time = time.time() + seconds
-            while True:
-                self.check()  # 每次循环都检查状态
-                remaining = end_time - time.time()
-                if remaining <= 0:
-                    break
-                # 等待指定时间或直到被唤醒
-                self.pause_condition.wait(timeout=remaining)
-        
-        # 结束后再次检查状态
-        self.check()
-    
-    def request_interrupt(self) -> None:
-        """
-        请求停止任务。
-
-        设置中断信号，所有正在执行的任务将在下一个检查点停止。
-        停止的优先级高于暂停。
-        """
-        logger.info('Interrupt requested.')
-        self.interrupt_event.set()
-    
-    def request_pause(self, *, wait_resume: bool = False) -> None:
-        """
-        请求暂停任务。
-
-        设置暂停标志，所有正在执行的任务将在下一个检查点暂停。
-        如果任务已经暂停，此操作无效果。
-        """
-        with self.pause_condition:
-            if not self.paused:
-                logger.info('Pause requested.')
-                self.paused = True
-            if wait_resume:
-                self.check()
-    
-    def request_resume(self) -> None:
-        """
-        请求恢复任务。
-
-        清除暂停标志并通知所有等待的线程恢复执行。
-        如果任务没有暂停，此操作无效果。
-        """
-        with self.pause_condition:
-            if self.paused:
-                logger.info('Resume requested.')
-                self.paused = False
-                self.pause_condition.notify_all()
-    
-    def toggle_pause(self) -> bool:
-        """
-        切换暂停/恢复状态。
-
-        :returns: 操作后的暂停状态。True 表示已暂停，False 表示已恢复。
-        """
-        with self.pause_condition:
-            logger.info('Pause toggled.')
-            if self.paused:
-                self.paused = False
-                self.pause_condition.notify_all()
-                return False
-            else:
-                self.paused = True
-                return True
-    
-    def clear_interrupt(self) -> None:
-        """
-        清除中断信号。
-
-        用于任务正常结束或重启时重置状态。
-        通常在开始新任务前调用。
-        """
-        self.interrupt_event.clear()
-        logger.info('Interrupt cleared.')
-    
-    def reset(self) -> None:
-        """
-        重置流程控制器到初始状态。
-
-        清除所有信号和状态，相当于重新创建一个新的控制器。
-        """
-        self.interrupt_event.clear()
-        with self.pause_condition:
-            if self.paused:
-                self.paused = False
-                self.pause_condition.notify_all()
-        logger.info('FlowController reset.')
-    
-    @property
-    def is_interrupted(self) -> bool:
-        """
-        检查是否收到中断请求。
-
-        :returns: True 表示已收到中断请求
-        """
-        return self.interrupt_event.is_set()
-    
-    @property
-    def is_paused(self) -> bool:
-        """
-        检查是否处于暂停状态。
-
-        :returns: True 表示当前处于暂停状态
-        """
-        return self.paused
-    
-    @property
-    def status(self) -> Literal['running', 'paused', 'interrupted']:
-        """
-        获取当前状态的字符串描述。
-
-        :returns: 状态描述，可能的值：'running', 'paused', 'interrupted'
-        """
-        if self.is_interrupted:
-            return 'interrupted'
-        elif self.is_paused:
-            return 'paused'
-        else:
-            return 'running'
-    
-    def __repr__(self) -> str:
+import time
+import logging
+import threading
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+class FlowController:
+    """
+    一个用于控制任务执行流程（如停止、暂停、恢复）的类。
+
+    这个类是线程安全的，提供了以下功能：
+
+    * 停止任务执行（通过中断信号）
+    * 暂停/恢复任务执行
+    * 可中断和可暂停的 sleep 功能
+    * 流程状态检查
+
+    使用方法::
+
+        controller = FlowController()
+
+        # 在任务的关键路径上调用检查
+        controller.check()
+
+        # 使用可控制的 sleep
+        controller.sleep(1.0)
+
+        # 外部控制
+        controller.request_pause()  # 暂停
+        controller.request_resume()  # 恢复
+        controller.request_stop()   # 停止
+    """
+    
+    def __init__(self):
+        self.interrupt_event: threading.Event = threading.Event()
+        """中断事件，用于停止任务"""
+
+        self.paused: bool = False
+        """暂停标志"""
+
+        self.pause_condition: threading.Condition = threading.Condition()
+        """暂停条件变量，用于线程间同步"""
+    
+    def check(self) -> None:
+        """
+        检查当前流程状态。
+
+        如果收到停止请求，则抛出 KeyboardInterrupt 异常。
+        如果收到暂停请求，则阻塞直到恢复。
+
+        这是核心的检查点方法，应在任务的关键路径上（如循环或等待前）调用。
+
+        :raises KeyboardInterrupt: 当收到停止请求时
+        """
+        # 优先检查中断信号
+        if self.interrupt_event.is_set():
+            raise KeyboardInterrupt("User requested interrupt.")
+        
+        # 检查暂停状态
+        with self.pause_condition:
+            while self.paused:
+                self.pause_condition.wait()
+    
+    def sleep(self, seconds: float) -> None:
+        """
+        一个可被中断和暂停的 sleep 方法。
+
+        与标准的 time.sleep() 不同，这个方法会响应停止和暂停请求。
+        在暂停状态下，计时器会暂停，恢复后继续计时。
+
+        :param seconds: 睡眠时间（秒）
+        :raises KeyboardInterrupt: 当收到停止请求时
+        """
+        with self.pause_condition:
+            end_time = time.time() + seconds
+            while True:
+                self.check()  # 每次循环都检查状态
+                remaining = end_time - time.time()
+                if remaining <= 0:
+                    break
+                # 等待指定时间或直到被唤醒
+                self.pause_condition.wait(timeout=remaining)
+        
+        # 结束后再次检查状态
+        self.check()
+    
+    def request_interrupt(self) -> None:
+        """
+        请求停止任务。
+
+        设置中断信号，所有正在执行的任务将在下一个检查点停止。
+        停止的优先级高于暂停。
+        """
+        logger.info('Interrupt requested.')
+        self.interrupt_event.set()
+    
+    def request_pause(self, *, wait_resume: bool = False) -> None:
+        """
+        请求暂停任务。
+
+        设置暂停标志，所有正在执行的任务将在下一个检查点暂停。
+        如果任务已经暂停，此操作无效果。
+        """
+        with self.pause_condition:
+            if not self.paused:
+                logger.info('Pause requested.')
+                self.paused = True
+            if wait_resume:
+                self.check()
+    
+    def request_resume(self) -> None:
+        """
+        请求恢复任务。
+
+        清除暂停标志并通知所有等待的线程恢复执行。
+        如果任务没有暂停，此操作无效果。
+        """
+        with self.pause_condition:
+            if self.paused:
+                logger.info('Resume requested.')
+                self.paused = False
+                self.pause_condition.notify_all()
+    
+    def toggle_pause(self) -> bool:
+        """
+        切换暂停/恢复状态。
+
+        :returns: 操作后的暂停状态。True 表示已暂停，False 表示已恢复。
+        """
+        with self.pause_condition:
+            logger.info('Pause toggled.')
+            if self.paused:
+                self.paused = False
+                self.pause_condition.notify_all()
+                return False
+            else:
+                self.paused = True
+                return True
+    
+    def clear_interrupt(self) -> None:
+        """
+        清除中断信号。
+
+        用于任务正常结束或重启时重置状态。
+        通常在开始新任务前调用。
+        """
+        self.interrupt_event.clear()
+        logger.info('Interrupt cleared.')
+    
+    def reset(self) -> None:
+        """
+        重置流程控制器到初始状态。
+
+        清除所有信号和状态，相当于重新创建一个新的控制器。
+        """
+        self.interrupt_event.clear()
+        with self.pause_condition:
+            if self.paused:
+                self.paused = False
+                self.pause_condition.notify_all()
+        logger.info('FlowController reset.')
+    
+    @property
+    def is_interrupted(self) -> bool:
+        """
+        检查是否收到中断请求。
+
+        :returns: True 表示已收到中断请求
+        """
+        return self.interrupt_event.is_set()
+    
+    @property
+    def is_paused(self) -> bool:
+        """
+        检查是否处于暂停状态。
+
+        :returns: True 表示当前处于暂停状态
+        """
+        return self.paused
+    
+    @property
+    def status(self) -> Literal['running', 'paused', 'interrupted']:
+        """
+        获取当前状态的字符串描述。
+
+        :returns: 状态描述，可能的值：'running', 'paused', 'interrupted'
+        """
+        if self.is_interrupted:
+            return 'interrupted'
+        elif self.is_paused:
+            return 'paused'
+        else:
+            return 'running'
+    
+    def __repr__(self) -> str:
         return f"FlowController(status='{self.status}')"

kotonebot/backend/loop.py

@@ -1,6 +1,7 @@
 import time
 from functools import lru_cache, partial
 from typing import Callable, Any, overload, Literal, Generic, TypeVar, cast, get_args, get_origin
+from typing_extensions import deprecated
 
 from cv2.typing import MatLike
 
@@ -9,8 +10,9 @@ from kotonebot import device, image, ocr
 from kotonebot.backend.core import Image
 from kotonebot.backend.ocr import TextComparator
 from kotonebot.client.protocol import ClickableObjectProtocol
+from .context import vars
 
-
+@deprecated('No longer used.')
 class LoopAction:
     def __init__(self, loop: 'Loop', func: Callable[[], ClickableObjectProtocol | None]):
         self.loop = loop
@@ -81,15 +83,16 @@ class Loop:
         是否在每次循环开始时（Loop.tick() 被调用时）截图。
         """
         self.__last_loop: float = -1
-        self.__interval = Interval(interval)
+        self.interval = interval
+        """每次循环后等待的时间。"""
         self.screenshot: MatLike | None = None
         """上次截图时的图像数据。"""
         self.__skip_first_wait = skip_first_wait
         self.__is_first_tick = True
 
     def __iter__(self):
-        self.__interval.reset()
         self.__is_first_tick = True
+        vars.flow.check()
         return self
 
     def __next__(self):
@@ -101,7 +104,7 @@ class Loop:
 
     def tick(self):
         if not (self.__is_first_tick and self.__skip_first_wait):
-            self.__interval.wait()
+            time.sleep(self.interval)
         self.__is_first_tick = False
 
         if self.auto_screenshot:
@@ -117,13 +120,16 @@ class Loop:
         self.running = False
 
     @overload
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: Image) -> LoopAction:
         ...
 
     @overload
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: TextComparator) -> LoopAction:
         ...
 
+    @deprecated('Use plain if statement instead.')
     def when(self, condition: Any):
         """
         判断某个条件是否成立。
@@ -142,6 +148,7 @@ class Loop:
         la.do()
         return la
 
+    @deprecated('Use plain if statement instead.')
     def until(self, condition: Any):
         """
         当满足指定条件时，结束循环。
@@ -150,6 +157,7 @@ class Loop:
         """
         return self.when(condition).call(lambda _: self.exit())
 
+    @deprecated('Use image.find() and device.click() instead.')
     def click_if(self, condition: Any, *, at: tuple[int, int] | None = None):
         """
         检测指定对象是否出现，若出现，点击该对象或指定位置。
@@ -198,87 +206,3 @@ class StatedLoop(Loop, Generic[StateType]):
             self.states = cast(tuple[StateType, ...], state_values)
             self.state = self.__tmp_initial_state or self.states[0]
             return state_values
-
-
-def StatedLoop2(states: StateType) -> StatedLoop[StateType]:
-    state_values = get_args(states)
-    return cast(StatedLoop[StateType], Loop())
-
-if __name__ == '__main__':
-    from kotonebot.kaa.tasks import R
-    from kotonebot.backend.ocr import contains
-    from kotonebot.backend.context import manual_context, init_context
-
-    # T = TypeVar('T')
-    # class Foo(Generic[T]):
-    #     def get_literal_params(self) -> list | None:
-    #         """
-    #         尝试获取泛型参数 T (如果它是 Literal 类型) 的参数列表。
-    #         """
-    #         # self.__orig_class__ 会是 Foo 的具体参数化类型，
-    #         # 例如 Foo[Literal['p0', 'p1', 'p2', 'p3', 'ap']]
-    #         if not hasattr(self, '__orig_class__'):
-    #             # 如果 Foo 不是以参数化泛型的方式实例化的，可能没有 __orig_class__
-    #             return None
-    #
-    #         # generic_type_args 是传递给 Foo 的类型参数元组
-    #         # 例如 (Literal['p0', 'p1', 'p2', 'p3', 'ap'],)
-    #         generic_type_args = get_args(self.__orig_class__)
-    #
-    #         if not generic_type_args:
-    #             # Foo 没有类型参数
-    #             return None
-    #
-    #         # T_type 是 Foo 的第一个类型参数
-    #         # 例如 Literal['p0', 'p1', 'p2', 'p3', 'ap']
-    #         t_type = generic_type_args[0]
-    #
-    #         # 检查 T_type 是否是 Literal 类型
-    #         if get_origin(t_type) is Literal:
-    #             # literal_args 是 Literal 类型的参数元组
-    #             # 例如 ('p0', 'p1', 'p2', 'p3', 'ap')
-    #             literal_args = get_args(t_type)
-    #             return list(literal_args)
-    #         else:
-    #             # T 不是 Literal 类型
-    #             return None
-    # f = Foo[Literal['p0', 'p1', 'p2', 'p3', 'ap']]()
-    # values = f.get_literal_params()
-    # 1
-
-    from typing_extensions import reveal_type
-    slp = StatedLoop[Literal['p0', 'p1', 'p2', 'p3', 'ap']]()
-    for l in slp:
-        reveal_type(l.states)
-
-    # init_context()
-    # manual_context().begin()
-    # for l in Loop():
-    #     l.when(R.Produce.ButtonUse).click()
-    #     l.when(R.Produce.ButtonRefillAP).click()
-    #     l.when(contains("123")).click()
-    #     l.click_if(contains("!23"), at=(1, 2))
-
-    # State = Literal['p0', 'p1', 'p2', 'p3', 'ap']
-    # for sl in StatedLoop[State]():
-    #     match sl.state:
-    #         case 'p0':
-    #             sl.click_if(R.Produce.ButtonProduce)
-    #             sl.click_if(contains('master'))
-    #             sl.when(R.Produce.ButtonPIdolOverview).goto('p1')
-    #             # AP 不足
-    #             sl.when(R.Produce.TextAPInsufficient).goto('ap')
-    #         case 'ap':
-    #             pass
-    #         # p1: 选择偶像
-    #         case 'p1':
-    #             sl.call(lambda _: select_idol(idol_skin_id), once=True)
-    #             sl.when(R.Produce.TextAnotherIdolAvailableDialog).call(dialog.no)
-    #             sl.click_if(R.Common.ButtonNextNoIcon)
-    #             sl.until(R.Produce.TextStepIndicator2).goto('p2')
-    #         case 'p2':
-    #             sl.when(contains("123")).click()
-    #         case 'p3':
-    #             sl.click_if(contains("!23"), at=(1, 2))
-    #         case _:
-    #             assert_never(sl.state)