mcsmapi 0.1.1__tar.gz → 0.1.2__tar.gz

mcsmapi-0.1.2/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.2
+Name: mcsmapi
+Version: 0.1.2
+Summary: Shortcut the pypi package of MCSM./快捷操作MCSM的pypi包
+Author-email: molanp <molanpp@outlook.com>
+Project-URL: Source, https://github.com/molanp/mcsmapi
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pydantic
+
+# MCSM API
+
+![Supported MCSManager Versions](https://img.shields.io/badge/Supported%20MCSManager%20Versions-10.x-blue)
+![Python Version](https://img.shields.io/badge/Python%20Version-%3E%3D3.7-blue)
+![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+
+English|[Chinese Simplified](README_zh-cn.md)
+
+> [!important]
+> We need your help, the documentation for this project has not been written yet, if you are willing, please submit pr to help us write the documentation.
+
+## Introduction
+
+`mcsmapi` is a PyPI package based on [MCSManager](https://github.com/MCSManager/MCSManager), designed to simplify interactions with the MCSM API.
+
+With this library, you can more easily access and operate the various features provided by MCSM.
+
+## Installation
+
+You can install `mcsmapi` using `pip`:
+
+```bash
+pip install mcsmapi
+```
+
+## Supported Features
+
+- [x] Dashboard data ([Overview](doc/en/Overview.md))
+- [x] User management ([User](doc/en/User.md))
+- [x] Instance management (`Instance`)
+- [x] Daemon management (`Daemon`)
+- [x] File management (`File`)
+- [x] Image management (`Image`)
+
+## Supported MCSM Versions
+
+| MCSM Version | Support Status |
+| :---: | :---: |
+| 10.x | ✅ |
+
+### Quick Example
+
+```python
+from mcsmapi import MCSMAPI
+
+# Initialize
+mcsm = MCSMAPI("https://example.com")
+
+# Log in with username and password (API permissions depend on the account permissions)
+mcsm.login("username", "password")
+
+# Log in with API key (API permissions depend on the API key permissions)
+mcsm.login_with_apikey("apikey")
+
+# Get dashboard data
+overview = mcsm.overview()
+
+# Get MCSM version
+mcsm_version = mcsm.overview().version
+```
+
+## Contributing
+
+If you encounter any issues or have suggestions for improvements, feel free to submit an [Issue](https://github.com/molanp/mcsmapi/issues) or create a [Pull Request](https://github.com/molanp/mcsmapi/pulls).
+
+## License
+
+`mcsmapi` is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+Please refer to the [LICENSE](LICENSE) file for more details.

mcsmapi-0.1.2/README.md

@@ -0,0 +1,70 @@
+# MCSM API
+
+![Supported MCSManager Versions](https://img.shields.io/badge/Supported%20MCSManager%20Versions-10.x-blue)
+![Python Version](https://img.shields.io/badge/Python%20Version-%3E%3D3.7-blue)
+![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+
+English|[Chinese Simplified](README_zh-cn.md)
+
+> [!important]
+> We need your help, the documentation for this project has not been written yet, if you are willing, please submit pr to help us write the documentation.
+
+## Introduction
+
+`mcsmapi` is a PyPI package based on [MCSManager](https://github.com/MCSManager/MCSManager), designed to simplify interactions with the MCSM API.
+
+With this library, you can more easily access and operate the various features provided by MCSM.
+
+## Installation
+
+You can install `mcsmapi` using `pip`:
+
+```bash
+pip install mcsmapi
+```
+
+## Supported Features
+
+- [x] Dashboard data ([Overview](doc/en/Overview.md))
+- [x] User management ([User](doc/en/User.md))
+- [x] Instance management (`Instance`)
+- [x] Daemon management (`Daemon`)
+- [x] File management (`File`)
+- [x] Image management (`Image`)
+
+## Supported MCSM Versions
+
+| MCSM Version | Support Status |
+| :---: | :---: |
+| 10.x | ✅ |
+
+### Quick Example
+
+```python
+from mcsmapi import MCSMAPI
+
+# Initialize
+mcsm = MCSMAPI("https://example.com")
+
+# Log in with username and password (API permissions depend on the account permissions)
+mcsm.login("username", "password")
+
+# Log in with API key (API permissions depend on the API key permissions)
+mcsm.login_with_apikey("apikey")
+
+# Get dashboard data
+overview = mcsm.overview()
+
+# Get MCSM version
+mcsm_version = mcsm.overview().version
+```
+
+## Contributing
+
+If you encounter any issues or have suggestions for improvements, feel free to submit an [Issue](https://github.com/molanp/mcsmapi/issues) or create a [Pull Request](https://github.com/molanp/mcsmapi/pulls).
+
+## License
+
+`mcsmapi` is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+
+Please refer to the [LICENSE](LICENSE) file for more details.

mcsmapi-0.1.2/mcsmapi/__init__.py

@@ -0,0 +1,54 @@
+import urllib.parse
+from .models.overview import OverviewModel
+from .pool import ApiPool
+from .apis.file import File
+from .apis.user import User
+from .apis.image import Image
+from .apis.daemon import Daemon
+from .apis.instance import Instance
+from .apis.overview import Overview
+from .request import Request, send
+
+
+class MCSMAPI:
+    def __init__(self, url: str, timeout: int = 5) -> None:
+        split_url = urllib.parse.urlsplit(url)
+        Request.set_mcsm_url(
+            urllib.parse.urljoin(f"{split_url.scheme}://{split_url.netloc}", "")
+        )
+        self.authentication = None
+        Request.set_timeout(timeout)
+
+    def login(self, username: str, password: str) -> "MCSMAPI":
+        Request.set_token(
+            send(
+                "POST",
+                f"{ApiPool.AUTH}/login",
+                data={"username": username, "password": password},
+            )
+        )
+        self.authentication = "account"
+        return self
+
+    def login_with_apikey(self, apikey: str):
+        Request.set_apikey(apikey)
+        self.authentication = "apikey"
+        return self
+
+    def overview(self) -> OverviewModel:
+        return Overview().init()
+
+    def instance(self) -> Instance:
+        return Instance()
+
+    def user(self) -> User:
+        return User()
+
+    def daemon(self) -> Daemon:
+        return Daemon()
+
+    def file(self) -> File:
+        return File()
+
+    def image(self) -> Image:
+        return Image()

mcsmapi-0.1.2/mcsmapi/apis/daemon.py

@@ -0,0 +1,70 @@
+from typing import Any
+from ..pool import ApiPool
+from ..request import send
+from ..models.daemon import DaemonConfig
+
+
+class Daemon:
+    def add(self, config: dict[str, Any]) -> str:
+        """
+        新增一个节点。
+
+        参数:
+        - config (dict): 节点的配置信息，以字典形式提供，缺失内容由DaemonConfig模型补全。
+
+        返回:
+        - str: 新增节点的ID
+        """
+        return send(
+            "POST",
+            f"{ApiPool.SERVICE}/remote_service",
+            data=DaemonConfig(**config).dict(),
+        )
+
+    def delete(self, daemonId: str) -> bool:
+        """
+        删除一个节点。
+
+        参数:
+        - daemonId (str): 节点的唯一标识符。
+
+        返回:
+        - bool: 删除成功后返回True
+        """
+        return send(
+            "DELETE", f"{ApiPool.SERVICE}/remote_service", params={"uuid": daemonId}
+        )
+
+    def link(self, daemonId: str) -> bool:
+        """
+        连接一个节点。
+
+        参数:
+        - daemonId (str): 节点的唯一标识符。
+
+        返回:
+        - bool: 连接成功后返回True
+        """
+        return send(
+            "GET", f"{ApiPool.SERVICE}/link_remote_service", params={"uuid": daemonId}
+        )
+
+    def update(self, daemonId: str, config: dict[str, Any]) -> bool:
+        """
+        更新一个节点的配置。
+        
+        **不建议直接使用此函数，建议调用overview()后在remote属性内使用updateConfig方法按需更新**
+
+        参数:
+        - daemonId (str): 节点的唯一标识符。
+        - config (dict): 节点的配置信息，以字典形式提供，缺失内容由DaemonConfig模型补全。
+
+        返回:
+        - bool: 更新成功后返回True
+        """
+        return send(
+            "PUT",
+            f"{ApiPool.SERVICE}/remote_service",
+            params={"uuid": daemonId},
+            data=DaemonConfig(**config).dict(),
+        )

mcsmapi-0.1.2/mcsmapi/apis/file.py

@@ -0,0 +1,318 @@
+from ..pool import ApiPool
+from ..request import Request, send, upload
+from ..models.file import CommonConfig, FileList
+import urllib.parse
+import os
+
+
+class File:
+    def show(
+        self,
+        daemonId: str,
+        uuid: str,
+        target: str = "",
+        page: int = 0,
+        page_size: int = 100,
+    ) -> FileList:
+        """
+        获取文件列表
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - target (str, 可选): 用于文件过滤的目标路径。默认为空字符串，表示不按路径过滤。
+        - page (int, 可选): 指定分页的页码。默认为0。
+        - page_size (int, 可选): 指定每页的项目数量。默认为100。
+
+        **返回:**
+        - FileList: 包含文件列表信息和分页详情的FileList模型。
+        """
+        result = send(
+            "GET",
+            f"{ApiPool.FILE}/list",
+            params={
+                "daemonId": daemonId,
+                "uuid": uuid,
+                "target": target,
+                "page": page,
+                "page_size": page_size,
+            },
+        )
+        return FileList(**result, daemonId=daemonId, uuid=uuid)
+
+    def content(self, daemonId: str, uuid: str, target: str) -> str | bytes:
+        """
+        获取文件内容
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - target (str): 文件的目标路径。
+
+        **返回:**
+        - str: 文件的内容信息。
+        """
+        return send(
+            "PUT",
+            f"{ApiPool.FILE}",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"target": target},
+        )
+
+    def update(self, daemonId: str, uuid: str, target: str, text: str) -> bool:
+        """
+        更新文件内容
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - target (str): 文件的目标路径。
+        - text (str): 新的文件内容。
+
+        **返回:**
+        - bool: 更新成功后返回True。
+        """
+        return send(
+            "PUT",
+            f"{ApiPool.FILE}",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"target": target, "text": text},
+        )
+
+    def download(self, daemonId: str, uuid: str, file_name: str) -> str:
+        """
+        下载文件
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - file_name (str): 要下载的文件名。路径+名字, 示例: /backup/world.zip
+
+        **返回:**
+        - str: 文件下载URL。
+        """
+
+        result = send(
+            "POST",
+            f"{ApiPool.FILE}/download",
+            params={"daemonId": daemonId, "uuid": uuid, "file_name": file_name},
+        )
+        result = CommonConfig(**result)
+        protocol = Request.mcsm_url.split("://")[0]
+        base_url = urllib.parse.urljoin(f"{protocol}://{result.addr}", "download")
+        return urllib.parse.urljoin(base_url, f"{result.password}/{file_name}")
+
+    async def upload(
+        self, daemonId: str, uuid: str, file: bytes, upload_dir: str
+    ) -> bool:
+        """
+        上传文件
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - file (bytes): 要上传的文件内容。
+        - upload_dir (str): 文件上传到的目标路径。
+
+        **返回:**
+        - bool: 上传成功后返回True。
+        """
+        result = send(
+            "POST",
+            f"{ApiPool.FILE}/upload",
+            params={"daemonId": daemonId, "uuid": uuid, "upload_dir": upload_dir},
+        )
+        result = CommonConfig(**result)
+        protocol = Request.mcsm_url.split("://")[0]
+        base_url = urllib.parse.urljoin(f"{protocol}://{result.addr}", "upload")
+        final_url = urllib.parse.urljoin(base_url, result.password)
+        await upload(final_url, file)
+        return True
+
+    def copy(self, daemonId: str, uuid: str, copy_map: dict[str, str]) -> bool:
+        """
+        复制多个文件夹或文件到指定位置。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 文件实例的唯一标识符。
+        - copy_map (dict): 复制映射，格式为 {源路径: 目标路径}
+
+        **返回:**
+        - bool: 上传成功后返回True。
+        """
+        targets = [[source, target] for source, target in copy_map.items()]
+        return send(
+            "POST",
+            f"{ApiPool.FILE}/copy",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"targets": targets},
+        )
+
+    def copyOne(self, daemonId: str, uuid: str, source: str, target: str) -> bool:
+        """
+        复制单个文件或文件夹到指定位置。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - source (str): 源文件或文件夹的路径。
+        - target (str): 目标文件或文件夹的路径。
+
+        **返回:**
+        - bool: 移动成功后返回True。
+        """
+        return self.copy(daemonId, uuid, {source: target})
+
+    def move(self, daemonId: str, uuid: str, copy_map: dict[str, str]) -> bool:
+        """
+        移动多个文件或文件夹到指定位置。
+
+        参数:
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - copy_map (dict): 移动映射，格式为 {源路径: 目标路径}
+
+        返回:
+        - bool: 移动成功后返回True。
+        """
+        targets = [[source, target] for source, target in copy_map.items()]
+        return send(
+            "PUT",
+            f"{ApiPool.FILE}/move",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"targets": targets},
+        )
+
+    def moveOne(self, daemonId: str, uuid: str, source: str, target: str) -> bool:
+        """
+        从源路径移动单个文件或文件夹到目标路径。
+
+        参数:
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - source (str): 源文件或文件夹的路径。
+        - target (str): 目标文件或文件夹的路径。
+
+        返回:
+        - bool: 移动成功后返回True。
+        """
+        return self.move(daemonId, uuid, {source: target})
+
+    def rename(self, daemonId: str, uuid: str, source: str, new_name: str) -> bool:
+        """
+        重命名单个文件或文件夹。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - source (str): 源文件或文件夹的路径。
+        - new_name (str): 源文件或文件夹的新名字。
+
+        **返回:**
+        - bool: 重命名成功后返回True。
+        """
+        directory = os.path.dirname(source)
+        target = os.path.join(directory, new_name)
+        return self.moveOne(daemonId, uuid, source, target)
+
+    def zip(self, daemonId: str, uuid: str, source: str, targets: list[str]) -> bool:
+        """
+        压缩多个文件或文件夹到指定位置。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - source (str): 需要压缩到的 zip 文件路径。
+        - targets (list): 要压缩的目标文件或文件夹的路径。
+
+        **返回:**
+        - bool: 压缩成功后返回True。
+        """
+        return send(
+            "POST",
+            f"{ApiPool.FILE}/compress",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"type": 1, "code": "utf-8", "source": source, "targets": targets},
+        )
+
+    def unzip(
+        self, daemonId: str, uuid: str, source: str, target: str, code: str = "utf-8"
+    ) -> bool:
+        """
+        解压缩指定的zip文件到目标位置。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - source (str): 需要解压的zip文件路径。
+        - target (str): 解压到的目标路径。
+        - code (str, optional): 压缩文件的编码方式，默认为"utf-8"。
+            可选值: utf-8, gbk, big5
+
+        **返回:**
+        - bool: 解压成功后返回True。
+        """
+        return send(
+            "POST",
+            f"{ApiPool.FILE}/compress",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"type": 2, "code": code, "source": source, "targets": target},
+        )
+
+    def delete(self, daemonId: str, uuid: str, targets: list[str]) -> bool:
+        """
+        删除多个文件或文件夹。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - targets (list): 要删除的文件或文件夹的路径。
+
+        **返回:**
+        - bool: 删除成功后返回True。
+        """
+        return send(
+            "DELETE",
+            ApiPool.FILE,
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"targets": targets},
+        )
+
+    def createFile(self, daemonId: str, uuid: str, target: str) -> bool:
+        """
+        创建文件。
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - target (str): 目标文件的路径，包含文件名。
+
+        **返回:**
+        - bool: 创建成功后返回True。
+        """
+        return send(
+            "POST",
+            f"{ApiPool.FILE}/touch",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"target": target},
+        )
+
+    def createFloder(self, daemonId: str, uuid: str, target: str) -> bool:
+        """
+        创建文件夹
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - uuid (str): 实例的唯一标识符。
+        - target (str): 目标文件夹的路径。
+
+        **返回:**
+        - bool: 创建成功后返回True。
+        """
+        return send(
+            "POST",
+            f"{ApiPool.FILE}/mkdir",
+            params={"daemonId": daemonId, "uuid": uuid},
+            data={"target": target},
+        )

mcsmapi-0.1.2/mcsmapi/apis/image.py

@@ -0,0 +1,102 @@
+from ..pool import ApiPool
+from ..request import send
+from ..models.image import DockerImageItem, DockerContainerItem, DockerNetworkItem
+
+
+class Image:
+    def images(self, daemonId: str) -> list[DockerImageItem]:
+        """
+        获取镜像列表
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+
+        **返回:**
+        - list[ImageModel]: 包含镜像列表详情的 ImageModel 模型的列表。
+        """
+        result = send(
+            "GET",
+            f"{ApiPool.IMAGE}/image",
+            params={
+                "daemonId": daemonId,
+            },
+        )
+
+        return [DockerImageItem(**item) for item in result]
+
+    def containers(self, daemonId: str) -> list[DockerContainerItem]:
+        """
+        获取容器列表
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+
+        **返回:**
+        - list[DockerContainerItem]: 包含容器列表详情的 DockerContainerItem 模型的列表。
+        """
+        result = send(
+            "GET",
+            f"{ApiPool.IMAGE}/containers",
+            params={
+                "daemonId": daemonId,
+            },
+        )
+
+        return [DockerContainerItem(**item) for item in result]
+
+    def network(self, daemonId: str) -> list[DockerNetworkItem]:
+        """
+        获取网络接口列表
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+
+        **返回:**
+        - list[DockerNetworkItem]: 包含网络接口列表详情的 DockerNetworkItem 模型的列表。
+        """
+        result = send(
+            "GET",
+            f"{ApiPool.IMAGE}/network",
+            params={
+                "daemonId": daemonId,
+            },
+        )
+        return [DockerNetworkItem(**item) for item in result]
+
+    def add(self, daemonId: str, dockerFile: str, name: str, tag: str) -> bool:
+        """
+        新增一个镜像
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+        - dockerFile (str): DockerFile Config
+        - name (str): 镜像名称。
+        - tag (str): 镜像版本。
+
+        **返回:**
+        - bool: 新增镜像成功后返回True。
+        """
+        return send(
+            "POST",
+            f"{ApiPool.IMAGE}/image",
+            params={"daemonId": daemonId},
+            data={"dockerFile": dockerFile, "name": name, "tag": tag},
+        )
+
+    def progress(self, daemonId: str) -> dict[str, int]:
+        """
+        获取镜像构建进度
+
+        ## **由于文档此部分内容不详，未使用模型**
+
+        **参数:**
+        - daemonId (str): 守护进程的唯一标识符。
+
+        **返回:**
+        - dict[str, int]: 包含构建进度信息的字典。
+        """
+        return send(
+            "GET",
+            f"{ApiPool.IMAGE}/progress",
+            params={"daemonId": daemonId},
+        )