carrotquant-data 1.2.1__py3-none-any.whl

carrotquant_data-1.2.1.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.5
+Name: carrotquant-data
+Version: 1.2.1
+Summary: 高性能、轻量级 A 股与指数金融数据增量同步与持久化流水线
+Author-email: Carrot <11172391+CRThu@users.noreply.github.com>
+Requires-Python: >=3.12
+Requires-Dist: baostock>=0.9.1
+Requires-Dist: curl-cffi>=0.7.4
+Requires-Dist: fastapi>=0.135.1
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: polars>=1.39.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: tdxpy>=0.2.7
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: typer>=0.24.1
+Requires-Dist: uvicorn>=0.41.0
+Description-Content-Type: text/markdown
+
+# CarrotQuant.Data
+
+![Python Version](https://img.shields.io/badge/python-%3E%3D3.12-blue)
+![License](https://img.shields.io/badge/license-Apache%202.0-blue)
+
+CarrotQuant.Data 是一个为量化交易体系设计的轻量级、模块化的本地数据同步与管理工具。它致力于从各类免费数据源（如 Baostock、东方财富等）获取金融数据，并将数据清洗、转换为统一格式（支持 CSV, Parquet 等），持久化到本地存储中以供各类量化研究和回测使用。
+
+## 🌟 核心特性 (Features)
+
+- **多数据源支持**：内置 [Baostock](http://baostock.com/)、东方财富、[通达信 (tdxpy)](https://github.com/rainx/tdxPy) 等金融数据源引擎，易于弹性拓展更多的数据源提供商。
+- **灵活的存储格式**：原生支持 `csv` 和基于列式存储的高效 `parquet` 格式，以满足不同体量的数据读写需求。
+- **增量与全量同步**：基于时间戳水位线的同步机制，支持从断点智能续接（增量拉取），以及强制全量覆盖更新刷新数据。
+- **现代化多通道接入支持**：
+  - **React Web 终端**：现代暗黑极速金融终端 (`web/`)，基于 Bun + Vite 6 + React 19 + TradingView Lightweight Charts (3-Pane 单屏无滚动图表) + 拼音/代码/名称通用搜索组件 `SearchInput` + **独立 `数据矩阵` 视图 + 数据中心与 Loguru SSE 日志流视窗与悬浮 Widget**。
+  - **Python SDK**：简单直观的 `import cqdata` API，支持高性能跨年份数据切片读取 (`cqdata.read`)、`columns` 按需字段选择、格式识别与元数据探查。
+  - **命令行工具 (CLI)**：统一的 `cqdata` 命令行工具，提供数据同步 (`cqdata sync`)、数据表探索 (`cqdata tables`)、元数据查询 (`cqdata info`) 与 HTTP 服务启动 (`cqdata server`)。
+  - **REST API 服务**：基于 FastAPI 的 REST API，为远程微服务与 Web 终端提供 HTTP 数据切片、SSE 实时日志流与同步触发。
+- **优秀的底层性能**：使用 [Polars](https://pola.rs/) 库进行高性能的数据加工和清洗。
+
+## 📁 目录结构 (Project Structure)
+
+```text
+CarrotQuant.Data/
+├── cqdata/           # 核心代码包 (支持 import cqdata)
+│   ├── entrypoints/  # 接入层 (python_api, cli, rest_api)
+│   ├── config/       # 配置管理模块
+│   ├── provider/     # 数据源驱动 (BaostockProvider, EastMoneyProvider, TDXProvider)
+│   ├── service/      # 核心业务逻辑 (DataReader, MetadataReader, SyncManager 等)
+│   ├── storage/      # 本地持久化存储 (CSVStorage, ParquetStorage)
+│   └── utils/        # 通用工具箱
+├── web/              # React Web 金融终端 (Bun + Vite 6 + React 19 + TradingView 3-Pane)
+│   ├── src/          # 视图 View、组件 Component、Hooks 与转换服务
+│   └── package.json
+├── scripts/
+│   ├── wizard.py         # 交互向导脚本 (也可通过 cqdata wizard 运行)
+│   └── download_tdx.py   # 通达信数据下载脚本
+├── tests/            # 单元测试与集成测试
+├── config/           # 项目配置文件存放目录
+├── logs/             # 系统运行日志目录
+├── AGENTS.md         # AI Agent 架构指南
+└── pyproject.toml    # 项目构建及依赖配置
+```
+
+## 🏗️ 系统架构
+
+```mermaid
+graph TB
+    subgraph Entrypoints["接入层 (cqdata/entrypoints)"]
+        PYTHON_API["python_api.py<br/>(Python SDK)"]
+        CLI["cli.py<br/>(Typer CLI)"]
+        REST["rest_api.py<br/>(FastAPI REST)"]
+        WIZARD["wizard.py<br/>(交互向导)"]
+    end
+
+    subgraph Service["业务逻辑层 (cqdata/service)"]
+        SM["SyncManager<br/>同步总调度"]
+        DR["DataReader<br/>切片与按列投影"]
+        MR["MetadataReader<br/>探查与过滤 API"]
+        TASK_PLANNER["TaskPlanner<br/>任务规划器"]
+        MM["MetadataManager<br/>元数据 IO"]
+    end
+
+    subgraph Provider["采集层 (cqdata/provider)"]
+        PM["ProviderManager"]
+        BP["BaostockProvider"]
+        EP["EastMoneyProvider"]
+        TDX_PROV["TDXProvider"]
+    end
+
+    subgraph Storage["存储层 (cqdata/storage)"]
+        SF["StorageFactory"]
+        CSV["CSVStorage"]
+        PQ["ParquetStorage"]
+    end
+
+    PYTHON_API --> DR
+    PYTHON_API --> MR
+    PYTHON_API --> SM
+    CLI --> SM
+    CLI --> MR
+    REST --> DR
+    REST --> MR
+    REST --> SM
+    WIZARD --> SM
+
+    SM --> TASK_PLANNER
+    SM --> PM
+    SM --> SF
+    TASK_PLANNER --> MM
+    SM --> MM
+    PM --> BP
+    PM --> EP
+    PM --> TDX_PROV
+    SF --> CSV
+    SF --> PQ
+```
+
+## 📊 支持的数据表 (Supported Tables)
+
+| Table ID | 类型 | 说明 |
+|----------|------|------|
+| `ashare.kline.1d.adj.baostock` | TS | A 股日线后复权 |
+| `ashare.kline.1d.raw.baostock` | TS | A 股日线不复权 |
+| `ashare.kline.5m.adj.baostock` | TS | A 股 5 分钟线后复权 |
+| `ashare.kline.5m.raw.baostock` | TS | A 股 5 分钟线不复权 |
+| `aindex.kline.1d.raw.baostock` | TS | A 股指数日线 |
+| `ashare.adj_factor.baostock` | EV | A 股复权因子 |
+| `ashare.concept.eastmoney` | EV | 概念板块成分股 |
+| `ashare.industry.eastmoney` | EV | 行业板块成分股 |
+| `ashare.dragon_tiger.eastmoney` | EV | 龙虎榜 |
+| `ashare.inst_trade.eastmoney` | EV | 机构买卖每日统计 |
+| `ashare.kline.1d.raw.tdx` | TS | A 股日线 (通达信) |
+| `ashare.kline.5m.raw.tdx` | TS | A 股 5 分钟线 (通达信) |
+| `ashare.kline.1m.raw.tdx` | TS | A 股 1 分钟线 (通达信) |
+| `aindex.kline.1d.raw.tdx` | TS | 指数日线 (通达信) |
+| `aindex.kline.5m.raw.tdx` | TS | 指数 5 分钟线 (通达信) |
+| `aindex.kline.1m.raw.tdx` | TS | 指数 1 分钟线 (通达信) |
+
+## 🛠️ 安装指南 (Installation)
+
+环境要求：**Python >= 3.12**。本项目推荐使用现代化的 Python 包管理器 [uv](https://github.com/astral-sh/uv) 进行极速安装与管理。
+
+1. **克隆项目并安装**
+    ```bash
+    git clone https://github.com/CRThu/CarrotQuant.Data.git
+    cd CarrotQuant.Data
+
+    # 可选：可编辑模式挂载命令行 cqdata
+    uv pip install -e .
+    ```
+
+## ⚙️ 配置说明 (Configuration)
+
+CarrotQuant.Data 秉承 **“显式胜于隐式 (Explicit is better than implicit)”** 的配置契约，支持以下显式加载与覆盖方式（优先级从高到低）：
+
+1. **代码程序化修改**：直接设置单例属性 `cqdata.settings.data_dir = "/path/to/data"` 或调用 `cqdata.configure("/path/to/config.yaml")`（最高优先级）。
+2. **环境变量 `CQDATA_DATA_DIR`**：如 `export CQDATA_DATA_DIR="/my/data/path"`（适合 Docker / CLI / 自动化部署）。
+3. **环境变量 `CQDATA_CONFIG_PATH`**：指定自定义 YAML 配置文件路径，如 `export CQDATA_CONFIG_PATH="/path/to/config.yaml"`。
+4. **内置默认配置**：默认存储路径 `data_dir = "data"`，默认日志 `log_dir = "logs"`, `log_level = "INFO"`。
+
+完整配置文件结构参考 [config.yaml.sample](file:///d:/Quant/CarrotQuant.Data/config/config.yaml.sample)：
+
+```yaml
+# config.yaml
+data_dir: "data"       # 数据存储根目录
+log_dir: "logs"        # 日志输出目录
+log_level: "INFO"      # 日志级别 (DEBUG/INFO/WARNING/ERROR)
+
+# OOP 访问层全局默认配置链
+defaults:
+  source: "baostock"
+  format: "parquet"
+```
+
+---
+
+## 🚀 快速开始 (Quick Start)
+
+### 方式一：使用 Python SDK (`import cqdata`) - 推荐
+
+在量化研究与 Python 策略脚本中直接读取本地清洗好的数据：
+
+```python
+import cqdata
+
+# 0. (可选) 从 YAML 配置文件加载全局配置
+cqdata.configure("./config.yaml")
+
+# 或者直接修改属性
+cqdata.settings.data_dir = "./custom_data"
+
+# 1. OOP 便捷读取 (界面极简，干净清爽)
+df_kline = cqdata.ashare.kline.get(symbols="sh.600000", start_date="2024-01-01")
+
+# 2. 查阅代码清单、时间跨度、Schema 映射与物理总行数
+symbols = cqdata.list_symbols("ashare.kline.1d.raw.baostock")
+start_dt, end_dt = cqdata.get_time_range("ashare.kline.1d.raw.baostock")
+schema = cqdata.get_schema("ashare.kline.1d.raw.baostock")         # {'timestamp': 'Int64', ...}
+total_rows = cqdata.get_row_count("ashare.kline.1d.raw.baostock") # 13570685
+
+# 3. 统一切片读取 K 线时序数据 (支持 columns 按需挑选列，极节省内存)
+df = cqdata.read(
+    table_id="ashare.kline.1d.raw.baostock",
+    symbols=["sh.600000", "sz.000001"],
+    start_date="2024-01-01",
+    end_date="2024-06-30",
+    columns=["timestamp", "datetime", "symbol", "close", "volume"]
+)
+print(df)
+
+# 4. 统一切片读取板块/龙虎榜事件数据
+events_df = cqdata.read(
+    table_id="ashare.concept.eastmoney",
+    symbols=["sh.600000"]
+)
+
+# 5. 代码中触发全自动数据同步
+cqdata.sync(table_ids=["ashare.kline.1d.raw.baostock"], formats=["parquet"])
+```
+
+### 方式二：使用统一 CLI 命令行工具 (`cqdata`)
+
+可在终端或 Cron 定时任务中直接调用 `cqdata` 交互：
+
+```bash
+# 查看本地存储的所有数据表概览
+cqdata tables
+
+# 查看某张表的物理行数、代码列表与 Schema 详细元数据
+cqdata info ashare.kline.1d.raw.baostock
+
+# 触发自动增量同步
+cqdata sync --tables "ashare.kline.1d.raw.baostock,ashare.adj_factor.baostock"
+
+# 指定日期区间与保存格式进行全量强制更新
+cqdata sync -t ashare.kline.1d.raw.baostock -f parquet -s 2023-01-01 -e 2023-12-31 --force
+```
+
+#### 💡 通达信 (TDX) 最佳同步实践说明
+
+通达信驱动支持 **Local (离线 vipdoc 导包)** 与 **Online (在线 TCP 协议)** 两种模式。两者的输出格式和字段完全对齐，落地在同一个 `table_id` 下，数据会自动无缝去重与合并。
+
+- **Local 离线模式读取能力**：原生支持解析本地 `vipdoc` 目录下的 **日线 (`.day`)、5分钟线 (`.lc5`) 以及 1分钟线 (`.lc1`)** 等所有离线二进制文件（包含通达信软件自行下载导出的分钟线文件）。
+- **极速初始化脚本 (`cqdata tdx download`)**：用于一键拉取并解压通达信官方服务器的全量日线行情包（`hsjday.zip`），实现数十年日线历史数据的秒级导入。
+
+> [!TIP]
+> **强烈推荐的最佳实践流程**：
+> 1. **首次极速初始化（Local 模式）**：通过 `cqdata tdx download` 下载官方 `vipdoc` 日线离线包（或直接挂载本地已有的通达信客户端 `vipdoc` 目录）解析导入，秒级完成历史数据装载。
+> 2. **日常增量更新（Online 模式）**：日常收盘后直接执行在线增量同步，系统会自动根据水位线补全最新几日的增量 K 线（支持 1d / 5m / 1m）。
+
+```bash
+# 步骤 1: 极速初始化 - 下载并解压通达信官方全量日线行情包 (hsjday.zip)
+cqdata tdx download
+# 或使用 uv 直接运行下载脚本 (也可通过 --tdx-vipdoc 指定本地已有通达信客户端目录)
+uv run scripts/download_tdx.py
+
+# 步骤 2: 日常盘后增量 - 触发通达信在线按水位线追加最新数据 (支持 1d 日线 / 5m / 1m 分钟线)
+cqdata sync -t ashare.kline.1d.raw.tdx
+```
+
+**命令行关键参数：**
+- `-t` / `--tables`: 必填，要同步的表 ID，多表用逗号分隔。
+- `-f` / `--formats`: 选填，保存格式（默认 `parquet,csv`）。
+- `-s` / `--start` & `-e` / `--end`: 选填，时间范围，留空则是自动接续水位线增量同步。
+- `--force`: 选填，强制全量刷新覆盖。
+- `--limit`: 选填，限制同步代码数量（调试用）。
+
+### 方式三：使用终端交互向导 (Wizard)
+
+```bash
+cqdata wizard
+```
+
+### 方式四：一键启动服务器与 Web 终端 (支持 --open / -o 自动打开浏览器)
+```bash
+# 启动后端 API 服务并自动调起系统浏览器打开 Web 终端
+cqdata server --port 8888 --open
+
+# (也可使用 -c 指定配置文件: cqdata server -p 8888 -c ./config.yaml -o)
+```
+
+启动后内置托管 React Web 终端并提供基于 FastAPI 的 RESTful HTTP 接口（全量端点汇总）：
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/` | GET | 内置托管的 React Web 金融终端主界面 |
+| `/api/v1/health` | GET | 系统健康检查与服务运行状态探针 |
+| `/api/v1/tables` | GET | 列出本地所有数据表总览 (平铺列表，含 `category` 属性) |
+| `/api/v1/tables/{table_id}/formats` | GET | 获取指定表已存储的物理格式列表 (`['parquet', 'csv']`) |
+| `/api/v1/tables/{table_id}/symbols` | GET | 获取指定表已下载的股票/证券代码列表 |
+| `/api/v1/tables/{table_id}/time_range` | GET | 获取指定表的时间跨度 tuple `(start_datetime, end_datetime)` |
+| `/api/v1/tables/{table_id}/schema` | GET | 获取指定表的字段列名与类型字典 |
+| `/api/v1/tables/{table_id}/row_count` | GET | 获取指定表的记录总条数/行数 |
+| `/api/v1/query` | GET | 统一切片查询接口（支持 `symbols`, `start_date`, `end_date`, `columns`, `page`, `page_size`），按 `table_id` 自动智能路由，输出 `columns` 表头与 `data` 二维 List 矩阵 |
+| `/api/v1/sync` | POST | 异步触发后台数据同步任务 |
+| `/api/v1/tasks` | GET | 查询活跃同步任务状态 |
+| `/api/v1/filesystem/list` | GET | 通用本地文件与目录探查接口 (为 Web 文件探查器 Modal 提供支持) |
+
+### 方式五：前端 UI 开发与热重载调试 (`web/`)
+
+进行前端界面开发或组件调试时，可启动 Vite 热重载服务：
+
+```bash
+# 1. 启动后端 REST API 服务
+cqdata server --port 8888
+
+
+# 2. 在另一个终端启动 Vite 开发调试服务 (支持 HMR 热更新)
+cd web
+bun install
+bun dev
+```
+
+打开浏览器访问 `http://localhost:5173/` 体验 Vite HMR 极速实时编译调试。
+详细使用指南与架构说明请参阅 [docs/web_terminal_guide.md](docs/web_terminal_guide.md)。
+
+
+## 📚 相关文档 (Documentation)
+
+- [Python SDK 使用指南](docs/python_sdk_guide.md)
+- [REST API 接口文档](docs/rest_api_guide.md)
+- [React Web 终端指南](docs/web_terminal_guide.md)
+- [示例代码与脚本](examples/README.md)
+
+## 📝 许可证 (License)
+
+本项目遵循 [Apache License 2.0](LICENSE) - 详细请参阅 LICENSE 文件。
+

carrotquant_data-1.2.1.dist-info/RECORD

@@ -0,0 +1,45 @@
+cqdata/__init__.py,sha256=WEjU3GmLtD4rUjTrMPDET6vYv-eshtzdiHY3bdXWggk,1460
+cqdata/config/__init__.py,sha256=p17OON5m7vL4cKdddcVhcURIgG2Nx2LLs8r_sZNWFeA,55
+cqdata/config/settings.py,sha256=W6NIe-u_4BaEmC0AcYY632W7EcfcWBlI6oOql_UZFi8,3432
+cqdata/entrypoints/__init__.py,sha256=1bBQQUmKy981Tu8tcsgH5u-UuHe-LFZ5FZmvPw50bkk,586
+cqdata/entrypoints/cli.py,sha256=37MkCWzwic7_jMne0Ng7d5znt8YdX4WTjp5tD4Z2t1k,6986
+cqdata/entrypoints/python_api.py,sha256=re-exu10eiyIKznqa0X_TGDUcXqIMa5ZQtnWGUGOi8A,5519
+cqdata/entrypoints/rest_api.py,sha256=Blqjqd6cA6OnMIYu9Vq3ZGaNDXbQGiQ4Q2ft-CkJCE8,26519
+cqdata/entrypoints/accessors/__init__.py,sha256=KfrgaWyHllJyRAMlAEhGnLOFkqGX3AgUJz5DRpmqaMk,839
+cqdata/entrypoints/accessors/aindex.py,sha256=kjAlt-c4MeUsx0GHE4fiMRIKAXVdC3FLiZpTYtbudEQ,1932
+cqdata/entrypoints/accessors/ashare.py,sha256=iYvlRIjxc_1EeQKxMiTZAKWRJz6U7-SisppxhPC79T0,5888
+cqdata/entrypoints/accessors/base.py,sha256=i5R5O_UWbjZ_WVSCUFCnnm3sxlFh6dJvoZ1yqJ53NQU,4441
+cqdata/provider/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cqdata/provider/baostock_provider.py,sha256=fQBfmfcG4kVzR7kl4hz3s8lBDN45lWwPF4Y70d47-Mw,16752
+cqdata/provider/base.py,sha256=-myhZXCP_8Bw2QyHpbESEhA4uNb9hri6mOQFlMGZIF4,2145
+cqdata/provider/data_cleaner.py,sha256=uOefzYB1wEgAI1aZZFX_FTh_xct7whtU8KTeMGv2pnc,4647
+cqdata/provider/eastmoney_provider.py,sha256=NsHgD7ZYOl66Z5JxwDc6ikQp2HbH1q5fljEIZvbV8Xo,30817
+cqdata/provider/em_utils.py,sha256=Qi4GDuDGDLDLRJ_mUIY4w38tI3Lp-Ck9Dt9hhFdHXZQ,5294
+cqdata/provider/provider_manager.py,sha256=fhBCv7zpj6s8mjR_EfkziowzQBVaUbsZr4IXW3qW_pM,1512
+cqdata/provider/tdx_provider.py,sha256=RwyBbmS3WL_pfShiJyFUAIVHo9XaDB642F88LLCLb60,10345
+cqdata/provider/tdx_utils.py,sha256=WXGSLvjbv4N7btQEXmM9xk7IuvRr0QEDoh-X1sYjTuo,16070
+cqdata/service/__init__.py,sha256=Ty-Rju8PMatz5Ty1HEDe-XWB-8lWzJbN6J7lPdMK5Ko,22
+cqdata/service/data_reader.py,sha256=HU0h3dSKyaPedSY1NLDxwKqzd8XxBXp0OFkI28az7Xw,11258
+cqdata/service/metadata_manager.py,sha256=telEfWgdqfdrlqujRoa41qbJ3x7sKWminEeDZXGThkI,1913
+cqdata/service/metadata_reader.py,sha256=GLTt7Bt7RzSOFWzN4_dtIOo3CymPx1FxOiy_8b3hFqU,10114
+cqdata/service/sync_manager.py,sha256=lx3Y8c1msdhet6roud1xY5_dTx-qvkj-fmJyFUDhF7s,14249
+cqdata/service/sync_tracker.py,sha256=fclIyCGOgoBDSR7XEl3VcJmxEcmGnDqzrHmObQb2j2Y,4787
+cqdata/service/task_planner.py,sha256=mP0ci8JXBDhIn6Gc2M_ZYFExG9zWr7eKbbNkOhH_U7I,4343
+cqdata/static/favicon.svg,sha256=YbyaFh3lgkgojmkFQl1xgPBiTChlAHuX12P9rBIEOmY,9522
+cqdata/static/icons.svg,sha256=tF-lBhlc_N70BrqfDHezbdwafCJAQJJuxwq8L96nuTo,5031
+cqdata/static/index.html,sha256=H6K5eU5FVri-wAecR8K9FKqinh2ldD1OfNLyBN1rhzA,453
+cqdata/static/assets/index-BDBCqr4Y.js,sha256=vcbK96Wwgq-vu6lg5CnZ3iQi8CPCY61tjycC4Qkm2wQ,524158
+cqdata/static/assets/index-Cpa46ehI.css,sha256=J4a2JywT2KSMzWx-YhrqtiDjKgFDJwsZ-5njrW3q3ZY,56047
+cqdata/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cqdata/storage/base.py,sha256=3GGUwXYrkpjmf6HDnsdFh9z8et0h8ajY2ko4oqL4Pj0,3023
+cqdata/storage/csv_storage.py,sha256=ga7cCsQWWnODtZfyMyiSPjjklN-IavZy3kiAGXKCSqI,12382
+cqdata/storage/data_merger.py,sha256=FhIBhTB5Hjlxe_4IPg3cC81HYvcfi9SEWG-f7lfhQo0,2071
+cqdata/storage/parquet_storage.py,sha256=03P3wZg3CgVLQ2gjxo7_Alo0y1t0kXwUSdEZjLYW1ko,12340
+cqdata/storage/storage_factory.py,sha256=GhSYGHNORQ4BhA8ko7XQH9Jrt-G3-Kc43c-5QQqmg_0,1038
+cqdata/utils/__init__.py,sha256=2lIhukCPD_bkmyf_qrU4_LNcJbmh8PHWzEmO0oEiXg4,20
+cqdata/utils/logger_utils.py,sha256=o9ByqRluLYRPfJsXLU5iQJe8q6soc6PhQ-uABFJf6q0,5414
+cqdata/utils/time_utils.py,sha256=D9jNFNthniMHXcxUkA6GhaKGMSGRhM8OP8IMp8rMiRA,3520
+carrotquant_data-1.2.1.dist-info/METADATA,sha256=Q5HEygIIWn8QU1t4eeg2-NPdMMFrwgNXJz0pO3KM3N0,14737
+carrotquant_data-1.2.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+carrotquant_data-1.2.1.dist-info/entry_points.txt,sha256=ClCSWUAIDIjLN6LZTxcPZ3z2U_Uze4WwwCkC2_4mWuc,54
+carrotquant_data-1.2.1.dist-info/RECORD,,

carrotquant_data-1.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

carrotquant_data-1.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cqdata = cqdata.entrypoints.cli:app

cqdata/__init__.py

@@ -0,0 +1,56 @@
+"""
+CarrotQuant.Data (cqdata)
+
+轻量级、模块化的本地金融数据同步与管理工具。
+
+对外暴露的统一 Python SDK API:
+- read: 统一切片读取 K 线/分笔/板块/龙虎榜等金融数据 (自动按分类智能路由)
+- ashare / aindex: OOP 极简便捷数据访问命名空间 (如 cqdata.ashare.kline.get())
+- default: 链式默认值配置 (cqdata.default.source = "tdx")
+- configure: 全局配置函数 (支持配置文件与参数混合设置)
+- settings: 全局 Settings 实例
+- list_tables: 列出本地已有的全量数据表清单 (含 category 属性)
+- list_formats: 查看某表已有的存储格式
+- list_symbols: 查看某表已有的股票/指数代码列表
+- get_time_range: 获取某表的时间起止跨度
+- get_schema: 获取某表的字段列定义与类型
+- get_row_count: 获取某表物理存储记录条数
+- sync: 触发数据全自动同步
+"""
+
+from cqdata.entrypoints import (
+    read,
+    list_tables,
+    list_formats,
+    list_symbols,
+    get_time_range,
+    get_schema,
+    get_row_count,
+    list_boards,
+    sync,
+    configure,
+    default,
+    ashare,
+    aindex
+)
+from cqdata.config import settings
+
+__version__ = "1.2.1"
+
+__all__ = [
+    "read",
+    "list_tables",
+    "list_formats",
+    "list_symbols",
+    "get_time_range",
+    "get_schema",
+    "get_row_count",
+    "list_boards",
+    "sync",
+    "configure",
+    "default",
+    "ashare",
+    "aindex",
+    "settings",
+    "__version__"
+]

cqdata/config/__init__.py

@@ -0,0 +1,3 @@
+from .settings import settings
+
+__all__ = ["settings"]

cqdata/config/settings.py

@@ -0,0 +1,106 @@
+"""
+cqdata/config/settings.py
+
+全局配置管理模块。
+纯 Python 实现轻量 Settings，支持显式配置加载与程序化动态修改：
+1. 环境变量 CQDATA_CONFIG_PATH / CQDATA_DATA_DIR (显式指定)
+2. 显式 configure(config_path) 加载 YAML 配置文件
+3. 显式修改 cqdata.settings 属性
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, Union, Dict, Any
+import yaml
+
+
+class Settings:
+    """
+    全局 Settings 类 (纯 Python 实现，无 pydantic-settings 依赖)
+    """
+
+    def __init__(self):
+        # 核心配置字段默认值
+        self.data_dir: str = "data"
+        self.log_dir: str = "logs"
+        self.log_level: str = "INFO"
+        self.defaults: Dict[str, Any] = {}
+
+        # 初始化时自动加载配置
+        self._load_initial_config()
+
+    def _load_initial_config(self) -> None:
+        """
+        按优先级规则初始化加载配置：
+        1. 内置默认值
+        2. 环境变量 CQDATA_CONFIG_PATH 显式指定配置文件
+        3. 环境变量 CQDATA_DATA_DIR 显式覆盖 data_dir
+        """
+        # 1. 环境变量 CQDATA_CONFIG_PATH 显式指定 YAML 配置文件
+        config_path_env = os.getenv("CQDATA_CONFIG_PATH")
+        if config_path_env:
+            path = Path(config_path_env)
+            if path.exists():
+                self.load_from_file(path)
+
+        # 2. 环境变量 CQDATA_DATA_DIR 显式覆盖 data_dir
+        if os.getenv("CQDATA_DATA_DIR"):
+            self.data_dir = os.getenv("CQDATA_DATA_DIR")
+
+    def load_from_file(self, config_path: Union[str, Path]) -> "Settings":
+        """
+        显式从指定 YAML 配置文件加载配置
+        """
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+
+        with open(path, "r", encoding="utf-8") as f:
+            config_data = yaml.safe_load(f)
+
+        if isinstance(config_data, dict):
+            if "data_dir" in config_data:
+                self.data_dir = str(config_data["data_dir"])
+
+            if "log_dir" in config_data:
+                self.log_dir = str(config_data["log_dir"])
+
+            if "log_level" in config_data:
+                self.log_level = str(config_data["log_level"]).upper()
+
+            if "defaults" in config_data and isinstance(config_data["defaults"], dict):
+                self.defaults = config_data["defaults"]
+                self._update_accessor_defaults()
+
+        return self
+
+    def configure(self, config_path: Union[str, Path]) -> "Settings":
+        """
+        从指定 YAML 配置文件加载全局参数。
+
+        示例:
+            cqdata.configure("./config.yaml")
+        """
+        self.load_from_file(config_path)
+        self._refresh_logger()
+        return self
+
+    def _refresh_logger(self) -> None:
+        """配置变更后安全刷新 loggerHandler"""
+        try:
+            from cqdata.utils.logger_utils import setup_logger
+            setup_logger(log_level=self.log_level, log_dir=self.log_dir)
+        except Exception:
+            pass
+
+    def _update_accessor_defaults(self) -> None:
+        """更新全局 accessor defaults 链"""
+        try:
+            from cqdata.entrypoints.accessors import default
+            default.update_from_dict(self.defaults)
+        except (ImportError, AttributeError):
+            pass
+
+
+# 全局 Settings 单例实例
+settings = Settings()

cqdata/entrypoints/__init__.py

@@ -0,0 +1,39 @@
+"""
+cqdata/entrypoints/__init__.py
+
+网关层统一导出
+"""
+
+from cqdata.entrypoints.python_api import (
+    read,
+    list_tables,
+    list_formats,
+    list_symbols,
+    get_time_range,
+    get_schema,
+    get_row_count,
+    list_boards,
+    sync,
+    configure
+)
+from cqdata.entrypoints.accessors import (
+    default,
+    ashare,
+    aindex
+)
+
+__all__ = [
+    "read",
+    "list_tables",
+    "list_formats",
+    "list_symbols",
+    "get_time_range",
+    "get_schema",
+    "get_row_count",
+    "list_boards",
+    "sync",
+    "configure",
+    "default",
+    "ashare",
+    "aindex"
+]

cqdata/entrypoints/accessors/__init__.py

@@ -0,0 +1,38 @@
+"""
+cqdata/entrypoints/accessors/__init__.py
+
+OOP 便捷访问层包导出。
+向外导出 default, ashare, aindex 单例与主要访问类。
+"""
+
+from cqdata.entrypoints.accessors.base import DefaultConfig, default
+from cqdata.entrypoints.accessors.ashare import (
+    AShare,
+    AShareKline,
+    AShareAdjFactor,
+    AShareConcept,
+    AShareIndustry,
+    AShareDragonTiger,
+    AShareInstTrade
+)
+from cqdata.entrypoints.accessors.aindex import AIndex, AIndexKline
+
+# 实例化命名空间单例
+ashare = AShare(parent_default=default)
+aindex = AIndex(parent_default=default)
+
+__all__ = [
+    "DefaultConfig",
+    "default",
+    "ashare",
+    "aindex",
+    "AShare",
+    "AIndex",
+    "AShareKline",
+    "AShareAdjFactor",
+    "AShareConcept",
+    "AShareIndustry",
+    "AShareDragonTiger",
+    "AShareInstTrade",
+    "AIndexKline",
+]