modelscope-api 0.0.1__py3-none-any.whl

modelscope_api/data_models/studio/studio.py

@@ -0,0 +1,207 @@
+"""
+创空间数据模型。
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import List, Optional, override
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from ...utils.regex import STUDIO_ID_PATTERN
+from ...utils.typing import JsonObject
+from ..base import BaseDataClass
+from .sdk import SDKType
+
+
+
+class StudioRuntimeStatus(StrEnum):
+    """
+    创空间运行状态。
+    """
+    INITIALIZED = "Initialized"
+    BUILDING = "Building"
+    BUILDFAILED = "BuildFailed"
+    DEPLOYING = "Deploying"
+    DEPLOYFAILED = "DeployFailed"
+    RUNNING = "Running"
+    STOPPING = "Stopping"
+    STOPPED = "Stopped"
+    DUPLICATING = "Duplicating"
+    SLEEPING = "Sleeping"
+
+
+@dataclass(frozen=True)
+class StudioActiveConfig(BaseDataClass):
+    """当前生效的运行时配置"""
+    hardware: Optional[str] = Field(
+        description="硬件配置，修改后需重新部署才能生效。",
+        default=None
+    )
+
+    base_image: Optional[str] = Field(
+        description="基础镜像，仅 Docker 类型不支持，建议选用最新版本，修改后需重新部署才能生效。",
+        default=None
+    )
+
+    sdk_type: Optional[SDKType] = Field(
+        description="SDK 类型，修改后需重新部署才能生效。",
+        default=None
+    )
+
+    sdk_version: Optional[str] = Field(
+        description="SDK 版本（仅 gradio 类型返回）",
+        default=None
+    )
+
+
+
+@dataclass(frozen=True)
+class StudioRuntimeInfo(BaseDataClass):
+    """创空间运行时状态信息"""
+    status: StudioRuntimeStatus = Field(
+        description="运行状态"
+    )
+
+    active_config: StudioActiveConfig = Field(
+        description="当前生效的配置详情",
+        default_factory=StudioActiveConfig
+    )
+
+    created_at: Optional[str] = Field(
+        description="部署时间（ISO 8601 格式）",
+        default=None
+    )
+
+    error_message: Optional[str] = Field(
+        description="失败信息（仅在错误状态时返回）",
+        default=None
+    )
+
+
+
+class StudioVisibility(StrEnum):
+    """
+    创空间可见性。
+    """
+    # 代码和体验都公开
+    PUBLIC = "public"
+
+    # 体验公开，代码仓库不可见
+    PROTECTED = "protected"
+
+    # 都不公开
+    PRIVATE = "private"
+
+
+@dataclass(frozen=True)
+class StudioInfo(BaseDataClass):
+    """
+    描述魔搭社区创空间（Studio）的完整信息模型。
+
+    该模型用于表示创空间的元数据、配置、运行时状态等所有公开属性，
+    适用于 API 响应或内部数据传递。
+    """
+    id: str = Field(
+        description="Studio ID (owner/repo_name)",
+        pattern=STUDIO_ID_PATTERN.pattern
+    )
+
+    repo_name: str = Field(
+        description="仓库名称，是创空间的唯一标识。"
+    )
+
+    display_name: Optional[str] = Field(
+        description="中文或友好的显示名称，默认将使用英文名称。",
+        default=None
+    )
+
+    owner: str = Field(
+        description="所有者（包括组织、个人）"
+    )
+
+    description: Optional[str] = Field(
+        description="描述",
+        default=None
+    )
+
+    cover_image: Optional[str] = Field(
+        description="封面图片的 URL 地址",
+        default=None
+    )
+
+    created_at: Optional[str] = Field(
+        description="部署时间（ISO 8601 格式）",
+        default=None
+    )
+
+    likes: int = Field(
+        description="获赞数量",
+        ge=0
+    )
+
+    view_count: int = Field(
+        description="访问量",
+        ge=0
+    )
+
+    tags: List[str] = Field(
+        description="关联的标签列表，用于分类和搜索",
+        default_factory=list
+    )
+
+    visibility: StudioVisibility = Field(
+        description="创空间可见性"
+    )
+
+    last_modified: Optional[str] = Field(
+        description="最后修改时间（ISO 8601 格式）",
+        default=None
+    )
+
+    sdk_type: Optional[SDKType] = Field(
+        description="使用的 SDK 类型，如 gradio、streamlit",
+        default=None
+    )
+
+    sdk_version: Optional[str] = Field(
+        description="SDK 版本，仅对 Gradio 类型生效",
+        default=None
+    )
+
+    hardware: Optional[str] = Field(
+        description="硬件配置，修改后需重新部署才能生效。",
+        default=None
+    )
+
+    base_image: Optional[str] = Field(
+        description="基础镜像，仅 Docker 类型不支持。",
+        default=None
+    )
+
+    license: Optional[str] = Field(
+        description="许可证",
+        default=None
+    )
+
+    host: str = Field(
+        description="API 访问地址（base url）"
+    )
+
+    mcp_support: bool = Field(
+        description="是否支持 MCP"
+    )
+
+    runtime: StudioRuntimeInfo = Field(
+        description="运行时状态与配置的嵌套信息"
+    )
+
+
+    @override
+    @classmethod
+    def from_json(cls, data: JsonObject) -> StudioInfo:
+        if "created_at" not in data:
+            data["created_at"] = data.get("runtime", {}).get("created_at")
+        return super().from_json(data)

modelscope_api/data_models/user/__init__.py

@@ -0,0 +1,5 @@
+"""
+与用户（User）有关的数据模型。
+"""
+
+from .user import UserInfo

modelscope_api/data_models/user/user.py

@@ -0,0 +1,47 @@
+"""
+用户数据模型。
+"""
+
+from typing import Optional
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from ..base import BaseDataClass
+
+
+
+@dataclass(frozen=True)
+class UserInfo(BaseDataClass):
+    """
+    用户信息
+    """
+    username: str = Field(
+        description="用户在平台上的唯一用户名。"
+    )
+
+    nickname: Optional[str] = Field(
+        description="用户自定义的昵称。",
+        default=None
+    )
+
+    description: Optional[str] = Field(
+        description="个人介绍。文档节点 JSON 结构。",
+        default=None
+    )
+
+    email: Optional[str] = Field(
+        description="邮箱。",
+        default=None
+    )
+
+    avatar_url: Optional[str] = Field(
+        description="头像的 URL。",
+        default=None
+    )
+
+
+    def __post_init__(self) -> None:
+        # nickname 为空时，使用 username 填充
+        if self.nickname is None:
+            object.__setattr__(self, "nickname", self.username)

modelscope_api/exceptions.py

@@ -0,0 +1,59 @@
+"""
+异常类
+"""
+
+from typing import Any, ClassVar, Dict, Optional
+
+
+class BusinessException(Exception):
+    """
+    业务异常基类，所有业务错误都继承自这里。
+    
+    Attributes:
+        code: 错误代码
+        message: 错误消息
+        details: 附加详情（可选）
+    """
+
+    # 默认消息
+    DEFAULT_MESSAGE     : ClassVar[str] = "Business Error"
+
+    # 默认错误代码
+    DEFAULT_CODE        : ClassVar[str] = "ERROR"
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        code: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.message : str = self.DEFAULT_MESSAGE if (message is None) else message
+        self.code    : str = self.DEFAULT_CODE    if (code    is None) else code
+        self.details : Dict[str, Any] = details or {}
+
+        super().__init__(self.message)
+
+
+class UpstreamException(BusinessException):
+    """
+    上游服务端异常。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "UpstreamException"
+    DEFAULT_CODE: ClassVar[str] = "UPSTREAM EXCEPTION"
+
+
+class ParseException(UpstreamException):
+    """
+    解析上游的响应失败。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "ParseException"
+    DEFAULT_CODE: ClassVar[str] = "PARSE EXCEPTION"
+
+
+class ModelScopeException(BusinessException):
+    """
+    ModelScope 业务错误。
+    """
+    DEFAULT_MESSAGE: ClassVar[str] = "ModelScopeError"
+    DEFAULT_CODE: ClassVar[str] = "MODELSCOPE ERROR"

modelscope_api/models/__init__.py

@@ -0,0 +1,9 @@
+"""
+封装了 API 的模型，
+"""
+
+from .collection import Collection, CollectionClient, CollectionItem, CollectionItemClient
+from .magicube import MagicubeClient
+from .modelscope_client import ModelScopeClient
+from .studio import EnvironmentVariableClient, Studio, StudioClient
+from .user import UserClient

modelscope_api/models/_sub_client.py

@@ -0,0 +1,71 @@
+"""
+集成封装子路由的 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],
+        *,
+        prefix: str
+    ):
+        self.super_client = super_client
+        self.prefix = prefix
+
+
+    @property
+    def openapi_url(self) -> URL:
+        """
+        The URL of OpenAPI sub interface.
+
+        Returns like:
+            "https://modelscope.cn/openapi/v1/studios"
+        """
+        return self.super_client.openapi_url / self.prefix
+
+
+    def get_openapi_url(self, subpath: Optional[str] = None) -> URL:
+        """
+        拼接完整的路由。
+        """
+        if subpath is None:
+            return self.openapi_url
+        return self.openapi_url / subpath
+
+
+    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: 如果请求失败。
+        """
+        if subpath is None:
+            subpath = self.prefix
+        else:
+            subpath = f"{self.prefix}/{subpath}"
+        return await self.super_client.request_openapi_data(subpath=subpath, **kwargs)

modelscope_api/models/collection/__init__.py

@@ -0,0 +1,8 @@
+"""
+与合集（Collection）有关的 API 模型。
+"""
+
+from .collection import Collection
+from .collection_client import CollectionClient
+from .collection_item import CollectionItem
+from .collection_item_client import CollectionItemClient

modelscope_api/models/collection/collection.py

@@ -0,0 +1,122 @@
+"""
+对单个合集的操作。
+"""
+
+
+from __future__ import annotations
+
+from typing import Optional, TYPE_CHECKING
+
+from ...utils.regex import COLLECTION_SLUG_PATTERN
+from ...data_models.collection import CollectionInfo, CollectionTheme, CollectionVisibility
+from .._sub_client import SubClient
+from .collection_item_client import CollectionItemClient
+
+if TYPE_CHECKING:
+    from .collection_client import CollectionClient
+
+
+
+class Collection(SubClient):
+    """
+    单个合集。
+    """
+
+    def __init__(self, collection_client: CollectionClient, slug: str):
+        self._slug = slug
+        assert COLLECTION_SLUG_PATTERN.fullmatch(self.slug), f"Invalid collection slug: {self.slug}"
+        super().__init__(
+            super_client=collection_client,
+            prefix=self.slug
+        )
+
+        # 聚合子路由
+        self.items = CollectionItemClient(self)
+
+
+    def __str__(self) -> str:
+        return f"{type(self).__name__}<{self.slug}>"
+
+
+    # ==== 只读属性 ====
+
+    @property
+    def slug(self) -> str:
+        """
+        Collection slug (owner/name)
+        """
+        return self._slug
+
+
+    @property
+    def owner(self) -> str:
+        """
+        拥有者（个人用户名或组织名）
+        """
+        return self._slug.split("/")[0]
+
+
+    @property
+    def name(self) -> str:
+        """
+        合集英文名。
+        """
+        return self._slug.split("/")[1]
+
+
+    # ==== 合集操作 ====
+
+    async def get_info(self, **kwargs) -> CollectionInfo:
+        """
+        获取当前 Collection 的详细信息。
+
+        visibility=public 时可以不认证；visibility=private 时必须认证。
+        """
+        kwargs["method"] = "GET"
+        kwargs["subpath"] = None
+        data = await self.request_openapi_data(**kwargs)
+        return CollectionInfo.from_json(data)
+
+
+    async def update(
+        self,
+        *,
+        title: Optional[str] = None,
+        description: Optional[str] = None,
+        owner: Optional[str] = None,
+        visibility: Optional[CollectionVisibility] = None,
+        theme: Optional[CollectionTheme] = None,
+        **kwargs
+    ) -> CollectionInfo:
+        """
+        更新 Collection 元数据。传入哪个字段即更新哪个字段，未传字段保持原值。
+
+        open/close 语义映射为 visibility（public/private）。
+
+        Args:
+            title: Collection 标题（最长 128 字符）。
+            description: Collection 描述（Markdown）。
+            owner: 所有者（用户名或组织名）。
+            visibility: 可见性：public / private。
+            theme: 主题标签，枚举值：Blue/Pink/Purple/Cyan。
+        """
+        kwargs["method"] = "PATCH"
+        kwargs["subpath"] = None
+        kwargs.setdefault("json", {}).update({
+            "title": title,
+            "description": description,
+            "owner": owner,
+            "visibility": visibility,
+            "theme": theme,
+        })
+        data = await self.request_openapi_data(**kwargs)
+        self._slug = data["slug"]
+        self.prefix = self._slug
+        return await self.get_info()
+
+
+    async def delete(self) -> None:
+        """
+        删除当前合集。
+        """
+        await self.super_client.delete_collection(self.slug)

modelscope_api/models/collection/collection_client.py

@@ -0,0 +1,132 @@
+"""
+集成封装与合集（Collection）有关的 API。
+"""
+
+from __future__ import annotations
+
+from typing import List, Literal, Optional, TYPE_CHECKING
+
+from ...data_models.collection import CollectionInfo, CollectionTheme, CollectionVisibility
+from .._sub_client import SubClient
+from .collection import Collection
+
+if TYPE_CHECKING:
+    from ..modelscope_client import ModelScopeClient
+
+
+
+class CollectionClient(SubClient):
+    """
+    集成封装与合集（Collection）有关的 API。
+    """
+
+    def __init__(
+        self,
+        modelscope_client: ModelScopeClient,
+        *,
+        prefix: str = "collections"
+    ):
+        super().__init__(
+            super_client=modelscope_client,
+            prefix=prefix
+        )
+
+
+    # ==== 查询合集信息 ====
+
+    async def search_collection_infos(
+        self,
+        search: Optional[str] = None,
+        owner: Optional[str] = None,
+        *,
+        sort: Optional[Literal["default", "last_modified", "likes"]] = None,
+        page_number: int = 1,
+        page_size: int = 10,
+        **kwargs
+    ) -> List[CollectionInfo]:
+        """
+        获取 Collection 列表，支持搜索、按所有者过滤与排序、分页。
+
+        公开列表无需用户认证；查询私有 Collection 需要认证。
+
+        Args:
+            search: 针对标题、描述的子字符串搜索。
+            owner: 所有者过滤。
+                仅允许过滤当前 Token 所属用户自己的 Collection，过滤他人（或匿名使用）返回 403 OperationNotAllowed。
+            sort: 排序方式：default（默认综合）/ last_modified（最近更新）/ likes（喜欢数）。
+            page_number: 页码（≥ 1，默认 1）
+            page_size: 每页大小（1 ~ 50，默认 10）
+        """
+        kwargs["method"] = "GET"
+        kwargs["subpath"] = None
+        kwargs.setdefault("params", {}).update({
+            "search": search,
+            "owner": owner,
+            "sort": sort,
+            "page_number": page_number,
+            "page_size": page_size,
+        })
+        data = await self.request_openapi_data(**kwargs)
+        collection_infos = list(map(
+            CollectionInfo.from_json,
+            data.get("collection_list") or []
+        ))
+        return collection_infos
+
+
+    # ==== 创建合集 ====
+
+    def get_collection(self, collection_slug: str) -> Collection:
+        """
+        构造一个 Collection 对象。
+        """
+        return Collection(collection_client=self, slug=collection_slug)
+
+
+    async def create_collection(
+        self,
+        title: str,
+        owner: Optional[str] = None,
+        *,
+        description: Optional[str] = None,
+        visibility: Optional[CollectionVisibility] = None,
+        theme: Optional[CollectionTheme] = None,
+        **kwargs
+    ) -> Collection:
+        """
+        创建一个新的 Collection。
+
+        Args:
+            title: Collection 标题（最长 128 字符）。
+            owner: 所有者（用户名或组织名）。默认使用当前登录的用户。
+            description: Collection 描述（Markdown）。
+            visibility: 可见性：public / private，默认 public。
+            theme: 主题标签，枚举值：Blue/Pink/Purple/Cyan。默认 Blue。
+        """
+        # 补全 `owner` 参数
+        if not owner:
+            current_user_info = await self.super_client.user.get_current_user_info()
+            owner = current_user_info.username
+
+        kwargs["method"] = "POST"
+        kwargs["subpath"] = None
+        kwargs.setdefault("json", {}).update({
+            "title": title,
+            "owner": owner,
+            "description": description,
+            "visibility": visibility,
+            "theme": theme,
+        })
+        data = await self.request_openapi_data(**kwargs)
+        return self.get_collection(data["slug"])
+
+
+    # ==== 删除合集 ====
+
+    async def delete_collection(self, collection_slug: str, **kwargs) -> None:
+        """
+        删除指定的 Collection。需具备 admin 权限的 Bearer Token。
+        """
+        kwargs["method"] = "DELETE"
+        kwargs["subpath"] = collection_slug
+        await self.request_openapi_data(**kwargs)