tinet-data-foundry-cli 0.1.6__tar.gz → 0.1.9__tar.gz

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinet-data-foundry-cli
-Version: 0.1.6
+Version: 0.1.9
 Summary: Tinet Data Foundry 取数 CLI（docs / catalog / query / schema）
 Author: Tinet
 License: MIT
@@ -57,6 +57,15 @@ tdf query \
 
 仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
+ODS 可以查询和过滤 `_source_ds`，值是来源数据源编码。编码清单：
+
+```bash
+tdf datasource-codes
+tdf datasource-codes --code nboss
+```
+
+只筛分区字段（如 `startTime`）时，服务端按同一范围另补 `_df_pt` 裁分区。其他时间字段不补。`_df_pt` 不能作为查询列。响应 `partitionWindow.prunedFrom` / `prunedTo` 是实际裁剪区间。
+
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
 ## Windows（cmd.exe）
@@ -87,23 +96,25 @@ tdf catalog --insecure
 | `tdf docs rev` | `GET /docs/credentials/{ak}?format=rev` |
 | `tdf docs pull` | 按 `copy.catalog.policy` 只拉取变化的 `part=public` 或 `part=policy` |
 | `tdf catalog` | `GET /data-api/v1/catalog` |
+| `tdf datasource-codes` | `GET /data-api/v1/datasource-codes` |
 | `tdf query` | `POST /data-api/v1/datasets/{id}/query` |
 | `tdf schema` | `GET /data-api/v1/datasets/{id}/schema` |
 
 文档站点默认 `https://data-foundry.tinetcloud.com`，可用 `DF_DOCS_BASE` 覆盖。`tdf docs` 只需要 `DF_AK`。缓存位于 `~/.cache/tinet-data-foundry/docs/<AK 哈希>/`，可用 `DF_DOCS_CACHE` 改根目录。stdout 非终端时 `tdf catalog` 改为 JSON。
 
-### Skill 查询大目录
+### 业务 Skill 锁定数据集
 
-`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+`tdf docs pull` 把公共目录与授权策略缓存到本机。业务 Skill 自行检索和阅读字段，不要把 `public.json` 或 `policy.json` 读进上下文：
 
 ```bash
-tdf docs search --query "京东云消费"
+tdf docs pull
+tdf docs search --query "<检索词>"
 tdf docs describe --dataset "DATASET_ID"
 ```
 
-`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+`search` 默认只返回有表权限的数据集，表名或中文名精确匹配排在前面，最多 20 条。`describe` 只返回该表已授权字段、分区粒度和脱敏规则。需要与网关当前结构核对时再用 `tdf schema --dataset "DATASET_ID"`。不要用不带 `--keyword` 的 `tdf catalog` 拉取整份目录。
 
-Agent / Skill 传查询体用文件，避免 shell 转义：
+DataFoundry 查询 Skill 只执行已经写好的查询。查询体用文件传入，避免 shell 转义：
 
 ```bash
 tdf query --dataset "DATASET_ID" --body-file query.json

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/README.md

@@ -40,6 +40,15 @@ tdf query \
 
 仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
+ODS 可以查询和过滤 `_source_ds`，值是来源数据源编码。编码清单：
+
+```bash
+tdf datasource-codes
+tdf datasource-codes --code nboss
+```
+
+只筛分区字段（如 `startTime`）时，服务端按同一范围另补 `_df_pt` 裁分区。其他时间字段不补。`_df_pt` 不能作为查询列。响应 `partitionWindow.prunedFrom` / `prunedTo` 是实际裁剪区间。
+
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
 ## Windows（cmd.exe）
@@ -70,23 +79,25 @@ tdf catalog --insecure
 | `tdf docs rev` | `GET /docs/credentials/{ak}?format=rev` |
 | `tdf docs pull` | 按 `copy.catalog.policy` 只拉取变化的 `part=public` 或 `part=policy` |
 | `tdf catalog` | `GET /data-api/v1/catalog` |
+| `tdf datasource-codes` | `GET /data-api/v1/datasource-codes` |
 | `tdf query` | `POST /data-api/v1/datasets/{id}/query` |
 | `tdf schema` | `GET /data-api/v1/datasets/{id}/schema` |
 
 文档站点默认 `https://data-foundry.tinetcloud.com`，可用 `DF_DOCS_BASE` 覆盖。`tdf docs` 只需要 `DF_AK`。缓存位于 `~/.cache/tinet-data-foundry/docs/<AK 哈希>/`，可用 `DF_DOCS_CACHE` 改根目录。stdout 非终端时 `tdf catalog` 改为 JSON。
 
-### Skill 查询大目录
+### 业务 Skill 锁定数据集
 
-`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+`tdf docs pull` 把公共目录与授权策略缓存到本机。业务 Skill 自行检索和阅读字段，不要把 `public.json` 或 `policy.json` 读进上下文：
 
 ```bash
-tdf docs search --query "京东云消费"
+tdf docs pull
+tdf docs search --query "<检索词>"
 tdf docs describe --dataset "DATASET_ID"
 ```
 
-`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+`search` 默认只返回有表权限的数据集，表名或中文名精确匹配排在前面，最多 20 条。`describe` 只返回该表已授权字段、分区粒度和脱敏规则。需要与网关当前结构核对时再用 `tdf schema --dataset "DATASET_ID"`。不要用不带 `--keyword` 的 `tdf catalog` 拉取整份目录。
 
-Agent / Skill 传查询体用文件，避免 shell 转义：
+DataFoundry 查询 Skill 只执行已经写好的查询。查询体用文件传入，避免 shell 转义：
 
 ```bash
 tdf query --dataset "DATASET_ID" --body-file query.json

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tinet-data-foundry-cli"
-version = "0.1.6"
+version = "0.1.9"
 description = "Tinet Data Foundry 取数 CLI（docs / catalog / query / schema）"
 readme = "README.md"
 requires-python = ">=3.10"

tinet_data_foundry_cli-0.1.9/src/tinet_data_foundry_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.9"

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/src/tinet_data_foundry_cli/cli.py

@@ -82,6 +82,56 @@ def _ok_data(parsed: Any) -> Any:
     return parsed.get("data") if isinstance(parsed, dict) else parsed
 
 
+def _print_datasource_codes(rows: List[Mapping[str, Any]]) -> None:
+    if not rows:
+        print("当前凭证没有可查询的数据源编码。")
+        return
+    cols = [
+        ("code", "编码", 24),
+        ("name", "名称", 28),
+        ("id", "id", 36),
+    ]
+    header = "  ".join(_cell(title, w) for _, title, w in cols)
+    print(header)
+    print("-" * len(header))
+    for row in rows:
+        print("  ".join(_cell(row.get(key), w) for key, _, w in cols))
+
+
+def cmd_datasource_codes(args: argparse.Namespace) -> int:
+    base, ak, sk = credentials(args.endpoint)
+    query = {
+        "code": args.code or "",
+        "keyword": args.keyword or "",
+    }
+    try:
+        _, parsed, _ = request(
+            "GET",
+            base,
+            "/data-api/v1/datasource-codes",
+            ak,
+            sk,
+            query=query,
+            timeout=args.timeout,
+            insecure=args.insecure,
+            dry_run=args.dry_run,
+        )
+    except ApiError as ex:
+        _exit_api(ex)
+    except TransportError as ex:
+        _exit_transport(ex)
+    fmt = args.format
+    if fmt == "table" and not sys.stdout.isatty():
+        fmt = "json"
+    if args.dry_run or fmt == "json":
+        _print_json(parsed)
+        return 0
+    data = _ok_data(parsed) or {}
+    rows = data.get("list") if isinstance(data, dict) else []
+    _print_datasource_codes(list(rows or []))
+    return 0
+
+
 def cmd_catalog(args: argparse.Namespace) -> int:
     base, ak, sk = credentials(args.endpoint)
     query = {
@@ -249,6 +299,13 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("--format", choices=["table", "json"], default="table")
     c.set_defaults(func=cmd_catalog)
 
+    codes = sub.add_parser("datasource-codes", help="列出当前凭证可查询数据集关联的数据源编码")
+    _add_insecure(codes, overlay=True)
+    codes.add_argument("--code", help="按编码精确匹配，忽略大小写")
+    codes.add_argument("--keyword", help="按编码或名称包含匹配")
+    codes.add_argument("--format", choices=["table", "json"], default="table")
+    codes.set_defaults(func=cmd_datasource_codes)
+
     q = sub.add_parser("query", help="查询 Dataset")
     _add_insecure(q, overlay=True)
     q.add_argument("--dataset", required=True)
@@ -260,7 +317,8 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             "filter AST JSON。字符串字段可 starts_with（右模糊）、ends_with（左模糊）、contains（左右模糊）。"
             "仅按日分区必填：省略分区字段时按上海时区补当天，显式 between 不超过 30 天。"
-            "按月、按年分区字段不是必填条件"
+            "按月、按年分区字段不是必填条件。"
+            "只筛分区字段时，服务端另补 _df_pt 裁分区；其他时间字段不补。_df_pt 不能作为查询列"
         ),
     )
     q.add_argument("--sort", help="sort JSON 数组")
@@ -280,9 +338,10 @@ def build_parser() -> argparse.ArgumentParser:
     d = sub.add_parser("docs", help="核对数据集开发文档修订号，并在本地缓存中检索数据集")
     _add_insecure(d, overlay=True)
     d.add_argument("action", choices=["rev", "pull", "search", "describe"])
-    d.add_argument("--query", help="search：按名称、描述、表名或业务域检索本地缓存")
+    d.add_argument("--query", help="search：按名称、描述、表名或业务域检索本地缓存。表名精确匹配优先")
     d.add_argument("--dataset", help="describe：输出指定数据集的已授权字段")
     d.add_argument("--all", action="store_true", help="search：包含无表权限的数据集")
+    d.add_argument("--limit", type=int, default=20, help="search：最多返回条数，默认 20")
     d.add_argument("--docs-base", help="覆盖文档站点。默认 DF_DOCS_BASE 或 https://data-foundry.tinetcloud.com")
     d.set_defaults(func=cmd_docs)
 

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/src/tinet_data_foundry_cli/docs.py

@@ -48,7 +48,12 @@ def run_docs(args: Any) -> int:
     base = docs_base(getattr(args, "docs_base", None))
     folder = cache_dir(ak)
     if args.action == "search":
-        return _search(folder, str(getattr(args, "query", "") or ""), bool(getattr(args, "all", False)))
+        return _search(
+            folder,
+            str(getattr(args, "query", "") or ""),
+            bool(getattr(args, "all", False)),
+            int(getattr(args, "limit", None) or 20),
+        )
     if args.action == "describe":
         return _describe(folder, str(getattr(args, "dataset", "") or ""))
     url = docs_url(base, ak, "rev")
@@ -76,25 +81,25 @@ def _cached_docs(folder: Path) -> tuple[Dict[str, Any], Dict[str, Any]]:
     return public, policy
 
 
-def _search(folder: Path, query: str, include_denied: bool) -> int:
+def _search(folder: Path, query: str, include_denied: bool, limit: int = 20) -> int:
     public, policy = _cached_docs(folder)
     needle = query.strip().casefold()
     if not needle:
         raise SystemExit("docs search 需要 --query")
+    if limit < 1:
+        raise SystemExit("docs search --limit 必须大于 0")
     grants = _index(policy)
-    matches: List[Dict[str, Any]] = []
+    ranked: List[tuple] = []
     for dataset in public.get("datasets") or []:
         if not isinstance(dataset, dict):
             continue
         grant = grants.get(str(dataset.get("id") or ""), {})
         if not include_denied and not grant.get("tableGranted"):
             continue
-        haystack = " ".join(str(dataset.get(key) or "") for key in (
-            "id", "name", "chineseName", "tableComment", "description", "businessDomainName",
-        )).casefold()
-        if needle not in haystack:
+        rank = _match_rank(dataset, needle)
+        if rank is None:
             continue
-        matches.append({
+        ranked.append((rank, str(dataset.get("name") or ""), {
             "id": dataset.get("id"),
             "name": dataset.get("name"),
             "chineseName": dataset.get("chineseName"),
@@ -103,11 +108,34 @@ def _search(folder: Path, query: str, include_denied: bool) -> int:
             "layer": dataset.get("layer"),
             "schemaVersion": dataset.get("schemaVersion"),
             "tableGranted": bool(grant.get("tableGranted")),
-        })
-    _print({"query": query, "datasets": matches})
+        }))
+    ranked.sort(key=lambda row: (row[0], row[1]))
+    shown = ranked[:limit]
+    _print({
+        "query": query,
+        "total": len(ranked),
+        "truncated": len(ranked) > limit,
+        "datasets": [row[2] for row in shown],
+    })
     return 0
 
 
+def _match_rank(dataset: Dict[str, Any], needle: str) -> Optional[int]:
+    identity = [str(dataset.get(key) or "").casefold() for key in ("id", "name", "chineseName")]
+    if needle in identity:
+        return 0
+    if any(value.startswith(needle) for value in identity if value):
+        return 1
+    if any(needle in value for value in identity if value):
+        return 2
+    extra = " ".join(str(dataset.get(key) or "") for key in (
+        "tableComment", "description", "businessDomainName",
+    )).casefold()
+    if needle in extra:
+        return 3
+    return None
+
+
 def _describe(folder: Path, dataset_id: str) -> int:
     public, policy = _cached_docs(folder)
     if not dataset_id.strip():
@@ -135,6 +163,7 @@ def _describe(folder: Path, dataset_id: str) -> int:
             "partition": column.get("partition"),
             "partitionGrain": column.get("partitionGrain"),
             "partitionRequired": column.get("partitionRequired"),
+            "suggestedRange": column.get("suggestedRange"),
             "outputRule": rules[name].get("outputRule"),
         })
     _print({

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/src/tinet_data_foundry_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinet-data-foundry-cli
-Version: 0.1.6
+Version: 0.1.9
 Summary: Tinet Data Foundry 取数 CLI（docs / catalog / query / schema）
 Author: Tinet
 License: MIT
@@ -57,6 +57,15 @@ tdf query \
 
 仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
+ODS 可以查询和过滤 `_source_ds`，值是来源数据源编码。编码清单：
+
+```bash
+tdf datasource-codes
+tdf datasource-codes --code nboss
+```
+
+只筛分区字段（如 `startTime`）时，服务端按同一范围另补 `_df_pt` 裁分区。其他时间字段不补。`_df_pt` 不能作为查询列。响应 `partitionWindow.prunedFrom` / `prunedTo` 是实际裁剪区间。
+
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
 ## Windows（cmd.exe）
@@ -87,23 +96,25 @@ tdf catalog --insecure
 | `tdf docs rev` | `GET /docs/credentials/{ak}?format=rev` |
 | `tdf docs pull` | 按 `copy.catalog.policy` 只拉取变化的 `part=public` 或 `part=policy` |
 | `tdf catalog` | `GET /data-api/v1/catalog` |
+| `tdf datasource-codes` | `GET /data-api/v1/datasource-codes` |
 | `tdf query` | `POST /data-api/v1/datasets/{id}/query` |
 | `tdf schema` | `GET /data-api/v1/datasets/{id}/schema` |
 
 文档站点默认 `https://data-foundry.tinetcloud.com`，可用 `DF_DOCS_BASE` 覆盖。`tdf docs` 只需要 `DF_AK`。缓存位于 `~/.cache/tinet-data-foundry/docs/<AK 哈希>/`，可用 `DF_DOCS_CACHE` 改根目录。stdout 非终端时 `tdf catalog` 改为 JSON。
 
-### Skill 查询大目录
+### 业务 Skill 锁定数据集
 
-`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+`tdf docs pull` 把公共目录与授权策略缓存到本机。业务 Skill 自行检索和阅读字段，不要把 `public.json` 或 `policy.json` 读进上下文：
 
 ```bash
-tdf docs search --query "京东云消费"
+tdf docs pull
+tdf docs search --query "<检索词>"
 tdf docs describe --dataset "DATASET_ID"
 ```
 
-`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+`search` 默认只返回有表权限的数据集，表名或中文名精确匹配排在前面，最多 20 条。`describe` 只返回该表已授权字段、分区粒度和脱敏规则。需要与网关当前结构核对时再用 `tdf schema --dataset "DATASET_ID"`。不要用不带 `--keyword` 的 `tdf catalog` 拉取整份目录。
 
-Agent / Skill 传查询体用文件，避免 shell 转义：
+DataFoundry 查询 Skill 只执行已经写好的查询。查询体用文件传入，避免 shell 转义：
 
 ```bash
 tdf query --dataset "DATASET_ID" --body-file query.json

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/tests/test_cli.py

@@ -21,12 +21,18 @@ class CliParserTest(unittest.TestCase):
         self.assertIn("30", help_text)
         self.assertIn("当天", help_text)
         self.assertIn("按月、按年分区字段不是必填条件", help_text)
+        self.assertIn("_df_pt", help_text)
+        self.assertIn("裁分区", help_text)
+        self.assertIn("不能作为查询列", help_text)
         self.assertNotIn("按月补当月", help_text)
 
     def test_subcommands(self):
         parser = build_parser()
         catalog = parser.parse_args(["catalog", "--format", "json"])
         self.assertEqual(catalog.cmd, "catalog")
+        codes = parser.parse_args(["datasource-codes", "--code", "nboss"])
+        self.assertEqual(codes.cmd, "datasource-codes")
+        self.assertEqual(codes.code, "nboss")
         query = parser.parse_args(["query", "--dataset", "ds_1", "--page-no", "1", "--page-size", "10"])
         self.assertEqual(query.cmd, "query")
         catalog_k = parser.parse_args(["catalog", "--insecure"])

{tinet_data_foundry_cli-0.1.6 → tinet_data_foundry_cli-0.1.9}/tests/test_docs.py

@@ -17,20 +17,45 @@ class DocsSummaryTest(unittest.TestCase):
                 "description": "京东云消费", "columns": [
                     {"name": "amount", "type": "decimal", "comment": "金额"},
                     {"name": "secret", "type": "text", "comment": "无权限"},
+                    {"name": "_df_pt", "type": "date", "comment": "分区查询时间",
+                     "suggestedRange": {"from": "2026-10-01", "to": "2026-10-01", "grain": "month"}},
                 ],
             }]}), encoding="utf-8")
             (folder / "policy.json").write_text(json.dumps({"datasets": [{
                 "id": "ds_bill", "tableGranted": True,
-                "columns": [{"name": "amount", "granted": True, "outputRule": "PLAIN"}],
+                "columns": [
+                    {"name": "amount", "granted": True, "outputRule": "PLAIN"},
+                    {"name": "_df_pt", "granted": True, "outputRule": "PLAIN"},
+                ],
             }]}), encoding="utf-8")
             self.assertEqual(_search(folder, "京东云", False), 0)
             search = json.loads(out.getvalue())
             self.assertEqual(search["datasets"][0]["id"], "ds_bill")
+            self.assertEqual(search["total"], 1)
+            self.assertFalse(search["truncated"])
             out.seek(0)
             out.truncate(0)
             self.assertEqual(_describe(folder, "ds_bill"), 0)
             described = json.loads(out.getvalue())
-            self.assertEqual([col["name"] for col in described["columns"]], ["amount"])
+            self.assertEqual([col["name"] for col in described["columns"]], ["amount", "_df_pt"])
+            self.assertEqual(described["columns"][1]["suggestedRange"]["from"], "2026-10-01")
+
+    def test_search_prefers_exact_name_and_limits_rows(self):
+        with tempfile.TemporaryDirectory() as tmp, patch("sys.stdout", new_callable=StringIO) as out:
+            folder = Path(tmp)
+            datasets = [
+                {"id": "ds_desc", "name": "other", "description": "bill detail"},
+                {"id": "ds_exact", "name": "bill", "chineseName": "账单"},
+                {"id": "ds_more", "name": "bill_extra", "description": "bill"},
+            ]
+            grants = [{"id": row["id"], "tableGranted": True, "columns": []} for row in datasets]
+            (folder / "public.json").write_text(json.dumps({"datasets": datasets}), encoding="utf-8")
+            (folder / "policy.json").write_text(json.dumps({"datasets": grants}), encoding="utf-8")
+            self.assertEqual(_search(folder, "bill", False, 2), 0)
+            search = json.loads(out.getvalue())
+            self.assertEqual([row["id"] for row in search["datasets"]], ["ds_exact", "ds_more"])
+            self.assertEqual(search["total"], 3)
+            self.assertTrue(search["truncated"])
 
     def test_summarize_catalog_and_policy(self):
         old_public = {"datasets": [{"id": "a", "schemaVersion": "1"}, {"id": "b", "schemaVersion": "1"}]}

tinet_data_foundry_cli-0.1.6/src/tinet_data_foundry_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.6"