cyberquant 1.0.0__tar.gz

cyberquant-1.0.0/.gitignore

@@ -0,0 +1,53 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+env/
+
+# Node
+dist/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Config
+~/.cyberquant/

cyberquant-1.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: cyberquant
+Version: 1.0.0
+Summary: 数据共享API服务平台命令行工具
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0

cyberquant-1.0.0/README.md

@@ -0,0 +1,202 @@
+# cyberquant — Python CLI
+
+数据共享API服务平台命令行工具（Python 版），通过 pipx 或 pip 安装使用。
+
+## 安装
+
+```bash
+# 一次性运行
+pipx run cyberquant query stock_daily --code 000001.SZ
+
+# 安装后使用
+pipx install cyberquant
+cyberquant query stock_daily --code 000001.SZ
+
+# 或 pip 安装
+pip install cyberquant
+```
+
+## 首次配置
+
+```bash
+cyberquant config set
+```
+
+交互式输入 API 端点地址和 API Key，保存后自动验证。
+
+配置文件存储在 `~/.cyberquant/config.json`（与 Node.js 版共用）：
+
+```json
+{
+  "endpoint": "https://api.example.com",
+  "apiKey": "sk_live_xxxxx",
+  "pageSize": 50
+}
+```
+
+## 命令
+
+### config — 配置管理
+
+```bash
+# 交互式设置端点地址和 API Key
+cyberquant config set
+
+# 查看当前配置
+cyberquant config list
+
+# 查询当前 API Key 对应的用户状态
+cyberquant config status
+```
+
+`config status` 调用 API Gateway 的 `/api/v1/me` 端点，显示：
+- 邮箱、Tier 等级、可用市场、过期时间、限流配置
+
+### query — 数据查询
+
+```bash
+cyberquant query <routeSlug> [动态参数...] [选项]
+```
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--format <format>` | 输出格式：`json` 或 `csv` | `json` |
+| `--output <file>` | 输出到文件（不指定则输出到终端） | - |
+| `--pageSize <number>` | 每页条数 | config.json > 50 |
+| `--cursor <cursor>` | 游标翻页 | - |
+
+**动态参数**：除上述固定选项外，所有 `--key value` 直接作为查询参数透传给 API Gateway，CLI 不做校验。
+
+**示例**：
+
+```bash
+# 基本查询（JSON 输出）
+cyberquant query stock_daily --code 000001.SZ
+
+# CSV 格式输出到文件
+cyberquant query stock_daily --code 000001.SZ --format csv --output daily.csv
+
+# 带日期范围和自定义每页条数
+cyberquant query stock_daily --code 000001.SZ --startDate 2026-01-01 --endDate 2026-05-01 --pageSize 100
+
+# 游标翻页（返回结果中会提示 nextCursor）
+cyberquant query stock_daily --code 000001.SZ --cursor eyJ0cmFkZV9kYXRlIjoiMjAyNC0wMS0wMiJ9
+```
+
+**pageSize 优先级**：`--pageSize` 参数 > `config.json` 中的 `pageSize` > 默认 50
+
+### stream — 实时流
+
+```bash
+cyberquant stream <routeSlug> [动态参数...] [选项]
+```
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--pageSize <number>` | 每批条数 | config.json > 50 |
+| `--format <format>` | 输出格式：`json` 或 `csv` | `json` |
+| `--output <file>` | 输出到文件（不指定则输出到终端） | - |
+
+**示例**：
+
+```bash
+# 实时行情（JSON 输出到终端）
+cyberquant stream stock_realtime --code 000001.SZ
+
+# 输出到 CSV 文件
+cyberquant stream stock_realtime --code 000001.SZ --format csv --output realtime.csv
+
+# Ctrl+C 优雅退出
+```
+
+## 技术栈
+
+| 依赖 | 用途 |
+|------|------|
+| Typer | CLI 框架（Click 现代封装） |
+| Rich | 终端美化（表格、面板、颜色、进度条） |
+| httpx | HTTP 客户端 |
+| hatchling | 构建后端 |
+
+**Python 版本**：>= 3.10
+
+## 项目结构
+
+```
+src/cyberquant/
+├── __init__.py           # 版本信息
+├── __main__.py           # Typer 入口
+├── commands/
+│   ├── config.py         # config set/list/status
+│   ├── query.py          # query 命令 + 动态参数解析
+│   ├── stream.py         # stream 命令（SSE）
+│   └── export.py         # export 命令（ThreadPoolExecutor 并发）
+└── lib/
+    ├── api_client.py     # httpx 客户端（自动重试、错误映射）
+    ├── sse_client.py     # SSE 客户端（httpx stream 解析）
+    ├── config.py         # 读写 ~/.cyberquant/config.json
+    ├── formatter.py      # JSON/CSV 格式化输出
+    ├── display.py        # Rich 面板展示用户信息
+    └── errors.py         # 异常类 + 中文消息映射
+```
+
+## 开发
+
+### 本地开发模式（推荐）
+
+使用 `pip install -e .` 进行**可编辑模式安装**，修改代码后无需重新安装即可直接运行：
+
+```bash
+cd packages/api-cli-py
+
+# 可编辑模式安装（仅需执行一次）
+pip install -e .
+
+# 运行
+cyberquant --help
+cyberquant query stock_daily --code 000001.SZ
+```
+
+### 直接运行模块模式（不安装）
+
+如果不希望安装到系统，也可以直接运行模块：
+
+```bash
+cd packages/api-cli-py
+
+# 不安装直接运行
+PYTHONPATH=src python3 -m cyberquant --help
+PYTHONPATH=src python3 -m cyberquant query stock_daily --code 000001.SZ
+```
+
+**注意**：直接运行模块模式需要每次都设置 `PYTHONPATH=src`，不如可编辑模式方便。
+
+### 卸载开发模式
+
+```bash
+pip uninstall cyberquant
+```
+
+## 构建
+
+```bash
+pip install build twine
+python3 -m build
+twine upload dist/*
+```
+
+## 错误码
+
+| HTTP 状态码 | 中文消息 |
+|-------------|---------|
+| 400 | 参数校验失败 |
+| 401 | API Key 无效或已过期 |
+| 403 | 权限不足 |
+| 404 | 未找到 API 路由 |
+| 429 | 请求频率超限（自动重试） |
+| 500 | 服务器内部错误 |
+| 503 | 服务暂不可用（自动重试） |

cyberquant-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cyberquant"
+version = "1.0.0"
+description = "数据共享API服务平台命令行工具"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "httpx>=0.28.0",
+]
+
+[project.scripts]
+cyberquant = "cyberquant.__main__:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cyberquant"]

cyberquant-1.0.0/src/cyberquant/__init__.py

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

cyberquant-1.0.0/src/cyberquant/__main__.py

@@ -0,0 +1,35 @@
+import typer
+from typing import Optional
+from cyberquant.commands import config, query, stream
+
+cli = typer.Typer(help="数据共享API服务平台命令行工具", no_args_is_help=True)
+
+cli.add_typer(config.app, name="config")
+
+# 直接注册 query 和 stream 为命令
+# 设置 allow_extra_args 和 allow_interspersed_args 以支持任意动态参数
+@cli.command(name="query", context_settings={"ignore_unknown_options": True, "allow_extra_args": True, "allow_interspersed_args": True})
+def query_cmd(
+    ctx: typer.Context,
+    route_slug: str = typer.Argument(help="路由名称"),
+    format: str = typer.Option("json", "--format", help="输出格式: json | csv"),
+    output: Optional[str] = typer.Option(None, "--output", help="输出到文件"),
+    page_size: Optional[int] = typer.Option(None, "--pageSize", help="每页条数"),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="游标翻页"),
+    fetch_all: bool = typer.Option(False, "--all", help="自动翻页查询全部数据（流式写入）"),
+) -> None:
+    """查询数据"""
+    query.query(ctx, route_slug, format, output, page_size, cursor, fetch_all)
+
+@cli.command(name="stream", context_settings={"ignore_unknown_options": True, "allow_extra_args": True, "allow_interspersed_args": True})
+def stream_cmd(
+    ctx: typer.Context,
+    route_slug: str = typer.Argument(help="路由名称"),
+    format: str = typer.Option("json", "--format", help="输出格式: json | csv"),
+    output: Optional[str] = typer.Option(None, "--output", help="输出到文件"),
+) -> None:
+    """流式查询"""
+    stream.stream_cmd(ctx, route_slug, format, output)
+
+if __name__ == "__main__":
+    cli()

cyberquant-1.0.0/src/cyberquant/commands/config.py

@@ -0,0 +1,62 @@
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.prompt import Prompt
+
+from cyberquant.lib.config import load_config, require_config, save_config, mask_api_key
+from cyberquant.lib.api_client import ApiClient
+from cyberquant.lib.display import show_user_info
+from cyberquant.lib.errors import ConfigError
+
+app = typer.Typer(help="配置管理")
+console = Console()
+
+
+@app.command("set")
+def config_set() -> None:
+    """设置 API 端点和密钥"""
+    existing = load_config()
+
+    endpoint = Prompt.ask("API 端点地址", default=existing.get("endpoint", "http://localhost:4000") if existing else "http://localhost:4000")
+    api_key = Prompt.ask("API Key", password=True)
+
+    with console.status("验证中..."):
+        with ApiClient({"endpoint": endpoint, "apiKey": api_key}) as client:
+            try:
+                res = client.get_profile()
+                if not res.get("success") or not res.get("data"):
+                    console.print(f"[red]验证失败: {res.get('error', '未知错误')}[/red]")
+                    return
+                save_config({"endpoint": endpoint, "apiKey": api_key})
+                console.print("[green]配置已保存并验证通过[/green]")
+                show_user_info(res["data"])
+            except Exception as e:
+                console.print(f"[red]验证失败: {e}[/red]")
+
+
+@app.command("list")
+def config_list() -> None:
+    """查看当前配置"""
+    cfg = require_config()
+    lines = [
+        f"端点:     {cfg['endpoint']}",
+        f"API Key:  {mask_api_key(cfg['apiKey'])}",
+    ]
+    if cfg.get("pageSize"):
+        lines.append(f"默认条数: {cfg['pageSize']}")
+    console.print("\n".join(lines))
+
+
+@app.command("status")
+def config_status() -> None:
+    """查询当前 API Key 用户状态"""
+    cfg = require_config()
+    with console.status("查询中..."):
+        with ApiClient(cfg) as client:
+            res = client.get_profile()
+            if not res.get("success") or not res.get("data"):
+                console.print(f"[red]查询失败: {res.get('error', '未知错误')}[/red]")
+                return
+            console.print("[green]查询成功[/green]")
+            show_user_info(res["data"])

cyberquant-1.0.0/src/cyberquant/commands/query.py

@@ -0,0 +1,158 @@
+import sys
+from typing import Optional
+
+import typer
+
+from cyberquant.lib.config import require_config
+from cyberquant.lib.api_client import ApiClient
+from cyberquant.lib.formatter import format_json, format_csv, create_stream_writer
+from cyberquant.lib.stream_writer import StreamWriter
+
+
+def _parse_extra_args(args: list[str], known_options: list[str] | None = None) -> dict[str, str | list[str]]:
+    """解析动态参数，支持重复参数转为数组
+
+    Args:
+        args: 原始参数列表
+        known_options: 已知选项列表，这些选项不会被解析为动态参数
+
+    Returns:
+        动态参数字典，重复的 key 会转为 list
+    """
+    params: dict[str, str | list[str]] = {}
+    known_set = set(known_options or [])
+
+    i = 0
+    while i < len(args):
+        if args[i].startswith("--"):
+            key = args[i][2:]
+
+            # 跳过已知选项及其值
+            if key in known_set:
+                i += 2
+                continue
+
+            # 处理动态参数
+            if i + 1 < len(args) and not args[i + 1].startswith("--"):
+                _append_param(params, key, args[i + 1])
+                i += 2
+            else:
+                _append_param(params, key, "true")
+                i += 1
+        else:
+            i += 1
+
+    return params
+
+
+def _append_param(params: dict[str, str | list[str]], key: str, value: str) -> None:
+    """添加参数到字典，如果 key 已存在则转为数组"""
+    if key in params:
+        existing = params[key]
+        if isinstance(existing, list):
+            existing.append(value)
+        else:
+            params[key] = [existing, value]
+    else:
+        params[key] = value
+
+
+def query(
+    ctx: typer.Context,
+    route_slug: str = typer.Argument(help="路由名称"),
+    format: str = typer.Option("json", "--format", help="输出格式: json | csv"),
+    output: Optional[str] = typer.Option(None, "--output", help="输出到文件"),
+    page_size: Optional[int] = typer.Option(None, "--pageSize", help="每页条数"),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="游标翻页"),
+    fetch_all: bool = typer.Option(False, "--all", help="自动翻页查询全部数据（流式写入）"),
+) -> None:
+    """查询数据"""
+    cfg = require_config()
+    ps = page_size or cfg.get("pageSize", 50)
+
+    # 从原始命令行参数解析动态参数
+    known_options = ["format", "output", "pageSize", "cursor", "all"]
+    dynamic = _parse_extra_args(ctx.args, known_options)
+    params: dict[str, str | list[str] | int] = {**dynamic, "pageSize": ps}
+
+    # 如果指定了 --all，忽略手动传入的 cursor
+    if not fetch_all and cursor:
+        params["cursor"] = cursor
+
+    try:
+        if fetch_all:
+            # 自动翻页查询全部数据，使用流式写入
+            # 确保 output 是字符串或 None，防止 Typer 的 OptionInfo 类型泄漏
+            output_path: str | None = output if isinstance(output, (str, type(None))) else None
+            writer: StreamWriter = create_stream_writer(format, output_path, cfg)
+            writer.initialize()
+
+            query_cursor: str | None = None
+            count = 0
+
+            try:
+                # 使用连接池复用 HTTP 连接
+                with ApiClient(cfg) as client:
+                    while True:
+                        query_params = {**params}
+                        if query_cursor:
+                            query_params["cursor"] = query_cursor
+
+                        res = client.query(route_slug, query_params)
+                        if not res.get("success"):
+                            print(res.get("error", "查询失败"), file=sys.stderr)
+                            return
+
+                        data = res.get("data", [])
+                        if isinstance(data, list):
+                            for record in data:
+                                writer.write_record(record)
+                                count += 1
+
+                        pagination = res.get("meta", {}).get("pagination", {})
+                        if not pagination.get("hasMore"):
+                            break
+
+                        query_cursor = pagination.get("nextCursor")
+
+            finally:
+                # 确保 Ctrl+C 时也能正确闭合文件
+                writer.finalize()
+
+            # 输出警告（如果有）
+            warning = writer.get_warning() if hasattr(writer, "get_warning") else None
+            if warning:
+                print(warning, file=sys.stderr)
+        else:
+            # 单页查询
+            with ApiClient(cfg) as client:
+                res = client.query(route_slug, params)
+
+            if not res.get("success"):
+                print(res.get("error", "查询失败"), file=sys.stderr)
+                return
+
+            data = res.get("data", [])
+
+            if format == "csv":
+                content = format_csv(data)
+            else:
+                content = format_json(data, pretty=False)
+
+            if output:
+                from pathlib import Path
+                expanded = Path(output).expanduser()
+                with open(expanded, "w", encoding="utf-8") as f:
+                    f.write(content)
+                print(f"数据已保存 → {output}", file=sys.stderr)
+            else:
+                print(content)
+
+            # 提示翻页
+            pagination = res.get("meta", {}).get("pagination", {})
+            if pagination.get("hasMore"):
+                nc = pagination.get("nextCursor", "")
+                print(f"还有更多数据，使用 --cursor {nc} 翻页", file=sys.stderr)
+
+    except Exception as e:
+        print(str(e), file=sys.stderr)

cyberquant-1.0.0/src/cyberquant/commands/query.py.bak2

@@ -0,0 +1,67 @@
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from cyberquant.lib.config import require_config
+from cyberquant.lib.api_client import ApiClient
+from cyberquant.lib.formatter import format_json, format_csv, write_output
+
+console = Console()
+
+
+def _parse_extra_args(args: list[str]) -> dict[str, str]:
+    params: dict[str, str] = {}
+    i = 0
+    while i < len(args):
+        if args[i].startswith("--"):
+            key = args[i][2:]
+            if i + 1 < len(args) and not args[i + 1].startswith("--"):
+                params[key] = args[i + 1]
+                i += 2
+            else:
+                params[key] = "true"
+                i += 1
+        else:
+            i += 1
+    return params
+
+
+def query(
+    ctx: typer.Context,
+    route_slug: str = typer.Argument(help="路由名称"),
+    format: str = typer.Option("json", "--format", help="输出格式: json | csv"),
+    output: Optional[str] = typer.Option(None, "--output", help="输出到文件"),
+    page_size: Optional[int] = typer.Option(None, "--pageSize", help="每页条数"),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="游标翻页"),
+) -> None:
+    """查询数据"""
+    cfg = require_config()
+    client = ApiClient(cfg)
+
+    ps = page_size or cfg.get("pageSize", 50)
+    dynamic = _parse_extra_args(ctx.args)
+    params: dict = {**dynamic, "pageSize": ps}
+    if cursor:
+        params["cursor"] = cursor
+
+    with console.status("查询中..."):
+        res = client.query(route_slug, params)
+
+    if not res.get("success"):
+        console.print(f"[red]{res.get('error', '查询失败')}[/red]")
+        return
+
+    data = res.get("data", [])
+    console.print(f"[green]查询成功，共 {len(data)} 条[/green]")
+
+    if format == "csv":
+        content = format_csv(data)
+    else:
+        content = format_json(data)
+    write_output(content, output)
+
+    pagination = res.get("meta", {}).get("pagination", {})
+    if pagination.get("hasMore"):
+        nc = pagination.get("nextCursor", "")
+        console.print(f"[dim]还有更多数据，使用 --cursor {nc} 翻页[/dim]")

cyberquant-1.0.0/src/cyberquant/commands/stream.py

@@ -0,0 +1,60 @@
+import sys
+from typing import Optional
+
+import typer
+
+from cyberquant.lib.config import require_config
+from cyberquant.lib.sse_client import connect_sse
+from cyberquant.lib.formatter import create_stream_writer
+from cyberquant.commands.query import _parse_extra_args
+
+
+def stream_cmd(
+    ctx: typer.Context,
+    route_slug: str = typer.Argument(help="路由名称"),
+    page_size: Optional[int] = typer.Option(None, "--pageSize", help="每批条数"),
+    format: str = typer.Option("json", "--format", help="输出格式: json | csv"),
+    output: Optional[str] = typer.Option(None, "--output", help="输出到文件"),
+) -> None:
+    """实时流式数据"""
+    cfg = require_config()
+    ps = page_size or cfg.get("pageSize", 50)
+
+    known_options = ["pageSize", "format", "output"]
+    dynamic = _parse_extra_args(ctx.args, known_options)
+    params: dict[str, str | list[str] | int] = {**dynamic, "pageSize": ps}
+
+    # 文件输出或 JSON 模式：使用流式写入
+    from cyberquant.lib.stream_writer import StreamWriter
+
+    # 确保 output 是字符串或 None，防止 Typer 的 OptionInfo 类型泄漏
+    output_path: str | None = output if isinstance(output, (str, type(None))) else None
+    writer: StreamWriter = create_stream_writer(format, output_path, cfg)
+    writer.initialize()
+
+    count = 0
+
+    def on_data(data: dict) -> None:
+        nonlocal count
+        writer.write_record(data)
+        count += 1
+
+    def on_complete(info=None) -> None:
+        writer.finalize()
+
+        # 输出警告（如果有）
+        warning = writer.get_warning() if hasattr(writer, "get_warning") else None
+        if warning:
+            print(warning, file=sys.stderr)
+
+        if output_path:
+            print(f"数据已保存 → {output_path}", file=sys.stderr)
+
+    def on_error(error: str) -> None:
+        print(f"流式错误: {error}", file=sys.stderr)
+
+    try:
+        connect_sse(cfg, route_slug, params, on_data, on_complete, on_error)
+    except KeyboardInterrupt:
+        writer.finalize()
+        print("已断开连接", file=sys.stderr)