mcsmapi 0.1.6__py3-none-any.whl → 0.1.8b1__py3-none-any.whl

mcsmapi/models/instance.py

@@ -1,291 +1,313 @@
-from typing import List, Dict, Optional
+from enum import IntEnum
+from typing import Any, TypedDict
 from pydantic import BaseModel
-from mcsmapi.models.file import FileList
 from mcsmapi.models.image import DockerConfig
 
 
+class CRLFType(IntEnum):
+    """换行符"""
+
+    LF = 0
+    CR = 1
+    CRLF = 2
+
+
+class Status(IntEnum):
+    """实例状态"""
+
+    BUSY = -1
+    STOP = 0
+    STOPPING = 1
+    STARTING = 2
+    RUNNING = 3
+
+
+class batchOperationDetail(TypedDict):
+    """批量操作的实例信息"""
+
+    uuid: str
+    """实例UUID"""
+    daemonId: str
+    """节点UUID"""
+
+
 class TerminalOption(BaseModel):
     """终端选项"""
 
-    """是否启用颜色输出"""
     haveColor: bool = False
-    """是否使用伪终端 (PTY)"""
+    """是否启用前端颜色渲染"""
     pty: bool = True
+    """是否使用伪终端 (PTY)"""
+    ptyWindowCol: int = 164
+    """PTY 窗口列数"""
+    ptyWindowRow: int = 40
+    """PTY 窗口行数"""
 
 
 class EventTask(BaseModel):
     """事件任务"""
 
-    """是否自动启动"""
     autoStart: bool = False
-    """是否自动重启"""
+    """是否自动启动"""
     autoRestart: bool = True
-    """是否忽略该任务"""
+    """是否自动重启"""
     ignore: bool = False
+    """是否忽略该任务"""
 
 
 class PingConfig(BaseModel):
-    """服务器 Ping 配置"""
+    """服务器 Ping 配置(已弃用)"""
 
-    """服务器 IP 地址"""
     ip: str = ""
-    """服务器端口"""
+    """服务器 IP 地址"""
     port: int = 25565
-    """Ping 类型 (1: 默认类型)"""
+    """服务器端口"""
     type: int = 1
+    """Ping 类型 (0: UDP, 1: TCP)"""
 
 
 class InstanceConfig(BaseModel):
     """实例配置信息"""
 
-    """实例名称"""
     nickname: str = "New Name"
-    """启动命令"""
+    """实例名称"""
     startCommand: str = "cmd.exe"
-    """停止命令"""
+    """启动命令"""
     stopCommand: str = "^C"
-    """工作目录"""
+    """停止命令"""
     cwd: str = ""
+    """工作目录"""
+    ie: str = "utf8"
     """输入编码"""
-    ie: str = "gbk"
+    oe: str = "UTF-8"
     """输出编码"""
-    oe: str = "gbk"
-    """创建时间 (Unix 时间戳)"""
     createDatetime: int = 0
-    """最后修改时间 (Unix 时间戳)"""
+    """创建时间 (Unix 时间戳)"""
     lastDatetime: int = 0
-    """实例类型 (universal, minecraft 等)"""
+    """最后修改时间 (Unix 时间戳)"""
     type: str = "universal"
+    """实例类型 (universal, minecraft 等)"""
+    tag: list[str] = []
     """实例标签"""
-    tag: List[str] = []
-    """实例结束时间 (可选)"""
-    endTime: Optional[int] = None
+    endTime: int | None = None
+    """实例到期时间"""
+    fileCode: str = "utf8"
     """文件编码"""
-    fileCode: str = "gbk"
-    """进程类型 (如 docker, local)"""
-    processType: str = "docker"
-    """更新命令"""
+    processType: str = "general"
+    """进程类型 (如 docker, general)"""
     updateCommand: str = "shutdown -s"
+    """更新命令"""
+    actionCommandList: list[str] = []
     """实例可执行的操作命令列表"""
-    actionCommandList: List[str] = []
-    """换行符 (0: LF, 1: CR, 2: CRLF)"""
-    crlf: int = 2
+    crlf: CRLFType = CRLFType.CRLF
+    """换行符"""
+    docker: DockerConfig = DockerConfig()
     """Docker 相关配置"""
-    docker: "DockerConfig" = DockerConfig()
+    enableRcon: bool = False
     """是否启用 RCON 远程控制"""
-    enableRcon: bool = True
-    """RCON 连接密码"""
     rconPassword: str = ""
-    """RCON 端口"""
+    """RCON 连接密码"""
     rconPort: int = 2557
-    """RCON IP 地址"""
+    """RCON 端口"""
     rconIp: str = ""
-    """终端选项配置"""
+    """RCON IP 地址"""
     terminalOption: TerminalOption = TerminalOption()
-    """事件任务配置"""
+    """终端选项配置"""
     eventTask: EventTask = EventTask()
-    """服务器 Ping 监测配置"""
+    """事件任务配置"""
     pingConfig: PingConfig = PingConfig()
+    """服务器 Ping 监测配置(已弃用)"""
+    runAs: str = ""
+    """运行该实例的系统用户，为空则使用启动面板的系统用户"""
 
 
-class ProcessInfo(BaseModel):
+class InstanceProcessInfo(BaseModel):
     """进程信息"""
 
+    cpu: int
     """CPU 使用率 (单位: %)"""
-    cpu: int = 0
+    memory: int
     """进程占用内存 (单位: KB)"""
-    memory: int = 0
+    ppid: int
     """父进程 ID"""
-    ppid: int = 0
+    pid: int
     """进程 ID"""
-    pid: int = 0
+    ctime: int
     """进程创建时间 (Unix 时间戳)"""
-    ctime: int = 0
+    elapsed: int
     """进程运行时长 (单位: 秒)"""
-    elapsed: int = 0
+    timestamp: int
     """时间戳"""
-    timestamp: int = 0
 
 
 class InstanceInfo(BaseModel):
-    """实例运行状态信息( 这些选项在新版中已不再支持设置，但仍在API中返回)"""
+    """实例运行状态信息(这些选项在新版中已不再支持设置，但仍在API中返回)"""
 
-    """当前玩家数量 (-1 表示未知)"""
-    currentPlayers: int = -1
-    """文件锁状态 (0: 无锁)"""
+    currentPlayers: int
+    """当前玩家数量"""
     fileLock: int = 0
-    """最大允许玩家数 (-1 表示未知)"""
+    """文件锁状态 (0: 无锁)"""
     maxPlayers: int = -1
-    """是否启用 FRP 远程服务"""
+    """最大允许玩家数 (-1 表示未知)"""
     openFrpStatus: bool = False
+    """是否启用 FRP 远程服务"""
+    playersChart: list[dict] = []
     """玩家数量变化图表数据"""
-    playersChart: List[Dict] = []
-    """服务器版本"""
     version: str = ""
+    """服务器版本"""
 
 
 class InstanceDetail(BaseModel):
     """实例详细信息"""
 
+    config: InstanceConfig
     """实例的配置信息"""
-    config: InstanceConfig = InstanceConfig()
+    info: InstanceInfo
     """实例的运行状态信息"""
-    info: InstanceInfo = InstanceInfo()
-    """所属的守护进程 (Daemon) ID"""
-    daemonId: str = ""
-    """实例唯一标识符 (UUID)"""
-    instanceUuid: str = ""
+    daemonId: str
+    """所属的节点UUID"""
+    instanceUuid: str
+    """实例UUID"""
+    processInfo: InstanceProcessInfo
     """实例的进程信息"""
-    processInfo: ProcessInfo = ProcessInfo()
-    """实例的存储空间大小(始终为`0`)"""
-    space: int = 0  # 在 MCSM 代码中，此项始终为 0，意义不明
+    started: int
     """实例的启动次数"""
-    started: int = 0
-    """实例状态 (-1: 忙碌, 0: 停止, 1: 停止中, 2: 启动中, 3: 运行中)"""
-    status: int = 0
+    status: Status
+    """实例状态"""
 
-    def start(self) -> str | bool:
+    def start(self):
         """
-        启动该实例。
+        启动该实例
 
-        **返回:**
-        - str|bool: str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 返回被操作的实例的UUID
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().start(self.daemonId, self.instanceUuid)
+        return Instance.start(self.daemonId, self.instanceUuid)
 
-    def stop(self) -> str | bool:
+    def stop(self):
         """
-        停止该实例。
+        停止该实例
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 返回被操作的实例的UUID
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().stop(self.daemonId, self.instanceUuid)
+        return Instance.stop(self.daemonId, self.instanceUuid)
 
-    def restart(self) -> str | bool:
+    def restart(self):
         """
-        重启该实例。
+        重启该实例
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 返回被操作的实例的UUID
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().restart(self.daemonId, self.instanceUuid)
+        return Instance.restart(self.daemonId, self.instanceUuid)
 
-    def kill(self) -> str | bool:
+    def kill(self):
         """
-        强制关闭该实例。
+        强制关闭该实例
 
-        **返回:**
-        - str|bool: 返回结果中的 "instanceUuid" 字段值，如果未找到该字段，则默认返回True。
+        :returns: 返回被操作的实例的UUID
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().kill(self.daemonId, self.instanceUuid)
+        return Instance.kill(self.daemonId, self.instanceUuid)
 
-    def delete(self, deleteFile=False) -> str:
+    def delete(self, deleteFile=False):
         """
-        删除该实例。
+        删除该实例
 
-        **返回:**
-        - str: 被删除的实例的uuid。
+        :returns: 被删除的实例的uuid
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().delete(self.daemonId, [self.instanceUuid], deleteFile)[0]
+        return Instance.delete(self.daemonId, [self.instanceUuid], deleteFile)[0]
 
-    def update(self) -> bool:
+    def update(self):
         """
-        升级实例。
+        升级实例
 
-        **返回:**
-        - bool: 返回操作结果，成功时返回True。
+        :returns: 操作成功返回True
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().update(self.daemonId, self.instanceUuid)
+        return Instance.update(self.daemonId, self.instanceUuid)
 
-    def updateConfig(self, config: dict) -> str | bool:
+    def updateConfig(self, config: dict[str, Any]):
         """
-        更新该实例配置。
+        更新该实例配置
 
-        **参数:**
-        - config (dict): 新的实例配置，以字典形式提供，缺失内容由使用原实例配置填充。
+        :params config: 新的实例配置，以字典形式提供，缺失内容由使用原实例配置填充
 
-        **返回:**
-        - str|bool: 更新成功后返回更新的实例UUID，如果未找到该字段，则默认返回True。
+        :returns: 更新成功后返回更新的实例UUID
         """
         from mcsmapi.apis.instance import Instance
 
-        updated_config = self.config.dict()
+        updated_config = self.config.model_dump()
         updated_config.update(config)
 
-        instance_config = InstanceConfig(**updated_config).dict()
+        instance_config = InstanceConfig(**updated_config).model_dump()
 
-        return Instance().updateConfig(
-            self.daemonId, self.instanceUuid, instance_config
-        )
+        return Instance.updateConfig(self.daemonId, self.instanceUuid, instance_config)
 
-    def reinstall(self, targetUrl: str, title: str = "", description: str = "") -> bool:
+    def reinstall(self, targetUrl: str, title: str = "", description: str = ""):
         """
-        重装实例。
+        重装实例
 
-        **参数:**
-        - targetUrl (str): 重装文件的目标URL。
-        - title (str): 重装文件的标题。
-        - description (str, optional): 重装文件的描述，默认为空字符串。
+        :params targetUrl: 重装文件的目标URL
+        :params title: 重装文件的标题
+        :params description: 重装文件的描述，默认为空字符串
 
-        **返回:**
-        - bool: 返回操作结果，成功时返回True
+        :returns: 操作成功返回True
         """
         from mcsmapi.apis.instance import Instance
 
-        return Instance().reinstall(
+        return Instance.reinstall(
             self.daemonId, self.instanceUuid, targetUrl, title, description
         )
 
-    def files(self, target: str = "", page: int = 0, page_size: int = 100) -> FileList:
+    def files(
+        self, target: str = "", page: int = 0, page_size: int = 100, file_name: str = ""
+    ):
         """
-        获取实例的文件列表。
+        获取实例的文件列表
 
-        **参数:**
-        - target (str, 可选): 用于文件过滤的目标路径。默认为空字符串，表示不按路径过滤
-        - page (int, 可选): 指定分页的页码。默认为0。
-        - page_size (int, 可选): 指定每页的文件数量。默认为100。
+        :params target: 用于文件过滤的目标路径默认为空字符串，表示不按路径过滤
+        :params page: 指定分页的页码
+        :params page_size: 指定每页的文件数量
+        :params file_name: 用于在文件列表中过滤出名称包含指定字符串的文件或文件夹
 
-        **返回:**
-        - FileList: 文件列表。
+        :returns: 文件列表
         """
         from mcsmapi.apis.file import File
 
-        return File().show(self.daemonId, self.instanceUuid, target, page, page_size)
+        return File.show(
+            self.daemonId, self.instanceUuid, target, page, page_size, file_name
+        )
 
 
 class InstanceCreateResult(BaseModel):
     """实例创建结果"""
 
-    """实例唯一标识符 (UUID)"""
     instanceUuid: str = ""
-    """实例的配置信息"""
+    """实例UUID"""
     config: InstanceConfig = InstanceConfig()
+    """实例的配置信息"""
 
 
 class InstanceSearchList(BaseModel):
     """实例搜索列表"""
 
-    """每页的实例数量"""
     pageSize: int = 0
-    """最大页数"""
+    """每页的实例数量"""
     maxPage: int = 0
+    """最大页数"""
+    data: list[InstanceDetail] = []
     """实例详细信息列表"""
-    data: List[InstanceDetail] = []
-    """所属的守护进程 (Daemon) ID"""
     daemonId: str = ""
+    """所属的节点UUID"""
 
     def __init__(self, **data: str):
         """实例化对象，并在每个实例中填充 daemonId"""
@@ -297,7 +319,7 @@ class InstanceSearchList(BaseModel):
 class UserInstancesList(BaseModel):
     """用户实例列表"""
 
-    """实例唯一标识符 (UUID)"""
     instanceUuid: str = ""
-    """所属的守护进程 (Daemon) ID"""
+    """实例UUID"""
     daemonId: str = ""
+    """所属的节点UUID"""