tytcli 0.2.0__py3-none-any.whl

tytcli/__init__.py

@@ -0,0 +1,7 @@
+"""tytcli — 投研通 (TYT) API CLI designed for agent + skill driven use."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

tytcli/cli.py

@@ -0,0 +1,174 @@
+"""tytcli 的命令行入口。
+
+输出契约（稳定 —— agent 要解析它）：
+
+* 结果是 **stdout** 上恰好一个 JSON 文档；**命令一律不写 stderr**（唯一两个例外
+  见 AGENTS.md：隐式自更新钩子的警告，以及裸调 ``tytcli`` 时被路由到 stderr 的
+  help 文本）。同一个事实只允许一个通道，否则两份副本会逐渐不一致，而自动化会
+  分不清哪份是结果。
+* 成功：``{"ok": true, "env": ..., "base_url": ..., "data": {...}}``
+* 失败：``{"ok": false, "error": {"code": ..., "message": ..., "details": {...}}}``
+* 退出码::
+
+      0  成功
+      1  API / 业务错误（服务端有响应，但请求失败）
+      2  用法或配置错误
+      3  认证错误（TYT_Token 缺失、无效或已过期）
+      4  网络错误或超时
+
+命令绝不交互式提问；缺值就是一个错误。
+
+
+命令实现住在 ``tytcli/commands/`` 里——一个命令组一个模块。本模块只保留入口该拥有
+的东西：根 group、全局的"异常 -> JSON"翻译，以及 ``main()`` / ``entrypoint()``。
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+# 以模块方式 import（而不是 `from .selfupdate import plan_upgrade`），这样测试
+# monkeypatch `selfupdate.plan_upgrade` 才会生效。把名字绑定到本地命名空间会
+# **静默**让 patch 失效，于是测试真的去跑一次安装器。
+from . import __version__, selfupdate, skill
+from .commands import ALL_COMMANDS
+from .config import ENV_VAR_CONFIG, ENV_VAR_ENV, ENV_VAR_TOKEN
+from .errors import TytCliError, UsageError
+from .output import (
+    EXIT_API,
+    EXIT_AUTH,
+    EXIT_NETWORK,
+    EXIT_OK,
+    EXIT_USAGE,
+    emit_error,
+)
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    epilog=(
+        "\b\n环境变量覆盖：\n"
+        f"  {ENV_VAR_CONFIG}    配置文件路径\n"
+        f"  {ENV_VAR_ENV}       当前环境\n"
+        f"  {ENV_VAR_TOKEN}     当前环境的 TYT_Token\n"
+        "\b\n退出码：0 成功 / 1 API 错误 / 2 用法或配置错误 / 3 认证失败 / 4 网络错误"
+    ),
+)
+@click.version_option(__version__, prog_name="tytcli", message="%(prog)s %(version)s")
+@click.option("--pretty", is_flag=True, help="缩进输出 JSON（默认紧凑单行）。")
+@click.pass_context
+def cli(ctx: click.Context, pretty: bool) -> None:
+    """tytcli — 投研通 API 命令行工具。"""
+    ctx.ensure_object(dict)
+    ctx.obj["pretty"] = pretty
+
+
+# 注册是显式的，而不是靠装饰器：import 一个命令模块不应该要求 import 本模块，
+# 否则就是循环依赖。
+for _command in ALL_COMMANDS:
+    cli.add_command(_command)
+
+
+def _append_doc_pointer(command: click.Command, topic: str) -> None:
+    """递归地往一个命令的 ``--help`` epilog 末尾加一行指针。
+
+    全文由 ``tytcli help`` 承载（见 commands/help.py）；``--help`` 只负责指路。
+    把指针压到一行，既保住了 ``--help`` 的本分——快而可扫的用法摘要——又让随包
+    的 skill 文档能从大家最先看的地方被发现。
+    """
+    line = skill.pointer_line(topic)
+    command.epilog = (command.epilog or "").rstrip() + "\n\n" + line
+    if isinstance(command, click.Group):
+        for sub in command.commands.values():
+            # 子命令继承所属 group 的主题：参考文档覆盖的是整个模块，
+            # 不是每个子命令各一份。
+            _append_doc_pointer(sub, topic)
+
+
+for _command in ALL_COMMANDS:
+    _append_doc_pointer(_command, _command.name or "")
+# 根 group 单独设置指针：从它往下递归会给每个顶层命令**再**追加一次，而它们
+# 已经各自带了一行（变成双指针）。
+cli.epilog = (cli.epilog or "").rstrip() + "\n\n" + skill.pointer_line("")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """运行 CLI，并且总是把失败翻译成一个 JSON 错误文档。"""
+    args = list(sys.argv[1:] if argv is None else argv)
+    pretty = "--pretty" in args
+
+    # 隐式自更新：查一次包索引（每 10 分钟最多一次），发现新版就升级，然后
+    # re-exec，让用户的命令跑在新代码上。**刻意 fail open**——索引不可达绝不能
+    # 成为业务命令失败的原因。
+    selfupdate.maybe_self_update(__version__, args)
+
+    try:
+        cli.main(args=args, prog_name="tytcli", standalone_mode=False)
+    except TytCliError as exc:
+        emit_error(exc, pretty=pretty)
+        return exc.exit_code
+    except click.exceptions.UsageError as exc:
+        details: dict[str, Any] = {}
+        ctx = getattr(exc, "ctx", None)
+        command = getattr(ctx, "command", None)
+        message = exc.format_message()
+
+        if ctx is not None:
+            details["command"] = ctx.command_path
+
+        # 裸调 `tytcli` 时，click 会把整份 help 文本塞进 UsageError 的 message。
+        # 为了保住 stdout 的机器可读性，把面向人的 help 送到 stderr——那才是
+        # 诊断信息该待的地方。
+        if message.startswith("Usage:"):
+            click.echo(message, err=True)
+            message = "缺少子命令。"
+
+        if isinstance(command, click.Group):
+            names = sorted(command.commands)
+            details["available_commands"] = names
+            details["hint"] = f"可用子命令：{', '.join(names)}"
+        else:
+            details["hint"] = f"运行 {(ctx.command_path if ctx else 'tytcli')} --help 查看用法。"
+
+        emit_error(UsageError(message, details=details), pretty=pretty)
+        return EXIT_USAGE
+    except click.exceptions.Abort:
+        emit_error(TytCliError("操作已取消。", code="ABORTED"), pretty=pretty)
+        return 130
+    except click.exceptions.Exit as exc:
+        return int(exc.exit_code or 0)
+    except Exception as exc:  # 最后一道防线：保证输出仍然是机器可读的
+        emit_error(
+            TytCliError(
+                f"未预期的内部错误：{type(exc).__name__}: {exc}",
+                code="INTERNAL_ERROR",
+                details={"error_type": type(exc).__name__},
+            ),
+            pretty=pretty,
+        )
+        return EXIT_API
+    return EXIT_OK
+
+
+def entrypoint() -> None:
+    """console script 的包装。"""
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    entrypoint()
+
+
+__all__ = [
+    "EXIT_API",
+    "EXIT_AUTH",
+    "EXIT_NETWORK",
+    "EXIT_OK",
+    "EXIT_USAGE",
+    "cli",
+    "entrypoint",
+    "main",
+]