mcsmapi 0.1.7__py3-none-any.whl → 0.1.8b2__py3-none-any.whl

mcsmapi/apis/instance.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Literal
 from mcsmapi.pool import ApiPool
 from mcsmapi.request import send
 from mcsmapi.models.instance import (
@@ -6,6 +6,7 @@ from mcsmapi.models.instance import (
     InstanceDetail,
     InstanceCreateResult,
     InstanceConfig,
+    batchOperationDetail,
 )
 
 
@@ -16,22 +17,20 @@ class Instance:
         page: int = 1,
         page_size: int = 20,
         instance_name: str = "",
-        status: str = "",
+        status: Literal[-1, 0, 1, 2, 3, ""] = "",
         tag: list[str] | None = None,
     ) -> InstanceSearchList:
         """
         根据指定的参数搜索实例信息
 
-        **参数:**
-        - daemonId (str): 守护进程的唯一标识符
-        - page (int): 页码，用于指示返回数据的页数。默认为1，表示返回第一页数据
-        - page_size (int): 每页大小，用于指定每页包含的数据条数。默认为20，表示每页包含20条数据
-        - instance_name (str): 实例的名称。默认为空字符串，表示不进行实例名称过滤
-        - status (str): 实例的状态。默认为空字符串，表示不进行状态过滤
-        - tag (list[str] | None): 实例的标签列表。默认为None，表示不进行标签过滤
+        :params daemonId: 节点的UUID
+        :params page: 页码，用于指示返回数据的页数
+        :params page_size: 每页大小，用于指定每页包含的数据条数
+        :params instance_name: 用于过滤的实例名称
+        :params status: 用于过滤的实例状态
+        :params tag: 用于过滤的实例标签列表
 
-        **返回:**
-        - InstanceSearchList: 包含搜索结果的模型。该模型包含了符合搜索条件的实例信息列表，以及总数据条数、总页数等分页信息。
+        :returns: 包含搜索结果的模型
         """
         if tag is None:
             tag = []
@@ -54,75 +53,67 @@ class Instance:
         """
         获取指定实例的详细信息
 
-        **参数:**
-        - daemonId (str): 守护进程的唯一标识符
-        - uuid (str): 实例的唯一标识符
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - InstanceDetail: 包含实例详细信息的模型。
+        :returns: 包含实例详细信息的模型
         """
         result = send(
             "GET",
             ApiPool.INSTANCE,
             params={"uuid": uuid, "daemonId": daemonId},
         )
-        return InstanceDetail(**result)
+        return InstanceDetail(**result, daemonId=daemonId)
 
     @staticmethod
     def create(daemonId: str, config: dict[str, Any]) -> InstanceCreateResult:
         """
-        创建一个实例。
+        创建一个实例
 
-        **参数:**
-        - daemonId (str): 守护进程的唯一标识符，用于关联新创建的实例。
-        - config (dict[str, Any]): 实例的配置信息，以字典形式提供，缺失内容由InstanceConfig模型补全。
+        :params daemonId: 节点的UUID，用于关联新创建的实例
+        :params config: 实例的配置信息，以字典形式提供，缺失内容由InstanceConfig模型补全
 
-        **返回:**
-        - InstanceCreateResult: 一个包含新创建实例信息的结果对象，内容由InstanceCreateResult模型定义。
+        :returns: 一个包含新创建实例信息的结果对象，内容由InstanceCreateResult模型定义
         """
         result = send(
             "POST",
             ApiPool.INSTANCE,
             params={"daemonId": daemonId},
-            data=InstanceConfig(**config).dict(),
+            data=InstanceConfig(**config).model_dump(),
         )
         return InstanceCreateResult(**result)
 
     @staticmethod
-    def updateConfig(daemonId: str, uuid: str, config: dict) -> str | bool:
+    def updateConfig(daemonId: str, uuid: str, config: dict[str, Any]) -> str:
         """
-        更新实例配置。
+        更新实例配置
 
-        **不建议直接使用此函数，建议调用search后在data属性内使用updateConfig方法按需更新**
+        **不建议直接使用此函数，建议调用search后使用实例对象的updateConfig方法按需更新**
 
-        **参数:**
-        - daemonId (str): 守护进程的标识符。
-        - uuid (str): 实例的唯一标识符。
-        - config (dict): 新的实例配置，以字典形式提供，缺失内容由InstanceConfig模型补全。
+        :params daemonId: 节点的标识符
+        :params uuid: 实例的UUID
+        :params config: 新的实例配置，以字典形式提供，缺失内容由InstanceConfig模型补全
 
-        **返回:**
-        - str|bool: 更新成功后返回更新的实例UUID，如果未找到该字段，则默认返回True。
+        :returns: 被更新配置的实例UUID
         """
         result = send(
             "PUT",
             ApiPool.INSTANCE,
             params={"uuid": uuid, "daemonId": daemonId},
-            data=InstanceConfig(**config).dict(),
+            data=InstanceConfig(**config).model_dump(),
         )
-        return result.get("uuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
     def delete(daemonId: str, uuids: list[str], deleteFile: bool = False) -> list[str]:
         """
-        删除实例。
+        删除实例
 
-        **参数:**
-        - daemonId (str): 守护进程的标识符。
-        - uuids (list): 要删除的实例UUID列表。
-        - deleteFile (bool, optional): 是否删除关联的文件，默认为False。
+        :params daemonId: 节点的UUID
+        :params uuids: 要删除的实例UUID列表
+        :params deleteFile: 是否删除关联的文件
 
-        **返回:**
-        - list[str]: 删除操作后返回的UUID列表。
+        :returns: 被删除的实例UUID列表
         """
         return send(
             "DELETE",
@@ -132,109 +123,97 @@ class Instance:
         )
 
     @staticmethod
-    def start(daemonId: str, uuid: str) -> str | bool:
+    def start(daemonId: str, uuid: str) -> str:
         """
-        启动实例。
+        启动实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要启动的实例。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 被启动的实例的UUID
         """
         result = send(
             "GET",
             f"{ApiPool.PROTECTED_INSTANCE}/open",
             params={"daemonId": daemonId, "uuid": uuid},
         )
-        return result.get("instanceUuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
-    def stop(daemonId: str, uuid: str) -> str | bool:
+    def stop(daemonId: str, uuid: str) -> str:
         """
-        关闭实例。
+        关闭实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要关闭的实例。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 被关闭的实例的UUID
         """
         result = send(
             "GET",
             f"{ApiPool.PROTECTED_INSTANCE}/stop",
             params={"daemonId": daemonId, "uuid": uuid},
         )
-        return result.get("instanceUuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
-    def restart(daemonId: str, uuid: str) -> str | bool:
+    def restart(daemonId: str, uuid: str) -> str:
         """
-        重启实例。
+        重启实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要重启的实例。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 被重启的实例的UUID
         """
         result = send(
             "GET",
             f"{ApiPool.PROTECTED_INSTANCE}/restart",
             params={"daemonId": daemonId, "uuid": uuid},
         )
-        return result.get("instanceUuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
-    def kill(daemonId: str, uuid: str) -> str | bool:
+    def kill(daemonId: str, uuid: str) -> str:
         """
-        强制关闭实例。
+        强制关闭实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要强制关闭的实例。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 被强制关闭的实例的UUID
         """
         result = send(
             "GET",
             f"{ApiPool.PROTECTED_INSTANCE}/kill",
             params={"daemonId": daemonId, "uuid": uuid},
         )
-        return result.get("instanceUuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
-    def batchOperation(instances: list[dict[str, str]], operation: str) -> bool:
+    def batchOperation(
+        instances: list[batchOperationDetail],
+        operation: Literal["start", "stop", "restart", "kill"],
+    ) -> bool:
         """
-        对多个实例进行批量操作。
+        对多个实例进行批量操作
 
-        **参数:**
-        - instances (list[dict[str,str]]): 包含多个实例信息的列表，每个实例信息为一个字典，包含 "uuid" 和 "daemonId" 字段。
-        - operation (str): 要执行的操作，可以是 "start", "stop", "restart", 或 "kill"。
+        :params instances: 包含多个实例信息的列表
+        :params operation: 要执行的操作
 
-        **返回:**
-        - list[dict[str,str]]:包含每个实例操作结果的列表，每个结果为一个字典，包含 "uuid" 和 "result" 字段。
+        :returns: 操作成功返回True
         """
-        if operation in {"start", "stop", "restart", "kill"}:
-            return send("POST", f"{ApiPool.INSTANCE}/multi_{operation}", data=instances)
-        else:
-            raise ValueError("operation must be one of start, stop, restart, kill")
+        return send("POST", f"{ApiPool.INSTANCE}/multi_{operation}", data=instances)
 
     @staticmethod
     def update(daemonId: str, uuid: str) -> bool:
         """
-        升级实例。
+        更新实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要升级的实例。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
 
-        **返回:**
-        - bool: 返回操作结果，成功时返回True。
+        :returns: 操作成功返回True
         """
         return send(
             "POST",
@@ -245,35 +224,29 @@ class Instance:
     @staticmethod
     def command(daemonId: str, uuid: str, command: str) -> str:
         """
-        向实例发送命令。
+        向实例发送命令
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要发送命令的实例。
-        - command (str): 要发送的命令。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
+        :params command: 要发送的命令
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 被操作的实例的UUID
         """
         result = send(
             "GET",
             f"{ApiPool.PROTECTED_INSTANCE}/command",
             params={"daemonId": daemonId, "uuid": uuid, "command": command},
         )
-        return result.get("instanceUuid", True)
+        return result["instanceUuid"]
 
     @staticmethod
-    def get_output(daemonId: str, uuid: str, size: int | str = "") -> str:
+    def get_output(daemonId: str, uuid: str, size: int | None = None) -> str:
         """
-        获取实例输出。
-
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符，用于指定需要获取输出的实例。
-        - size (int, optional): 获取的日志大小: 1KB ~ 2048KB，如果未设置，则返回所有日志
+        获取实例输出
 
-        **返回:**
-        - str: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
+        :params size: 获取的输出大小: 1KB ~ 2048KB，如果未设置，则返回所有日志
         """
         return send(
             "GET",
@@ -290,17 +263,15 @@ class Instance:
         description: str = "",
     ) -> bool:
         """
-        重装实例。
+        重装实例
 
-        **参数:**
-        - daemonId (str): 守护进程的ID，用于标识特定的守护进程。
-        - uuid (str): 实例的唯一标识符。
-        - targetUrl (str): 重装文件的目标URL。
-        - title (str): 重装文件的标题。
-        - description (str, optional): 重装文件的描述，默认为空字符串。
+        :params daemonId: 节点的UUID
+        :params uuid: 实例的UUID
+        :params targetUrl: 重装文件的目标URL
+        :params title: 重装文件的标题
+        :params description: 重装文件的描述
 
-        **返回:**
-        - bool: 返回操作结果，成功时返回True。
+        :returns: 操作成功返回True
         """
         return send(
             "POST",

mcsmapi/apis/overview.py

@@ -11,7 +11,7 @@ class Overview:
         """
         result = send("GET", ApiPool.OVERVIEW)
         return OverviewModel(**result)
-    
+
     @staticmethod
     def logs():
         """

mcsmapi/apis/user.py

@@ -1,25 +1,26 @@
-from typing import Any
+from typing import Any, Literal
 from mcsmapi.pool import ApiPool
 from mcsmapi.request import send
-from mcsmapi.models.user import SearchUserModel, UserConfig
+from mcsmapi.models.user import SearchUserModel, UserConfig, UserCreateResult
 
 
 class User:
     @staticmethod
     def search(
-        username: str = "", page: int = 1, page_size: int = 20, role: str = ""
+        username: str = "",
+        page: int = 1,
+        page_size: int = 20,
+        role: Literal[-1, 1, 10, ""] = "",
     ) -> SearchUserModel:
-        """根据用户名和角色搜索用户信息
+        """
+        根据用户名和角色搜索用户信息
 
-        **参数:**
-        - username (str): 要搜索的用户名。默认为空字符串，表示不进行用户名过滤
-        - page (int): 页码，用于指示返回数据的页数。默认为1，表示返回第一页数据
-        - page_size (int): 每页大小，用于指定每页包含的数据条数。默认为20，表示每页包含20条数据
-        - role (str): 用户权限。默认为空字符串，表示不进行权限过滤
-                     可用的值为 1=用户, 10=管理员, -1=被封禁的用户
+        :params uername: 要搜索的用户名,为空则列出全部用户
+        :params page: 页码，用于指示返回数据的第几页
+        :params page_size: 每页数据条数
+        :params role: 用于过滤的用户权限
 
-        **返回:**
-        - SearchUserModel: 包含搜索结果的模型。该模型包含了符合搜索条件的用户信息列表，以及总数据条数、总页数等分页信息。
+        :returns: 包含搜索结果的模型
         """
         result = send(
             "GET",
@@ -34,37 +35,34 @@ class User:
         return SearchUserModel(**result)
 
     @staticmethod
-    def create(username: str, password: str, permission: int = 1) -> str | bool:
+    def create(username: str, password: str, permission: int = 1) -> UserCreateResult:
         """
-        创建新用户的方法
+        创建新用户
 
-        **参数:**
-        - username (str): 用户名，字符串类型
-        - password (str): 密码，字符串类型
-        - permission (int): 权限等级，整数类型，默认值为1
+        :params username: 用户名
+        :params password: 密码
+        :params permission: 权限等级
 
-        **返回:**
-        - str|bool: 创建成功后返回用户的UUID，如果未找到该字段，则默认返回True。
+        :returns: 包含创建结果的模型
         """
-        return send(
+        result = send(
             "POST",
             ApiPool.AUTH,
             data={"username": username, "password": password, "permission": permission},
-        ).get("uuid", True)
+        )
+        return UserCreateResult(**result)
 
     @staticmethod
     def update(uuid: str, config: dict[str, Any]) -> bool:
         """
-        更新用户信息的方法
+        更新用户信息
 
-        **不建议直接使用此函数，建议调用search后使用update方法按需更新**
+        **不建议直接使用此函数，建议调用search后使用用户对象的update方法按需更新**
 
-        **参数:**
-        - uuid (str): 用户的唯一标识符UUID
-        - config (dict[str, Any]): 新的用户信息，以字典形式提供，缺失内容由UserConfig模型补全。
+        :params uuid: 用户的UUID
+        :params config: 新的用户信息，以字典形式提供，缺失内容由 UserConfig 模型提供默认值
 
-        **返回:**
-        - bool: 成功时返回True
+        :returns: 成功时返回True
         """
         return send(
             "PUT",
@@ -75,12 +73,10 @@ class User:
     @staticmethod
     def delete(uuids: list[str]) -> bool:
         """
-        删除用户的方法
+        删除用户
 
-        **参数:**
-        - uuids (list[str]): 包含要删除的用户UUID的列表。
+        :params uuids: 包含要删除的用户UUID的列表
 
-        **返回:**
-        - bool: 成功时返回True
+        :returns: 成功时返回True
         """
         return send("DELETE", ApiPool.AUTH, data=uuids)

mcsmapi/models/common.py

@@ -2,7 +2,7 @@ from pydantic import BaseModel
 
 
 class CpuMemChart(BaseModel):
-    """节点资源使用率信息"""
+    """资源使用率信息"""
 
     cpu: float
     """cpu使用率"""
@@ -11,17 +11,17 @@ class CpuMemChart(BaseModel):
 
 
 class ProcessInfo(BaseModel):
-    """节点进程详细信息"""
+    """进程详细信息"""
 
     cpu: int
-    """远程节点使用的cpu资源(单位: byte)"""
+    """CPU 使用率（百分比）"""
     memory: int
-    """远程节点使用的内存资源(单位: byte)"""
+    """内存使用量（MB）"""
     cwd: str
-    """远程节点的工作路径"""
+    """工作路径"""
 
 
-class InstanceInfo(BaseModel):
+class InstanceStat(BaseModel):
     """实例统计信息"""
 
     running: int