MaaFw 2.1.0__py3-none-manylinux2014_x86_64.whl → 5.4.0b1__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

@@ -1,72 +1,131 @@
-from typing import Union
-
 from .define import *
 
 
-class Status:
-    _status: MaaStatusEnum
-
-    def __init__(self, status: Union[MaaStatus, MaaStatusEnum]):
-        self._status = MaaStatusEnum(status)
-
-    def done(self) -> bool:
-        return self._status in [MaaStatusEnum.succeeded, MaaStatusEnum.failed]
-
-    def succeeded(self) -> bool:
-        return self._status == MaaStatusEnum.succeeded
-
-    def failed(self) -> bool:
-        return self._status == MaaStatusEnum.failed
-
-    def pending(self) -> bool:
-        return self._status == MaaStatusEnum.pending
-
-    def running(self) -> bool:
-        return self._status == MaaStatusEnum.running
+class Job:
+    """异步作业句柄 / Asynchronous job handle
 
+    用于跟踪和管理异步操作的状态，如资源加载、控制器连接等。
+    Used to track and manage the status of asynchronous operations
+    such as resource loading, controller connection, etc.
+    """
 
-class Job:
-    job_id: MaaId
+    _job_id: MaaId
 
     def __init__(self, job_id: MaaId, status_func, wait_func):
-        self.job_id = job_id
+        self._job_id = job_id
         self._status_func = status_func
         self._wait_func = wait_func
 
-    def get_id(self) -> int:
-        return int(self.job_id)
+    @property
+    def job_id(self) -> int:
+        """获取作业 ID / Get job ID
+
+        Returns:
+            int: 作业 ID / Job ID
+        """
+        return int(self._job_id)
 
     def wait(self) -> "Job":
-        self._wait_func(self.job_id)
+        """等待作业完成 / 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:
-        return Status(self._status_func(self.job_id))
+        """获取作业状态 / Get job status
 
+        Returns:
+            Status: 作业状态 / Job status
+        """
+        return Status(self._status_func(self._job_id))
+
+    @property
     def done(self) -> bool:
-        return self.status().done()
+        """判断作业是否已完成 / Check if job is done
+
+        Returns:
+            bool: 是否已完成（成功或失败） / Whether done (succeeded or failed)
+        """
+        return self.status.done
 
+    @property
     def succeeded(self) -> bool:
-        return self.status().succeeded()
+        """判断作业是否成功 / Check if job succeeded
 
+        Returns:
+            bool: 是否成功 / Whether succeeded
+        """
+        return self.status.succeeded
+
+    @property
     def failed(self) -> bool:
-        return self.status().failed()
+        """判断作业是否失败 / Check if job failed
+
+        Returns:
+            bool: 是否失败 / Whether failed
+        """
+        return self.status.failed
 
+    @property
     def pending(self) -> bool:
-        return self.status().pending()
+        """判断作业是否等待中 / Check if job is pending
 
+        Returns:
+            bool: 是否等待中 / Whether pending
+        """
+        return self.status.pending
+
+    @property
     def running(self) -> bool:
-        return self.status().running()
+        """判断作业是否运行中 / 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):
-        return self._get_func(self.job_id)
+    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,68 +1,197 @@
 import ctypes
-import ctypes.util
 import pathlib
 import platform
-from typing import Optional, Union
+from typing import Optional
 
 from .define import *
 
 
 class Library:
+    """库加载管理器 / Library loading manager
 
-    initialized = False
+    管理 MaaFramework 各动态库的加载和访问。
+    Manages loading and access to MaaFramework dynamic libraries.
+    """
 
-    @staticmethod
-    def open(path: Union[pathlib.Path, str]) -> Optional[str]:
-        platform_values = {
-            "windows": ("MaaFramework.dll", "MaaToolkit.dll"),
-            "darwin": ("libMaaFramework.dylib", "libMaaToolkit.dylib"),
-            "linux": ("libMaaFramework.so", "libMaaToolkit.so"),
+    _is_agent_server: bool = False
+
+    _framework: Optional[ctypes.CDLL] = None
+    _toolkit: Optional[ctypes.CDLL] = None
+    _agent_client: Optional[ctypes.CDLL] = None
+    _agent_server: Optional[ctypes.CDLL] = None
+    _lib_type = None
+
+    @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():
+            raise FileNotFoundError(f"`{path}` does not exist.")
+
+        WINDOWS = "windows"
+        MACOS = "darwin"
+        LINUX = "linux"
+
+        cls._is_agent_server = agent_server
+
+        if not cls.is_agent_server():
+            framework_library = {
+                WINDOWS: "MaaFramework.dll",
+                MACOS: "libMaaFramework.dylib",
+                LINUX: "libMaaFramework.so",
+            }
+            agent_client_library = {
+                WINDOWS: "MaaAgentClient.dll",
+                MACOS: "libMaaAgentClient.dylib",
+                LINUX: "libMaaAgentClient.so",
+            }
+        else:
+            agent_server_library = {
+                WINDOWS: "MaaAgentServer.dll",
+                MACOS: "libMaaAgentServer.dylib",
+                LINUX: "libMaaAgentServer.so",
+            }
+
+        toolkit_library = {
+            WINDOWS: "MaaToolkit.dll",
+            MACOS: "libMaaToolkit.dylib",
+            LINUX: "libMaaToolkit.so",
         }
 
         platform_type = platform.system().lower()
 
-        if platform_type == "windows":
-            lib_import = ctypes.WinDLL
+        if platform_type == WINDOWS:
+            cls._lib_type = ctypes.WinDLL
         else:
-            lib_import = ctypes.CDLL
-
-        try:
-            Library.framework_libpath = (
-                pathlib.Path(path) / platform_values[platform_type][0]
-            )
-            Library.framework = lib_import(str(Library.framework_libpath))
-        except OSError:
-            Library.framework_libpath = ctypes.util.find_library("MaaFramework")
-            Library.framework = lib_import(str(Library.framework_libpath))
-
-        try:
-            Library.toolkit_libpath = (
-                pathlib.Path(path) / platform_values[platform_type][1]
-            )
-            Library.toolkit = lib_import(str(Library.toolkit_libpath))
-        except OSError:
-            Library.toolkit_libpath = ctypes.util.find_library("MaaToolkit")
-            Library.toolkit = lib_import(str(Library.toolkit_libpath))
-
-        if not Library.framework or not Library.toolkit:
-            Library.initialized = False
-            return None
-
-        Library._set_api_properties()
-        Library.initialized = True
-
-        return Library.version()
-
-    @staticmethod
-    def version() -> str:
-        if not Library.initialized:
-            raise RuntimeError(
-                "Library not initialized, please call `library.open()` first."
-            )
-
-        return Library.framework.MaaVersion().decode()
-
-    @staticmethod
-    def _set_api_properties():
-        Library.framework.MaaVersion.restype = ctypes.c_char_p
-        Library.framework.MaaVersion.argtypes = []
+            cls._lib_type = ctypes.CDLL
+
+        if cls._lib_type is None:
+            raise
+
+        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:
+            cls.agent_server_libpath = path / agent_server_library[platform_type]
+
+        cls.toolkit_libpath = path / toolkit_library[platform_type]
+
+    @classmethod
+    def framework(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaFramework 库 / Get MaaFramework library
+
+        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 cls.agent_server()
+
+    @classmethod
+    def toolkit(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaToolkit 库 / Get MaaToolkit library
+
+        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._toolkit:
+            cls._toolkit = cls._lib_type(str(cls.toolkit_libpath))
+
+        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 cls._agent_client:
+            cls._agent_client = cls._lib_type(str(cls.agent_client_libpath))
+
+        return cls._agent_client
+
+    @classmethod
+    def agent_server(cls) -> Union["ctypes.CDLL", "ctypes.WinDLL"]:
+        """获取 MaaAgentServer 库 / Get MaaAgentServer library
+
+        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 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
+
+        Returns:
+            bool: 是否为 AgentServer 模式 / Whether in AgentServer mode
+        """
+        return cls._is_agent_server
+
+    @classmethod
+    def version(cls) -> str:
+        """获取 MaaFramework 版本 / Get MaaFramework version
+
+        Returns:
+            str: 版本字符串 / Version string
+        """
+        cls._set_api_properties()
+
+        return cls.framework().MaaVersion().decode()
+
+    _api_properties_initialized: bool = False
+
+    @classmethod
+    def _set_api_properties(cls):
+        if cls._api_properties_initialized:
+            return
+
+        cls._api_properties_initialized = True
+
+        cls.framework().MaaVersion.restype = ctypes.c_char_p
+        cls.framework().MaaVersion.argtypes = []