chore(core): 标记一些函数为 deprecated

kotonebot/backend/context/context.py

@@ -591,7 +591,7 @@ class ContextColor:
     def find_all(self, *args, **kwargs):
         return color_find_all(ContextStackVars.ensure_current().screenshot, *args, **kwargs)
 
-
+@deprecated('使用 kotonebot.backend.debug 模块替代')
 class ContextDebug:
     def __init__(self, context: 'Context'):
         self.__context = context
@@ -817,6 +817,7 @@ def use_screenshot(*args: MatLike | None) -> MatLike:
     return device.screenshot()
 
 WaitBeforeType = Literal['screenshot']
+@deprecated('使用普通 sleep 代替')
 def wait(at_least: float = 0.3, *, before: WaitBeforeType) -> None:
     global next_wait, next_wait_time
     if before == 'screenshot':

kotonebot/backend/context/task_action.py

@@ -1,6 +1,7 @@
 import logging
 from typing import Callable, ParamSpec, TypeVar, overload, Concatenate, Literal
 from dataclasses import dataclass
+from typing_extensions import deprecated
 
 import cv2
 from cv2.typing import MatLike
@@ -108,6 +109,7 @@ def action(
     ...
 
 @overload
+@deprecated('使用普通 while 循环代替')
 def action(
     name: str,
     *,

kotonebot/backend/dispatch.py

@@ -6,7 +6,7 @@ from logging import Logger
 from types import CodeType
 from dataclasses import dataclass
 from typing import Annotated, Any, Callable, Concatenate, Sequence, TypeVar, ParamSpec, Literal, Protocol, cast
-from typing_extensions import Self
+from typing_extensions import deprecated
 
 from dataclasses import dataclass
 
@@ -74,6 +74,7 @@ class DispatcherContext:
         """是否即将结束运行"""
         return self.finished
 
+@deprecated('使用 SimpleDispatcher 类或 while 循环替代')
 def dispatcher(
         func: Callable[Concatenate[DispatcherContext, P], R],
         *,

kotonebot/backend/ocr.py

@@ -4,7 +4,8 @@ import logging
 import unicodedata
 from functools import lru_cache
 from dataclasses import dataclass
-from typing_extensions import Self
+import warnings
+from typing_extensions import Self, deprecated
 from typing import Callable, NamedTuple
 
 import cv2
@@ -129,6 +130,7 @@ class TextComparator:
     def __repr__(self) -> str:
         return f'{self.name}("{self.text}")'
 
+@deprecated("即将移除")
 @lru_cache(maxsize=1000)
 def fuzz(text: str) -> TextComparator:
     """返回 fuzzy 算法的字符串匹配函数。"""
@@ -401,6 +403,7 @@ class Ocr:
         :return: 找到的文本，如果未找到则返回 None
         """
         if hint is not None:
+            warnings.warn("使用 `rect` 参数代替")
             if ret := self.find(img, text, rect=hint):
                 logger.debug(f"find: {text} SUCCESS [hint={hint}]")
                 return ret
@@ -438,6 +441,7 @@ class Ocr:
         """
         # HintBox 处理
         if hint is not None:
+            warnings.warn("使用 `rect` 参数代替")
             result = self.find_all(img, texts, rect=hint, pad=pad)
             if all(result):
                 return result

kotonebot/util.py

@@ -7,6 +7,7 @@ import cProfile
 from importlib import resources
 from functools import lru_cache
 from typing import Literal, Callable, TYPE_CHECKING, TypeGuard
+from typing_extensions import deprecated
 
 import cv2
 from cv2.typing import MatLike
@@ -30,6 +31,7 @@ def is_rect(rect: typing.Any) -> TypeGuard[Rect]:
 def is_point(point: typing.Any) -> TypeGuard[Point]:
     return isinstance(point, typing.Sequence) and len(point) == 2 and all(isinstance(i, int) for i in point)
 
+@deprecated('使用 HintBox 类与 Devtool 工具替代')
 def crop(img: MatLike, /, x1: float = 0, y1: float = 0, x2: float = 1, y2: float = 1) -> MatLike:
     """
     按比例裁剪图像。
@@ -47,6 +49,7 @@ def crop(img: MatLike, /, x1: float = 0, y1: float = 0, x2: float = 1, y2: float
     y2_px = int(h * y2)
     return img[y1_px:y2_px, x1_px:x2_px]
 
+@deprecated('使用 numpy 的切片替代')
 def crop_rect(img: MatLike, rect: Rect) -> MatLike:
     """
     按范围裁剪图像。
@@ -89,6 +92,7 @@ class DeviceHookContextManager:
         if self.click_hook_before is not None:
             self.device.click_hooks_before.remove(self.click_hook_before)
 
+@deprecated('使用 HintBox 类与 Devtool 工具替代')
 def cropped(
     device: 'Device',
     x1: float = 0,