instance-repo 1.4.1.dev0__tar.gz → 1.4.6__tar.gz

instance_repo-1.4.6/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: instance-repo
+Version: 1.4.6
+Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: irepo-artifact<0.3.0,>=0.1.1
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: oss
+Requires-Dist: oss2>=2.19; extra == "oss"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+
+# InstanceRepository Python SDK
+
+Python、Go、Java SDK 源码版本均为 `1.4.6`。Split create 可将初始 `run_type` 交给支持该能力的服务端原子写入，重复创建保留已有标签。具体兼容条件见下文。实际安装版本以获准制品库的发布记录为准。[三语言功能矩阵](../../docs/sdk/parity.md)。
+
+## 安装与配置
+
+Python3.10+。从批准的索引中选择已发布版本，真实OSS使用`oss` extra；镜像操作需要`skopeo`，不用镜像时显式`push_image=False`。源码隔离环境已有依赖时可使用：
+
+```bash
+cd sdk/python
+python -m pip install -e .
+```
+
+规范主配置：`AP_API_KEY`、`AP_BASE_URL`、`IR_API_ENV`、`AP_CLUSTER`或`INSTANCE_REPO_STORAGE_ENV`。旧token/base/storage变量仅保留兼容。内部渠道包可能注入站点默认地址，外部包不能据此假设同样默认值。profile仅作标签；控制面Env不等于数据面环境，也不授予权限。
+
+## Dataset 实例操作
+
+```python
+from instance_repo import Repo
+from instance_repo.models import OwnerReference
+
+
+def publish_input(repo: Repo, dataset: str, local_dir: str, owner: OwnerReference):
+    repo.splits.create(dataset, 'test')
+    result = repo.instances.push(local_dir, dataset, '', split='test',
+        owner_reference=owner, push_image=False, register=False)
+    repo.versions.ingest(dataset, '', splits=['test'])
+    return result
+
+
+def download(repo: Repo, dataset: str, instance_id: str, output_dir: str):
+    return repo.instances.pull(dataset, '', instance_id, output_dir, split='test')
+
+
+def remove_metadata(repo: Repo, dataset: str, instance_id: str):
+    return repo.instances.delete(dataset, '', instance_id, split='test')
+```
+
+业务Repo使用split_first；version位置参数传空串代表真实无版本，不是latest。Split create不接受非空storage_path。`register=True`通过ingest完成元数据注册，不能依赖历史`:commit`。已有目录格式与SWE单JSON格式的差异、批量结果和失败行为见[当前指南](../../docs/sdk/README.md)。
+
+### Split 创建与服务端兼容
+
+`repo.splits.create(dataset, split, version=..., run_type=...)` 在 POST 中传入初始标签。服务端返回 `run_type_on_create_supported=true` 时，SDK 直接读取详情，不再 PATCH 已有记录。重复创建会保留已有 `run_type`，包括空标签；新建记录的标签由服务端写入。
+
+旧服务端没有返回该能力标识时，SDK 保留 POST 后 PATCH 的兼容流程。此时重复创建仍可能更新标签。需要严格保持已有标签的调用方，必须先部署支持该契约的服务端。SDK 不通过 legacy 列表或 OSS 扫描判断本次是否新建。
+
+Python 版本升级通过 CR 合入后，可按 `.aoneci/release_pysdk.yaml` 使用 `pysdk/v1.4.6` tag 的现有发布流程。本次源码版本不表示制品已经发布。
+
+`instances.list_objects`返回文件/目录及`truncated`；不完整结果不能当完整目录。`compute_source_hash`与`list_content_hashes`用于变更检测；`push/push_many`的`skip_unchanged`不能替代内容校验或权限判定。
+
+显式`delete_files=True`只处理匹配注册记录的canonical主JSON、专属assets/report；默认仍仅删除元数据。必须停止同实例的上传/ingest；OSS与DB无跨系统原子性，文件删除后DB可能失败。它不是尚在设计的operation_id删除协议，不会删除镜像、历史对象版本或任意manifest引用。
+
+## canonical user-data 与 shared
+
+- `Repo(expected_replica_policy=policy, cluster=..., bootstrap_dataset=False)`可用于只进行canonical用户操作的调用方。policy由部署方可信配置构造`ReplicasPolicy`，含恰好CN/SG的storage_id、bucket与OSS region；不能来自同一未验证的discovery响应。
+- 上传使用`upload_user_data_verified`；下载使用`download_user_data_verified`；兼容 façade `upload_user_data/download_user_data`同样走canonical流程。结果须按receipt和最终状态判定。
+- metadata列表使用`user_data_entries_page/iter_user_data_entries/list_user_data`，默认总限制10000行、32MiB、512页；旧直接OSS LIST与其语义不同。
+- 目录操作是低层`UserDataDirectoriesClient.mkdir`，必须提供可信policy及幂等UUID，不存在`Repo.mkdir`。
+- 共享发布是独立`SharedReleaseClient`，不存在`Repo.shared`；generic shared读取另需真实`shared_library_id`。精确ap-tool profile仅限当前注册的RewardKit格式。
+- ACL façade的`grant/revoke/list/permissions`保留，明确主体、role、subpath、storage_env和deadline；展示权限不是客户端授权证明。
+
+准确构造示例、低层入口、错误族与流式/预算要求见[当前指南](../../docs/sdk/README.md#3-canonical-user-data)。Dataset、user-data、shared、artifact配置及授权不得互相借用或静默降级。
+
+## 验证
+
+```bash
+cd sdk/python
+python -m pytest tests -m 'not integration'
+```
+
+真实环境只在具备批准权限与受控资源后执行；单元通过不等于生产双副本、真实STS或跨地域网络通过。日志不得保存API Key、AK/SK、STS、签名URL或含这些值的异常链。

instance_repo-1.4.6/README.md

@@ -0,0 +1,71 @@
+# InstanceRepository Python SDK
+
+Python、Go、Java SDK 源码版本均为 `1.4.6`。Split create 可将初始 `run_type` 交给支持该能力的服务端原子写入，重复创建保留已有标签。具体兼容条件见下文。实际安装版本以获准制品库的发布记录为准。[三语言功能矩阵](../../docs/sdk/parity.md)。
+
+## 安装与配置
+
+Python3.10+。从批准的索引中选择已发布版本，真实OSS使用`oss` extra；镜像操作需要`skopeo`，不用镜像时显式`push_image=False`。源码隔离环境已有依赖时可使用：
+
+```bash
+cd sdk/python
+python -m pip install -e .
+```
+
+规范主配置：`AP_API_KEY`、`AP_BASE_URL`、`IR_API_ENV`、`AP_CLUSTER`或`INSTANCE_REPO_STORAGE_ENV`。旧token/base/storage变量仅保留兼容。内部渠道包可能注入站点默认地址，外部包不能据此假设同样默认值。profile仅作标签；控制面Env不等于数据面环境，也不授予权限。
+
+## Dataset 实例操作
+
+```python
+from instance_repo import Repo
+from instance_repo.models import OwnerReference
+
+
+def publish_input(repo: Repo, dataset: str, local_dir: str, owner: OwnerReference):
+    repo.splits.create(dataset, 'test')
+    result = repo.instances.push(local_dir, dataset, '', split='test',
+        owner_reference=owner, push_image=False, register=False)
+    repo.versions.ingest(dataset, '', splits=['test'])
+    return result
+
+
+def download(repo: Repo, dataset: str, instance_id: str, output_dir: str):
+    return repo.instances.pull(dataset, '', instance_id, output_dir, split='test')
+
+
+def remove_metadata(repo: Repo, dataset: str, instance_id: str):
+    return repo.instances.delete(dataset, '', instance_id, split='test')
+```
+
+业务Repo使用split_first；version位置参数传空串代表真实无版本，不是latest。Split create不接受非空storage_path。`register=True`通过ingest完成元数据注册，不能依赖历史`:commit`。已有目录格式与SWE单JSON格式的差异、批量结果和失败行为见[当前指南](../../docs/sdk/README.md)。
+
+### Split 创建与服务端兼容
+
+`repo.splits.create(dataset, split, version=..., run_type=...)` 在 POST 中传入初始标签。服务端返回 `run_type_on_create_supported=true` 时，SDK 直接读取详情，不再 PATCH 已有记录。重复创建会保留已有 `run_type`，包括空标签；新建记录的标签由服务端写入。
+
+旧服务端没有返回该能力标识时，SDK 保留 POST 后 PATCH 的兼容流程。此时重复创建仍可能更新标签。需要严格保持已有标签的调用方，必须先部署支持该契约的服务端。SDK 不通过 legacy 列表或 OSS 扫描判断本次是否新建。
+
+Python 版本升级通过 CR 合入后，可按 `.aoneci/release_pysdk.yaml` 使用 `pysdk/v1.4.6` tag 的现有发布流程。本次源码版本不表示制品已经发布。
+
+`instances.list_objects`返回文件/目录及`truncated`；不完整结果不能当完整目录。`compute_source_hash`与`list_content_hashes`用于变更检测；`push/push_many`的`skip_unchanged`不能替代内容校验或权限判定。
+
+显式`delete_files=True`只处理匹配注册记录的canonical主JSON、专属assets/report；默认仍仅删除元数据。必须停止同实例的上传/ingest；OSS与DB无跨系统原子性，文件删除后DB可能失败。它不是尚在设计的operation_id删除协议，不会删除镜像、历史对象版本或任意manifest引用。
+
+## canonical user-data 与 shared
+
+- `Repo(expected_replica_policy=policy, cluster=..., bootstrap_dataset=False)`可用于只进行canonical用户操作的调用方。policy由部署方可信配置构造`ReplicasPolicy`，含恰好CN/SG的storage_id、bucket与OSS region；不能来自同一未验证的discovery响应。
+- 上传使用`upload_user_data_verified`；下载使用`download_user_data_verified`；兼容 façade `upload_user_data/download_user_data`同样走canonical流程。结果须按receipt和最终状态判定。
+- metadata列表使用`user_data_entries_page/iter_user_data_entries/list_user_data`，默认总限制10000行、32MiB、512页；旧直接OSS LIST与其语义不同。
+- 目录操作是低层`UserDataDirectoriesClient.mkdir`，必须提供可信policy及幂等UUID，不存在`Repo.mkdir`。
+- 共享发布是独立`SharedReleaseClient`，不存在`Repo.shared`；generic shared读取另需真实`shared_library_id`。精确ap-tool profile仅限当前注册的RewardKit格式。
+- ACL façade的`grant/revoke/list/permissions`保留，明确主体、role、subpath、storage_env和deadline；展示权限不是客户端授权证明。
+
+准确构造示例、低层入口、错误族与流式/预算要求见[当前指南](../../docs/sdk/README.md#3-canonical-user-data)。Dataset、user-data、shared、artifact配置及授权不得互相借用或静默降级。
+
+## 验证
+
+```bash
+cd sdk/python
+python -m pytest tests -m 'not integration'
+```
+
+真实环境只在具备批准权限与受控资源后执行；单元通过不等于生产双副本、真实STS或跨地域网络通过。日志不得保存API Key、AK/SK、STS、签名URL或含这些值的异常链。

{instance_repo-1.4.1.dev0 → instance_repo-1.4.6}/instance_repo/__init__.py

@@ -20,7 +20,7 @@ from .errors import (
     RegistrationFailed, TransportError,
 )
 
-__version__ = "1.4.1.dev0"
+__version__ = "1.4.6"
 
 __all__ = [
     "Repo", "load_instances",

{instance_repo-1.4.1.dev0 → instance_repo-1.4.6}/instance_repo/_site_defaults.py

@@ -37,3 +37,11 @@ ARTIFACT_PREFIX_ROOT = ""
 #: 注入。运行时也可经环境变量 AP_ARTIFACT_BUCKET_MAP（JSON）覆盖，优先级：
 #: 环境变量 > 本模块注入值 > 空（空则 artifact 下载报错并引导配置）。
 ARTIFACT_BUCKET_MAP_JSON = ""
+
+#: 期望 replica policy（canonical 双桶对）的 JSON 串。**源码恒为空**；
+#: 内网构建时由发布脚本注入（与 API_BASE 同模式——静态可审计、无
+#: envvar 通道）。运行时解析为 ``ReplicasPolicy``（严格 JSON/拒重复
+#: keys/构造验证）；公共包通过显式构造参数传入有效 policy 亦可运行。
+#: 优先级：显式构造参数 > 本模块注入值 > 缺失（缺失=新客户端零 IO
+#: typed error）。
+EXPECTED_REPLICA_POLICY_JSON = ""

{instance_repo-1.4.1.dev0 → instance_repo-1.4.6}/instance_repo/artifacts.py

@@ -119,98 +119,29 @@ def artifact_key(job_id: str) -> str:
 
 def fetch_job_info(api_key: str, job_id: str, cluster: str,
                    ap_endpoint: str | None = None) -> dict[str, Any]:
-    """调 AP GET /api/jobs/{job_id}?include_params=true 获取 job 信息。
-
-    AP 内部执行 workspace ACL 检查（enforce_workspace_action_req）。
-    403 → ArtifactPermissionError；404 → ArtifactNotFoundError。
-    """
-    endpoint = _ap_endpoint(ap_endpoint)
-    url = f"{endpoint}/api/jobs/{job_id}?include_params=true"
-    headers = {
-        "X-API-Key": api_key,
-        "Accept": "application/json",
-    }
-    if cluster:
-        headers["X-Cluster"] = cluster
-
-    req = urllib.request.Request(url, headers=headers, method="GET")
+    """Explicit legacy detail helper; normal downloads do not precheck Jobs."""
+    from irepo_artifact import ArtifactError
+    from irepo_artifact.api import validate_id
+    failure = None
     try:
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            return json.loads(resp.read().decode())
-    except urllib.error.HTTPError as e:
-        if e.code == 403:
-            raise ArtifactPermissionError(
-                f"workspace ACL denied access to job {job_id!r}"
-            ) from e
-        if e.code == 404:
-            raise ArtifactNotFoundError(
-                f"job {job_id!r} not found"
-            ) from e
-        raise InstanceRepoError(
-            f"AP returned HTTP {e.code} for job {job_id!r}: {e.reason}"
-        ) from e
-    except urllib.error.URLError as e:
-        raise InstanceRepoError(
-            f"failed to reach AP at {endpoint}: {e.reason}"
-        ) from e
+        validate_id(job_id)
+        return _client(api_key, cluster, ap_endpoint)._api._call(
+            f"/jobs/{job_id}?include_params=true")
+    except ArtifactError as exc:
+        failure = _legacy_error(exc.clone())
+    raise failure
 
 
 def fetch_group_job_ids(api_key: str, group_id: str, cluster: str,
                         ap_endpoint: str | None = None) -> list[str]:
-    """调 AP GET /api/groups/{group_id}/jobs 分页收集全部 job_id。
-
-    endpoint 解析与 fetch_job_info 完全一致（复用 _ap_endpoint），
-    且 URL 必须带 /api 前缀：AP 网关的裸 /groups/{id}/jobs 路径返回
-    控制台 HTML 页（HTTP 200），json 解析会报错（真机实测）。
-    """
-    endpoint = _ap_endpoint(ap_endpoint)
-    job_ids: list[str] = []
-    skip = 0
-    limit = 500
-
-    while True:
-        url = (f"{endpoint}/api/groups/{group_id}/jobs"
-               f"?skip={skip}&limit={limit}&include_post_process=false")
-        headers = {
-            "X-API-Key": api_key,
-            "Accept": "application/json",
-        }
-        if cluster:
-            headers["X-Cluster"] = cluster
-
-        req = urllib.request.Request(url, headers=headers, method="GET")
-        try:
-            with urllib.request.urlopen(req, timeout=60) as resp:
-                data = json.loads(resp.read().decode())
-        except urllib.error.HTTPError as e:
-            if e.code == 403:
-                raise ArtifactPermissionError(
-                    f"workspace ACL denied access to group {group_id!r}"
-                ) from e
-            if e.code == 404:
-                raise ArtifactNotFoundError(
-                    f"group {group_id!r} not found"
-                ) from e
-            raise InstanceRepoError(
-                f"AP returned HTTP {e.code} for group {group_id!r}"
-            ) from e
-        except urllib.error.URLError as e:
-            raise InstanceRepoError(
-                f"failed to reach AP at {endpoint}: {e.reason}"
-            ) from e
-
-        jobs = data.get("jobs", [])
-        if not jobs:
-            break
-        for j in jobs:
-            jid = j.get("job_id")
-            if jid:
-                job_ids.append(jid)
-        if len(jobs) < limit:
-            break
-        skip += limit
-
-    return job_ids
+    """Bounded, deduplicated Group enumeration on credential-isolated AP HTTP."""
+    from irepo_artifact import ArtifactError
+    failure = None
+    try:
+        return _client(api_key, cluster, ap_endpoint)._api.list_group_job_ids(group_id)
+    except ArtifactError as exc:
+        failure = _legacy_error(exc.clone())
+    raise failure
 
 
 def _client(api_key: str, cluster: str, ap_endpoint: str | None):

{instance_repo-1.4.1.dev0 → instance_repo-1.4.6}/instance_repo/bootstrap.py

@@ -14,7 +14,7 @@ registry/namespace），校验并缓存。
 **二、优先级固定为 显式 > 遗留环境变量 > 自动发现。** 已经显式配好的调用方不会因为
 引入自动发现而行为漂移；反过来，自动发现也不会覆盖调用方的明确意图。
 
-**三、缓存按 ``(api_base, api_env, selector_type, selector_value)`` 四元组。** cluster
+**三、缓存按 ``(api_base, api_env, selector_type, selector_value)`` 及 transport 实例隔离。** cluster
 与 storage_env 即使值相同也不会串味；默认 TTL 内复用，``refresh=True`` 可强制重新拉取。
 """
 from __future__ import annotations
@@ -23,7 +23,7 @@ import logging
 import threading
 import time
 
-from .cache import TTLCache
+from .cache import TTLCache, transport_cache_identity
 from .clients.config import (
     Profile, fetch_repo_config, normalize_storage_env,
 )
@@ -39,7 +39,7 @@ DISCOVERY_TTL_SECONDS = 3600.0
 DISCOVERABLE_FIELDS = ("oss_bucket", "oss_prefix", "acr_host",
                        "acr_public_host", "acr_namespace")
 
-_cache = TTLCache(safety=0.0)
+_cache = TTLCache(safety=0.0, max_entries=512)
 _lock = threading.Lock()
 
 
@@ -56,9 +56,9 @@ def _selector(profile: Profile) -> tuple[str, str]:
     return "", ""
 
 
-def _cache_key(profile: Profile) -> tuple:
+def _cache_key(profile: Profile, transport) -> tuple:
     selector_type, selector_value = _selector(profile)
-    return (profile.api_base, profile.api_env, selector_type, selector_value)
+    return (transport_cache_identity(transport), profile.api_base, profile.api_env, selector_type, selector_value)
 
 
 def discover(transport, profile: Profile, *, refresh: bool = False) -> dict:
@@ -71,7 +71,7 @@ def discover(transport, profile: Profile, *, refresh: bool = False) -> dict:
     selector_type, selector_value = _selector(profile)
     if not selector_type:
         return {}
-    key = _cache_key(profile)
+    key = _cache_key(profile, transport)
     if not refresh:
         cached = _cache.get(key)
         if cached is not None:

{instance_repo-1.4.1.dev0 → instance_repo-1.4.6}/instance_repo/cache.py

@@ -6,6 +6,7 @@ oss2 Bucket 按 (bucket,prefix,security_token) 缓存以复用底层连接池。
 """
 from __future__ import annotations
 
+import hashlib
 import threading
 import time
 from datetime import datetime, timezone
@@ -29,13 +30,36 @@ def parse_expiry(rfc3339: str | None) -> float | None:
     return dt.timestamp()
 
 
+_identity_lock = threading.Lock()
+
+
+def transport_cache_identity(transport):
+    """Opaque per-instance token: no credentials or recyclable object addresses."""
+    with _identity_lock:
+        token = getattr(transport, "_config_cache_identity", None)
+        if token is None:
+            token = object()
+            try:
+                setattr(transport, "_config_cache_identity", token)
+            except (AttributeError, TypeError):
+                pass  # Immutable adapters safely disable reuse instead of sharing.
+        subject = getattr(transport, "token", "")
+        digest = hashlib.sha256(subject.encode("utf-8", "surrogatepass")).digest() if isinstance(subject, str) else b""
+        return token, digest
+
+
 class TTLCache:
     """线程安全 TTL 缓存。"""
 
-    def __init__(self, *, safety: float = 60.0) -> None:
+    def __init__(self, *, safety: float = 60.0, max_entries: int | None = None) -> None:
         self._d: dict[Any, tuple[Any, float | None]] = {}
         self._lock = threading.Lock()
         self._safety = safety
+        if max_entries is not None and (isinstance(max_entries, bool)
+                                        or not isinstance(max_entries, int)
+                                        or max_entries < 1):
+            raise ValueError("max_entries must be a positive integer")
+        self._max_entries = max_entries
 
     def get(self, key: Any) -> Any | None:
         with self._lock:
@@ -50,6 +74,13 @@ class TTLCache:
 
     def put(self, key: Any, value: Any, expiry: float | None) -> None:
         with self._lock:
+            if self._max_entries is not None:
+                now = time.time()
+                for stale, (_, exp) in list(self._d.items()):
+                    if exp is not None and now >= exp - self._safety:
+                        self._d.pop(stale, None)
+                if key not in self._d and len(self._d) >= self._max_entries:
+                    self._d.pop(next(iter(self._d)))
             self._d[key] = (value, expiry)
 
     def clear(self) -> None:

instance_repo-1.4.6/instance_repo/clients/_rfc3339.py

@@ -0,0 +1,41 @@
+"""Private RFC3339 calendar parser with Python 3.10+ fraction behavior.
+
+Wire values remain untouched at the call sites. Python datetime arithmetic uses
+microseconds, matching 3.11+ fromisoformat truncation of finer fractions; expiry
+is never rounded up. The original wire precision is not an integrity anchor.
+"""
+from datetime import datetime, timedelta, timezone
+import re
+
+_UTC = re.compile(
+    r'([0-9]{4})-([0-9]{2})-([0-9]{2})T([0-9]{2}):([0-9]{2}):([0-9]{2})'
+    r'(?:\.([0-9]+))?(Z|[+-][0-9]{2}:[0-9]{2})\Z')
+
+
+def parse_utc(value: str, *, allow_offset: bool = False) -> datetime:
+    """Validate calendar fields without version-specific ISO parsing.
+
+    Fraction processing is bounded to six digits, including arbitrarily precise
+    values permitted by existing read/write callers. Entries keeps its existing
+    one-to-nine-digit and byte bounds before invoking this helper.
+    """
+    match = _UTC.fullmatch(value) if type(value) is str and type(allow_offset) is bool else None
+    if match is None:
+        raise ValueError('invalid RFC3339 UTC datetime')
+    fraction = match.group(7) or ''
+    microsecond = int((fraction[:6] + '000000')[:6])
+    suffix = match.group(8)
+    hours, minutes = (0, 0) if suffix == 'Z' else (int(suffix[1:3]), int(suffix[4:6]))
+    if hours > 23 or minutes > 59 or (not allow_offset and (hours or minutes)):
+        raise ValueError('invalid RFC3339 datetime offset')
+    offset = (hours * 60 + minutes) * (-1 if suffix.startswith('-') else 1)
+    parsed = None
+    try:
+        parsed = datetime(*(int(match.group(n)) for n in range(1, 7)),
+                          microsecond=microsecond, tzinfo=timezone(timedelta(minutes=offset)))
+    except ValueError:
+        pass
+    if parsed is None:
+        # Do not attach a calendar exception or raw wire string to the error.
+        raise ValueError('invalid RFC3339 UTC calendar datetime')
+    return parsed