api-wecom-cli 0.1.0a1__py3-none-any.whl

cli/help_formatter.py

@@ -0,0 +1,217 @@
+"""Custom argparse help formatter for WeCom CLI — grouped, readable output."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+# Domains grouped by function, ordered by usage frequency.
+DOMAIN_GROUPS: dict[str, dict[str, str]] = {
+    "通讯录": {
+        "contacts": "成员、部门、标签",
+        "departments": "部门管理",
+        "users": "用户管理",
+        "tags": "标签管理",
+        "idconvert": "ID 转换",
+    },
+    "消息": {
+        "messages": "文本、卡片、文件推送",
+    },
+    "OA / 协同": {
+        "oa": "OA 数据接口",
+        "checkin": "打卡管理",
+        "meeting": "会议管理",
+        "living": "直播管理",
+        "appchat": "应用群聊管理",
+        "wedoc": "企业文档",
+        "wedrive": "企业微盘",
+    },
+    "客户 / 外部": {
+        "customers": "外部联系人管理",
+        "kf": "客服管理",
+        "externalpay": "外部支付",
+    },
+    "安全 / 审计": {
+        "security": "安全管理",
+        "msgaudit": "会话审计",
+        "chatdata": "会话内容存档",
+    },
+    "企业": {
+        "corp": "企业信息",
+        "corpgroup": "企业互联",
+        "batch": "异步任务",
+        "export": "数据导出",
+    },
+    "应用": {
+        "auth": "授权验证",
+        "miniprogram": "小程序管理",
+        "miniapppay": "小程序支付",
+        "advanced_feature": "高级功能账号管理",
+    },
+    "其他": {
+        "exmail": "企业邮箱",
+        "dial": "公费电话",
+        "pstncc": "企业专线电话",
+        "hardware": "硬件管理",
+        "health": "健康上报",
+        "hr": "人事管理",
+        "school": "家校沟通",
+        "ticket": "电子发票",
+        "network": "网络管理",
+        "unknown": "未知域",
+    },
+}
+
+# Flat lookup: domain -> description
+DOMAIN_DESCRIPTIONS: dict[str, str] = {
+    domain: desc for group in DOMAIN_GROUPS.values() for domain, desc in group.items()
+}
+
+# ANSI helpers (no-op when not a tty)
+_BOLD = "\033[1m" if sys.stderr.isatty() else ""
+_DIM = "\033[2m" if sys.stderr.isatty() else ""
+_CYAN = "\033[36m" if sys.stderr.isatty() else ""
+_RESET = "\033[0m" if sys.stderr.isatty() else ""
+
+
+def _pad(text: str, width: int) -> str:
+    return text.ljust(width)
+
+
+class WeComHelpFormatter(argparse.HelpFormatter):
+    """Produces grouped, readable help output for wecom CLI.
+
+    Stores a back-reference to the owning parser via bind().
+    When format_help is called without a bound parser (e.g. during
+    add_subparsers prog computation), falls back to default formatting.
+    """
+
+    _bound_parser: argparse.ArgumentParser | None = None
+
+    def bind(self, parser: argparse.ArgumentParser) -> None:
+        self._bound_parser = parser
+
+    def format_help(self) -> str:
+        parser = self._bound_parser
+        if parser is None:
+            return super().format_help()
+
+        # Find subparsers action
+        sp_action = None
+        for action in parser._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                sp_action = action
+                break
+
+        if sp_action is None:
+            return super().format_help()
+
+        # Root parser has prog="wecom", domain parser has prog="wecom <domain>"
+        is_root = " " not in parser.prog
+
+        if is_root:
+            return self._format_root_help(sp_action)
+
+        # Domain level — check if sub-choices have subparsers (real actions)
+        if sp_action.choices:
+            first_choice = next(iter(sp_action.choices.values()))
+            has_sub_subparsers = any(isinstance(a, argparse._SubParsersAction) for a in first_choice._actions)
+            if has_sub_subparsers:
+                # This is a domain parser whose sub-choices are action parsers with their own subparsers
+                # Shouldn't happen normally but handle gracefully
+                return self._format_domain_help(sp_action)
+            return self._format_domain_help(sp_action)
+
+        return super().format_help()
+
+    def _format_root_help(self, sp_action: argparse._SubParsersAction) -> str:
+        lines: list[str] = []
+
+        lines.append(f"{_BOLD}Usage:{_RESET}  wecom {_DIM}[options]{_RESET} <domain> <action> [action-flags]")
+        lines.append("")
+        lines.append("企业微信命令行工具 — 通过命令行调用企业微信 API")
+        lines.append("")
+
+        lines.append(f"{_CYAN}{_BOLD}常用命令:{_RESET}")
+        lines.append("  wecom contacts list --department-id 1     查看部门成员")
+        lines.append("  wecom departments list                    查看部门列表")
+        lines.append("  wecom messages send-text --to-user ...    发送文本消息")
+        lines.append("")
+
+        max_name_len = max(len(d) for d in DOMAIN_DESCRIPTIONS)
+        for group_name, domains in DOMAIN_GROUPS.items():
+            lines.append(f"{_CYAN}{_BOLD}{group_name}:{_RESET}")
+            for domain, desc in domains.items():
+                lines.append(f"  {_pad(domain, max_name_len)}  {desc}")
+            lines.append("")
+
+        lines.append(f"用 {_CYAN}wecom <domain> --help{_RESET} 查看域内命令")
+        lines.append("")
+        lines.append(f"{_CYAN}{_BOLD}Options:{_RESET}")
+        lines.append("  -h, --help     显示帮助")
+        lines.append("  --verbose      打印请求 URL 到 stderr")
+        lines.append("  --debug        打印完整请求/响应 JSON 到 stderr")
+        lines.append("")
+
+        return "\n".join(lines)
+
+    def _format_domain_help(self, sp_action: argparse._SubParsersAction) -> str:
+        lines: list[str] = []
+        prog = self._prog
+        domain = prog.split()[-1] if " " in prog else prog
+
+        domain_desc = DOMAIN_DESCRIPTIONS.get(domain, "")
+        desc_suffix = f" — {domain_desc}" if domain_desc else ""
+
+        lines.append(f"{_BOLD}Usage:{_RESET}  wecom {_DIM}[options]{_RESET} {domain} <action> [action-flags]")
+        lines.append("")
+        lines.append(f"{domain}{desc_suffix}")
+        lines.append("")
+
+        lines.append(f"{_CYAN}{_BOLD}命令:{_RESET}")
+        # Get help text from _SubParsersAction._choices_actions, not from sub-parser internals
+        choices_help: dict[str, str] = {}
+        for choice_act in sp_action._choices_actions:
+            choices_help[choice_act.dest] = choice_act.help or ""
+
+        actions: list[tuple[str, str]] = []
+        for name in sp_action.choices:
+            actions.append((name, choices_help.get(name, "")))
+
+        if actions:
+            max_name_len = max(len(a[0]) for a in actions)
+            for name, help_text in actions:
+                lines.append(f"  {_pad(name, max_name_len)}  {help_text}")
+
+        lines.append("")
+        lines.append(f"用 {_CYAN}wecom {domain} <action> --help{_RESET} 查看参数详情")
+        lines.append("")
+
+        return "\n".join(lines)
+
+
+def install_formatter(parser: argparse.ArgumentParser) -> None:
+    """Attach WeComHelpFormatter to parser and all sub-parsers."""
+    parser.formatter_class = WeComHelpFormatter  # type: ignore[assignment]
+
+    def _make_fmt(p: argparse.ArgumentParser = parser) -> WeComHelpFormatter:
+        fmt = WeComHelpFormatter(p.prog)
+        fmt.bind(p)
+        return fmt
+
+    parser._get_formatter = _make_fmt  # type: ignore[assignment]
+
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for sub_parser in action.choices.values():
+                sub_parser.formatter_class = WeComHelpFormatter  # type: ignore[assignment]
+                _install_sub(sub_parser)
+
+
+def _install_sub(parser: argparse.ArgumentParser) -> None:
+    def _make_fmt(p: argparse.ArgumentParser = parser) -> WeComHelpFormatter:
+        fmt = WeComHelpFormatter(p.prog)
+        fmt.bind(p)
+        return fmt
+
+    parser._get_formatter = _make_fmt  # type: ignore[assignment]

cli/main.py

@@ -0,0 +1,145 @@
+"""Command-line interface for WeCom CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from apis.generated_client import GeneratedWeComClient
+from cli.generated_commands import CommandHandler, register_generated_commands
+from cli.help_formatter import DOMAIN_DESCRIPTIONS, WeComHelpFormatter, install_formatter
+from core.auth import AccessTokenProvider
+from core.config import WeComConfig
+from core.errors import WeComCLIError
+from core.requester import UnifiedRequester
+
+
+def register_domain_help(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    for name, desc in DOMAIN_DESCRIPTIONS.items():
+        subparsers.add_parser(name, help=desc, formatter_class=WeComHelpFormatter)
+
+
+class _HelpOnlyClient:
+    """Stub client for --help mode. Handler closures capture this but are never called."""
+
+    def __getattr__(self, _name: str) -> object:
+        raise RuntimeError("Help-only client method called unexpectedly")
+
+
+def bootstrap(*, verbose: bool = False, debug: bool = False) -> GeneratedWeComClient:
+    config = WeComConfig.load()
+    requester = UnifiedRequester(config)
+    requester.set_verbose(verbose, debug)
+    token_provider = AccessTokenProvider(requester, config)
+    requester.bind_token_provider(token_provider)
+    return GeneratedWeComClient(requester)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wecom",
+        formatter_class=WeComHelpFormatter,
+        add_help=False,
+        description="企业微信命令行工具 — 通过命令行调用企业微信API",
+    )
+    # Bind formatter immediately so add_subparsers() doesn't crash
+    parser._get_formatter = lambda: WeComHelpFormatter(parser.prog)  # type: ignore[assignment]
+    parser.add_argument(
+        "-h",
+        "--help",
+        action="store_true",
+        default=False,
+        dest="wecom_help",
+    )
+    parser.add_argument(
+        "--verbose", action="store_true", default=bool(os.getenv("WECOM_VERBOSE")), help="Print request URLs to stderr"
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=bool(os.getenv("WECOM_DEBUG")),
+        help="Print full request/response JSON to stderr",
+    )
+    return parser
+
+
+def route(args: argparse.Namespace, command_table: dict[tuple[str, str], CommandHandler]) -> dict:
+    action = str(getattr(args, "__action", None) or getattr(args, "action", ""))
+    key = (args.domain, action)
+    if key not in command_table:
+        raise WeComCLIError(f"Unknown command: {args.domain} {action}")
+    return command_table[key](args)
+
+
+def main(argv: list[str] | None = None) -> int:
+    effective_argv = argv if argv is not None else sys.argv[1:]
+    parser = build_parser()
+
+    # No args → root help with domain list
+    if not effective_argv:
+        subparsers = parser.add_subparsers(dest="domain")
+        register_domain_help(subparsers)
+        install_formatter(parser)
+        parser.print_help()
+        return 0
+
+    has_help = "-h" in effective_argv or "--help" in effective_argv
+
+    if has_help:
+        positional = [a for a in effective_argv if not a.startswith("-")]
+        subparsers = parser.add_subparsers(dest="domain")
+        if not positional:
+            # Root help → lightweight domain list only
+            register_domain_help(subparsers)
+        else:
+            # Domain/action help → full registration with stub client
+            register_generated_commands(subparsers, _HelpOnlyClient())  # type: ignore[arg-type]
+        install_formatter(parser)
+        parser.parse_args(effective_argv)
+        # print_help was triggered by our custom flag or argparse
+        # For domain-level, the sub-parser's format_help handles it
+        # For root level, we need to explicitly print
+        if not positional:
+            parser.print_help()
+        else:
+            # argparse handles sub-parser help via SystemExit
+            try:
+                parser.parse_args(effective_argv)
+            except SystemExit:
+                pass
+        return 0
+
+    # Normal execution path
+    args, _ = parser.parse_known_args(effective_argv)
+    remaining = [a for a in effective_argv if a not in {"--verbose", "--debug"}]
+    if not remaining:
+        subparsers = parser.add_subparsers(dest="domain")
+        register_domain_help(subparsers)
+        install_formatter(parser)
+        parser.print_help()
+        return 0
+
+    try:
+        client = bootstrap(verbose=args.verbose, debug=args.debug)
+        subparsers = parser.add_subparsers(dest="domain", required=True)
+        command_table = register_generated_commands(subparsers, client)
+        install_formatter(parser)
+        args = parser.parse_args(effective_argv)
+        payload = route(args, command_table)
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 0
+    except WeComCLIError as exc:
+        print(f"[wecom-cli] {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"[wecom-cli] Unexpected error: {exc}", file=sys.stderr)
+        print("[wecom-cli] Re-run with --debug for details.", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

core/__init__.py

@@ -0,0 +1,7 @@
+"""Core infrastructure for WeCom CLI."""
+
+from core.auth import AccessTokenProvider
+from core.config import WeComConfig
+from core.requester import UnifiedRequester
+
+__all__ = ["AccessTokenProvider", "UnifiedRequester", "WeComConfig"]

core/auth.py

@@ -0,0 +1,45 @@
+"""WeCom access token acquisition and caching."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from core.config import WeComConfig
+from core.errors import APIRequestError, APIResponseError, AuthError
+from core.requester import UnifiedRequester
+
+
+@dataclass
+class TokenBundle:
+    access_token: str
+    expires_at_epoch: float
+
+
+class AccessTokenProvider:
+    def __init__(self, requester: UnifiedRequester, config: WeComConfig) -> None:
+        self._requester = requester
+        self._config = config
+        self._bundle: TokenBundle | None = None
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        if not force_refresh and self._bundle and self._bundle.expires_at_epoch > time.time() + 30:
+            return self._bundle.access_token
+
+        try:
+            payload = self._requester.request(
+                method="GET",
+                endpoint="/cgi-bin/gettoken",
+                query={"corpid": self._config.corp_id, "corpsecret": self._config.corp_secret},
+                require_auth=False,
+            )
+        except (APIRequestError, APIResponseError) as exc:
+            raise AuthError(str(exc)) from exc
+
+        token = str(payload.get("access_token") or "")
+        expires_in = int(payload.get("expires_in") or 0)
+        if not token or expires_in <= 0:
+            raise AuthError("Token response missing access_token/expires_in")
+
+        self._bundle = TokenBundle(access_token=token, expires_at_epoch=time.time() + expires_in)
+        return token

core/config.py

@@ -0,0 +1,53 @@
+"""Configuration loading for WeCom CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from core.errors import ConfigError
+
+DEFAULT_CONFIG_PATH = Path.home() / ".wecom-cli" / "config.json"
+
+
+@dataclass(frozen=True)
+class WeComConfig:
+    corp_id: str
+    corp_secret: str
+    base_url: str = "https://qyapi.weixin.qq.com"
+    timeout_seconds: float = 10.0
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> WeComConfig:
+        path = config_path or DEFAULT_CONFIG_PATH
+        raw_data: dict[str, object] = {}
+
+        if path.exists():
+            try:
+                raw_data = json.loads(path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ConfigError(f"Failed to read config from {path}: {exc}") from exc
+
+        corp_id = str(os.getenv("WECOM_CORP_ID") or raw_data.get("corp_id") or "")
+        corp_secret = str(os.getenv("WECOM_CORP_SECRET") or raw_data.get("corp_secret") or "")
+        base_url = str(os.getenv("WECOM_BASE_URL") or raw_data.get("base_url") or cls.base_url)
+        timeout_raw = os.getenv("WECOM_TIMEOUT_SECONDS") or raw_data.get("timeout_seconds")
+
+        if not corp_id or not corp_secret:
+            raise ConfigError(f"corp_id/corp_secret are required (env vars or config file at {path})")
+
+        timeout_seconds = cls.timeout_seconds
+        if timeout_raw is not None:
+            try:
+                timeout_seconds = float(str(timeout_raw))
+            except (TypeError, ValueError) as exc:
+                raise ConfigError("timeout_seconds should be a valid number") from exc
+
+        return cls(
+            corp_id=corp_id,
+            corp_secret=corp_secret,
+            base_url=base_url.rstrip("/"),
+            timeout_seconds=timeout_seconds,
+        )

core/errors.py

@@ -0,0 +1,29 @@
+"""Unified error hierarchy for WeCom CLI."""
+
+from __future__ import annotations
+
+
+class WeComCLIError(Exception):
+    """Base class for predictable CLI failures."""
+
+
+class ConfigError(WeComCLIError):
+    """Raised when loading configuration fails."""
+
+
+class AuthError(WeComCLIError):
+    """Raised when access token acquisition fails."""
+
+
+class APIRequestError(WeComCLIError):
+    """Raised when a transport-level request error occurs."""
+
+
+class APIResponseError(WeComCLIError):
+    """Raised when WeCom API returns a non-success errcode."""
+
+    def __init__(self, *, endpoint: str, errcode: int, errmsg: str) -> None:
+        self.endpoint = endpoint
+        self.errcode = errcode
+        self.errmsg = errmsg
+        super().__init__(f"{endpoint}: errcode={errcode}, errmsg={errmsg}")

core/requester.py

@@ -0,0 +1,193 @@
+"""Unified requester for WeCom API calls."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Protocol
+
+from core.config import WeComConfig
+from core.errors import APIRequestError, APIResponseError
+
+_TOKEN_EXPIRED_CODES = frozenset({40014, 42001})
+_RATE_LIMIT_CODES = frozenset({45001, 45009})
+_MAX_RETRIES = 2
+
+
+class TokenProvider(Protocol):
+    def get_token(self, force_refresh: bool = False) -> str: ...
+
+
+class UnifiedRequester:
+    def __init__(self, config: WeComConfig, token_provider: TokenProvider | None = None) -> None:
+        self._config = config
+        self._token_provider = token_provider
+        self._verbose = False
+        self._debug = False
+
+    def bind_token_provider(self, token_provider: TokenProvider) -> None:
+        self._token_provider = token_provider
+
+    def set_verbose(self, verbose: bool, debug: bool = False) -> None:
+        self._verbose = verbose or debug
+        self._debug = debug
+
+    def request(
+        self,
+        *,
+        method: str,
+        endpoint: str,
+        query: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        require_auth: bool = True,
+        _retrying: bool = False,
+    ) -> dict[str, Any]:
+        return self._request_with_retry(
+            method=method,
+            endpoint=endpoint,
+            query=query,
+            json_body=json_body,
+            require_auth=require_auth,
+            _retrying=_retrying,
+            _attempt=0,
+        )
+
+    def _request_with_retry(
+        self,
+        *,
+        method: str,
+        endpoint: str,
+        query: dict[str, Any] | None,
+        json_body: dict[str, Any] | None,
+        require_auth: bool,
+        _retrying: bool,
+        _attempt: int,
+    ) -> dict[str, Any]:
+        try:
+            return self._do_request(
+                method=method,
+                endpoint=endpoint,
+                query=query,
+                json_body=json_body,
+                require_auth=require_auth,
+            )
+        except APIResponseError as exc:
+            if _retrying or _attempt >= _MAX_RETRIES:
+                raise
+            if exc.errcode in _TOKEN_EXPIRED_CODES and require_auth and self._token_provider:
+                self._log_verbose(f"[retry {exc.errcode}] refreshing token")
+                self._token_provider.get_token(force_refresh=True)
+                return self._request_with_retry(
+                    method=method,
+                    endpoint=endpoint,
+                    query=query,
+                    json_body=json_body,
+                    require_auth=require_auth,
+                    _retrying=True,
+                    _attempt=_attempt + 1,
+                )
+            if exc.errcode in _RATE_LIMIT_CODES:
+                wait = 0.5 * (2**_attempt)
+                self._log_verbose(f"[retry {exc.errcode}] backing off {wait:.1f}s")
+                time.sleep(wait)
+                return self._request_with_retry(
+                    method=method,
+                    endpoint=endpoint,
+                    query=query,
+                    json_body=json_body,
+                    require_auth=require_auth,
+                    _retrying=_retrying,
+                    _attempt=_attempt + 1,
+                )
+            raise
+
+    def _do_request(
+        self,
+        *,
+        method: str,
+        endpoint: str,
+        query: dict[str, Any] | None,
+        json_body: dict[str, Any] | None,
+        require_auth: bool,
+    ) -> dict[str, Any]:
+        query_data: dict[str, Any] = dict(query or {})
+        if require_auth:
+            if self._token_provider is None:
+                raise APIRequestError("Token provider is not configured")
+            query_data["access_token"] = self._token_provider.get_token()
+
+        query_text = urllib.parse.urlencode(query_data)
+        url = f"{self._config.base_url}{endpoint}"
+        if query_text:
+            url = f"{url}?{query_text}"
+
+        body_data = None
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if json_body is not None:
+            body_data = json.dumps(_strip_none(json_body)).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        if self._verbose:
+            import sys
+
+            display_url = url
+            if "access_token=" in url:
+                parsed = urllib.parse.urlparse(url)
+                qs = urllib.parse.parse_qs(parsed.query)
+                if "access_token" in qs:
+                    qs["access_token"] = ["***MASKED***"]
+                display_url = parsed._replace(query=urllib.parse.urlencode(qs, doseq=True)).geturl()
+            print(f"[wecom-cli] {method} {display_url}", file=sys.stderr)
+        if self._debug:
+            import sys
+
+            if json_body:
+                print(f"[wecom-cli] body: {json.dumps(_strip_none(json_body), ensure_ascii=False)}", file=sys.stderr)
+
+        request = urllib.request.Request(
+            url=url,
+            data=body_data,
+            headers=headers,
+            method=method.upper(),
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._config.timeout_seconds) as response:
+                raw = response.read().decode("utf-8")
+        except urllib.error.URLError as exc:
+            raise APIRequestError(f"Request failed for {endpoint}: {exc}") from exc
+
+        if self._debug:
+            import sys
+
+            print(f"[wecom-cli] response: {raw[:500]}", file=sys.stderr)
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise APIRequestError(f"Invalid JSON response for {endpoint}: {raw[:200]}") from exc
+
+        errcode = int(payload.get("errcode") or 0)
+        if errcode != 0:
+            raise APIResponseError(
+                endpoint=endpoint,
+                errcode=errcode,
+                errmsg=str(payload.get("errmsg") or "unknown"),
+            )
+        return payload
+
+    def _log_verbose(self, msg: str) -> None:
+        if self._verbose:
+            import sys
+
+            print(f"[wecom-cli] {msg}", file=sys.stderr)
+
+
+def _strip_none(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: _strip_none(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [_strip_none(item) for item in value if item is not None]
+    return value