tytcli 0.2.0__py3-none-any.whl

tytcli/commands/sentiment.py

@@ -0,0 +1,200 @@
+"""``tytcli sentiment`` —— 机构交易情绪指数日报（sentimentIndex 模块）。
+
+``/middleApi/sentimentIndex`` 根下的两个只读命令：
+
+* ``dates`` —— 哪些天有日报
+* ``image`` —— 把某一天的日报下载成 PNG
+
+``image`` 是本 CLI 里第一个 payload 为**二进制**的命令：该端点返回的是
+``image/png``（约 4.3 MiB）而不是 JSON 信封，所以字节落盘，stdout 只报告文件的
+路径与摘要——这样"恰好一个 JSON 文档"的契约得以保住，而不必把图片本身塞进去。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+
+import click
+
+from ..client import (
+    IMAGE_MAGICS,
+    SENTIMENT_DATE_FORMAT,
+    TytClient,
+)
+from ..errors import ApiError, UsageError
+from ..output import emit_ok
+from .shared import raise_for_envelope, require_config
+
+#: ``reportDate`` 必须是 ``yyyy-MM-dd``。在客户端就校验，因为服务端对不可用的
+#: 日期回答的是 ``-101 服务器繁忙``——这句报文会把调用方引向"服务端出故障了"，
+#: 而真正的原因只是打错了一个日期。
+DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+#: 下载日报的默认文件名。这个命名空间归本工具所有，所以覆盖风险只限于它自己
+#: 写出来的文件。
+DEFAULT_IMAGE_NAME = "tytcli-sentiment-{date}{ext}"
+
+
+def _validate_date(raw: str) -> str:
+    """``raw`` 是真实的 ``yyyy-MM-dd`` 日期就原样返回，否则抛用法错误。"""
+    if not DATE_PATTERN.match(raw):
+        raise UsageError(
+            f"--date 必须是 yyyy-MM-dd 格式（当前 {raw!r}）。",
+            code="USAGE_DATE_INVALID",
+            details={"date": raw, "expected_format": "yyyy-MM-dd"},
+        )
+    try:
+        datetime.strptime(raw, SENTIMENT_DATE_FORMAT)
+    except ValueError as exc:
+        raise UsageError(
+            f"--date 不是真实存在的日期（当前 {raw!r}）。",
+            code="USAGE_DATE_INVALID",
+            details={"date": raw, "reason": str(exc)},
+        ) from exc
+    return raw
+
+
+def _detect_image_format(content: bytes) -> tuple[str, str] | None:
+    """把魔数映射成 ``(格式, 扩展名)``；不是图片则返回 ``None``。"""
+    for magic, name, ext in IMAGE_MAGICS:
+        if content.startswith(magic):
+            return name, ext
+    return None
+
+
+@click.group()
+def sentiment() -> None:
+    """机构交易情绪指数日报。
+
+    \b
+    注意：与公众号模块一样，该模块可能未在所有环境部署。
+    若命令返回 HTTP 404，错误的 details.hint 会说明原因。
+    """
+
+
+@sentiment.command("dates")
+@click.pass_context
+def sentiment_dates(ctx: click.Context) -> None:
+    """列出有日报的日期。
+
+    \b
+    输出 ``data`` 是日期字符串列表（yyyy-MM-dd，新→旧）。
+    拿到日期后取图：
+      tytcli sentiment image --date <YYYY-MM-DD>
+    """
+    pretty: bool = ctx.obj["pretty"]
+
+    config = require_config()
+    client = TytClient(
+        config.base_url,
+        config.require_token(),
+        middle_base_url=config.middle_base_url,
+        timeout=config.timeout_seconds,
+    )
+    envelope = client.sentiment_daily_report_dates()
+    raise_for_envelope(
+        envelope, env_name=config.active_env, base_url=config.middle_base_url
+    )
+
+    dates_raw = envelope.payload.get("Data")
+    # isinstance() 会把 Any 窄化成 list[Unknown]；紧跟一次 cast，len() 才有类型。
+    dates: list[Any] | None = (
+        cast("list[Any]", dates_raw) if isinstance(dates_raw, list) else None
+    )
+    emit_ok(
+        dates_raw,
+        pretty=pretty,
+        env=config.active_env,
+        base_url=config.middle_base_url,
+        api_root="middleApi",
+        http_status=envelope.http_status,
+        count=len(dates) if dates is not None else None,
+    )
+
+
+@sentiment.command("image")
+@click.option(
+    "--date",
+    "report_date",
+    required=True,
+    metavar="YYYY-MM-DD",
+    help="日报日期。可用 `tytcli sentiment dates` 查看有哪些天。",
+)
+@click.option(
+    "--output",
+    "output_option",
+    default=None,
+    type=click.Path(dir_okay=False, path_type=Path),
+    metavar="PATH",
+    help=f"图片保存路径。默认当前目录下 {DEFAULT_IMAGE_NAME.format(date='<日期>', ext='.<格式>')}。",
+)
+@click.pass_context
+def sentiment_image(
+    ctx: click.Context, report_date: str, output_option: Path | None
+) -> None:
+    """下载某一天的日报图片。
+
+    \b
+    图片写入文件，stdout 只输出元数据：path / bytes / format / sha256。
+    图片约 4 MiB，首次下载需要几秒。
+    """
+    pretty: bool = ctx.obj["pretty"]
+    report_date = _validate_date(report_date)
+
+    config = require_config()
+    client = TytClient(
+        config.base_url,
+        config.require_token(),
+        middle_base_url=config.middle_base_url,
+        timeout=config.timeout_seconds,
+    )
+    binary = client.sentiment_daily_report_image(report_date)
+
+    detected = _detect_image_format(binary.content)
+    if detected is None:
+        # content-type 说是图片，但字节并不是我们认得的任何一种。
+        # 把它存成 .png 扩展名，等于产出一个会撒谎的文件。
+        raise ApiError(
+            "服务端返回的内容不是可识别的图片格式。",
+            code="UNEXPECTED_SHAPE",
+            details={
+                "url": binary.url,
+                "http_status": binary.http_status,
+                "content_type": binary.content_type,
+                "bytes": len(binary.content),
+                "leading_bytes": binary.content[:16].hex(),
+            },
+        )
+    image_format, extension = detected
+
+    if output_option is not None:
+        path = output_option.expanduser()
+    else:
+        path = Path.cwd() / DEFAULT_IMAGE_NAME.format(date=report_date, ext=extension)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    overwritten = path.exists()
+    path.write_bytes(binary.content)
+
+    emit_ok(
+        {
+            "report_date": report_date,
+            "path": str(path),
+            "bytes": len(binary.content),
+            "format": image_format,
+            "sha256": hashlib.sha256(binary.content).hexdigest(),
+            "content_type": binary.content_type,
+            "overwritten": overwritten,
+        },
+        pretty=pretty,
+        env=config.active_env,
+        base_url=config.middle_base_url,
+        api_root="middleApi",
+        http_status=binary.http_status,
+    )
+
+
+__all__: list[str] = ["sentiment"]

tytcli/commands/shared.py

@@ -0,0 +1,210 @@
+"""每个命令模块都需要的那些辅助函数。
+
+``require_config`` / ``raise_for_envelope`` / ``effective_config_payload`` 曾经是
+``cli.py`` 里的私有函数。现在它们跨模块被 import，所以改成公开的——再加个前导
+下划线只会误导人。
+
+列表裁剪那一半是后来加进来的：``commands/roadshow.py`` 需要同一套机制，于是从
+``commands/wechat.py`` 里提取出来。现在有三个列表端点共用它，而**共用正是目的**：
+裁剪契约（``trimmed`` / ``record_fields`` / ``unknown_fields`` /
+``available_fields`` / ``__tytcli_hint__``）是已发布输出形状的一部分，所以第二份
+实现就意味着第二件要保持诚实的东西。
+
+本模块不能变成命令模块：``tests/test_architecture.py`` 要求 ``commands/`` 下除
+``__init__.py`` 与 ``shared.py`` 之外的每个模块都必须贡献一个已注册命令。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+from ..client import ApiEnvelope, TytClient, error_for_envelope
+from ..config import ResolvedConfig, load_config, visible_envs
+from ..errors import UsageError
+
+
+def require_config(allow_missing_token: bool = False) -> ResolvedConfig:
+    """加载配置，并把配置类错误以 TytCliError 的形式抛出。"""
+    cfg = load_config()
+    if not allow_missing_token and cfg.token is None:
+        cfg.require_token()
+    return cfg
+
+
+def effective_config_payload(cfg: ResolvedConfig) -> dict[str, Any]:
+    """"当前实际生效的配置"摘要，Token 已脱敏。
+
+    一个构造器，两个入口：公开的 ``config show`` 与面向开发者（隐藏）的
+    ``env show``。共用才是重点——两者绝不能漂移，而且脱敏逻辑的 bug 修一处
+    就等于修了两处。
+
+    ``known_envs`` 走 ``visible_envs()``，所以那个开发环境只会被说给**已经
+    自己选中了它**的人听。
+    """
+    return {
+        "active_env": cfg.active_env,
+        "env_source": cfg.env_source,
+        "base_url": cfg.base_url,
+        "base_url_source": "code",  # 固定在 config.BASE_URLS 里，不可覆盖
+        "token_configured": cfg.token is not None,
+        "token_source": cfg.token_source,
+        "token_hint": cfg.masked_token(),
+        "timeout_seconds": cfg.timeout_seconds,
+        "config_path": str(cfg.path),
+        "config_path_source": cfg.path_source,
+        "config_exists": cfg.path_exists,
+        "known_envs": list(visible_envs(cfg.active_env)),
+    }
+
+
+def raise_for_envelope(envelope: ApiEnvelope, *, env_name: str, base_url: str) -> None:
+    """当解析出来的信封不是成功时抛错。
+
+    这是 :func:`tytcli.client.error_for_envelope` 的一层薄包装：信封到错误的映射
+    属于协议知识，所以住在协议层；而这一层让命令模块里的调用点保持一行、显而易见。
+    """
+    error = error_for_envelope(envelope, env_name=env_name, base_url=base_url)
+    if error is not None:
+        raise error
+
+
+# --------------------------------------------------------------------------- #
+# middle API 客户端
+# --------------------------------------------------------------------------- #
+
+
+def middle_client(config: ResolvedConfig) -> TytClient:
+    """一个能同时访问两个 API 根（核心根与 ``/middleApi``）的客户端。"""
+    return TytClient(
+        config.base_url,
+        config.require_token(),
+        middle_base_url=config.middle_base_url,
+        timeout=config.timeout_seconds,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# 列表裁剪
+# --------------------------------------------------------------------------- #
+
+
+def unwrap_data(payload: dict[str, Any]) -> Any:
+    """返回信封的 ``Data`` 成员。
+
+    与 ``whoami`` 不同（它的 ``data`` 是整个原样信封），基于本辅助函数构建的命令
+    会拆开 ``Data``：信封的 ``Success`` / ``ErrorCode`` / ``Error`` 已经由 ``ok``
+    和错误文档表达过了，而对 agent 来说，``data`` 在 ``--fields`` / ``--full`` 下
+    保持**稳定形状**比逐字节重放信封更有用。``--full`` 仍然返回服务端发来的每一个
+    *记录*字段。
+    """
+    return payload.get("Data")
+
+
+def observed_fields(records: Sequence[Any]) -> list[str]:
+    """所有记录键的并集，按首次出现的顺序。
+
+    从响应里动态取，而不是写死，这样后端加字段时提示仍然是真的——它已经加过两次了。
+    而且字段存在性在**同一次响应的不同行之间**也会变：2026-11-07 探测路演列表时，
+    有些行没有 ``duration`` / ``meetingPwd`` / ``summary``，另一些行有。所以写死的
+    字段表会逐行出错。
+    """
+    seen: list[str] = []
+    for record in records:
+        if isinstance(record, dict):
+            # isinstance() 会把 Any 窄化成 dict[Unknown, Unknown]；紧跟一次 cast，
+            # 让键的类型确定为 str（这正是 AGENTS.md 为这些 API 返回的任意
+            # camelCase JSON 规定的写法）。
+            mapping = cast("dict[str, Any]", record)
+            for key in mapping:
+                if key not in seen:
+                    seen.append(key)
+    return seen
+
+
+def select_fields(record: dict[str, Any], keys: Sequence[str]) -> dict[str, Any]:
+    """把一条记录投影到 ``keys`` 上，本记录没有的键直接跳过。
+
+    跳过而不是补成 ``null``：服务端本来就省略空值，凭空造出来只会增加字节数，
+    还会暗示"这个字段存在，只是值为 null"。
+    """
+    return {key: record[key] for key in keys if key in record}
+
+
+def parse_fields_option(raw: str) -> list[str]:
+    """拆分 ``--fields a,b,c``，保留调用方给的顺序并去重。"""
+    keys = [part.strip() for part in raw.split(",")]
+    keys = [key for key in keys if key]
+    if not keys:
+        raise UsageError(
+            "--fields 不能为空。请给出逗号分隔的字段名，如 --fields title,appId。",
+            code="USAGE_FIELDS_EMPTY",
+        )
+    unique: list[str] = []
+    for key in keys:
+        if key not in unique:
+            unique.append(key)
+    return unique
+
+
+@dataclass(frozen=True)
+class TrimmedPage:
+    """一页数据（裁剪或未裁剪），外加那些让裁剪"不静默"的 meta 键。"""
+
+    #: 放进 ``data`` 的内容
+    payload: Any
+    #: ``trimmed`` 及其同伴；由调用方合并进自己的 meta
+    meta: dict[str, Any]
+    #: ``__tytcli_hint__`` 的值；调用方用了 --fields 时为 None
+    hint: str | None
+
+
+def trim_page(
+    *,
+    inner_raw: Any,
+    list_key: str,
+    default_fields: Sequence[str],
+    selected: list[str] | None,
+    full: bool,
+    make_hint: Callable[[Sequence[str], list[str]], str] | None = None,
+) -> TrimmedPage:
+    """把本项目的列表裁剪契约应用到一个分页响应上。
+
+    **绝不静默丢字段**：结果里带着 ``trimmed``、``record_fields``，以及（当请求了
+    本次响应里没有的字段时）``unknown_fields`` + ``available_fields``。``--full``、
+    空页、以及形状不符合预期的情况都原样透传 ``Data``——空页没有字段可裁，往它上面
+    加键只是噪音。
+    """
+    inner_map: dict[str, Any] | None = (
+        cast("dict[str, Any]", inner_raw) if isinstance(inner_raw, dict) else None
+    )
+    records_raw = inner_map.get(list_key) if inner_map is not None else None
+    records: list[Any] = (
+        cast("list[Any]", records_raw) if isinstance(records_raw, list) else []
+    )
+    observed = observed_fields(records)
+
+    if full or not records or inner_map is None:
+        meta: dict[str, Any] = {"trimmed": False}
+        if full and observed:
+            meta["record_fields"] = observed
+        return TrimmedPage(payload=inner_raw, meta=meta, hint=None)
+
+    keys: list[str] = list(selected) if selected is not None else list(default_fields)
+    trimmed = [
+        select_fields(cast("dict[str, Any]", record), keys)
+        if isinstance(record, dict)
+        else record
+        for record in records
+    ]
+    meta = {"trimmed": True, "record_fields": keys}
+    if observed:
+        unknown = [key for key in keys if key not in observed]
+        if unknown:
+            # 请求了本次响应没有携带的字段。明说出来，好过让 agent 自己纳闷
+            # 为什么每条记录里都没有这个键。
+            meta["unknown_fields"] = unknown
+            meta["available_fields"] = observed
+    hint = make_hint(default_fields, observed) if (make_hint and selected is None) else None
+    return TrimmedPage(payload={**inner_map, list_key: trimmed}, meta=meta, hint=hint)

tytcli/commands/upgrade.py

@@ -0,0 +1,95 @@
+"""``tytcli upgrade`` —— 显式地检查并升级（查的是解析出来的那个包索引）。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+# 以模块方式 import（而不是 `from ..selfupdate import plan_upgrade`），这样测试
+# monkeypatch `selfupdate.plan_upgrade` 才会生效。把名字绑定到本地命名空间会
+# **静默**让 patch 失效，于是测试真的去跑一次安装器——这个错误曾经让套件多花 29 秒
+# 才被发现。
+from .. import __version__, selfupdate
+from ..errors import ApiError
+from ..output import emit_ok
+
+
+@click.command()
+@click.option("--check", "check_only", is_flag=True, help="只检查是否有新版本，不执行升级。")
+@click.option("--force", is_flag=True, help="忽略版本比较，强制执行升级命令。")
+@click.pass_context
+def upgrade(ctx: click.Context, check_only: bool, force: bool) -> None:
+    """检查包索引中的新版本，有则升级。
+
+    \b
+    隐式检查：每条命令启动时会自动做一次（10 分钟最多一次），
+    发现新版先升级再重新执行原命令。**没有关闭开关**：产品契约是
+    始终运行最新版。本命令是显式版本，会绕过缓存直接联网，并把失败
+    如实报出来（“无法判断”不等于“无需升级”）。
+    """
+    pretty: bool = ctx.obj["pretty"]
+
+    # 与隐式钩子不同，这里的失败必须暴露出来：本命令存在的意义正是告诉用户
+    # 能不能升级。
+    latest = selfupdate.fetch_latest_version()
+    result = selfupdate.record_check(latest)
+    plan = selfupdate.plan_upgrade(index=result.index_url)
+    newer = result.is_newer_than(__version__)
+
+    info: dict[str, Any] = {
+        "current_version": __version__,
+        "latest_version": latest or None,
+        "update_available": newer,
+        "index_url": result.index_url,
+        # 是哪个旋钮选出了这个 URL（某个环境变量名，或 "default"）。没有它，
+        # "它为什么在查 pypi.org？"从输出里就无从回答。
+        "index_source": selfupdate.index_source(),
+        "install_kind": plan.kind,
+        "install_reason": plan.reason,
+        "upgrade_argv": plan.argv or None,
+    }
+
+    if not latest:
+        # 这**不是**成功：命令被问"需不需要升级"，而它答不出来。在这里报
+        # ok:true 会让任何按退出码分支的自动化拿到假阳性——而且它会与"索引不可达"
+        # 那种情形自相矛盾，后者已经是失败了。
+        raise ApiError(
+            "包索引上没有该包的任何版本，无法判断是否需要升级。",
+            code="UPDATE_NOT_PUBLISHED",
+            details={
+                **info,
+                "hint": (
+                    f"确认包已发布到 {result.index_url}。源码安装"
+                    "（uv sync / pip install -e .）本来就不在索引上，属正常情况。"
+                ),
+            },
+        )
+
+    if check_only:
+        emit_ok(info, pretty=pretty)
+        return
+
+    if not newer and not force:
+        info["upgraded"] = False
+        info["reason"] = "已是最新版本"
+        emit_ok(info, pretty=pretty)
+        return
+
+    if not plan.can_upgrade:
+        raise ApiError(
+            f"无法自动升级：{plan.reason}",
+            code="UPDATE_UNSUPPORTED",
+            details={**info, "hint": selfupdate.manual_instruction()},
+        )
+
+    output = selfupdate.run_upgrade(plan)
+    info["upgraded"] = True
+    # 本进程跑的仍是**旧**代码；新版要到下次调用才生效。自动化需要把这件事
+    # 当数据拿到，而不是当成 stderr 上的一句旁白。
+    info["restart_required"] = True
+    info["note"] = (
+        f"升级命令已执行；新版将在下次调用 tytcli 时生效（当前进程仍为 {__version__}）。"
+    )
+    info["output"] = output[-2000:]
+    emit_ok(info, pretty=pretty)