modelscope-api 0.0.1__tar.gz → 0.0.2__tar.gz

modelscope_api-0.0.2/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: modelscope-api
+Version: 0.0.2
+Summary: A Python async SDK that wraps the ModelScope API into a clean, type-safe interface.
+Author-email: Jerry <wujr24@m.fudan.edu.cn>
+License: MIT
+Project-URL: Homepage, https://github.com/Jerry-Wu-GitHub/modelscope-api
+Project-URL: Repository, https://github.com/Jerry-Wu-GitHub/modelscope-api.git
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fake-useragent
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: typing-extensions
+Requires-Dist: yarl
+Dynamic: license-file
+
+# ModelScope API Python SDK
+
+[![PyPI version](https://badge.fury.io/py/modelscope-api.svg)](https://badge.fury.io/py/modelscope-api)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+一个**异步**、**类型安全**的 Python SDK，用于调用 [ModelScope 开放 API](https://modelscope.cn/docs/openapi)。
+
+它提供了直观的对象化接口，覆盖了合集、创空间、魔粒、用户等核心模块，让您能以 Pythonic 的方式与 ModelScope 平台交互。
+
+## ✨ 特性
+
+- 🚀 **全异步** – 基于 `httpx.AsyncClient`，支持高并发请求。
+- 🧩 **模块化设计** – 按业务领域拆分：`User`、`Magicube`、`Studio`、`Collection` 等。
+- 📦 **类型安全** – 使用 Pydantic 数据模型，提供 IDE 自动补全和校验。
+- 🔐 **自动认证** – 通过环境变量或构造参数传入 API Token，自动注入请求头。
+- 🛠️ **开箱即用** – 支持 `.env` 配置，内置随机 UA 伪装，简化开发。
+
+## 📦 安装
+
+```bash
+pip install modelscope-api
+```
+
+或直接从源码安装：
+
+```bash
+git clone https://github.com/Jerry-Wu-GitHub/modelscope-api.git
+cd modelscope-api
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 1. 获取 API Token
+
+访问 [ModelScope 个人设置](https://www.modelscope.cn/my/settings/token) 生成您的 `MODELSCOPE_API_TOKEN`。
+
+### 2. 配置环境变量（推荐）
+
+在项目根目录创建 `.env` 文件：
+
+```env
+MODELSCOPE_API_TOKEN=your_token_here
+```
+
+也可以直接在代码中传入：
+
+```python
+from modelscope_api import ModelScopeClient
+
+client = ModelScopeClient(api_key="your_token_here")
+```
+
+### 3. 基础用法
+
+```python
+import asyncio
+from modelscope_api import ModelScopeClient
+
+async def main():
+    async with ModelScopeClient() as client:
+        # 获取当前用户信息
+        user_info = await client.user.get_current_user_info()
+        print(f"当前用户: {user_info.username}")
+
+        # 查询魔粒余额
+        balance = await client.magicube.query_magicube_balance()
+        print(f"可用魔粒: {balance.available_balance}")
+
+        # 搜索创空间
+        studios = await client.studio.search_studio_infos(search="chatbot", owner="iic")
+        for studio in studios:
+            print(f"- {studio.display_name} ({studio.id})")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 📖 API 概览
+
+SDK 的所有功能通过 `ModelScopeClient` 聚合，您可以通过其属性访问各子客户端：
+
+| 子客户端            | 说明         | 主要方法                                                     |
+| ------------------- | ------------ | ------------------------------------------------------------ |
+| `client.user`       | 用户信息     | `get_current_user_info()`                                    |
+| `client.magicube`   | 魔粒（积分） | `query_magicube_balance()`                                   |
+| `client.studio`     | 创空间管理   | `search_studio_infos()`, `create_studio()`, `get_studio()`   |
+| `client.collection` | 合集管理     | `search_collection_infos()`, `create_collection()`, `get_collection()` |
+
+每个子客户端返回的数据均为 Pydantic 模型，可直接访问属性。
+
+### 详细示例：操作创空间
+
+```python
+async def studio_example(client):
+    # 创建创空间
+    studio = await client.studio.create_studio(
+        repo_name="my-awesome-space",
+        display_name="我的炫酷空间",
+        visibility="public",
+        sdk_type="gradio",
+        hardware="platform/2v-cpu-16g-mem"
+    )
+    print(f"创建成功: {studio.id}")
+
+    # 部署
+    runtime = await studio.deploy(timeout=30)
+    print(f"部署状态: {runtime.status}")
+
+    # 查看日志
+    logs = await studio.get_logs("run", page_size=50)
+    for line in logs.logs:
+        print(line)
+
+    # 添加环境变量
+    await studio.variables.add("MY_KEY", "my_value")
+```
+
+### 详细示例：操作合集
+
+```python
+async def collection_example(client):
+    # 创建合集
+    collection = await client.collection.create_collection(
+        title="我的收藏",
+        visibility="private"
+    )
+
+    # 添加条目（模型）
+    failed = await collection.items.add_items([
+        {
+            "item_type": "model",
+            "item_object_id": "Qwen/Qwen3.8-27B",
+            "position": 1
+        }
+    ])
+    if failed:
+        print("添加失败:", failed)
+
+    # 获取条目列表
+    items = await collection.items.get_items()
+    for item in items:
+        print(f"- {item.item_object_id}")
+
+    # 删除合集
+    await collection.delete()
+```
+
+## 🧪 运行测试
+
+项目包含完整的测试用例，位于 `tests/` 目录。运行前请确保已设置有效的 `MODELSCOPE_API_TOKEN`。
+
+> [!CAUTION]
+>
+> 测试用例里包含“删除创空间”，这是一个危险的操作，请确保您没有会受影响的创空间。
+>
+> 要实现该操作，需要使用“管理员权限”的 API Token。
+
+## 📄 许可证
+
+本项目使用 [MIT](LICENSE) 许可证。

modelscope_api-0.0.2/README.md

@@ -0,0 +1,162 @@
+# ModelScope API Python SDK
+
+[![PyPI version](https://badge.fury.io/py/modelscope-api.svg)](https://badge.fury.io/py/modelscope-api)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+一个**异步**、**类型安全**的 Python SDK，用于调用 [ModelScope 开放 API](https://modelscope.cn/docs/openapi)。
+
+它提供了直观的对象化接口，覆盖了合集、创空间、魔粒、用户等核心模块，让您能以 Pythonic 的方式与 ModelScope 平台交互。
+
+## ✨ 特性
+
+- 🚀 **全异步** – 基于 `httpx.AsyncClient`，支持高并发请求。
+- 🧩 **模块化设计** – 按业务领域拆分：`User`、`Magicube`、`Studio`、`Collection` 等。
+- 📦 **类型安全** – 使用 Pydantic 数据模型，提供 IDE 自动补全和校验。
+- 🔐 **自动认证** – 通过环境变量或构造参数传入 API Token，自动注入请求头。
+- 🛠️ **开箱即用** – 支持 `.env` 配置，内置随机 UA 伪装，简化开发。
+
+## 📦 安装
+
+```bash
+pip install modelscope-api
+```
+
+或直接从源码安装：
+
+```bash
+git clone https://github.com/Jerry-Wu-GitHub/modelscope-api.git
+cd modelscope-api
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 1. 获取 API Token
+
+访问 [ModelScope 个人设置](https://www.modelscope.cn/my/settings/token) 生成您的 `MODELSCOPE_API_TOKEN`。
+
+### 2. 配置环境变量（推荐）
+
+在项目根目录创建 `.env` 文件：
+
+```env
+MODELSCOPE_API_TOKEN=your_token_here
+```
+
+也可以直接在代码中传入：
+
+```python
+from modelscope_api import ModelScopeClient
+
+client = ModelScopeClient(api_key="your_token_here")
+```
+
+### 3. 基础用法
+
+```python
+import asyncio
+from modelscope_api import ModelScopeClient
+
+async def main():
+    async with ModelScopeClient() as client:
+        # 获取当前用户信息
+        user_info = await client.user.get_current_user_info()
+        print(f"当前用户: {user_info.username}")
+
+        # 查询魔粒余额
+        balance = await client.magicube.query_magicube_balance()
+        print(f"可用魔粒: {balance.available_balance}")
+
+        # 搜索创空间
+        studios = await client.studio.search_studio_infos(search="chatbot", owner="iic")
+        for studio in studios:
+            print(f"- {studio.display_name} ({studio.id})")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## 📖 API 概览
+
+SDK 的所有功能通过 `ModelScopeClient` 聚合，您可以通过其属性访问各子客户端：
+
+| 子客户端            | 说明         | 主要方法                                                     |
+| ------------------- | ------------ | ------------------------------------------------------------ |
+| `client.user`       | 用户信息     | `get_current_user_info()`                                    |
+| `client.magicube`   | 魔粒（积分） | `query_magicube_balance()`                                   |
+| `client.studio`     | 创空间管理   | `search_studio_infos()`, `create_studio()`, `get_studio()`   |
+| `client.collection` | 合集管理     | `search_collection_infos()`, `create_collection()`, `get_collection()` |
+
+每个子客户端返回的数据均为 Pydantic 模型，可直接访问属性。
+
+### 详细示例：操作创空间
+
+```python
+async def studio_example(client):
+    # 创建创空间
+    studio = await client.studio.create_studio(
+        repo_name="my-awesome-space",
+        display_name="我的炫酷空间",
+        visibility="public",
+        sdk_type="gradio",
+        hardware="platform/2v-cpu-16g-mem"
+    )
+    print(f"创建成功: {studio.id}")
+
+    # 部署
+    runtime = await studio.deploy(timeout=30)
+    print(f"部署状态: {runtime.status}")
+
+    # 查看日志
+    logs = await studio.get_logs("run", page_size=50)
+    for line in logs.logs:
+        print(line)
+
+    # 添加环境变量
+    await studio.variables.add("MY_KEY", "my_value")
+```
+
+### 详细示例：操作合集
+
+```python
+async def collection_example(client):
+    # 创建合集
+    collection = await client.collection.create_collection(
+        title="我的收藏",
+        visibility="private"
+    )
+
+    # 添加条目（模型）
+    failed = await collection.items.add_items([
+        {
+            "item_type": "model",
+            "item_object_id": "Qwen/Qwen3.8-27B",
+            "position": 1
+        }
+    ])
+    if failed:
+        print("添加失败:", failed)
+
+    # 获取条目列表
+    items = await collection.items.get_items()
+    for item in items:
+        print(f"- {item.item_object_id}")
+
+    # 删除合集
+    await collection.delete()
+```
+
+## 🧪 运行测试
+
+项目包含完整的测试用例，位于 `tests/` 目录。运行前请确保已设置有效的 `MODELSCOPE_API_TOKEN`。
+
+> [!CAUTION]
+>
+> 测试用例里包含“删除创空间”，这是一个危险的操作，请确保您没有会受影响的创空间。
+>
+> 要实现该操作，需要使用“管理员权限”的 API Token。
+
+## 📄 许可证
+
+本项目使用 [MIT](LICENSE) 许可证。

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/pyproject.toml

@@ -4,15 +4,30 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modelscope-api"         # 包名，保持与项目仓库名一致
-version = "0.0.1"               # 当前版本
+version = "0.0.2"               # 当前版本
 description = "A Python async SDK that wraps the ModelScope API into a clean, type-safe interface." # 简短描述
 readme = "README.md"            # 自述文件，PyPI 会将其渲染为项目首页
 authors = [{name = "Jerry", email = "wujr24@m.fudan.edu.cn"}]  # 作者信息
 license = {text = "MIT"}        # 指定许可证，与 LICENSE 文件一致
 classifiers = [                 # 帮助用户在 PyPI 上找到你的项目
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: Apache Software License",
+    # 开发状态
+    "Development Status :: 3 - Alpha",
+
+    # 目标受众
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+
+    # 许可证
+    "License :: OSI Approved :: MIT License",
+
+    # 操作系统
     "Operating System :: OS Independent",
+
+    # 编程语言 & Python 版本
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
 requires-python = ">=3.11"
 dependencies = [                # 项目的运行时依赖，从 requirements.txt 移植
@@ -20,7 +35,7 @@ dependencies = [                # 项目的运行时依赖，从 requirements.tx
     "httpx",
     "python-dotenv",
     "typing-extensions",
-    "yarl"
+    "yarl",
 ]
 
 [project.urls]                  # 可选，但推荐，指向你的项目主页或仓库

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/config.py

@@ -15,6 +15,13 @@ load_dotenv()
 # 用于 ModelScope 用户进行身份验证的令牌
 MODELSCOPE_API_TOKEN: Optional[str] = os.getenv("MODELSCOPE_API_TOKEN")
 
+# API 基础地址
+MODELSCOPE_API_VERSION: str = "v1"
+MODELSCOPE_API_BASE_URL: URL = URL(os.getenv(
+    "MODELSCOPE_API_BASE_URL",
+    "https://www.modelscope.cn/api"
+))
+
 # OpenAPI 基础地址
 MODELSCOPE_OPENAPI_VERSION: str = "v1"
 MODELSCOPE_OPENAPI_BASE_URL: URL = URL(os.getenv(

modelscope_api-0.0.2/src/modelscope_api/models/_sub_client.py

@@ -0,0 +1,143 @@
+"""
+集成封装子路由的 API。
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Union, TYPE_CHECKING
+
+from yarl import URL
+
+if TYPE_CHECKING:
+    from .modelscope_client import ModelScopeClient, JsonObject
+
+
+class SubClient:
+    """
+    集成封装子路由的 API。
+    """
+
+    def __init__(
+        self,
+        super_client: Union[ModelScopeClient, SubClient],
+        *,
+        api_prefix: Optional[str] = None,
+        openapi_prefix: Optional[str] = None,
+    ):
+        """
+        Args:
+            super_client: 上一级路由的 HTTP 客户端。
+            api_prefix: 要接在父级 api_url 后的前缀。
+            openapi_prefix: 要接在父级 openapi_prefix 后的前缀。
+        """
+        self.super_client = super_client
+        self.api_prefix: Optional[str] = api_prefix
+        self.openapi_prefix: Optional[str] = openapi_prefix
+
+
+    # ==== API ====
+
+    @property
+    def api_url(self) -> URL:
+        """
+        The URL of API sub interface.
+
+        Returns like:
+            "https://www.modelscope.cn/api/v1/studio"
+        """
+        if self.api_prefix is None:
+            return self.super_client.api_url
+        return self.super_client.api_url / self.api_prefix
+
+
+    def get_api_url(self, subpath: Optional[str] = None) -> URL:
+        """
+        拼接完整的 API 路由。
+        """
+        if subpath is None:
+            return self.api_url
+        return self.api_url / subpath
+
+
+    async def request_api_data(
+        self,
+        subpath: Optional[str] = None,
+        *,
+        data_field="data",
+        **kwargs
+    ) -> Optional[JsonObject | List[JsonObject]]:
+        """
+        向 ModelScope API 发送请求，并返回响应体中的字段 `data_field` （默认为 "data"）的值。
+        如果响应体中没有 `data_field` 字段，则返回整个响应体。
+
+        Args:
+            subpath: 在 `self.api_url` 之后要拼接的子路径。
+                不能以 `/` 开头。
+
+        Raises:
+            ParseException: 如果解析失败。
+            ModelScopeException: 如果请求失败。
+        """
+        if subpath is None:
+            subpath = self.api_prefix
+        else:
+            subpath = f"{self.api_prefix}/{subpath}"
+        return await self.super_client.request_api_data(
+            subpath=subpath,
+            data_field=data_field,
+            **kwargs
+        )
+
+
+    # ==== OpenAPI ====
+
+    @property
+    def openapi_url(self) -> URL:
+        """
+        The URL of OpenAPI sub interface.
+
+        Returns like:
+            "https://modelscope.cn/openapi/v1/studios"
+        """
+        if self.openapi_prefix is None:
+            return self.super_client.openapi_url
+        return self.super_client.openapi_url / self.openapi_prefix
+
+
+    def get_openapi_url(self, subpath: Optional[str] = None) -> URL:
+        """
+        拼接完整的 OpenAPI 路由。
+        """
+        if subpath is None:
+            return self.openapi_url
+        return self.openapi_url / subpath
+
+
+    async def request_openapi_data(
+        self,
+        subpath: Optional[str] = None,
+        *,
+        data_field="data",
+        **kwargs
+    ) -> Optional[JsonObject | List[JsonObject]]:
+        """
+        向 ModelScope OpenAPI 发送请求，并返回响应体中的字段 `data_field` （默认为 "data"）的值。
+        如果响应体中没有 `data_field` 字段，则返回整个响应体。
+
+        Args:
+            subpath: 在 `self.openapi_url` 之后要拼接的子路径。
+                不能以 `/` 开头。
+
+        Raises:
+            ParseException: 如果解析失败。
+            ModelScopeException: 如果请求失败。
+        """
+        if subpath is None:
+            subpath = self.openapi_prefix
+        else:
+            subpath = f"{self.openapi_prefix}/{subpath}"
+        return await self.super_client.request_openapi_data(
+            subpath=subpath,
+            data_field=data_field,
+            **kwargs
+        )

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/models/collection/collection.py

@@ -27,7 +27,7 @@ class Collection(SubClient):
         assert COLLECTION_SLUG_PATTERN.fullmatch(self.slug), f"Invalid collection slug: {self.slug}"
         super().__init__(
             super_client=collection_client,
-            prefix=self.slug
+            openapi_prefix=self.slug
         )
 
         # 聚合子路由
@@ -111,7 +111,7 @@ class Collection(SubClient):
         })
         data = await self.request_openapi_data(**kwargs)
         self._slug = data["slug"]
-        self.prefix = self._slug
+        self.openapi_prefix = self._slug
         return await self.get_info()
 
 

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/models/collection/collection_client.py

@@ -24,11 +24,11 @@ class CollectionClient(SubClient):
         self,
         modelscope_client: ModelScopeClient,
         *,
-        prefix: str = "collections"
+        openapi_prefix: str = "collections"
     ):
         super().__init__(
             super_client=modelscope_client,
-            prefix=prefix
+            openapi_prefix=openapi_prefix
         )
 
 

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/models/collection/collection_item.py

@@ -30,7 +30,7 @@ class CollectionItem(SubClient):
         self._item_object_id = item_object_id
         super().__init__(
             super_client=collection_item_client,
-            prefix=f"{self.item_type}/{self.item_object_id}"
+            openapi_prefix=f"{self.item_type}/{self.item_object_id}"
         )
 
 

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/models/collection/collection_item_client.py

@@ -24,11 +24,11 @@ class CollectionItemClient(SubClient):
         self,
         collection: Collection,
         *,
-        prefix: str = "items"
+        openapi_prefix: str = "items"
     ):
         super().__init__(
             super_client=collection,
-            prefix=prefix
+            openapi_prefix=openapi_prefix
         )
 
 

{modelscope_api-0.0.1 → modelscope_api-0.0.2}/src/modelscope_api/models/magicube/magicube_client.py

@@ -23,11 +23,11 @@ class MagicubeClient(SubClient):
         self,
         modelscope_client: ModelScopeClient,
         *,
-        prefix: str = "magicubes"
+        openapi_prefix: str = "magicubes"
     ):
         super().__init__(
             super_client=modelscope_client,
-            prefix=prefix
+            openapi_prefix=openapi_prefix
         )