mcsmapi 0.1.8b4__tar.gz → 0.2.0__tar.gz

mcsmapi-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: mcsmapi
+Version: 0.2.0
+Summary: Shortcut the pypi package of MCSM./快捷操作MCSM的pypi包
+Author-email: sokoko-org <contact@sokoko.org>
+License-Expression: MIT
+Project-URL: Source, https://github.com/sokoko-org/mcsmapi
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Dynamic: license-file
+
+# 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.10-blue)
+![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/molanp/mcsmapi)
+
+English|[Chinese Simplified](README_zh-cn.md)
+
+## Documentation
+
+📄 Docs: [docs](https://mcsmapi.awkchan.top/en/)
+
+💡 Example: [example](example)
+
+## Introduction
+
+mcsmapi is an async Python SDK for [MCSManager](https://github.com/MCSManager/MCSManager), built on httpx + pydantic.
+
+- Fully async (sync/await)
+- Typed models with IDE autocompletion
+- Chainable operations on returned objects
+- Supports sync with context manager
+
+## Installation
+
+`ash
+pip install mcsmapi
+`
+
+For the latest build: [Actions](https://github.com/molanp/mcsmapi/actions/workflows/auto-build.yml)
+
+## Supported Features
+
+- [x] Dashboard data (Overview)
+- [x] User management (User)
+- [x] Instance management (Instance)
+- [x] Daemon management (Daemon)
+- [x] File management (File)
+- [x] Image management (Image)
+- [x] Schedule task management (Schedule)
+- [x] Java runtime management (Java)
+- [x] Mod management (Mod)
+- [x] Panel & Daemon upgrade (Upgrade)
+
+## Supported MCSM Versions
+
+| MCSM Version | Support Status |
+| :----------: | :------------: |
+|     10.x     |       ✅       |
+
+## Quick Example
+
+`python
+import asyncio
+from mcsmapi import MCSMAPI
+
+
+async def main():
+    mcsm = MCSMAPI("http://localhost:23333")
+    await mcsm.login("admin", "password")
+
+    # Dashboard
+    data = await mcsm.overview.overview()
+    print(f"Panel version: {data.version}")
+
+    # List daemons
+    daemons = await mcsm.daemon.config()
+    for d in daemons:
+        print(f"  {d.remarks} ({d.ip}:{d.port})")
+
+    # Search instances on a daemon
+    instances = await daemons[0].search_instances()
+    for inst in instances.data:
+        print(f"  {inst.config.nickname} [{inst.status.name}]")
+
+    # Partial config update (only sends provided fields)
+    inst = instances.data[0]
+    await inst.updateConfig({"nickname": "My Server"})
+
+    # File operations via chaining
+    files = await inst.files(target=".")
+    for f in files.items[:5]:
+        print(f"  {f.name}")
+
+    await mcsm.close()
+
+
+asyncio.run(main())
+`
+
+See [example/](example/) for more usage patterns.
+
+## Contributing
+
+Feel free to submit an [Issue](https://github.com/molanp/mcsmapi/issues) or [Pull Request](https://github.com/molanp/mcsmapi/pulls).
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT) — see [LICENSE](LICENSE).

mcsmapi-0.2.0/README.md

@@ -0,0 +1,100 @@
+# 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.10-blue)
+![PyPI Downloads](https://img.shields.io/pypi/dm/mcsmapi)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/molanp/mcsmapi)
+
+English|[Chinese Simplified](README_zh-cn.md)
+
+## Documentation
+
+📄 Docs: [docs](https://mcsmapi.awkchan.top/en/)
+
+💡 Example: [example](example)
+
+## Introduction
+
+mcsmapi is an async Python SDK for [MCSManager](https://github.com/MCSManager/MCSManager), built on httpx + pydantic.
+
+- Fully async (sync/await)
+- Typed models with IDE autocompletion
+- Chainable operations on returned objects
+- Supports sync with context manager
+
+## Installation
+
+`ash
+pip install mcsmapi
+`
+
+For the latest build: [Actions](https://github.com/molanp/mcsmapi/actions/workflows/auto-build.yml)
+
+## Supported Features
+
+- [x] Dashboard data (Overview)
+- [x] User management (User)
+- [x] Instance management (Instance)
+- [x] Daemon management (Daemon)
+- [x] File management (File)
+- [x] Image management (Image)
+- [x] Schedule task management (Schedule)
+- [x] Java runtime management (Java)
+- [x] Mod management (Mod)
+- [x] Panel & Daemon upgrade (Upgrade)
+
+## Supported MCSM Versions
+
+| MCSM Version | Support Status |
+| :----------: | :------------: |
+|     10.x     |       ✅       |
+
+## Quick Example
+
+`python
+import asyncio
+from mcsmapi import MCSMAPI
+
+
+async def main():
+    mcsm = MCSMAPI("http://localhost:23333")
+    await mcsm.login("admin", "password")
+
+    # Dashboard
+    data = await mcsm.overview.overview()
+    print(f"Panel version: {data.version}")
+
+    # List daemons
+    daemons = await mcsm.daemon.config()
+    for d in daemons:
+        print(f"  {d.remarks} ({d.ip}:{d.port})")
+
+    # Search instances on a daemon
+    instances = await daemons[0].search_instances()
+    for inst in instances.data:
+        print(f"  {inst.config.nickname} [{inst.status.name}]")
+
+    # Partial config update (only sends provided fields)
+    inst = instances.data[0]
+    await inst.updateConfig({"nickname": "My Server"})
+
+    # File operations via chaining
+    files = await inst.files(target=".")
+    for f in files.items[:5]:
+        print(f"  {f.name}")
+
+    await mcsm.close()
+
+
+asyncio.run(main())
+`
+
+See [example/](example/) for more usage patterns.
+
+## Contributing
+
+Feel free to submit an [Issue](https://github.com/molanp/mcsmapi/issues) or [Pull Request](https://github.com/molanp/mcsmapi/pulls).
+
+## License
+
+[MIT License](https://opensource.org/licenses/MIT) — see [LICENSE](LICENSE).

mcsmapi-0.2.0/mcsmapi/__init__.py

@@ -0,0 +1,118 @@
+import urllib.parse
+from functools import cached_property
+
+from mcsmapi.pool import ApiPool
+from mcsmapi.apis.file import File
+from mcsmapi.apis.java import Java
+from mcsmapi.apis.mod import Mod
+from mcsmapi.apis.user import User
+from mcsmapi.apis.image import Image
+from mcsmapi.apis.daemon import Daemon
+from mcsmapi.apis.instance import Instance
+from mcsmapi.apis.overview import Overview
+from mcsmapi.apis.schedule import Schedule
+from mcsmapi.apis.upgrade import Upgrade
+from mcsmapi.request import Request
+
+
+class MCSMAPI:
+    """MCSManager API 客户端
+
+    支持 async context manager::
+
+        async with MCSMAPI("http://localhost:23333") as mcsm:
+            await mcsm.login("admin", "password")
+            daemons = await mcsm.daemon.config()
+
+    也可以手动管理::
+
+        mcsm = MCSMAPI("http://localhost:23333")
+        await mcsm.login("admin", "password")
+        ...
+        await mcsm.close()
+    """
+
+    def __init__(self, url: str, timeout: int = 5):
+        split_url = urllib.parse.urlsplit(url)
+        mcsm_url = f"{split_url.scheme}://{split_url.netloc}/"
+        self._req = Request(mcsm_url, timeout)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+        return False
+
+    async def login(self, username: str, password: str):
+        """
+        使用账号密码登录面板。
+
+        重复调用时，如果服务端 session 仍有效，MCSManager 会返回 `"Logined"`
+        而非新 token。此时会先注销旧 session 再重新登录以获取有效 token。
+        """
+        result = await self._req.send(
+            "POST",
+            f"{ApiPool.AUTH}/login",
+            data={"username": username, "password": password},
+        )
+        if result == "Logined":
+            await self._req.send("GET", f"{ApiPool.AUTH}/logout")
+            result = await self._req.send(
+                "POST",
+                f"{ApiPool.AUTH}/login",
+                data={"username": username, "password": password},
+            )
+        self._req.set_token(result)
+        self.authentication = "account"
+        return self
+
+    def login_with_apikey(self, apikey: str):
+        """使用 API Key 认证（无需 await）"""
+        self._req.set_apikey(apikey)
+        self.authentication = "apikey"
+        return self
+
+    async def close(self):
+        """关闭底层 HTTP 连接"""
+        await self._req.close()
+
+    @cached_property
+    def overview(self) -> Overview:
+        return Overview(self._req)
+
+    @cached_property
+    def instance(self) -> Instance:
+        return Instance(self._req)
+
+    @cached_property
+    def user(self) -> User:
+        return User(self._req)
+
+    @cached_property
+    def daemon(self) -> Daemon:
+        return Daemon(self._req)
+
+    @cached_property
+    def file(self) -> File:
+        return File(self._req)
+
+    @cached_property
+    def image(self) -> Image:
+        return Image(self._req)
+
+    @cached_property
+    def schedule(self) -> Schedule:
+        return Schedule(self._req)
+
+    @cached_property
+    def java(self) -> Java:
+        return Java(self._req)
+
+    @cached_property
+    def mod(self) -> Mod:
+        return Mod(self._req)
+
+    @cached_property
+    def upgrade(self) -> Upgrade:
+        return Upgrade(self._req)

mcsmapi-0.2.0/mcsmapi/apis/daemon.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+from mcsmapi.pool import ApiPool
+from mcsmapi.models.daemon import (
+    DaemonConfig,
+    DaemonStatus,
+)
+
+if TYPE_CHECKING:
+    from mcsmapi.request import Request
+
+
+class Daemon:
+    def __init__(self, req: Request):
+        self._req = req
+
+    async def config(self) -> list[DaemonStatus]:
+        """获取全部节点配置信息"""
+        daemons = await self._req.send(
+            "GET",
+            f"{ApiPool.SERVICE}/remote_services_list",
+        )
+        return [DaemonStatus(**daemon, _req=self._req) for daemon in daemons]
+
+
+    async def add(self, config: DaemonConfig) -> str:
+        """
+        新增节点
+
+        :params config: 节点配置信息
+        """
+        return await self._req.send(
+            "POST",
+            f"{ApiPool.SERVICE}/remote_service",
+            data=config.model_dump(),
+        )
+
+    async def delete(self, daemonId: str) -> bool:
+        """
+        删除节点
+
+        :params daemonId: 节点的UUID
+        """
+        return await self._req.send(
+            "DELETE", f"{ApiPool.SERVICE}/remote_service", params={"uuid": daemonId}
+        )
+
+    async def link(self, daemonId: str) -> bool:
+        """
+        连接节点
+
+        :params daemonId: 节点的UUID
+        """
+        return await self._req.send(
+            "GET", f"{ApiPool.SERVICE}/link_remote_service", params={"uuid": daemonId}
+        )
+
+    async def update(self, daemonId: str, config: dict[str, Any]) -> bool:
+        """
+        更新节点配置（部分更新）
+
+        :params daemonId: 节点的UUID
+        :params config: 要修改的配置字段
+        """
+        return await self._req.send(
+            "PUT",
+            f"{ApiPool.SERVICE}/remote_service",
+            params={"uuid": daemonId},
+            data=config,
+        )