ap-client 0.2.2.dev0__tar.gz → 0.2.2.dev2__tar.gz

{ap_client-0.2.2.dev0 → ap_client-0.2.2.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.2.2.dev0
+Version: 0.2.2.dev2
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0

{ap_client-0.2.2.dev0 → ap_client-0.2.2.dev2}/ap_client/api.py

@@ -935,6 +935,11 @@ class APIClient:
         keyword: Optional[str] = None,
         visibility: Optional[str] = None,
         benchmark_id: Optional[str] = None,
+        owned_by_me: bool = False,
+        updated_from: Optional[str] = None,
+        updated_to: Optional[str] = None,
+        sort_by: Optional[str] = None,
+        order: Optional[str] = None,
         include_deprecated: bool = False,
         environment: Optional[str] = None,
         page: int = 1,
@@ -942,7 +947,20 @@ class APIClient:
     ) -> dict:
         """一页 dataset series(原始 PagedSuccess envelope)。
 
-        服务端没有 owner/mine/l1 过滤参数,调用方需要时只能在客户端做页内过滤。
+        服务端在**分页之前**完成筛选与排序,所以响应里的 ``total`` 就是过滤后的计数
+        (``docs/openapi.json`` 的 ``GET /datasets/series``)。可用过滤参数:
+
+        * ``q``/``keyword``:对 ``dataset_name`` + ``display_name`` 模糊匹配
+          (``keyword`` 是 ``q`` 的废弃别名,仅当 ``q`` 为空时生效);
+        * ``visibility``:逗号分隔多值,同维 OR(逐项 ``public``/``private``);
+        * ``benchmark_id``:精确匹配绑定,特殊值 ``none`` 表示未绑定;
+        * ``owned_by_me``:只保留 owner == 调用方身份的 dataset(需登录态);
+        * ``updated_from``/``updated_to``:``updated_at`` 闭区间(RFC3339,可只给一侧);
+        * ``environment``:默认 ``online``。
+
+        排序用 ``sort_by``(``updated_at``/``dataset_name``)+``order``(``asc``/``desc``)。
+        **没有按任意 uid 过滤 owner 的参数**:``owned_by_me`` 只能是"我自己",查别人的
+        dataset 仍要在客户端过滤。非法取值由服务端 400 拒绝。
         """
         params: dict = {"page": page, "page_size": page_size}
         if q:
@@ -953,6 +971,16 @@ class APIClient:
             params["visibility"] = visibility
         if benchmark_id:
             params["benchmark_id"] = benchmark_id
+        if owned_by_me:
+            params["owned_by_me"] = "true"
+        if updated_from:
+            params["updated_from"] = updated_from
+        if updated_to:
+            params["updated_to"] = updated_to
+        if sort_by:
+            params["sort_by"] = sort_by
+        if order:
+            params["order"] = order
         if include_deprecated:
             params["include_deprecated"] = "true"
         if environment:

{ap_client-0.2.2.dev0 → ap_client-0.2.2.dev2}/ap_client/dataset_commands.py

@@ -8,10 +8,14 @@ is implemented in split_publish.py and never publishes a whole version.
 from __future__ import annotations
 
 import json
-from typing import Any, Optional
+import re
+from typing import TYPE_CHECKING, Any, List, Optional
 
 import typer
 
+if TYPE_CHECKING:  # pragma: no cover - 仅用于类型标注,运行时不 import
+    from datetime import datetime
+
 __all__ = [
     "dataset_version_app",
     "dataset_split_app",
@@ -104,6 +108,11 @@ _VISIBILITIES = ("private", "public")
 #: 服务端 version 枚举(设计 §9:上游的 publishing/failed 是 ingest 任务状态,不在此列)。
 _VERSION_STATUSES = ("draft", "published", "deprecated", "archived")
 _RUN_TYPES = ("train", "eval")
+#: ``dataset list`` 的服务端排序键与方向(``GET /apis/v1/datasets/series``)。
+_SORT_KEYS = ("updated_at", "dataset_name")
+_SORT_ORDERS = ("asc", "desc")
+#: 服务端 ``benchmark_id`` 的特殊取值:未绑定 benchmark 的治理查询。
+_NO_BENCHMARK = "none"
 
 _FORMAT_HELP = "Output format: plain/table/json/yaml (default: AP_FORMAT or command default)"
 
@@ -274,6 +283,71 @@ def _resolve_benchmark_id(client, value: str) -> str:
     )
 
 
+def _visibility_values(values: Optional[List[str]]) -> list[str]:
+    """``--visibility`` 归一成服务端的逗号分隔多值形式(同维 OR)。
+
+    既支持重复给(``--visibility public --visibility private``),也支持逗号分隔
+    (``--visibility public,private``);逐项校验枚举,非法值 exit 2,不等到服务端 400。
+    """
+    resolved: list[str] = []
+    for raw in values or []:
+        for part in str(raw).split(","):
+            part = part.strip()
+            if not part:
+                continue
+            checked = _check_choice(part, _VISIBILITIES, "--visibility")
+            if checked not in resolved:
+                resolved.append(checked)
+    return resolved
+
+
+#: ``--updated-from/--updated-to`` 的 RFC3339 形状:日期 + 分隔符 + 时间 + 可选小数秒 + 带
+#: 偏移的时区(与 ``time.Parse(time.RFC3339, ...)`` 的接受面基本一致)。
+_UPDATED_AT_PATTERN = re.compile(
+    r"^(\d{4}-\d{2}-\d{2})[Tt ](\d{2}:\d{2}:\d{2})(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})$"
+)
+
+
+def _parse_updated_at(option: str, raw: str) -> "datetime":
+    """把 ``--updated-from/--updated-to`` 解析成带时区的 ``datetime``;形状不对则 exit 2。
+
+    只做前置校验,下发给服务端的仍是用户原样输入的字符串——服务端的
+    ``datasetUpdatedRangeFromQuery`` 才是最终解释方(它会把入参归一到 UTC 并做同样的
+    区间倒挂检查)。小数秒超过 6 位时截断,避免 Python <3.11 的 ``fromisoformat`` 把
+    服务端能接受的纳秒时间戳误判成非法。
+    """
+    from datetime import datetime
+
+    match = _UPDATED_AT_PATTERN.match(raw)
+    if match is None:
+        raise _fail(
+            f"{option} 取值非法：{raw!r}",
+            "用带时区的 RFC3339 时间戳,例如 2026-03-01T00:00:00Z 或 2026-03-02T12:30:00+08:00",
+            exit_code=2,
+        )
+    date, clock, fraction, zone = match.groups()
+    fraction = (fraction or "")[:7]  # ".123456789" → ".123456"
+    zone = "+00:00" if zone in ("Z", "z") else zone
+    if len(zone) == 5:  # "+0800" → "+08:00"
+        zone = f"{zone[:3]}:{zone[3:]}"
+    return datetime.fromisoformat(f"{date}T{clock}{fraction}{zone}")
+
+
+def _updated_range(from_value: Optional[str], to_value: Optional[str]) -> tuple[str, str]:
+    """校验 ``--updated-from/--updated-to``(闭区间,可只给一侧),原样返回待下发字符串。"""
+    lower = str(from_value or "").strip()
+    upper = str(to_value or "").strip()
+    parsed_lower = _parse_updated_at("--updated-from", lower) if lower else None
+    parsed_upper = _parse_updated_at("--updated-to", upper) if upper else None
+    if parsed_lower is not None and parsed_upper is not None and parsed_lower > parsed_upper:
+        raise _fail(
+            "--updated-from 不能晚于 --updated-to",
+            "区间是闭区间;调换两个时间戳,或只给一侧",
+            exit_code=2,
+        )
+    return lower, upper
+
+
 def _dataset_id_or_fail(client, dataset: str, *, stage: str) -> tuple[str, dict]:
     """取 ``dataset_id``(access/claim 都要),失败按设计 §5 的固定文案退出。"""
     from .api import APIError
@@ -493,13 +567,38 @@ def dataset_list(
         None, "--query", help="Fuzzy match on dataset name / description"
     ),
     benchmark: Optional[str] = typer.Option(
-        None, "--benchmark", help="Benchmark name or source_id"
+        None,
+        "--benchmark",
+        help=f"Benchmark name or source_id; '{_NO_BENCHMARK}' selects datasets with no binding",
     ),
-    visibility: Optional[str] = typer.Option(
-        None, "--visibility", help=f"Filter by visibility: {'/'.join(_VISIBILITIES)}"
+    visibility: Optional[List[str]] = typer.Option(
+        None,
+        "--visibility",
+        help=f"Filter by visibility: {'/'.join(_VISIBILITIES)}; repeat or comma-separate for OR",
+    ),
+    mine: bool = typer.Option(
+        False,
+        "--mine",
+        help="Only datasets owned by the caller (server-side owned_by_me=true)",
     ),
     owner: Optional[str] = typer.Option(
-        None, "--owner", help="Filter by owner uid (client-side, current page only)"
+        None,
+        "--owner",
+        help="Filter by owner uid (client-side; the server only filters by the caller: --mine)",
+    ),
+    updated_from: Optional[str] = typer.Option(
+        None,
+        "--updated-from",
+        help="Inclusive RFC3339 lower bound on updated_at (metadata edits only)",
+    ),
+    updated_to: Optional[str] = typer.Option(
+        None, "--updated-to", help="Inclusive RFC3339 upper bound on updated_at"
+    ),
+    sort_by: Optional[str] = typer.Option(
+        None, "--sort-by", help=f"Sort key: {'/'.join(_SORT_KEYS)} (server default: updated_at)"
+    ),
+    order: Optional[str] = typer.Option(
+        None, "--order", help=f"Sort direction: {'/'.join(_SORT_ORDERS)} (server default: desc)"
     ),
     page: Optional[int] = typer.Option(
         None,
@@ -548,7 +647,12 @@ def dataset_list(
             for name, value in (
                 ("--benchmark", benchmark),
                 ("--visibility", visibility),
+                ("--mine", mine),
                 ("--owner", owner),
+                ("--updated-from", updated_from),
+                ("--updated-to", updated_to),
+                ("--sort-by", sort_by),
+                ("--order", order),
                 ("--page", page),
                 ("--page-size", page_size),
             )
@@ -570,21 +674,43 @@ def dataset_list(
             _print_formatted(result, output_format)
         return
 
-    resolved_visibility = (
-        _check_choice(visibility, _VISIBILITIES, "--visibility") if visibility else ""
-    )
+    resolved_visibility = _visibility_values(visibility)
+    if mine and str(owner or "").strip():
+        # --mine 是服务端的 owned_by_me(只认调用方自己),与"查别人的 uid"互斥;
+        # 两个一起下发只会得到空结果,不如直接报用法错。
+        raise _fail(
+            "--mine 与 --owner 不能同时给出",
+            "--mine 查自己(服务端过滤);要查别人的 dataset 用 --owner <uid>(客户端过滤)",
+            exit_code=2,
+        )
+    resolved_sort_by = _check_choice(sort_by, _SORT_KEYS, "--sort-by") if sort_by else ""
+    resolved_order = _check_choice(order, _SORT_ORDERS, "--order") if order else ""
+    resolved_from, resolved_to = _updated_range(updated_from, updated_to)
+
     client = get_client()
-    benchmark_id = _resolve_benchmark_id(client, benchmark) if benchmark else ""
+    if str(benchmark or "").strip() == _NO_BENCHMARK:
+        # 服务端的治理查询:benchmark_id=none 表示"未绑定 benchmark",不经过名称解析。
+        benchmark_id = _NO_BENCHMARK
+    else:
+        benchmark_id = _resolve_benchmark_id(client, benchmark) if benchmark else ""
+
+    # 服务端在分页前完成筛选/排序,这些条件对每一页都成立,自动翻页可以直接复用。
+    filters: dict[str, Any] = {
+        "q": resolved_query or None,
+        "visibility": ",".join(resolved_visibility) or None,
+        "benchmark_id": benchmark_id or None,
+        "owned_by_me": mine,
+        "updated_from": resolved_from or None,
+        "updated_to": resolved_to or None,
+        "sort_by": resolved_sort_by or None,
+        "order": resolved_order or None,
+    }
 
     resolved_page = page or 1
-    # 自动翻页沿用主干旧口径的 500 条/页;显式分页仍是默认 20。
-    resolved_page_size = page_size or (500 if page is None else 20)
+    # 自动翻页用 100 条/页(500 对一次全量拉取偏大);显式分页仍是默认 20。
+    resolved_page_size = page_size or (100 if page is None else 20)
     records, pagination = client.list_dataset_series(
-        q=resolved_query or None,
-        visibility=resolved_visibility or None,
-        benchmark_id=benchmark_id or None,
-        page=resolved_page,
-        page_size=resolved_page_size,
+        page=resolved_page, page_size=resolved_page_size, **filters
     )
     records = [record for record in (records or []) if isinstance(record, dict)]
 
@@ -597,11 +723,7 @@ def dataset_list(
         while records and (total is None or seen < total) and guard < 100:
             guard += 1
             more, pagination = client.list_dataset_series(
-                q=resolved_query or None,
-                visibility=resolved_visibility or None,
-                benchmark_id=benchmark_id or None,
-                page=resolved_page + guard,
-                page_size=resolved_page_size,
+                page=resolved_page + guard, page_size=resolved_page_size, **filters
             )
             more = [record for record in (more or []) if isinstance(record, dict)]
             if not more:
@@ -617,13 +739,16 @@ def dataset_list(
     wanted_owner = str(owner or "").strip()
     payload: dict[str, Any] = {}
     if wanted_owner:
-        # 服务端没有 owner 查询参数(设计 §8.5),只能页内过滤,必须在 stderr 说清楚。
+        # 服务端只有 owned_by_me(按调用方身份过滤),没有任意 uid 的 owner 参数,
+        # 所以只能在客户端过滤,必须在 stderr 说清楚。
         _note(
-            f"--owner 只在客户端过滤当前页：服务端不支持 owner 查询,"
+            f"--owner 只在客户端过滤：服务端只支持按调用方身份过滤(--mine),"
             f"本次在 {len(records)} 条结果里筛 owner == {wanted_owner}"
         )
         records = [record for record in records if str(record.get("owner") or "") == wanted_owner]
         payload["owner_filter"] = wanted_owner
+    if mine:
+        payload["owned_by_me"] = True
 
     rows = [_dataset_row(record) for record in records]
     payload["datasets"] = [_legacy_dataset_record(record) for record in records]

{ap_client-0.2.2.dev0 → ap_client-0.2.2.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.2.2.dev0"
+version = "0.2.2.dev2"
 description = "Agent Platform API Client & CLI"
 readme = { text = "A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.", content-type = "text/markdown" }
 requires-python = ">=3.10"