tytcli 0.2.0__py3-none-any.whl

tytcli/output.py

@@ -0,0 +1,82 @@
+"""stdout / stderr 的输出契约。
+
+每个命令都通过 :func:`emit_ok` / :func:`emit_error` 汇报结果，所以 stdout 上那一个
+JSON 文档的形状只在**一处**定义。退出码也住在这里：它们属于同一份契约，而
+``main()`` 返回的就是 ``TytCliError.exit_code`` 携带的值。
+
+从 ``cli.py`` 里拆出来，是为了让命令模块不必 import 入口就能输出结果（那会构成
+循环依赖）。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import click
+
+from .errors import TytCliError
+
+EXIT_OK = 0
+EXIT_API = 1
+EXIT_USAGE = 2
+EXIT_AUTH = 3
+EXIT_NETWORK = 4
+
+
+#: 给 agent 的机器可读提示所用的顶层键。公众号列表命令用它说明"裁掉了哪些字段、
+#: 怎么取回其余的"，自更新钩子用它说明"发现了新版但本次没装成"。
+#: 用双下划线包起来，这样它不可能与服务端字段撞名。
+HINT_KEY = "__tytcli_hint__"
+
+#: 由 :mod:`tytcli.selfupdate` 在隐式钩子发现"有新版但本进程不会安装"时写入，
+#: 由本进程接下来写出的那一个文档消费。做成模块状态而不是函数参数，是因为钩子
+#: 跑在 ``main()`` 里，那时还没有任何命令知道自己将要输出东西。
+_pending_hint: str | None = None
+
+
+def set_pending_hint(text: str) -> None:
+    """把一条提示排进队列，交给本进程接下来写出的 JSON 文档。"""
+    global _pending_hint
+    _pending_hint = text
+
+
+def take_pending_hint() -> str | None:
+    """取出并清空排队中的提示。公开是为了让测试能把它排空。"""
+    global _pending_hint
+    value, _pending_hint = _pending_hint, None
+    return value
+
+
+def emit_ok(data: Any, *, pretty: bool = False, **meta: Any) -> None:
+    """向 stdout 写一个成功文档。"""
+    document: dict[str, Any] = {"ok": True}
+    document.update(meta)
+    hint = take_pending_hint()
+    if hint is not None:
+        # 命令自己可能已经在同一个键下放了提示（公众号列表就会），
+        # 所以要合并而不是覆盖。
+        existing = document.pop(HINT_KEY, None)
+        document[HINT_KEY] = f"{existing}\n{hint}" if existing else hint
+    document["data"] = data
+    _write(document, pretty)
+
+
+def emit_error(exc: TytCliError, *, pretty: bool = False) -> None:
+    """向 stdout 写一个失败文档。"""
+    document: dict[str, Any] = {"ok": False, "error": exc.to_dict()}
+    hint = take_pending_hint()
+    if hint is not None:
+        document[HINT_KEY] = hint
+    _write(document, pretty)
+
+
+def _write(document: dict[str, Any], pretty: bool) -> None:
+    text = json.dumps(
+        document,
+        ensure_ascii=False,
+        indent=2 if pretty else None,
+        separators=None if pretty else (",", ":"),
+        sort_keys=False,
+    )
+    click.echo(text)