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或含这些值的异常链。
