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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinet-data-foundry-cli
-Version: 0.1.5
+Version: 0.1.6
 Summary: Tinet Data Foundry 取数 CLI（docs / catalog / query / schema）
 Author: Tinet
 License: MIT
@@ -55,7 +55,7 @@ tdf query \
 | `ends_with` | 左模糊，匹配后缀 | `{"op":"ends_with","field":"name","value":"公司"}` |
 | `contains` | 左右模糊 | `{"op":"contains","field":"name","value":"科技"}` |
 
-分区表可以不传分区字段。服务端按上海时区补默认闭区间：按日为当天，按月为当月，按年为当年，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 时，按日不超过 30 天，按月不超过 12 个月，按年不超过 3 年，否则 422 `PARTITION_RANGE_INVALID`。
+仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
@@ -92,6 +92,17 @@ tdf catalog --insecure
 
 文档站点默认 `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 查询大目录
+
+`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+
+```bash
+tdf docs search --query "京东云消费"
+tdf docs describe --dataset "DATASET_ID"
+```
+
+`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+
 Agent / Skill 传查询体用文件，避免 shell 转义：
 
 ```bash

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

@@ -38,7 +38,7 @@ tdf query \
 | `ends_with` | 左模糊，匹配后缀 | `{"op":"ends_with","field":"name","value":"公司"}` |
 | `contains` | 左右模糊 | `{"op":"contains","field":"name","value":"科技"}` |
 
-分区表可以不传分区字段。服务端按上海时区补默认闭区间：按日为当天，按月为当月，按年为当年，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 时，按日不超过 30 天，按月不超过 12 个月，按年不超过 3 年，否则 422 `PARTITION_RANGE_INVALID`。
+仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
@@ -75,6 +75,17 @@ tdf catalog --insecure
 
 文档站点默认 `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 查询大目录
+
+`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+
+```bash
+tdf docs search --query "京东云消费"
+tdf docs describe --dataset "DATASET_ID"
+```
+
+`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+
 Agent / Skill 传查询体用文件，避免 shell 转义：
 
 ```bash

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

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

tinet_data_foundry_cli-0.1.6/src/tinet_data_foundry_cli/__init__.py

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

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

@@ -259,8 +259,8 @@ def build_parser() -> argparse.ArgumentParser:
         "--filter",
         help=(
             "filter AST JSON。字符串字段可 starts_with（右模糊）、ends_with（左模糊）、contains（左右模糊）。"
-            "分区表省略分区字段时，按日补当天、按月补当月、按年补当年；"
-            "显式 between 按日不超过 30 天、按月不超过 12 个月、按年不超过 3 年"
+            "仅按日分区必填：省略分区字段时按上海时区补当天，显式 between 不超过 30 天。"
+            "按月、按年分区字段不是必填条件"
         ),
     )
     q.add_argument("--sort", help="sort JSON 数组")
@@ -277,9 +277,12 @@ def build_parser() -> argparse.ArgumentParser:
     )
     q.set_defaults(func=cmd_query)
 
-    d = sub.add_parser("docs", help="核对数据集开发文档修订号并缓存 public/policy")
+    d = sub.add_parser("docs", help="核对数据集开发文档修订号，并在本地缓存中检索数据集")
     _add_insecure(d, overlay=True)
-    d.add_argument("action", choices=["rev", "pull"])
+    d.add_argument("action", choices=["rev", "pull", "search", "describe"])
+    d.add_argument("--query", help="search：按名称、描述、表名或业务域检索本地缓存")
+    d.add_argument("--dataset", help="describe：输出指定数据集的已授权字段")
+    d.add_argument("--all", action="store_true", help="search：包含无表权限的数据集")
     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.5 → tinet_data_foundry_cli-0.1.6}/src/tinet_data_foundry_cli/docs.py

@@ -47,6 +47,10 @@ def run_docs(args: Any) -> int:
     ak = access_key()
     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)))
+    if args.action == "describe":
+        return _describe(folder, str(getattr(args, "dataset", "") or ""))
     url = docs_url(base, ak, "rev")
     if args.dry_run:
         _print({
@@ -64,6 +68,90 @@ def run_docs(args: Any) -> int:
     return _pull(folder, base, ak, args.timeout, args.insecure)
 
 
+def _cached_docs(folder: Path) -> tuple[Dict[str, Any], Dict[str, Any]]:
+    public = _read_json(folder / "public.json")
+    policy = _read_json(folder / "policy.json")
+    if not public or not policy:
+        raise SystemExit("本地文档缓存不存在，请先运行 tdf docs pull")
+    return public, policy
+
+
+def _search(folder: Path, query: str, include_denied: bool) -> int:
+    public, policy = _cached_docs(folder)
+    needle = query.strip().casefold()
+    if not needle:
+        raise SystemExit("docs search 需要 --query")
+    grants = _index(policy)
+    matches: List[Dict[str, Any]] = []
+    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:
+            continue
+        matches.append({
+            "id": dataset.get("id"),
+            "name": dataset.get("name"),
+            "chineseName": dataset.get("chineseName"),
+            "description": dataset.get("description"),
+            "businessDomainName": dataset.get("businessDomainName"),
+            "layer": dataset.get("layer"),
+            "schemaVersion": dataset.get("schemaVersion"),
+            "tableGranted": bool(grant.get("tableGranted")),
+        })
+    _print({"query": query, "datasets": matches})
+    return 0
+
+
+def _describe(folder: Path, dataset_id: str) -> int:
+    public, policy = _cached_docs(folder)
+    if not dataset_id.strip():
+        raise SystemExit("docs describe 需要 --dataset")
+    datasets = _index(public)
+    dataset = datasets.get(dataset_id)
+    if not dataset:
+        raise SystemExit(f"缓存中没有数据集 {dataset_id}；先执行 tdf docs search --query <关键词>")
+    grant = _index(policy).get(dataset_id, {})
+    rules = {
+        str(col.get("name")): col
+        for col in grant.get("columns") or []
+        if isinstance(col, dict) and col.get("granted") and col.get("name")
+    }
+    columns = []
+    for column in dataset.get("columns") or []:
+        if not isinstance(column, dict) or str(column.get("name")) not in rules:
+            continue
+        name = str(column["name"])
+        columns.append({
+            "name": name,
+            "type": column.get("type"),
+            "comment": column.get("comment"),
+            "pk": column.get("pk"),
+            "partition": column.get("partition"),
+            "partitionGrain": column.get("partitionGrain"),
+            "partitionRequired": column.get("partitionRequired"),
+            "outputRule": rules[name].get("outputRule"),
+        })
+    _print({
+        "id": dataset.get("id"),
+        "name": dataset.get("name"),
+        "chineseName": dataset.get("chineseName"),
+        "description": dataset.get("description"),
+        "businessDomainName": dataset.get("businessDomainName"),
+        "schemaVersion": dataset.get("schemaVersion"),
+        "primaryKey": dataset.get("primaryKey"),
+        "partitionFields": dataset.get("partitionFields"),
+        "tableGranted": bool(grant.get("tableGranted")),
+        "columns": columns,
+    })
+    return 0
+
+
 def _pull(folder: Path, base: str, ak: str, timeout: float, insecure: bool) -> int:
     local = _read_json(folder / "rev.json")
     local_etag = str(local.get("etag") or "")

{tinet_data_foundry_cli-0.1.5 → tinet_data_foundry_cli-0.1.6}/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.5
+Version: 0.1.6
 Summary: Tinet Data Foundry 取数 CLI（docs / catalog / query / schema）
 Author: Tinet
 License: MIT
@@ -55,7 +55,7 @@ tdf query \
 | `ends_with` | 左模糊，匹配后缀 | `{"op":"ends_with","field":"name","value":"公司"}` |
 | `contains` | 左右模糊 | `{"op":"contains","field":"name","value":"科技"}` |
 
-分区表可以不传分区字段。服务端按上海时区补默认闭区间：按日为当天，按月为当月，按年为当年，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 时，按日不超过 30 天，按月不超过 12 个月，按年不超过 3 年，否则 422 `PARTITION_RANGE_INVALID`。
+仅按日分区表必须带分区条件。未传分区字段时，服务端按上海时区补当天闭区间，并在响应 `data.partitionWindow` 里返回实际 `field/from/to`。显式 `between` 不超过 30 天，否则 422 `PARTITION_RANGE_INVALID`。按月、按年分区字段不是必填条件。
 
 若 pip 提示 scripts 目录不在 PATH，把该目录加入 PATH，或用 `python3 -m tinet_data_foundry_cli`。
 
@@ -92,6 +92,17 @@ tdf catalog --insecure
 
 文档站点默认 `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 查询大目录
+
+`tdf docs pull` 把公共目录与授权策略缓存到本机。Skill / Agent 不应直接把大 `public.json` 读进上下文，而是通过以下命令只取需要的精简结果：
+
+```bash
+tdf docs search --query "京东云消费"
+tdf docs describe --dataset "DATASET_ID"
+```
+
+`search` 默认只返回有表权限的数据集；`describe` 只返回该表已授权字段及其脱敏规则。首次使用先执行 `tdf docs pull`。
+
 Agent / Skill 传查询体用文件，避免 shell 转义：
 
 ```bash

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

@@ -17,8 +17,11 @@ class CliParserTest(unittest.TestCase):
         self.assertIn("starts_with", help_text)
         self.assertIn("ends_with", help_text)
         self.assertIn("contains", help_text)
+        self.assertIn("仅按日分区必填", help_text)
         self.assertIn("30", help_text)
         self.assertIn("当天", help_text)
+        self.assertIn("按月、按年分区字段不是必填条件", help_text)
+        self.assertNotIn("按月补当月", help_text)
 
     def test_subcommands(self):
         parser = build_parser()

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

@@ -1,13 +1,37 @@
 import json
 import tempfile
 import unittest
+from io import StringIO
 from pathlib import Path
 from unittest.mock import patch
 
-from tinet_data_foundry_cli.docs import summarize
+from tinet_data_foundry_cli.docs import _describe, _search, summarize
 
 
 class DocsSummaryTest(unittest.TestCase):
+    def test_search_and_describe_only_print_authorized_dataset_content(self):
+        with tempfile.TemporaryDirectory() as tmp, patch("sys.stdout", new_callable=StringIO) as out:
+            folder = Path(tmp)
+            (folder / "public.json").write_text(json.dumps({"datasets": [{
+                "id": "ds_bill", "name": "monthly_bill", "chineseName": "月账单",
+                "description": "京东云消费", "columns": [
+                    {"name": "amount", "type": "decimal", "comment": "金额"},
+                    {"name": "secret", "type": "text", "comment": "无权限"},
+                ],
+            }]}), encoding="utf-8")
+            (folder / "policy.json").write_text(json.dumps({"datasets": [{
+                "id": "ds_bill", "tableGranted": True,
+                "columns": [{"name": "amount", "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")
+            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"])
+
     def test_summarize_catalog_and_policy(self):
         old_public = {"datasets": [{"id": "a", "schemaVersion": "1"}, {"id": "b", "schemaVersion": "1"}]}
         new_public = {"datasets": [{"id": "b", "schemaVersion": "2"}, {"id": "c", "schemaVersion": "1"}]}

tinet_data_foundry_cli-0.1.5/src/tinet_data_foundry_cli/__init__.py

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