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

kotonebot/backend/context/__init__.py

@@ -1,3 +1,3 @@
-from .context import *
-from .context import _c
-from .task_action import task, action, task_registry, action_registry, current_callstack, Task, Action, tasks_from_id
+from .context import *
+from .context import _c
+from .task_action import task, action, task_registry, action_registry, current_callstack, Task, Action, tasks_from_id

kotonebot/backend/context/context.py

@@ -175,6 +175,8 @@ class ContextGlobalVars:
         self.__vars = dict[str, Any]()
         self.flow: FlowController = FlowController()
         """流程控制器，负责停止、暂停、恢复等操作"""
+        self.screenshot_data: MatLike | None = None
+        """截图数据"""
 
     def __getitem__(self, key: str) -> Any:
         return self.__vars[key]
@@ -197,6 +199,7 @@ class ContextGlobalVars:
     def clear(self):
         self.__vars.clear()
         self.flow.reset()  # 重置流程控制器
+        self.screenshot_data = None
 
 def check_flow_control():
     """
@@ -220,45 +223,40 @@ class ContextStackVars:
             自动截图。即调用 `color`、`image`、`ocr` 上的方法时，会自动更新截图。
         * `manual`
             完全手动截图，不自动截图。如果在没有截图数据的情况下调用 `color` 等的方法，会抛出异常。
-        * `manual-inherit`：
-            第一张截图继承自调用者，此后同手动截图。
-            如果调用者没有截图数据，则继承的截图数据为空。
-            如果在没有截图数据的情况下调用 `color` 等的方法，会抛出异常。
+        * ~~`manual-inherit`~~：
+            已废弃。
         """
-        self._screenshot: MatLike | None = None
-        """截图数据"""
-        self._inherit_screenshot: MatLike | None = None
-        """继承的截图数据"""
 
     @property
     def screenshot(self) -> MatLike:
         match self.screenshot_mode:
-            case 'manual':
-                if self._screenshot is None:
-                    raise ValueError("No screenshot data found.")
-                return self._screenshot
-            case 'manual-inherit':
-                # TODO: 这一部分要考虑和 device.screenshot() 合并
-                if self._inherit_screenshot is not None:
-                    self._screenshot = self._inherit_screenshot
-                    self._inherit_screenshot = None
-                if self._screenshot is None:
-                    raise ValueError("No screenshot data found.")
-                return self._screenshot
+            case 'manual' | 'manual-inherit':
+                if vars.screenshot_data is None:
+                    raise ValueError("No screenshot data found. Did you forget to call `device.screenshot()`?")
+                return vars.screenshot_data
             case 'auto':
-                self._screenshot = device.screenshot()
-                return self._screenshot
+                device.screenshot()
+                if vars.screenshot_data is None:
+                    raise ValueError("No screenshot data found. Did you forget to call `device.screenshot()`?")
+                return vars.screenshot_data
             case _:
                 raise ValueError(f"Invalid screenshot mode: {self.screenshot_mode}")
 
+    @property
+    @deprecated('Use `vars.screenshot_data` instead.')
+    def _screenshot(self) -> MatLike | None:
+        return vars.screenshot_data
+
+    @_screenshot.setter
+    @deprecated('Use `vars.screenshot_data` instead.')
+    def _screenshot(self, value: MatLike | None) -> None:
+        vars.screenshot_data = value
+
     @staticmethod
     def push(*, screenshot_mode: ScreenshotMode | None = None) -> 'ContextStackVars':
         vars = ContextStackVars()
         if screenshot_mode is not None:
             vars.screenshot_mode = screenshot_mode
-        current = ContextStackVars.current()
-        if current and vars.screenshot_mode == 'manual-inherit':
-            vars._inherit_screenshot = current._screenshot
         ContextStackVars.stack.append(vars)
         return vars
 
@@ -266,7 +264,7 @@ class ContextStackVars:
     def pop() -> 'ContextStackVars':
         last = ContextStackVars.stack.pop()
         return last
-    
+
     @staticmethod
     def current() -> 'ContextStackVars | None':
         if len(ContextStackVars.stack) == 0:
@@ -331,7 +329,7 @@ class ContextOcr:
         )
         self.context.device.last_find = ret.original_rect if ret else None
         return ret
-    
+
     def find_all(
         self,
         patterns: Sequence[str | re.Pattern | StringMatchFunction],
@@ -366,7 +364,7 @@ class ContextOcr:
         ret = engine.expect(ContextStackVars.ensure_current().screenshot, pattern, rect=rect, hint=hint)
         self.context.device.last_find = ret.original_rect if ret else None
         return ret
-    
+
     def expect_wait(
         self,
         pattern: str | re.Pattern | StringMatchFunction,
@@ -447,7 +445,7 @@ class ContextImage:
         等待指定图像出现。
         """
         is_manual = is_manual_screenshot_mode()
-        
+
         start_time = time.time()
         while True:
             if is_manual:
@@ -702,7 +700,7 @@ class ContextConfig(Generic[T]):
     def current(self) -> UserConfig[T]:
         """
         当前配置数据。
-        
+
         如果当前配置不存在，则使用默认值自动创建一个新配置。
         （不推荐，建议在 UI 中启动前要求用户手动创建，或自行创建一个默认配置。）
         """
@@ -729,7 +727,7 @@ class Forwarded:
         if self._FORWARD_getter is None:
             raise ContextNotInitializedError(f"Forwarded object {self._FORWARD_name} called before initialization.")
         return getattr(self._FORWARD_getter(), name)
-    
+
     def __setattr__(self, name: str, value: Any):
         if name.startswith('_FORWARD_'):
             return object.__setattr__(self, name, value)
@@ -761,25 +759,20 @@ class ContextDevice(Generic[T_Device], Device):
         """
         check_flow_control()
         global next_wait, last_screenshot_time, next_wait_time
-        current = ContextStackVars.ensure_current()
-        if force:
-            current._inherit_screenshot = None
-        if current._inherit_screenshot is not None:
-            img = current._inherit_screenshot
-            current._inherit_screenshot = None
-        else:
-            if self._screenshot_interval is not None:
-                self._screenshot_interval.wait()
-
-            if next_wait == 'screenshot':
-                delta = time.time() - last_screenshot_time
-                if delta < next_wait_time:
-                    sleep(next_wait_time - delta)
-                last_screenshot_time = time.time()
-                next_wait_time = 0
-                next_wait = None
-            img = self._device.screenshot()
-        current._screenshot = img
+        ContextStackVars.ensure_current()
+
+        if self._screenshot_interval is not None:
+            self._screenshot_interval.wait()
+
+        if next_wait == 'screenshot':
+            delta = time.time() - last_screenshot_time
+            if delta < next_wait_time:
+                sleep(next_wait_time - delta)
+            last_screenshot_time = time.time()
+            next_wait_time = 0
+            next_wait = None
+        img = self._device.screenshot()
+        vars.screenshot_data = img
         return img
 
     def __getattribute__(self, name: str):
@@ -787,7 +780,7 @@ class ContextDevice(Generic[T_Device], Device):
             return object.__getattribute__(self, name)
         else:
             return getattr(self._device, name)
-        
+
     def __setattr__(self, name: str, value: Any):
         if name in ['_device', 'screenshot', 'of_android', 'of_windows']:
             return object.__setattr__(self, name, value)
@@ -853,7 +846,7 @@ class Context(Generic[T]):
         if vars is not None:
             self.__vars = vars
         if debug is not None:
-            self.__debug = debug    
+            self.__debug = debug
         if config is not None:
             self.__config = config
 
@@ -864,7 +857,7 @@ class Context(Generic[T]):
     @property
     def ocr(self) -> 'ContextOcr':
         return self.__ocr
-    
+
     @property
     def image(self) -> 'ContextImage':
         return self.__image
@@ -876,7 +869,7 @@ class Context(Generic[T]):
     @property
     def vars(self) -> 'ContextGlobalVars':
         return self.__vars
-    
+
     @property
     def debug(self) -> 'ContextDebug':
         return self.__debug
@@ -895,7 +888,7 @@ def rect_expand(rect: Rect, left: int = 0, top: int = 0, right: int = 0, bottom:
 def use_screenshot(*args: MatLike | None) -> MatLike:
     for img in args:
         if img is not None:
-            ContextStackVars.ensure_current()._screenshot = img # HACK
+            vars.screenshot_data = img
             return img
     return device.screenshot()
 
@@ -1006,4 +999,4 @@ def manual_context(screenshot_mode: ScreenshotMode = 'auto') -> ManualContextMan
     默认情况下，Context* 类仅允许在 @task/@action 函数中使用。
     如果想要在其他地方使用，使用此函数手动创建一个上下文。
     """
-    return ManualContextManager(screenshot_mode)
+    return ManualContextManager(screenshot_mode)

kotonebot/backend/context/task_action.py

@@ -1,176 +1,184 @@
-import logging
-from typing import Callable, ParamSpec, TypeVar, overload, Literal
-from dataclasses import dataclass
-
-
-from .context import ContextStackVars, ScreenshotMode
-from ...errors import TaskNotFoundError
-
-P = ParamSpec('P')
-R = TypeVar('R')
-logger = logging.getLogger(__name__)
-
-TaskRunAtType = Literal['pre', 'post', 'manual', 'regular'] | str
-
-
-@dataclass
-class Task:
-    name: str
-    id: str
-    description: str
-    func: Callable
-    priority: int
-    """
-    任务优先级，数字越大优先级越高。
-    """
-    run_at: TaskRunAtType = 'regular'
-
-
-@dataclass
-class Action:
-    name: str
-    description: str
-    func: Callable
-    priority: int
-    """
-    动作优先级，数字越大优先级越高。
-    """
-
-
-task_registry: dict[str, Task] = {}
-action_registry: dict[str, Action] = {}
-current_callstack: list[Task|Action] = []
-
-def _placeholder():
-    raise NotImplementedError('Placeholder function')
-
-def task(
-    name: str,
-    task_id: str|None = None,
-    description: str|None = None,
-    *,
-    pass_through: bool = False,
-    priority: int = 0,
-    screenshot_mode: ScreenshotMode = 'auto',
-    run_at: TaskRunAtType = 'regular'
-):
-    """
-    `task` 装饰器，用于标记一个函数为任务函数。
-
-    :param name: 任务名称
-    :param task_id: 任务 ID。如果为 None，则使用函数名称作为 ID。
-    :param description: 任务描述。如果为 None，则使用函数的 docstring 作为描述。
-    :param pass_through: 
-        默认情况下， @task 装饰器会包裹任务函数，跟踪其执行情况。
-        如果不想跟踪，则设置此参数为 False。
-    :param priority: 任务优先级，数字越大优先级越高。
-    :param run_at: 任务运行时间。
-    """
-    # 设置 ID
-    # 获取 caller 信息
-    def _task_decorator(func: Callable[P, R]) -> Callable[P, R]:
-        nonlocal description, task_id
-        description = description or func.__doc__ or ''
-        # TODO: task_id 冲突检测
-        task_id = task_id or func.__name__
-        task = Task(name, task_id, description, _placeholder, priority, run_at)
-        task_registry[name] = task
-        logger.debug(f'Task "{name}" registered.')
-        if pass_through:
-            return func
-        else:
-            def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-                current_callstack.append(task)
-                vars = ContextStackVars.push(screenshot_mode=screenshot_mode)
-                ret = func(*args, **kwargs)
-                ContextStackVars.pop()
-                current_callstack.pop()
-                return ret
-            task.func = _wrapper
-            return _wrapper
-    return _task_decorator
-
-@overload
-def action(func: Callable[P, R]) -> Callable[P, R]: ...
-
-@overload
-def action(
-    name: str,
-    *,
-    description: str|None = None,
-    pass_through: bool = False,
-    priority: int = 0,
-    screenshot_mode: ScreenshotMode | None = None,
-) -> Callable[[Callable[P, R]], Callable[P, R]]:
-    """
-    `action` 装饰器，用于标记一个函数为动作函数。
-
-    :param name: 动作名称。如果为 None，则使用函数的名称作为名称。
-    :param description: 动作描述。如果为 None，则使用函数的 docstring 作为描述。
-    :param pass_through: 
-        默认情况下， @action 装饰器会包裹动作函数，跟踪其执行情况。
-        如果不想跟踪，则设置此参数为 False。
-    :param priority: 动作优先级，数字越大优先级越高。
-    :param screenshot_mode: 截图模式。
-    """
-    ...
-
-# TODO: 需要找个地方统一管理这些属性名
-ATTR_ORIGINAL_FUNC = '_kb_inner'
-ATTR_ACTION_MARK = '__kb_action_mark'
-def action(*args, **kwargs):
-    def _register(func: Callable, name: str, description: str|None = None, priority: int = 0) -> Action:
-        description = description or func.__doc__ or ''
-        action = Action(name, description, func, priority)
-        action_registry[name] = action
-        logger.debug(f'Action "{name}" registered.')
-        return action
-
-    if len(args) == 1 and isinstance(args[0], Callable):
-        func = args[0]
-        action = _register(_placeholder, func.__name__, func.__doc__)
-        def _wrapper(*args: P.args, **kwargs: P.kwargs):
-            current_callstack.append(action)
-            vars = ContextStackVars.push()
-            ret = func(*args, **kwargs)
-            ContextStackVars.pop()
-            current_callstack.pop()
-            return ret
-        setattr(_wrapper, ATTR_ORIGINAL_FUNC, func)
-        setattr(_wrapper, ATTR_ACTION_MARK, True)
-        action.func = _wrapper
-        return _wrapper
-    else:
-        name = args[0]
-        description = kwargs.get('description', None)
-        pass_through = kwargs.get('pass_through', False)
-        priority = kwargs.get('priority', 0)
-        screenshot_mode = kwargs.get('screenshot_mode', None)
-        def _action_decorator(func: Callable):
-            nonlocal pass_through
-            action = _register(_placeholder, name, description)
-            pass_through = kwargs.get('pass_through', False)
-            if pass_through:
-                return func
-            else:
-                def _wrapper(*args: P.args, **kwargs: P.kwargs):
-                    current_callstack.append(action)
-                    vars = ContextStackVars.push(screenshot_mode=screenshot_mode)
-                    ret = func(*args, **kwargs)
-                    ContextStackVars.pop()
-                    current_callstack.pop()
-                    return ret
-                setattr(_wrapper, ATTR_ORIGINAL_FUNC, func)
-                setattr(_wrapper, ATTR_ACTION_MARK, True)
-                action.func = _wrapper
-                return _wrapper
-        return _action_decorator
-
-def tasks_from_id(task_ids: list[str]) -> list[Task]:
-    result = []
-    for tid in task_ids:
-        target = next(task for task in task_registry.values() if task.id == tid)
-        if target is None:
-            raise TaskNotFoundError(f'Task "{tid}" not found.')
-        result.append(target)
+import logging
+import warnings
+from dataclasses import dataclass
+from typing_extensions import deprecated
+from typing import Callable, ParamSpec, TypeVar, overload, Literal
+
+
+from .context import ContextStackVars, ScreenshotMode
+from ...errors import TaskNotFoundError
+
+P = ParamSpec('P')
+R = TypeVar('R')
+logger = logging.getLogger(__name__)
+
+TaskRunAtType = Literal['pre', 'post', 'manual', 'regular'] | str
+
+
+@dataclass
+class Task:
+    name: str
+    id: str
+    description: str
+    func: Callable
+    priority: int
+    """
+    任务优先级，数字越大优先级越高。
+    """
+    run_at: TaskRunAtType = 'regular'
+
+
+@dataclass
+class Action:
+    name: str
+    description: str
+    func: Callable
+    priority: int
+    """
+    动作优先级，数字越大优先级越高。
+    """
+
+
+task_registry: dict[str, Task] = {}
+action_registry: dict[str, Action] = {}
+current_callstack: list[Task|Action] = []
+
+def _placeholder():
+    raise NotImplementedError('Placeholder function')
+
+def task(
+    name: str,
+    task_id: str|None = None,
+    description: str|None = None,
+    *,
+    pass_through: bool = False,
+    priority: int = 0,
+    screenshot_mode: ScreenshotMode = 'auto',
+    run_at: TaskRunAtType = 'regular'
+):
+    """
+    `task` 装饰器，用于标记一个函数为任务函数。
+
+    :param name: 任务名称
+    :param task_id: 任务 ID。如果为 None，则使用函数名称作为 ID。
+    :param description: 任务描述。如果为 None，则使用函数的 docstring 作为描述。
+    :param pass_through: 
+        默认情况下， @task 装饰器会包裹任务函数，跟踪其执行情况。
+        如果不想跟踪，则设置此参数为 False。
+    :param priority: 任务优先级，数字越大优先级越高。
+    :param run_at: 任务运行时间。
+    """
+    # 设置 ID
+    # 获取 caller 信息
+    def _task_decorator(func: Callable[P, R]) -> Callable[P, R]:
+        nonlocal description, task_id
+        description = description or func.__doc__ or ''
+        # TODO: task_id 冲突检测
+        task_id = task_id or func.__name__
+        task = Task(name, task_id, description, _placeholder, priority, run_at)
+        task_registry[name] = task
+        logger.debug(f'Task "{name}" registered.')
+        if pass_through:
+            return func
+        else:
+            def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                current_callstack.append(task)
+                vars = ContextStackVars.push(screenshot_mode=screenshot_mode)
+                ret = func(*args, **kwargs)
+                ContextStackVars.pop()
+                current_callstack.pop()
+                return ret
+            task.func = _wrapper
+            return _wrapper
+    return _task_decorator
+
+@overload
+def action(func: Callable[P, R]) -> Callable[P, R]: ...
+
+@deprecated('Use `action` with screenshot_mode=`manual` instead.')
+@overload
+def action(
+    name: str,
+    *,
+    description: str|None = None,
+    pass_through: bool = False,
+    priority: int = 0,
+    screenshot_mode: Literal['manual-inherit'],
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+@overload
+def action(
+    name: str,
+    *,
+    description: str|None = None,
+    pass_through: bool = False,
+    priority: int = 0,
+    screenshot_mode: ScreenshotMode | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    `action` 装饰器，用于标记一个函数为动作函数。
+
+    :param name: 动作名称。如果为 None，则使用函数的名称作为名称。
+    :param description: 动作描述。如果为 None，则使用函数的 docstring 作为描述。
+    :param pass_through: 
+        默认情况下， @action 装饰器会包裹动作函数，跟踪其执行情况。
+        如果不想跟踪，则设置此参数为 False。
+    :param priority: 动作优先级，数字越大优先级越高。
+    :param screenshot_mode: 截图模式。
+    """
+    ...
+
+def action(*args, **kwargs):
+    def _register(func: Callable, name: str, description: str|None = None, priority: int = 0) -> Action:
+        description = description or func.__doc__ or ''
+        action = Action(name, description, func, priority)
+        action_registry[name] = action
+        logger.debug(f'Action "{name}" registered.')
+        return action
+
+    if len(args) == 1 and isinstance(args[0], Callable):
+        func = args[0]
+        action = _register(_placeholder, func.__name__, func.__doc__)
+        def _wrapper(*args: P.args, **kwargs: P.kwargs):
+            current_callstack.append(action)
+            vars = ContextStackVars.push()
+            ret = func(*args, **kwargs)
+            ContextStackVars.pop()
+            current_callstack.pop()
+            return ret
+        action.func = _wrapper
+        return _wrapper
+    else:
+        name = args[0]
+        description = kwargs.get('description', None)
+        pass_through = kwargs.get('pass_through', False)
+        priority = kwargs.get('priority', 0)
+        screenshot_mode = kwargs.get('screenshot_mode', None)
+        if screenshot_mode == 'manual-inherit':
+            warnings.warn('`screenshot_mode=manual-inherit` is deprecated. Use `screenshot_mode=manual` instead.')
+        def _action_decorator(func: Callable):
+            nonlocal pass_through
+            action = _register(_placeholder, name, description)
+            pass_through = kwargs.get('pass_through', False)
+            if pass_through:
+                return func
+            else:
+                def _wrapper(*args: P.args, **kwargs: P.kwargs):
+                    current_callstack.append(action)
+                    vars = ContextStackVars.push(screenshot_mode=screenshot_mode)
+                    ret = func(*args, **kwargs)
+                    ContextStackVars.pop()
+                    current_callstack.pop()
+                    return ret
+                action.func = _wrapper
+                return _wrapper
+        return _action_decorator
+
+def tasks_from_id(task_ids: list[str]) -> list[Task]:
+    result = []
+    for tid in task_ids:
+        target = next(task for task in task_registry.values() if task.id == tid)
+        if target is None:
+            raise TaskNotFoundError(f'Task "{tid}" not found.')
+        result.append(target)
     return result