MaaFw 4.4.0b1__py3-none-manylinux2014_x86_64.whl → 5.4.0__py3-none-manylinux2014_x86_64.whl

maa/event_sink.py

@@ -0,0 +1,103 @@
+import ctypes
+import json
+from abc import ABC
+from typing import Tuple
+from enum import IntEnum
+
+from .define import MaaEventCallback
+
+
+# class NotificationEvent(IntEnum):
+#     ResourceLoading = 1
+#     ControllerAction = 2
+#     TaskerTask = 3
+#     TaskNextList = 4
+#     TaskRecognition = 5
+#     TaskAction = 6
+
+
+class NotificationType(IntEnum):
+    """通知类型枚举 / Notification type enumeration
+
+    用于标识事件回调的状态类型。
+    Used to identify the status type of event callbacks.
+
+    Attributes:
+        Unknown: 未知类型 / Unknown type
+        Starting: 开始 / Starting
+        Succeeded: 成功 / Succeeded
+        Failed: 失败 / Failed
+    """
+
+    Unknown = 0
+    Starting = 1
+    Succeeded = 2
+    Failed = 3
+
+
+class EventSink(ABC):
+    """事件监听器基类 / Event sink base class
+
+    用于接收 MaaFramework 各种事件回调的抽象基类。
+    派生类包括 ResourceEventSink、ControllerEventSink、TaskerEventSink、ContextEventSink。
+    Abstract base class for receiving various event callbacks from MaaFramework.
+    Derived classes include ResourceEventSink, ControllerEventSink, TaskerEventSink, ContextEventSink.
+    """
+
+    def on_unknown_notification(self, instance, msg: str, details: dict):
+        """处理未知类型的通知 / Handle unknown notification
+
+        当收到无法识别的通知时调用。
+        Called when an unrecognized notification is received.
+
+        Args:
+            instance: 相关实例对象 / Related instance object
+            msg: 消息类型 / Message type
+            details: 消息详情 / Message details
+        """
+        pass
+
+    def _on_raw_notification(self, handle: ctypes.c_void_p, msg: str, details: dict):
+        pass
+
+    @property
+    def c_callback(self) -> MaaEventCallback:
+        return self._c_sink_agent
+
+    @property
+    def c_callback_arg(self) -> ctypes.c_void_p:
+        return ctypes.c_void_p.from_buffer(ctypes.py_object(self))
+
+    @staticmethod
+    def _gen_c_param(
+        sink: "EventSink",
+    ) -> Tuple[MaaEventCallback, ctypes.c_void_p]:
+        return sink.c_callback, sink.c_callback_arg
+
+    @staticmethod
+    def _notification_type(message: str) -> NotificationType:
+        if message.endswith(".Starting"):
+            return NotificationType.Starting
+        elif message.endswith(".Succeeded"):
+            return NotificationType.Succeeded
+        elif message.endswith(".Failed"):
+            return NotificationType.Failed
+        else:
+            return NotificationType.Unknown
+
+    @staticmethod
+    @MaaEventCallback
+    def _c_sink_agent(
+        handle: ctypes.c_void_p,
+        msg: ctypes.c_char_p,
+        details_json: ctypes.c_char_p,
+        callback_arg: ctypes.c_void_p,
+    ):
+        if not callback_arg:
+            return
+
+        self: EventSink = ctypes.cast(callback_arg, ctypes.py_object).value
+
+        self._on_raw_notification(
+            handle, msg.decode(), json.loads(details_json.decode())
+        )

maa/job.py

@@ -2,6 +2,13 @@ from .define import *
 
 
 class Job:
+    """异步作业句柄 / Asynchronous job handle
+
+    用于跟踪和管理异步操作的状态，如资源加载、控制器连接等。
+    Used to track and manage the status of asynchronous operations
+    such as resource loading, controller connection, etc.
+    """
+
     _job_id: MaaId
 
     def __init__(self, job_id: MaaId, status_func, wait_func):
@@ -11,45 +18,114 @@ class Job:
 
     @property
     def job_id(self) -> int:
+        """获取作业 ID / Get job ID
+
+        Returns:
+            int: 作业 ID / Job ID
+        """
         return int(self._job_id)
 
     def wait(self) -> "Job":
+        """等待作业完成 / Wait for job completion
+
+        阻塞当前线程直到作业完成
+        Blocks the current thread until the job is done
+
+        Returns:
+            Job: 返回自身，支持链式调用 / Returns self for method chaining
+        """
         self._wait_func(self._job_id)
         return self
 
     @property
     def status(self) -> Status:
+        """获取作业状态 / Get job status
+
+        Returns:
+            Status: 作业状态 / Job status
+        """
         return Status(self._status_func(self._job_id))
 
     @property
     def done(self) -> bool:
+        """判断作业是否已完成 / Check if job is done
+
+        Returns:
+            bool: 是否已完成（成功或失败） / Whether done (succeeded or failed)
+        """
         return self.status.done
 
     @property
     def succeeded(self) -> bool:
+        """判断作业是否成功 / Check if job succeeded
+
+        Returns:
+            bool: 是否成功 / Whether succeeded
+        """
         return self.status.succeeded
 
     @property
     def failed(self) -> bool:
+        """判断作业是否失败 / Check if job failed
+
+        Returns:
+            bool: 是否失败 / Whether failed
+        """
         return self.status.failed
 
     @property
     def pending(self) -> bool:
+        """判断作业是否等待中 / Check if job is pending
+
+        Returns:
+            bool: 是否等待中 / Whether pending
+        """
         return self.status.pending
 
     @property
     def running(self) -> bool:
+        """判断作业是否运行中 / Check if job is running
+
+        Returns:
+            bool: 是否运行中 / Whether running
+        """
         return self.status.running
 
 
 class JobWithResult(Job):
+    """带结果的异步作业句柄 / Asynchronous job handle with result
+
+    继承自 Job，额外提供获取作业结果的功能。
+    Inherits from Job, additionally provides the ability to get job result.
+    """
+
     def __init__(self, job_id: MaaId, status_func, wait_func, get_func):
         super().__init__(job_id, status_func, wait_func)
         self._get_func = get_func
 
     def wait(self) -> "JobWithResult":
+        """等待作业完成 / Wait for job completion
+
+        Returns:
+            JobWithResult: 返回自身，支持链式调用 / Returns self for method chaining
+        """
         super().wait()
         return self
 
-    def get(self):
+    def get(self, wait: bool = False):
+        """获取作业结果 / Get job result
+
+        Args:
+            wait: 是否在获取结果前等待作业完成，默认为 False。建议先显式调用 wait()（或传入 wait=True），
+                确保异步操作已完成后再获取结果 / Whether to wait for job completion before getting result,
+                default is False. It's recommended to call wait() first (or pass wait=True) to ensure the
+                async operation is finished before getting the result.
+
+        Returns:
+            作业执行结果，类型取决于具体作业 / Job execution result, type depends on the specific job
+        """
+
+        if wait:
+            self.wait()
+
         return self._get_func(self._job_id)

maa/library.py

@@ -1,5 +1,4 @@
 import ctypes
-import ctypes.util
 import pathlib
 import platform
 from typing import Optional
@@ -8,6 +7,12 @@ from .define import *
 
 
 class Library:
+    """库加载管理器 / Library loading manager
+
+    管理 MaaFramework 各动态库的加载和访问。
+    Manages loading and access to MaaFramework dynamic libraries.
+    """
+
     _is_agent_server: bool = False
 
     _framework: Optional[ctypes.CDLL] = None
@@ -16,9 +21,18 @@ class Library:
     _agent_server: Optional[ctypes.CDLL] = None
     _lib_type = None
 
-    @staticmethod
-    def open(path: pathlib.Path, agent_server: bool = False):
-        if Library._api_properties_initialized:
+    @classmethod
+    def open(cls, path: pathlib.Path, agent_server: bool = False):
+        """打开并加载库 / Open and load libraries
+
+        Args:
+            path: 库文件所在目录 / Directory containing library files
+            agent_server: 是否以 AgentServer 模式加载 / Whether to load in AgentServer mode
+
+        Raises:
+            FileNotFoundError: 如果路径不存在
+        """
+        if cls._api_properties_initialized:
             return
 
         if not path.exists():
@@ -28,9 +42,9 @@ class Library:
         MACOS = "darwin"
         LINUX = "linux"
 
-        Library._is_agent_server = agent_server
+        cls._is_agent_server = agent_server
 
-        if not Library.is_agent_server():
+        if not cls.is_agent_server():
             framework_library = {
                 WINDOWS: "MaaFramework.dll",
                 MACOS: "libMaaFramework.dylib",
@@ -57,73 +71,127 @@ class Library:
         platform_type = platform.system().lower()
 
         if platform_type == WINDOWS:
-            Library._lib_type = ctypes.WinDLL
+            cls._lib_type = ctypes.WinDLL
         else:
-            Library._lib_type = ctypes.CDLL
+            cls._lib_type = ctypes.CDLL
+
+        if cls._lib_type is None:
+            raise
 
-        if not Library.is_agent_server():
-            Library.framework_libpath = path / framework_library[platform_type]
-            Library.agent_client_libpath = path / agent_client_library[platform_type]
+        if not cls.is_agent_server():
+            cls.framework_libpath = path / framework_library[platform_type]
+            cls.agent_client_libpath = path / agent_client_library[platform_type]
         else:
-            Library.agent_server_libpath = path / agent_server_library[platform_type]
+            cls.agent_server_libpath = path / agent_server_library[platform_type]
 
-        Library.toolkit_libpath = path / toolkit_library[platform_type]
+        cls.toolkit_libpath = path / toolkit_library[platform_type]
 
-    @staticmethod
-    def framework() -> ctypes.CDLL:
-        if not Library.is_agent_server():
-            if not Library._framework:
-                Library._framework = Library._lib_type(str(Library.framework_libpath))  # type: ignore
+    @classmethod
+    def framework(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaFramework 库 / Get MaaFramework library
 
-            return Library._framework
+        Returns:
+            (ctypes.CDLL | ctypes.WinDLL): MaaFramework 动态库对象 / MaaFramework dynamic library object
+        """
+        if cls._lib_type is None:
+            raise RuntimeError("Library._lib_type is None!")
+
+        if not cls.is_agent_server():
+            if not cls._framework:
+                cls._framework = cls._lib_type(str(cls.framework_libpath))
+
+            if cls._framework is None:
+                raise RuntimeError("Library._framework is None!")
+
+            return cls._framework
         else:
-            return Library.agent_server()
+            return cls.agent_server()
+
+    @classmethod
+    def toolkit(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaToolkit 库 / Get MaaToolkit library
 
-    @staticmethod
-    def toolkit() -> ctypes.CDLL:
-        if not Library._toolkit:
-            Library._toolkit = Library._lib_type(str(Library.toolkit_libpath))  # type: ignore
+        Returns:
+            (ctypes.CDLL | ctypes.WinDLL): MaaFramework 动态库对象 / MaaFramework dynamic library object
+        """
+        if cls._lib_type is None:
+            raise RuntimeError("Library._lib_type is None!")
 
-        return Library._toolkit
+        if not cls._toolkit:
+            cls._toolkit = cls._lib_type(str(cls.toolkit_libpath))
 
-    @staticmethod
-    def agent_client() -> ctypes.CDLL:
-        if Library.is_agent_server():
+        return cls._toolkit
+
+    @classmethod
+    def agent_client(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaAgentClient 库 / Get MaaAgentClient library
+
+        Returns:
+            (ctypes.CDLL | ctypes.WinDLL): MaaFramework 动态库对象 / MaaFramework dynamic library object
+
+        Raises:
+            ValueError: 如果在 AgentServer 模式下调用
+        """
+        if cls._lib_type is None:
+            raise RuntimeError("Library._lib_type is None!")
+
+        if cls.is_agent_server():
             raise ValueError("Agent server is not available in the current context.")
 
-        if not Library._agent_client:
-            Library._agent_client = Library._lib_type(str(Library.agent_client_libpath))  # type: ignore
+        if not cls._agent_client:
+            cls._agent_client = cls._lib_type(str(cls.agent_client_libpath))
+
+        return cls._agent_client
 
-        return Library._agent_client
+    @classmethod
+    def agent_server(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaAgentServer 库 / Get MaaAgentServer library
 
-    @staticmethod
-    def agent_server() -> ctypes.CDLL:
-        if not Library.is_agent_server():
+        Returns:
+            (ctypes.CDLL | ctypes.WinDLL): MaaAgentServer 动态库对象 / MaaAgentServer dynamic library object
+
+        Raises:
+            ValueError: 如果不在 AgentServer 模式下调用
+        """
+        if cls._lib_type is None:
+            raise RuntimeError("Library._lib_type is None!")
+
+        if not cls.is_agent_server():
             raise ValueError("Agent client is not available in the current context.")
 
-        if not Library._agent_server:
-            Library._agent_server = Library._lib_type(str(Library.agent_server_libpath))  # type: ignore
+        if not cls._agent_server:
+            cls._agent_server = cls._lib_type(str(cls.agent_server_libpath))
+
+        return cls._agent_server
+
+    @classmethod
+    def is_agent_server(cls) -> bool:
+        """判断是否为 AgentServer 模式 / Check if in AgentServer mode
 
-        return Library._agent_server
+        Returns:
+            bool: 是否为 AgentServer 模式 / Whether in AgentServer mode
+        """
+        return cls._is_agent_server
 
-    @staticmethod
-    def is_agent_server() -> bool:
-        return Library._is_agent_server
+    @classmethod
+    def version(cls) -> str:
+        """获取 MaaFramework 版本 / Get MaaFramework version
 
-    @staticmethod
-    def version() -> str:
-        Library._set_api_properties()
+        Returns:
+            str: 版本字符串 / Version string
+        """
+        cls._set_api_properties()
 
-        return Library.framework().MaaVersion().decode()
+        return cls.framework().MaaVersion().decode()
 
     _api_properties_initialized: bool = False
 
-    @staticmethod
-    def _set_api_properties():
-        if Library._api_properties_initialized:
+    @classmethod
+    def _set_api_properties(cls):
+        if cls._api_properties_initialized:
             return
 
-        Library._api_properties_initialized = True
+        cls._api_properties_initialized = True
 
-        Library.framework().MaaVersion.restype = ctypes.c_char_p
-        Library.framework().MaaVersion.argtypes = []
+        cls.framework().MaaVersion.restype = ctypes.c_char_p
+        cls.framework().MaaVersion.argtypes = []