modelscope-api 0.0.1__py3-none-any.whl

modelscope_api/models/collection/collection_item.py

@@ -0,0 +1,92 @@
+"""
+对单个合集条目的操作。
+"""
+
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+from ...data_models.collection import CollectionItemInfo
+from .._sub_client import SubClient
+
+if TYPE_CHECKING:
+    from .collection_item_client import CollectionItemClient
+
+
+
+class CollectionItem(SubClient):
+    """
+    单个合集。
+    """
+
+    def __init__(
+        self,
+        collection_item_client: CollectionItemClient,
+        item_type: str,
+        item_object_id: str,
+    ):
+        self._item_type = item_type
+        self._item_object_id = item_object_id
+        super().__init__(
+            super_client=collection_item_client,
+            prefix=f"{self.item_type}/{self.item_object_id}"
+        )
+
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}<{self.item_type}/{self.item_object_id}>"
+
+
+    # ==== 只读属性 ====
+
+    @property
+    def item_type(self) -> str:
+        """
+        资源类型：model / dataset / studio / paper / skill / mcp
+        """
+        return self._item_type
+
+
+    @property
+    def item_object_id(self) -> str:
+        """
+        资源标识
+        """
+        return self._item_object_id
+
+
+    # ==== 对条目的操作 ====
+
+    async def update(
+        self,
+        *,
+        note: Optional[str] = None,
+        position: Optional[int] = None,
+        **kwargs
+    ) -> CollectionItemInfo:
+        """
+        更新单个条目。传入哪个字段即更新哪个字段。
+
+        Args:
+            note: 备注（Markdown）。
+            position: 排序位置（从 1 开始）。
+        """
+        kwargs["method"] = "PATCH"
+        kwargs["subpath"] = None
+        kwargs.setdefault("json", {}).update({
+            "note": note,
+            "position": position,
+        })
+        data = await self.request_openapi_data(**kwargs)
+        return CollectionItemInfo.from_json(data)
+
+
+    async def delete(self) -> None:
+        """
+        从合集中删除本条目。
+        """
+        await self.super_client.delete_item(
+            item_type=self.item_type,
+            item_object_id=self.item_object_id,
+        )

modelscope_api/models/collection/collection_item_client.py

@@ -0,0 +1,247 @@
+"""
+集成封装与合集条目（Collection Item）有关的 API。
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Optional, TYPE_CHECKING
+
+from ...utils.typing import JsonObject
+from ...data_models.collection import CollectionItemType, CollectionItemInfo
+from .._sub_client import SubClient
+from .collection_item import CollectionItem
+
+if TYPE_CHECKING:
+    from .collection import Collection
+
+
+class CollectionItemClient(SubClient):
+    """
+    集成封装与合集条目（Collection Item）有关的 API。
+    """
+
+    def __init__(
+        self,
+        collection: Collection,
+        *,
+        prefix: str = "items"
+    ):
+        super().__init__(
+            super_client=collection,
+            prefix=prefix
+        )
+
+
+    # ==== 查看条目信息 ====
+
+    async def get_item_infos(
+        self,
+        item_type: Optional[CollectionItemType] = None,
+        page_number: int = 1,
+        page_size: int = 10,
+        **kwargs
+    ) -> List[CollectionItemInfo]:
+        """
+        分页获取指定 Collection 的条目列表，支持按资源类型过滤。
+
+        visibility=public 时 Token 可选；private 时必填。
+
+        Args:
+            item_type: 按资源类型过滤：model / dataset / studio / paper / skill / mcp。
+            page_number: 页码（≥1）。
+            page_size: 每页大小（1~50）。
+        """
+        kwargs["method"] = "GET"
+        kwargs["subpath"] = None
+        kwargs.setdefault("params", {}).update({
+            "item_type": item_type,
+            "page_number": page_number,
+            "page_size": page_size,
+        })
+        data = await self.request_openapi_data(**kwargs)
+        collection_item_infos = list(map(
+            CollectionItemInfo.from_json,
+            data.get("items") or []
+        ))
+        return collection_item_infos
+
+
+    # ==== 添加条目 ====
+
+    @staticmethod
+    def _extract_item_infos(
+        items: Iterable[CollectionItemInfo | JsonObject]
+    ) -> List[Dict[str, str | int]]:
+        """
+        从给定的 items 列表中提取 item 的主要信息：
+        - item_type （必须）
+        - item_object_id （必须）
+        - note （可选）
+        - position （添加时必须，更新时可选）
+        """
+        item_list = []
+        for item in items:
+            # 统一转换为 CollectionItemInfo 类型
+            if isinstance(item, dict):
+                item_info = CollectionItemInfo.from_json(item)
+            elif isinstance(item, CollectionItemInfo):
+                item_info = item
+            else:
+                continue
+
+            # 添加到列表中
+            item_to_be_added = {
+                "item_type": item_info.item_type,
+                "item_object_id": item_info.item_object_id,
+            }
+            if item_info.note is not None:
+                item_to_be_added["note"] = item_info.note
+            if item_info.position is not None:
+                item_to_be_added["position"] = item_info.position
+            item_list.append(item_to_be_added)
+
+        return item_list
+
+
+    async def add_items(
+        self,
+        items: Iterable[CollectionItemInfo | JsonObject],
+        **kwargs
+    ) -> List[CollectionItemInfo]:
+        """
+        向 Collection 批量添加条目。传入 items 数组。
+
+        Args:
+            items: 条目信息列表。
+                对于其中的每个条目，需要有 item_type, item_object_id, position 字段；note 字段是可选的。
+
+        Returns:
+            添加失败的条目列表。每个条目有 reason 属性指示其失败原因。
+        """
+        kwargs["method"] = "POST"
+        kwargs["subpath"] = None
+
+        # 往请求体中添加 items 列表
+        item_list = kwargs.setdefault("json", {}).setdefault("items", [])
+        item_list.extend(self._extract_item_infos(items))
+
+        # 发送请求
+        data = await self.request_openapi_data(**kwargs)
+
+        # 失败的条目
+        failed_item_infos = list(map(
+            CollectionItemInfo.from_json,
+            data.get("failed_items") or []
+        ))
+        return failed_item_infos
+
+
+    # ==== 修改条目 ====
+
+    async def update_items(
+        self,
+        items: Iterable[CollectionItemInfo | JsonObject],
+        **kwargs
+    ) -> List[CollectionItemInfo]:
+        """
+        批量更新 Collection 条目。
+
+        通过每个条目的 item_type + item_object_id 定位，传入哪个字段就修改哪个字段。
+
+        Args:
+            items: 条目信息列表。
+                对于其中的每个条目，需要有 item_type 和 item_object_id 字段；note 和 position 字段是可选的。
+
+        Returns:
+            更新失败的条目列表。每个条目有 reason 属性指示其失败原因。
+        """
+        kwargs["method"] = "PATCH"
+        kwargs["subpath"] = None
+
+        # 往请求体中添加 items 列表
+        item_list = kwargs.setdefault("json", {}).setdefault("items", [])
+        item_list.extend(self._extract_item_infos(items))
+
+        # 如果没有要修改的条目，则直接返回
+        if not item_list:
+            return []
+
+        # 发送请求
+        data = await self.request_openapi_data(**kwargs)
+
+        # 失败的条目
+        failed_item_infos = list(map(
+            CollectionItemInfo.from_json,
+            data.get("failed_items") or []
+        ))
+        return failed_item_infos
+
+
+    # ==== 删除条目 ====
+
+    async def delete_item(
+        self,
+        item_type: str,
+        item_object_id: str,
+        **kwargs
+    ) -> None:
+        """
+        通过 item_type + item_object_id 定位并从 Collection 中移除单个条目。
+
+        Args:
+            item_type: 资源类型：model / dataset / studio / paper / skill / mcp
+            item_object_id: 资源标识，如 damo/nlp_bert_base。
+                可包含 /（作为 items/{item_type}/ 之后的整段剩余路径），无需 URL 编码。
+        """
+        kwargs["method"] = "DELETE"
+        kwargs["subpath"] = f"{item_type}/{item_object_id}"
+        await self.request_openapi_data(**kwargs)
+
+
+    # ==== 获得条目对象 ====
+
+    def get_item(
+        self,
+        item_type: str,
+        item_object_id: str,
+    ) -> CollectionItem:
+        """
+        构造 CollectionItem 对象。
+        """
+        return CollectionItem(
+            collection_item_client=self,
+            item_type=item_type,
+            item_object_id=item_object_id,
+        )
+
+
+    async def get_items(
+        self,
+        item_type: Optional[CollectionItemType] = None,
+        page_number: int = 1,
+        page_size: int = 10,
+        **kwargs
+    ) -> List[CollectionItem]:
+        """
+        分页获取指定 Collection 的条目列表，支持按资源类型过滤。
+
+        visibility=public 时 Token 可选；private 时必填。
+
+        Args:
+            item_type: 按资源类型过滤：model / dataset / studio / paper / skill / mcp。
+            page_number: 页码（≥1）。
+            page_size: 每页大小（1~50）。
+        """
+        collection_item_infos = await self.get_item_infos(
+            item_type=item_type,
+            page_number=page_number,
+            page_size=page_size,
+            **kwargs
+        )
+        return [
+            self.get_item(
+                item_type=item_info.item_type,
+                item_object_id=item_info.item_object_id
+            )
+            for item_info in collection_item_infos
+        ]

modelscope_api/models/magicube/__init__.py

@@ -0,0 +1,5 @@
+"""
+与魔粒（Magicube）有关的 API 模型。
+"""
+
+from .magicube_client import MagicubeClient

modelscope_api/models/magicube/magicube_client.py

@@ -0,0 +1,46 @@
+"""
+集成封装与魔粒体系有关的 API。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...data_models.magicube import MagicubeBalanceInfo
+from .._sub_client import SubClient
+
+if TYPE_CHECKING:
+    from ..modelscope_client import ModelScopeClient
+
+
+
+class MagicubeClient(SubClient):
+    """
+    集成封装与魔粒（Magicube）有关的 API。
+    """
+
+    def __init__(
+        self,
+        modelscope_client: ModelScopeClient,
+        *,
+        prefix: str = "magicubes"
+    ):
+        super().__init__(
+            super_client=modelscope_client,
+            prefix=prefix
+        )
+
+
+    # ==== 查询魔粒余额 ====
+
+    async def query_magicube_balance(self, **kwargs) -> MagicubeBalanceInfo:
+        """
+        查询当前用户的魔粒余额信息。
+
+        Raises:
+            ModelScopeException: 如果未登录。
+        """
+        kwargs["method"] = "GET"
+        kwargs["subpath"] = "balance"
+        data = await self.request_openapi_data(**kwargs)
+        return MagicubeBalanceInfo.from_json(data)

modelscope_api/models/modelscope_client.py

@@ -0,0 +1,206 @@
+"""
+对所有 API 的聚合。
+"""
+
+import json
+from typing import Any, Dict, List, Optional, Union
+
+from fake_useragent import UserAgent
+import httpx
+from typing_extensions import Self
+from yarl import URL
+
+from ..config import (
+    MODELSCOPE_API_TOKEN,
+    MODELSCOPE_OPENAPI_BASE_URL,
+    MODELSCOPE_OPENAPI_VERSION,
+)
+from ..exceptions import ParseException, ModelScopeException
+from ..utils.typing import JsonObject
+from .collection import CollectionClient
+from .magicube import MagicubeClient
+from .studio import StudioClient
+from .user import UserClient
+
+
+class ModelScopeClient:
+    """Client that requests APIs of ModelScope."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        openapi_base_url: Optional[Union[str, URL]] = None,
+        openapi_version: Optional[str] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
+        **kwargs
+    ):
+        """
+        Args:
+            api_key (str): to obtain: https://www.modelscope.cn/my/settings/token
+                It can be passed in through the environment variable `MODELSCOPE_API_TOKEN`.
+                This will overwrite the header::Authorization in http_cient.
+            openapi_base_url (str): to obtain: https://www.modelscope.cn/docs/openapi
+                The base URL of ModelScope OpenAPI,
+                defaults to `"https://modelscope.cn/openapi"`.
+            openapi_version (str): The version of the API, defaults to `"v1"`.
+            http_client (httpx.AsyncClient): An HTTP‑client object with the same methods
+                as `httpx.AsyncClient.request`, used for sending network requests.
+            kwargs: The initialization parameters passed to `http_client`.
+        """
+        # API Token
+        if api_key is None:
+            api_key = MODELSCOPE_API_TOKEN
+
+        self.api_key: Optional[str] = api_key
+
+        # URL
+        if openapi_base_url is None:
+            openapi_base_url = MODELSCOPE_OPENAPI_BASE_URL
+        if openapi_version is None:
+            openapi_version = MODELSCOPE_OPENAPI_VERSION
+
+        self.openapi_base_url: URL = URL(openapi_base_url)
+        self.openapi_version: str = openapi_version
+
+        # HTTP Client
+        self._http_client_is_local: bool = http_client is None
+        if self._http_client_is_local:
+            http_client = httpx.AsyncClient(**kwargs)
+        self._http_client = http_client
+        self._kwargs: Dict[str, Any] = kwargs.copy()
+
+        # 添加伪造的 User-Agent 头
+        headers = self._kwargs.setdefault("headers", {})
+        if "user-agent" not in headers:
+            headers["user-agent"] = UserAgent().random # 生成随机 UA
+
+        # 聚合子路由
+        self.collection = CollectionClient(self)
+        self.magicube = MagicubeClient(self)
+        self.studio = StudioClient(self)
+        self.user = UserClient(self)
+
+
+    async def __aenter__(self) -> Self:
+        if self._http_client_is_local:
+            await self._http_client.__aenter__()
+        return self
+
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        if self._http_client_is_local:
+            await self._http_client.__aexit__(exc_type, exc_val, exc_tb)
+
+
+    async def aclose(self) -> None:
+        """Close the client within the instance."""
+        if self._http_client_is_local:
+            await self._http_client.aclose()
+
+
+    @property
+    def openapi_url(self) -> URL:
+        """
+        The URL of OpenAPI interface.
+
+        Returns like:
+            "https://modelscope.cn/openapi/v1"
+        """
+        return self.openapi_base_url / self.openapi_version
+
+
+    def get_openapi_url(self, subpath: Optional[str] = None) -> URL:
+        """
+        拼接完整的路由。
+        """
+        if subpath is None:
+            return self.openapi_url
+        return self.openapi_url / subpath
+
+
+    # ==== 发送请求 ====
+
+    def _get_kwargs(self, kwargs: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        将给定的关键字参数与本客户端的合并并输出。
+
+        具体来说，该方法会合并以下内容（按优先级从大到小排序）并返回：
+        - 调用本方法时输入的 `kwargs`
+        - "headers": {"Authorization": "Bearer api_key"} （如果 self.api_key 存在）
+        - 初始化本客户端时输入的 `kwargs`
+        """
+        result = self._kwargs.copy()
+        if self.api_key:
+            result.setdefault("headers", {}).update({
+                "Authorization": f"Bearer {self.api_key}"
+            })
+        if kwargs:
+            for key, value in kwargs.items():
+                if isinstance(value, dict):
+                    result.setdefault(key, {}).update(value)
+                else:
+                    result[key] = value
+        return result
+
+
+    async def request(self, **kwargs) -> httpx.Response:
+        """
+        用该客户端发送请求。
+        """
+        kwargs = self._get_kwargs(kwargs)
+        response = await self._http_client.request(**kwargs)
+        return response
+
+
+    async def request_data(self, **kwargs) -> Optional[JsonObject | List[JsonObject]]:
+        """
+        发送请求，并返回响应体中的 `data` 字段。
+        如果响应体中没有 `data` 字段，则返回整个响应体。
+
+        Raises:
+            ParseException: 如果解析失败。
+            ModelScopeException: 如果请求失败。
+        """
+        response = await self.request(**kwargs)
+
+        # 解析响应体
+        try:
+            resp_json = response.json()
+        except json.JSONDecodeError as exp:
+            raise ParseException(
+                code="JSON DECODE ERROR",
+                message=f"unexpected json string: {response.text}"
+            ) from exp
+
+        # 判断请求是否失败
+        if not resp_json.get("success", True):
+            raise ModelScopeException(
+                code=resp_json.get("code"),
+                message=resp_json.get("message")
+            )
+
+        if "data" in resp_json:
+            return resp_json["data"]
+        return resp_json
+
+
+    async def request_openapi_data(
+        self,
+        subpath: Optional[str] = None,
+        **kwargs
+    ) -> Optional[JsonObject | List[JsonObject]]:
+        """
+        向 ModelScope OpenAPI 发送请求，并返回响应体中的 `data` 字段。
+        如果响应体中没有 `data` 字段，则返回整个响应体。
+
+        Args:
+            subpath: 在 `self.openapi_url` 之后要拼接的子路径。
+                不能以 `/` 开头。
+
+        Raises:
+            ParseException: 如果解析失败。
+            ModelScopeException: 如果请求失败。
+        """
+        kwargs["url"] = str(self.get_openapi_url(subpath))
+        return await self.request_data(**kwargs)

modelscope_api/models/studio/__init__.py

@@ -0,0 +1,7 @@
+"""
+与创空间（Studio）有关的 API 模型。
+"""
+
+from .environment_variable_client import EnvironmentVariableClient
+from .studio import Studio
+from .studio_client import StudioClient