mcsmapi 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

mcsmapi/apis/instance.py

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

mcsmapi/apis/overview.py

@@ -0,0 +1,17 @@
+from ..pool import ApiPool
+from ..request import send
+from ..models.overview import OverviewModel
+
+
+class Overview:
+    def init(self):
+        """
+        初始化方法，用于获取API概览信息并构建概览模型。
+
+        本方法通过发送GET请求获取API概览信息，确保返回的数据类型为字典，
+        然后使用这些数据来构建一个OverviewModel实例。
+
+        :return: 返回一个OverviewModel实例，该实例使用获取的API概览信息进行初始化。
+        """
+        result = send("GET", ApiPool.OVERVIEW)
+        return OverviewModel(**result)

mcsmapi/apis/user.py

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

mcsmapi/exceptions.py

@@ -0,0 +1,5 @@
+class MCSMError(Exception):
+    def __init__(self, status_code, data=None):
+        self.status_code = status_code
+        self.data = data
+        super().__init__(status_code, data)

mcsmapi/models/daemon.py

@@ -0,0 +1,134 @@
+from typing import Any, List
+from pydantic import BaseModel
+from ..models.instance import InstanceCreateResult
+
+
+class CpuMemChart(BaseModel):
+    cpu: float = 0
+    mem: float = 0
+
+
+class ProcessInfo(BaseModel):
+    cpu: int = 0
+    memory: int = 0
+    cwd: str = ""
+
+
+class InstanceInfo(BaseModel):
+    running: int = 0
+    total: int = 0
+
+
+class SystemInfo(BaseModel):
+    type: str = ""
+    hostname: str = ""
+    platform: str = ""
+    release: str = ""
+    uptime: float = 0
+    cwd: str = ""
+    loadavg: List[float] = []
+    freemem: int = 0
+    cpuUsage: float = 0
+    memUsage: float = 0
+    totalmem: int = 0
+    processCpu: int = 0
+    processMem: int = 0
+
+
+class DaemonModel(BaseModel):
+    version: str = ""
+    process: ProcessInfo = ProcessInfo()
+    instance: InstanceInfo = InstanceInfo()
+    system: SystemInfo = SystemInfo()
+    cpuMemChart: List[CpuMemChart] = []
+    uuid: str = ""
+    ip: str = ""
+    port: int = 24444
+    prefix: str = ""
+    available: bool = False
+    remarks: str = ""
+
+    def delete(self) -> bool:
+        """
+        删除该节点。
+
+        返回:
+        - bool: 删除成功后返回True
+        """
+        from ..apis.daemon import Daemon
+
+        return Daemon().delete(self.uuid)
+
+    def link(self) -> bool:
+        """
+        链接该节点。
+
+        返回:
+        - bool: 链接成功后返回True
+        """
+        from ..apis.daemon import Daemon
+
+        return Daemon().link(self.uuid)
+
+    def updateConfig(self, config: dict[str, Any]) -> bool:
+        """
+        更新该节点的配置。
+
+        参数:
+        - config (dict[str, Any]): 节点的配置信息，以字典形式提供，缺失内容使用原节点配置填充。
+
+        返回:
+        - bool: 更新成功后返回True
+        """
+        from ..apis.daemon import Daemon
+
+        updated_config = self.dict()
+        updated_config.update(config)
+        # 过滤节点配置中不需要的字段
+        daemon_config_dict = {
+            key: updated_config[key]
+            for key in DaemonConfig.__fields__.keys()
+            if key in updated_config
+        }
+
+        daemon_config = DaemonConfig(**daemon_config_dict).dict()
+
+        return Daemon().update(self.uuid, daemon_config)
+
+    def createInstance(self, config: dict[str, Any]) -> "InstanceCreateResult":
+        """
+        在当前节点创建一个实例。
+
+        参数:
+        - config (dict[str, Any]): 实例的配置信息，以字典形式提供，缺失内容由InstanceConfig模型补全。
+
+        返回:
+        - InstanceCreateResult: 一个包含新创建实例信息的结果对象，内容由InstanceCreateResult模型定义。
+        """
+        from ..apis.instance import Instance
+        from .instance import InstanceConfig
+
+        return Instance().create(self.uuid, InstanceConfig(**config).dict())
+
+    def deleteInstance(self, uuids: list[str], deleteFile=False) -> list[str]:
+        """
+        删除当前节点的一个或多个实例。
+
+        参数:
+        - uuids (list[str]): 要删除的实例UUID列表。
+        - deleteFile (bool, optional): 是否删除关联的文件，默认为False。
+
+        返回:
+        - list[str]: 删除操作后返回的UUID列表。
+        """
+        from ..apis.instance import Instance
+
+        return Instance().delete(self.uuid, uuids, deleteFile)
+
+
+class DaemonConfig(BaseModel):
+    ip: str = "localhost"
+    port: int = 24444
+    prefix: str = ""
+    remarks: str = "New Daemon"
+    available: bool = True

mcsmapi/models/file.py

@@ -0,0 +1,108 @@
+from pydantic import BaseModel
+from typing import List
+import os
+
+
+class FileItem(BaseModel):
+    name: str = "New File"
+    size: int = 0  # byte
+    time: str = ""
+    mode: int = 777  # Linux file permission
+    type: int = 0  # 0 = Folder, 1 = File
+    daemonId: str = ""
+    uuid: str = ""
+    target: str = ""
+
+    def rename(self, newName: str) -> bool:
+        """
+        重命名该文件或文件夹。
+
+        **参数:**
+        - new_name (str): 源文件或文件夹的新名字。
+
+        **返回:**
+        - bool: 重命名成功后返回True。
+        """
+        from ..apis.file import File
+
+        return File().rename(
+            self.daemonId, self.uuid, os.path.join(self.target, self.name), newName
+        )
+
+    def delete(self) -> bool:
+        """
+        删除该文件或文件夹。
+
+        **返回:**
+        - bool: 重命名成功后返回True。
+        """
+        from ..apis.file import File
+
+        return File().delete(
+            self.daemonId, self.uuid, [os.path.join(self.target, self.name)]
+        )
+
+    def copy(self, target: str) -> bool:
+        from ..apis.file import File
+
+        return File().copyOne(
+            self.daemonId, self.uuid, os.path.join(self.target, self.name), target
+        )
+
+    def move(self, target: str) -> bool:
+        """
+        移动该文件或文件夹到目标路径。
+
+        **参数:**
+        - target (str): 目标文件或文件夹的路径。
+
+        **返回:**
+        - bool: 移动成功后返回True。
+        """
+        from ..apis.file import File
+
+        return File().moveOne(
+            self.daemonId, self.uuid, os.path.join(self.target, self.name), target
+        )
+
+    def unzip(self, target: str, code: str = "utf-8") -> bool:
+        """
+        解压缩该 zip 文件到目标位置。
+
+        **参数:**
+        - target (str): 解压到的目标路径。
+        - code (str, optional): 压缩文件的编码方式，默认为"utf-8"。
+            可选值: utf-8, gbk, big5
+
+        **返回:**
+        - bool: 解压成功后返回True。
+        """
+        from ..apis.file import File
+
+        return File().unzip(
+            self.daemonId, self.uuid, os.path.join(self.target, self.name), target, code
+        )
+
+
+class FileList(BaseModel):
+    items: List[FileItem]
+    page: int = 0
+    pageSize: int = 100
+    total: int = 0
+    absolutePath: str = "\\"
+    daemonId: str = ""
+    uuid: str = ""
+    target: str = ""
+
+    def __init__(self, **data: str):
+        super().__init__(**data)
+        for item in self.items:
+            item.daemonId = self.daemonId
+            item.uuid = self.uuid
+            item.target = self.target
+
+
+
+class CommonConfig(BaseModel):
+    password: str = ""
+    addr: str = ""