alpha-dc-client 0.2.2__tar.gz → 0.3.1__tar.gz

{alpha_dc_client-0.2.2 → alpha_dc_client-0.3.1}/.gitignore

@@ -70,6 +70,7 @@ __pypackages__/
 
 # Environments
 .env
+.env_copy
 .venv
 env/
 venv/
@@ -82,9 +83,6 @@ venv.bak/
 .dmypy.json
 dmypy.json
 
-# uv lock file
-uv.lock
-
 # Log files
 logs/
 *.log
@@ -159,11 +157,22 @@ qmt_probe_report_*.json
 # IC 回填脚本产生的运行时日志
 ic_backfill_*.log
 ic_backfill_*.err
-
-# 港股回补运行时状态（断点续传，本地产物）
-dc_quant/scripts/_hk_*_progress.json
-dc_quant/scripts/check/_tmp_*
-dc_quant/scripts/_us_edgar_repull_progress.json
-dc_quant/scripts/check/_layer_reconcile_done.json
-dc_quant/scripts/_cn_index_full_progress.json
-dc_quant/scripts/_etf_fundamentals_progress.json
+
+# 港股回补运行时状态（断点续传，本地产物）
+dc_quant/scripts/_hk_*_progress.json
+dc_quant/scripts/check/_tmp_*
+dc_quant/scripts/_us_edgar_repull_progress.json
+dc_quant/scripts/check/_layer_reconcile_done.json
+dc_quant/scripts/_cn_index_full_progress.json
+dc_quant/scripts/_etf_fundamentals_progress.json
+
+# frp 隧道本地配置（scripts/frp 目录已随 dc_qmt 退役删除，但 Windows 部署机
+# 仍可能残留含密钥的 frpc.toml 等——退役实物清理完成前保留 ignore 保护）
+frpc.toml
+frpc-visitor.toml
+frpc.exe
+frpc.log
+frps.log
+
+# E7 模块 env 分层：真实模块配置不入库（模板 .example 提交）
+configs/*.env

{alpha_dc_client-0.2.2 → alpha_dc_client-0.3.1}/DATA.md

@@ -1,188 +1,188 @@
-# 因子数据访问指南（dc_client.data）
-
-> 从零开始，大约 10 分钟接入。目标：本机持有一份因子数据镜像，像读本地文件一样
-> 查询 A股/美股/港股的全部因子。
->
-> HTTP API（DataApi）部分见 [USAGE.md](USAGE.md)，本文只讲因子数据（Parquet）。
-
-## 数据流（一分钟理解）
-
-```
-生产（60 服务器）──每天 9:30──> 锐驰（备份分发源，只读）
-                                   │  ssh 拉取（加密 + 增量）
-                                   ▼
-                          你的本机 ~/.dc_data/parquet（全量镜像）
-                                   │  本地 duckdb 查询（零网络）
-                                   ▼
-                          data.cn.stock.load(...) 等
-```
-
-- 市场命名空间：`data.cn` / `data.us` / `data.hk`，跨市场语义一致只换前缀
-- 新鲜度：锐驰是 T+1 早上 9:30 的快照（当天数据次日上午可取）
-
----
-
-## 第 0 步：SSH 免登（前置，一次性）
-
-同步走 SSH 公钥认证（无密码、传输加密）。**公钥 = 你的门禁卡**。
-
-### 0.1 检查/生成密钥对
-
-```bash
-# 有没有现成的（多数人已有）
-ls ~/.ssh/id_ed25519.pub 2>/dev/null && echo "已有公钥"
-
-# 没有 → 生成（一路回车即可，三平台命令相同；Windows 用 Git Bash 或 PowerShell）
-ssh-keygen -t ed25519 -C "你的名字"
-```
-
-Windows 10+/macOS/Linux 都自带 ssh 客户端，无需额外安装。
-
-### 0.2 把公钥发给管理员
-
-```bash
-cat ~/.ssh/id_ed25519.pub
-```
-
-把输出的那一行（`ssh-ed25519 AAAA... 你的名字`）发给管理员。管理员在锐驰执行：
-
-```bash
-echo "ssh-ed25519 AAAA... 你的名字" >> /home/dcsync/.ssh/authorized_keys
-```
-
-> dcsync 是**只读账户**：你的钥匙只能读数据目录，写不进、删不了，弄丢了及时
-> 告知管理员删掉对应那行即吊销。
-
-### 0.3 验证
-
-```bash
-ssh dcsync@124.221.18.9 'ls /srv/dc_factor_parquet | head -3'
-```
-
-能列出 dataset 目录（stock_fct_pricevolume 等）即通，不会再问密码。
-
----
-
-## 第 1 步：安装
-
-```bash
-pip install 'alpha-dc-client[parquet]'
-```
-
-`[parquet]` 会带上 duckdb/pandas/paramiko。**装完即用**——Windows 没有额外要求；
-macOS/Linux 想要更快的增量同步可选装 rsync（系统一般自带）。
-
-## 第 2 步：配置（一次性）
-
-```bash
-python -m dc_client.data configure
-```
-
-默认值就是生产环境（锐驰地址/只读账户/数据根），**一般全部直接回车**。
-想换本机落盘位置（默认 `~/.dc_data/parquet`）就填 `local_root`。
-配置文件：`~/.dc_data/config.json`，随时可改。
-
-## 第 3 步：首次全量同步
-
-```bash
-python -m dc_client.data sync --market cn --full    # A股全量，~13G，半小时级
-python -m dc_client.data sync --market us --full    # 美股（按需）
-```
-
-只做某个市场就不用拉全量。进度按 dataset 逐个显示，中断了重跑接着传（断点续传）。
-
-## 生产机（又计算又使用）的免重复配置
-
-如果你的机器本身就是数据生产方（跑 dc_quant），无需镜像一份 13G——在**仓库的
-`.env`** 里配置数据根，client 初始化时自动读取（load_dotenv，幂等）：
-
-```bash
-# monorepo 的 .env（推荐：集中管理、随机器迁移、进 .env.example 留档）
-DC_CLIENT_PARQUET_ROOT=C:/Users/<user>/.cache/dc_quant
-
-# 也可以用系统环境变量（不依赖 .env 文件），二者等价、env 优先
-```
-
-优先级：**显式配置**（configure 写入的 local_root / 代码传入参数）> **环境变量**（.env 或系统）> 默认镜像目录。env 只覆盖默认值，不会劫持显式配置。
-指向生产缓存后 **sync 自动被拒绝**（生产标记守卫），只剩读取——数据零重复。
-普通使用者不配此项，默认独立镜像目录，行为不变。
-
-## 第 4 步：日常使用
-
-### ── sync 能力：独立顶层入口（与读取分离，可挂定时）──
-# 每天增量同步（秒级~分钟级）
-
-```bash
-python -m dc_client.data sync                # 全部
-python -m dc_client.data sync --market cn    # 只 A股
-```
-
-或代码 `data.sync(market="cn")`（**sync 是独立顶层能力**，读取命名空间上没有 sync）。建议挂系统定时（Windows 任务计划程序 /
-`crontab -e` 写 `0 11 * * 1-5 python -m dc_client.data sync` 之类）。
-
-### 读数据
-
-```python
-from dc_client import data
-
-# ── 读能力：命名空间纯读取 ──
-# A股全因子宽表（视图：自动跨层合并，只读含目标列的文件）
-df = data.cn.stock.load(
-    start="2026-01-01",
-    columns=["stock_code", "stock_mom_20d", "stock_alpha101_001"],
-)
-
-# A股策略参考美股因子——只换前缀，语义完全一致
-us = data.us.stock.load(start="2026-01-01", columns=["symbol", "us_mom_20d"])
-
-# 单层直读 / 附加过滤
-data.cn.pricevolume.load(start="2026-09-01")
-data.cn.pricevolume.load(where="stock_code = '000001.SZ'")
-
-# 市场信号（每天一行的择时指标：涨跌比/杠杆率/中位PE 等）
-data.cn.market.load()
-
-# 探索：这个市场有什么入口？某层有哪些列？
-data.cn.datasets()                  # 语义入口清单
-data.cn.pricevolume.columns         # 列清单
-data.cn.stock.columns               # 宽表全部可用列
-data.status(market="cn")            # 新鲜度面板（哪些该 sync 了）
-```
-
-### CLI 查看清单
-
-```bash
-python -m dc_client.data datasets            # 按市场列出全部语义入口
-python -m dc_client.data status              # 本地/远端新鲜度
-```
-
----
-
-## 语义入口速查
-
-| 入口 | 含义 | cn | us | hk |
-|---|---|---|---|---|
-| `stock` | 股票全因子宽表（视图） | ✅ 9 层 | ✅ | ✅ |
-| `pricevolume` / `raw` / `capital` / `alpha101` / `alpha191` / `fundamental` / `reversal` / `quality` / `ratio` | 单因子层 | 部分 | 部分 | 部分 |
-| `market` | 市场级日频信号 | ✅ | 待接入 | ✅ |
-| `etf` / `industry` / `l2_industry` | ETF/行业因子 | 部分 | 部分 | - |
-
-新 dataset 上线后**自动可用**（同步时从远端目录发现，无需更新包）。
-
-## 常见问题
-
-| 症状 | 原因与解法 |
-|---|---|
-| `Permission denied (publickey)` | 公钥没配好——回到第 0 步；确认 `ssh dcsync@124.221.18.9` 免密 |
-| `FileNotFoundError: 本地无 X 数据` | 还没同步该 dataset：`sync --market ...` |
-| `ValueError: 必须指定 columns` | 视图跨多层、有 13G 级宽表，**故意**强制列清单（剪裁）；先 `.columns` 看可用列 |
-| `列不存在于视图任何已知层` | 列名抄错，或该列在未同步的层——对照 `.columns` |
-| 数据不是今天的 | 正常：锐驰是 T+1 早上 9:30 快照，当天数据次日上午取 |
-| 想换落盘目录 | `configure(local_root="D:/dc_data")`；镜像账本跟随目录，多目录互不干扰 |
-| 同步慢 | Windows 走纯 Python 通道（够用）；`scoop install rsync` 后自动提速 |
-
-## 维护者备注
-
-内部机制/设计文档：主仓库 `docs/dc_client/data-access.md`；
-测试：`uv run pytest dc_client/src/dc_client/tests/test_data.py -q`（必须用独立
-local_root，勿污染默认镜像目录）。
+# 因子数据访问指南（dc_client.data）
+
+> 从零开始，大约 10 分钟接入。目标：本机持有一份因子数据镜像，像读本地文件一样
+> 查询 A股/美股/港股的全部因子。
+>
+> HTTP API（DataApi）部分见 [USAGE.md](USAGE.md)，本文只讲因子数据（Parquet）。
+
+## 数据流（一分钟理解）
+
+```
+生产（60 服务器）──每天 9:30──> 锐驰（备份分发源，只读）
+                                   │  ssh 拉取（加密 + 增量）
+                                   ▼
+                          你的本机 ~/.dc_data/parquet（全量镜像）
+                                   │  本地 duckdb 查询（零网络）
+                                   ▼
+                          data.cn.stock.load(...) 等
+```
+
+- 市场命名空间：`data.cn` / `data.us` / `data.hk`，跨市场语义一致只换前缀
+- 新鲜度：锐驰是 T+1 早上 9:30 的快照（当天数据次日上午可取）
+
+---
+
+## 第 0 步：SSH 免登（前置，一次性）
+
+同步走 SSH 公钥认证（无密码、传输加密）。**公钥 = 你的门禁卡**。
+
+### 0.1 检查/生成密钥对
+
+```bash
+# 有没有现成的（多数人已有）
+ls ~/.ssh/id_ed25519.pub 2>/dev/null && echo "已有公钥"
+
+# 没有 → 生成（一路回车即可，三平台命令相同；Windows 用 Git Bash 或 PowerShell）
+ssh-keygen -t ed25519 -C "你的名字"
+```
+
+Windows 10+/macOS/Linux 都自带 ssh 客户端，无需额外安装。
+
+### 0.2 把公钥发给管理员
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+把输出的那一行（`ssh-ed25519 AAAA... 你的名字`）发给管理员。管理员在锐驰执行：
+
+```bash
+echo "ssh-ed25519 AAAA... 你的名字" >> /home/dcsync/.ssh/authorized_keys
+```
+
+> dcsync 是**只读账户**：你的钥匙只能读数据目录，写不进、删不了，弄丢了及时
+> 告知管理员删掉对应那行即吊销。
+
+### 0.3 验证
+
+```bash
+ssh dcsync@124.221.18.9 'ls /srv/dc_factor_parquet | head -3'
+```
+
+能列出 dataset 目录（stock_fct_pricevolume 等）即通，不会再问密码。
+
+---
+
+## 第 1 步：安装
+
+```bash
+pip install 'alpha-dc-client[parquet]'
+```
+
+`[parquet]` 会带上 duckdb/pandas/paramiko。**装完即用**——Windows 没有额外要求；
+macOS/Linux 想要更快的增量同步可选装 rsync（系统一般自带）。
+
+## 第 2 步：配置（一次性）
+
+```bash
+python -m dc_client.data configure
+```
+
+默认值就是生产环境（锐驰地址/只读账户/数据根），**一般全部直接回车**。
+想换本机落盘位置（默认 `~/.dc_data/parquet`）就填 `local_root`。
+配置文件：`~/.dc_data/config.json`，随时可改。
+
+## 第 3 步：首次全量同步
+
+```bash
+python -m dc_client.data sync --market cn --full    # A股全量，~13G，半小时级
+python -m dc_client.data sync --market us --full    # 美股（按需）
+```
+
+只做某个市场就不用拉全量。进度按 dataset 逐个显示，中断了重跑接着传（断点续传）。
+
+## 生产机（又计算又使用）的免重复配置
+
+如果你的机器本身就是数据生产方（跑 dc_quant），无需镜像一份 13G——在**仓库的
+env 配置**里配置数据根，client 初始化时自动读取（load_dotenv，幂等）：
+
+```bash
+# configs/{module}.env（推荐：集中管理、随机器迁移、进 configs/*.env.example 留档）
+DC_CLIENT_PARQUET_ROOT=C:/Users/<user>/.cache/dc_quant
+
+# 也可以用系统环境变量（不依赖 .env 文件），二者等价、env 优先
+```
+
+优先级：**显式配置**（configure 写入的 local_root / 代码传入参数）> **环境变量**（.env 或系统）> 默认镜像目录。env 只覆盖默认值，不会劫持显式配置。
+指向生产缓存后 **sync 自动被拒绝**（生产标记守卫），只剩读取——数据零重复。
+普通使用者不配此项，默认独立镜像目录，行为不变。
+
+## 第 4 步：日常使用
+
+### ── sync 能力：独立顶层入口（与读取分离，可挂定时）──
+# 每天增量同步（秒级~分钟级）
+
+```bash
+python -m dc_client.data sync                # 全部
+python -m dc_client.data sync --market cn    # 只 A股
+```
+
+或代码 `data.sync(market="cn")`（**sync 是独立顶层能力**，读取命名空间上没有 sync）。建议挂系统定时（Windows 任务计划程序 /
+`crontab -e` 写 `0 11 * * 1-5 python -m dc_client.data sync` 之类）。
+
+### 读数据
+
+```python
+from dc_client import data
+
+# ── 读能力：命名空间纯读取 ──
+# A股全因子宽表（视图：自动跨层合并，只读含目标列的文件）
+df = data.cn.stock.load(
+    start="2026-01-01",
+    columns=["stock_code", "stock_mom_20d", "stock_alpha101_001"],
+)
+
+# A股策略参考美股因子——只换前缀，语义完全一致
+us = data.us.stock.load(start="2026-01-01", columns=["symbol", "us_mom_20d"])
+
+# 单层直读 / 附加过滤
+data.cn.pricevolume.load(start="2026-09-01")
+data.cn.pricevolume.load(where="stock_code = '000001.SZ'")
+
+# 市场信号（每天一行的择时指标：涨跌比/杠杆率/中位PE 等）
+data.cn.market.load()
+
+# 探索：这个市场有什么入口？某层有哪些列？
+data.cn.datasets()                  # 语义入口清单
+data.cn.pricevolume.columns         # 列清单
+data.cn.stock.columns               # 宽表全部可用列
+data.status(market="cn")            # 新鲜度面板（哪些该 sync 了）
+```
+
+### CLI 查看清单
+
+```bash
+python -m dc_client.data datasets            # 按市场列出全部语义入口
+python -m dc_client.data status              # 本地/远端新鲜度
+```
+
+---
+
+## 语义入口速查
+
+| 入口 | 含义 | cn | us | hk |
+|---|---|---|---|---|
+| `stock` | 股票全因子宽表（视图） | ✅ 9 层 | ✅ | ✅ |
+| `pricevolume` / `raw` / `capital` / `alpha101` / `alpha191` / `fundamental` / `reversal` / `quality` / `ratio` | 单因子层 | 部分 | 部分 | 部分 |
+| `market` | 市场级日频信号 | ✅ | 待接入 | ✅ |
+| `etf` / `industry` / `l2_industry` | ETF/行业因子 | 部分 | 部分 | - |
+
+新 dataset 上线后**自动可用**（同步时从远端目录发现，无需更新包）。
+
+## 常见问题
+
+| 症状 | 原因与解法 |
+|---|---|
+| `Permission denied (publickey)` | 公钥没配好——回到第 0 步；确认 `ssh dcsync@124.221.18.9` 免密 |
+| `FileNotFoundError: 本地无 X 数据` | 还没同步该 dataset：`sync --market ...` |
+| `ValueError: 必须指定 columns` | 视图跨多层、有 13G 级宽表，**故意**强制列清单（剪裁）；先 `.columns` 看可用列 |
+| `列不存在于视图任何已知层` | 列名抄错，或该列在未同步的层——对照 `.columns` |
+| 数据不是今天的 | 正常：锐驰是 T+1 早上 9:30 快照，当天数据次日上午取 |
+| 想换落盘目录 | `configure(local_root="D:/dc_data")`；镜像账本跟随目录，多目录互不干扰 |
+| 同步慢 | Windows 走纯 Python 通道（够用）；`scoop install rsync` 后自动提速 |
+
+## 维护者备注
+
+内部机制/设计文档：主仓库 `docs/dc_client/data-access.md`；
+测试：`uv run pytest dc_client/src/dc_client/tests/test_data.py -q`（必须用独立
+local_root，勿污染默认镜像目录）。