instance-repo 1.3.3.dev2__tar.gz → 1.3.5.dev0__tar.gz

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.3.dev2
+Version: 1.3.5.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/instance_repo/__init__.py

@@ -9,6 +9,7 @@ from .models import (
     DatasetSeries, DatasetVersion, DatasetInstance, ManifestEntry,
     OwnerReference, Feedback, Identity, PushResult,
     RolloutReport, RolloutJob, ScaffoldConfig,
+    DatasetObjectDirectory, DatasetObjectFile, DatasetObjectListResult,
     canonical_json, parse_feedbacks, append_feedback,
 )
 from .errors import (
@@ -18,13 +19,14 @@ from .errors import (
     TransportError,
 )
 
-__version__ = "1.3.3.dev2"
+__version__ = "1.3.5.dev0"
 
 __all__ = [
     "Repo", "load_instances",
     "DatasetSeries", "DatasetVersion", "DatasetInstance", "ManifestEntry",
     "OwnerReference", "Feedback", "Identity", "PushResult",
     "RolloutReport", "RolloutJob", "ScaffoldConfig",
+    "DatasetObjectDirectory", "DatasetObjectFile", "DatasetObjectListResult",
     "canonical_json", "parse_feedbacks", "append_feedback",
     "InstanceRepoError", "LayoutError", "SchemaError", "OwnerRefMissing",
     "ImageMissing", "Immutable", "DigestMismatch", "Forbidden", "NotVisible",

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/instance_repo/clients/instances.py

@@ -384,6 +384,145 @@ class InstancesClient:
                 result[parts[0]] = ""
         return result
 
+    # ── 实例目录/文件列举（GET /datasets/objects）──────────────────
+
+    def list_objects(self, dataset: str, instance_id: str,
+                     split: str | None = None, *,
+                     version: str = "",
+                     prefix: str | None = None,
+                     page_size: int = 100,
+                     token: str | None = None,
+                     environment: str | None = None,
+                     metadata_model: str | None = None,
+                     dataset_split_id: str | None = None
+                     ) -> "DatasetObjectListResult":
+        """列举实例资产目录下的文件/子目录（单页）。
+
+        调用控制面 ``GET /apis/v1/datasets/objects``，返回指定实例的
+        ``{split}-assets/{instance_id}/`` 路径下的目录和文件列表。
+
+        Parameters
+        ----------
+        dataset : str
+            Dataset 名称（``L1/L2`` 格式）。
+        instance_id : str
+            实例 ID。
+        split : str, optional
+            Split 名称；为 None 时使用 ``"default"``。
+        version : str
+            版本号，默认空串（split_first 布局下可为空）。
+        prefix : str, optional
+            子目录前缀过滤（相对于实例资产根目录）；为 None 时列举实例根目录。
+        page_size : int
+            每页大小，默认 100。
+        token : str, optional
+            分页游标（首次传 None，后续传上次返回的 ``next_token``）。
+        environment : str, optional
+            ``online`` / ``pre``，None 时用 profile 派生值。
+        metadata_model : str, optional
+            ``split_first`` / ``version_first``，None 时用 profile 派生值。
+        dataset_split_id : str, optional
+            Split ID，可直接指定以避免 split 名称解析。
+
+        Returns
+        -------
+        DatasetObjectListResult
+            包含 ``directories``、``files``、``next_token``、``truncated``。
+        """
+        from urllib.parse import quote
+        from ..models import DatasetObjectListResult
+        if not (dataset or "").strip():
+            raise SchemaError("dataset is required for instances.list_objects")
+        if not (instance_id or "").strip():
+            raise SchemaError(
+                "instance_id is required for instances.list_objects")
+        split = (split or "default").strip()
+        # 计算实例资产根前缀：{split}-assets/{instance_id}/
+        instance_asset_prefix = f"{split}-assets/{instance_id.strip()}"
+        if prefix:
+            full_prefix = f"{instance_asset_prefix}/{prefix.strip().strip('/')}"
+        else:
+            full_prefix = instance_asset_prefix
+        # 构建查询参数
+        params: list[tuple[str, str]] = [
+            ("dataset_name", dataset.strip()),
+            ("split", split),
+            ("prefix", full_prefix),
+            ("page_size", str(int(page_size)))]
+        if (version or "").strip():
+            params.append(("version", version.strip()))
+        if (dataset_split_id or "").strip():
+            params.append(("dataset_split_id", dataset_split_id.strip()))
+        if (token or "").strip():
+            params.append(("token", token.strip()))
+        # environment / metadata_model：优先显式值，其次 profile 派生
+        env = (environment or "").strip()
+        if not env:
+            env = (getattr(self._p, "dataset_environment", "") or "").strip()
+        if env:
+            params.append(("environment", env))
+        mm = (metadata_model or "").strip()
+        if not mm:
+            mm = (getattr(self._p, "metadata_model", "") or "").strip()
+        if mm:
+            params.append(("metadata_model", mm))
+        qs = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
+        data = self._t.get(f"/apis/v1/datasets/objects?{qs}")
+        if isinstance(data, dict):
+            return DatasetObjectListResult.from_dict(data)
+        return DatasetObjectListResult()
+
+    def list_all_objects(self, dataset: str, instance_id: str,
+                         split: str | None = None, *,
+                         version: str = "",
+                         prefix: str | None = None,
+                         environment: str | None = None,
+                         metadata_model: str | None = None,
+                         dataset_split_id: str | None = None,
+                         page_size: int = 100,
+                         max_pages: int = 50
+                         ) -> "DatasetObjectListResult":
+        """自动翻页列举实例资产目录下的全部文件/子目录。
+
+        反复调用 :meth:`list_objects` 直到 ``truncated=False`` 或达到
+        ``max_pages`` 上限，合并所有页的 ``directories`` 和 ``files``。
+
+        Parameters
+        ----------
+        max_pages : int
+            最大翻页数（安全阀，防无限循环），默认 50。
+
+        其余参数同 :meth:`list_objects`。
+
+        Returns
+        -------
+        DatasetObjectListResult
+            合并后的完整结果，``truncated`` 反映是否因 ``max_pages`` 截断。
+        """
+        from ..models import DatasetObjectListResult
+        all_dirs: list = []
+        all_files: list = []
+        tk: str | None = None
+        result = DatasetObjectListResult()
+        for _ in range(max_pages):
+            page = self.list_objects(
+                dataset, instance_id, split,
+                version=version, prefix=prefix,
+                page_size=page_size, token=tk,
+                environment=environment,
+                metadata_model=metadata_model,
+                dataset_split_id=dataset_split_id)
+            all_dirs.extend(page.directories)
+            all_files.extend(page.files)
+            result = page  # 保留最后一页的 dataset/version/prefix 元信息
+            if not page.truncated or not page.next_token:
+                break
+            tk = page.next_token
+        result.directories = all_dirs
+        result.files = all_files
+        # 若因 max_pages 截断，truncated 保持 True + 保留 next_token
+        return result
+
     def update(self, dataset: str, version: str, instance_id: str, *,
                split: str | None = None, dataset_split_id: str | None = None,
                manifest: list[dict] | None = None,

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/instance_repo/models.py

@@ -871,3 +871,82 @@ class RoleBinding:
             role_id=d.get("role_id", ""),
             added_by=d.get("added_by", ""),
             added_at=d.get("added_at", ""))
+
+
+# ── Dataset Objects（目录/文件列举）──────────────────────────────────
+
+@dataclass
+class DatasetObjectDirectory:
+    """``GET /datasets/objects`` 返回的目录项。"""
+    name: str
+    path: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectDirectory":
+        return cls(name=d.get("name", ""), path=d.get("path", ""))
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "path": self.path}
+
+
+@dataclass
+class DatasetObjectFile:
+    """``GET /datasets/objects`` 返回的文件项。"""
+    name: str
+    path: str
+    size_bytes: int = 0
+    content_type: str = ""
+    previewable: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectFile":
+        return cls(
+            name=d.get("name", ""),
+            path=d.get("path", ""),
+            size_bytes=int(d.get("size_bytes", 0)),
+            content_type=d.get("content_type", ""),
+            previewable=bool(d.get("previewable", False)))
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "path": self.path,
+                "size_bytes": self.size_bytes,
+                "content_type": self.content_type,
+                "previewable": self.previewable}
+
+
+@dataclass
+class DatasetObjectListResult:
+    """``GET /datasets/objects`` 分页响应。
+
+    ``directories`` 和 ``files`` 为当前页条目；``truncated`` 为 True 时
+    可用 ``next_token`` 继续翻页。
+    """
+    dataset: str = ""
+    version: str = ""
+    prefix: str = ""
+    directories: list[DatasetObjectDirectory] = field(default_factory=list)
+    files: list[DatasetObjectFile] = field(default_factory=list)
+    next_token: str = ""
+    truncated: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectListResult":
+        return cls(
+            dataset=d.get("dataset", ""),
+            version=d.get("version", ""),
+            prefix=d.get("prefix", ""),
+            directories=[DatasetObjectDirectory.from_dict(x)
+                         for x in d.get("directories", [])],
+            files=[DatasetObjectFile.from_dict(x)
+                   for x in d.get("files", [])],
+            next_token=d.get("next_token", ""),
+            truncated=bool(d.get("truncated", False)))
+
+    def to_dict(self) -> dict:
+        return {
+            "dataset": self.dataset, "version": self.version,
+            "prefix": self.prefix,
+            "directories": [d.to_dict() for d in self.directories],
+            "files": [f.to_dict() for f in self.files],
+            "next_token": self.next_token,
+            "truncated": self.truncated}

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/instance_repo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.3.dev2
+Version: 1.3.5.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.3.3.dev2 → instance_repo-1.3.5.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.3.3.dev2"
+version = "1.3.5.dev0"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"