liaozhaorun
aefe6d06cf
- 新增 sync_registry.py 模块，提供统一的同步任务注册和管理机制 - 在 api_wrappers/__init__.py 中实现自动注册逻辑，新增接口无需修改 sync.py - 重构 sync_all_data() 函数，使用注册表模式替代手动罗列，代码从 400+ 行精简至 293 行 - 新增 selected 参数，支持选择性执行特定同步任务 - 新增 list_sync_tasks() 函数，方便查看所有已注册任务
292 lines
9.7 KiB
Python
292 lines
9.7 KiB
Python
"""数据同步调度中心模块。
|
||
|
||
该模块作为数据同步的调度中心，统一管理各类型数据的同步流程。
|
||
|
||
【重要规范 - sync.py 职责范围】
|
||
本模块**仅包含每日更新的数据接口**，季度/低频数据不应放入此文件：
|
||
|
||
✅ 本模块包含的同步逻辑（每日更新）：
|
||
- api_daily.py: 日线数据同步 (DailySync 类)
|
||
- api_daily_basic.py: 每日指标数据同步 (DailyBasicSync 类)
|
||
- api_bak_basic.py: 历史股票列表同步 (BakBasicSync 类)
|
||
- api_pro_bar.py: Pro Bar 数据同步 (ProBarSync 类)
|
||
- api_stock_basic.py: 股票基本信息同步
|
||
- api_trade_cal.py: 交易日历同步
|
||
|
||
❌ 不应包含的同步逻辑（季度/低频更新）：
|
||
- financial_data/: 财务数据（利润表、资产负债表、现金流量表等）
|
||
使用方式：
|
||
from src.data.api_wrappers.financial_data.api_financial_sync import sync_financial
|
||
sync_financial()
|
||
|
||
- api_namechange.py: 股票名称变更（不频繁）
|
||
使用方式：
|
||
from src.data.api_wrappers import sync_namechange
|
||
sync_namechange(force=True)
|
||
|
||
【架构说明】
|
||
本模块使用 SyncRegistry 注册表模式管理同步任务，避免手动罗列各个接口。
|
||
同步任务在 api_wrappers/__init__.py 中自动注册，新增接口无需修改 sync.py。
|
||
|
||
使用方式：
|
||
# 预览同步（检查数据量，不写入）
|
||
from src.data.sync import preview_sync
|
||
preview = preview_sync()
|
||
|
||
# 同步所有每日更新数据（不包括财务数据、namechange）
|
||
from src.data.sync import sync_all_data
|
||
result = sync_all_data()
|
||
|
||
# 强制全量重载
|
||
result = sync_all_data(force_full=True)
|
||
|
||
# 查看已注册的所有同步任务
|
||
from src.data.sync_registry import sync_registry
|
||
tasks = sync_registry.list_tasks()
|
||
for task in tasks:
|
||
print(f"{task.name}: {task.display_name}")
|
||
"""
|
||
|
||
from typing import Optional, Dict, Union, Any
|
||
|
||
import pandas as pd
|
||
|
||
# 导入以触发自动注册
|
||
from src.data import api_wrappers # noqa: F401
|
||
from src.data.sync_registry import sync_registry
|
||
from src.data.api_wrappers import sync_all_stocks
|
||
from src.data.api_wrappers.api_daily import sync_daily, preview_daily_sync
|
||
|
||
|
||
def preview_sync(
|
||
force_full: bool = False,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
sample_size: int = 3,
|
||
max_workers: Optional[int] = None,
|
||
) -> dict[str, Any]:
|
||
"""预览日线同步数据量和样本（不实际同步）。
|
||
|
||
这是推荐的方式，可在实际同步前检查将要同步的内容。
|
||
|
||
Args:
|
||
force_full: 若为 True，预览全量同步（从 20180101）
|
||
start_date: 手动指定起始日期（覆盖自动检测）
|
||
end_date: 手动指定结束日期（默认为今天）
|
||
sample_size: 预览用样本股票数量（默认: 3）
|
||
max_workers: 工作线程数（默认: 10）
|
||
|
||
Returns:
|
||
包含预览信息的字典：
|
||
{
|
||
'sync_needed': bool,
|
||
'stock_count': int,
|
||
'start_date': str,
|
||
'end_date': str,
|
||
'estimated_records': int,
|
||
'sample_data': pd.DataFrame,
|
||
'mode': str, # 'full', 'incremental', 'partial', 或 'none'
|
||
}
|
||
|
||
Example:
|
||
>>> # 预览将要同步的内容
|
||
>>> preview = preview_sync()
|
||
>>>
|
||
>>> # 预览全量同步
|
||
>>> preview = preview_sync(force_full=True)
|
||
>>>
|
||
>>> # 预览更多样本
|
||
>>> preview = preview_sync(sample_size=5)
|
||
"""
|
||
return preview_daily_sync(
|
||
force_full=force_full,
|
||
start_date=start_date,
|
||
end_date=end_date,
|
||
sample_size=sample_size,
|
||
)
|
||
|
||
|
||
def sync_all(
|
||
force_full: bool = False,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
max_workers: Optional[int] = None,
|
||
dry_run: bool = False,
|
||
) -> dict[str, pd.DataFrame]:
|
||
"""同步所有股票的日线数据。
|
||
|
||
这是日线数据同步的主要入口点。
|
||
|
||
Args:
|
||
force_full: 若为 True，强制从 20180101 完整重载
|
||
start_date: 手动指定起始日期（YYYYMMDD）
|
||
end_date: 手动指定结束日期（默认为今天）
|
||
max_workers: 工作线程数（默认: 10）
|
||
dry_run: 若为 True，仅预览将要同步的内容，不写入数据
|
||
|
||
Returns:
|
||
映射 ts_code 到 DataFrame 的字典
|
||
|
||
Example:
|
||
>>> # 首次同步（从 20180101 全量加载）
|
||
>>> result = sync_all()
|
||
>>>
|
||
>>> # 后续同步（增量 - 仅新数据）
|
||
>>> result = sync_all()
|
||
>>>
|
||
>>> # 强制完整重载
|
||
>>> result = sync_all(force_full=True)
|
||
>>>
|
||
>>> # 手动指定日期范围
|
||
>>> result = sync_all(start_date='20240101', end_date='20240131')
|
||
>>>
|
||
>>> # 自定义线程数
|
||
>>> result = sync_all(max_workers=20)
|
||
>>>
|
||
>>> # Dry run（仅预览）
|
||
>>> result = sync_all(dry_run=True)
|
||
"""
|
||
return sync_daily(
|
||
force_full=force_full,
|
||
start_date=start_date,
|
||
end_date=end_date,
|
||
max_workers=max_workers,
|
||
dry_run=dry_run,
|
||
)
|
||
|
||
|
||
def sync_all_data(
|
||
force_full: bool = False,
|
||
max_workers: Optional[int] = None,
|
||
dry_run: bool = False,
|
||
selected: Optional[list[str]] = None,
|
||
) -> dict[str, Any]:
|
||
"""同步所有每日更新的数据类型。
|
||
|
||
【重要】本函数仅同步每日更新的数据，不包含季度/低频数据。
|
||
|
||
【自动注册机制】
|
||
同步任务在 api_wrappers/__init__.py 中自动注册到 SyncRegistry。
|
||
当前注册的同步任务（按执行顺序）：
|
||
1. trade_cal: 交易日历缓存
|
||
2. stock_basic: 股票基本信息
|
||
3. pro_bar: Pro Bar 数据（复权、换手率、量比）
|
||
4. daily_basic: 每日指标（PE、PB、换手率、市值）
|
||
5. bak_basic: 历史股票列表
|
||
6. stock_st: ST股票列表
|
||
|
||
新增接口时，只需在 api_wrappers/__init__.py 中添加注册代码，
|
||
无需修改本函数。
|
||
|
||
【不包含的同步（需单独调用）】
|
||
- 财务数据: 利润表、资产负债表、现金流量表（季度更新）
|
||
使用: from src.data.api_wrappers.financial_data.api_financial_sync import sync_financial
|
||
调用: sync_financial()
|
||
|
||
- 名称变更 (namechange): 股票曾用名（低频更新）
|
||
使用: from src.data.api_wrappers import sync_namechange
|
||
调用: sync_namechange(force=True)
|
||
|
||
Args:
|
||
force_full: 若为 True，强制所有数据类型完整重载
|
||
max_workers: 日线数据同步的工作线程数（默认: 10）
|
||
dry_run: 若为 True，仅显示将要同步的内容，不写入数据
|
||
selected: 只同步指定的任务列表，None表示同步所有
|
||
例如: selected=["trade_cal", "stock_basic"] 只同步交易日历和股票基本信息
|
||
|
||
Returns:
|
||
映射数据类型到同步结果的字典
|
||
|
||
Example:
|
||
>>> result = sync_all_data()
|
||
>>>
|
||
>>> # 强制完整重载
|
||
>>> result = sync_all_data(force_full=True)
|
||
>>>
|
||
>>> # Dry run
|
||
>>> result = sync_all_data(dry_run=True)
|
||
>>>
|
||
>>> # 只同步特定任务
|
||
>>> result = sync_all_data(selected=["trade_cal", "stock_basic"])
|
||
>>>
|
||
>>> # 查看所有可用任务
|
||
>>> from src.data.sync_registry import sync_registry
|
||
>>> tasks = sync_registry.list_tasks()
|
||
>>> for t in tasks:
|
||
... print(f"{t.name}: {t.display_name}")
|
||
"""
|
||
return sync_registry.sync_all(
|
||
force_full=force_full,
|
||
max_workers=max_workers,
|
||
dry_run=dry_run,
|
||
selected=selected,
|
||
)
|
||
|
||
|
||
def list_sync_tasks() -> list[dict[str, Any]]:
|
||
"""列出所有已注册的同步任务。
|
||
|
||
Returns:
|
||
任务信息列表，每个任务包含 name, display_name, description, order, enabled
|
||
|
||
Example:
|
||
>>> tasks = list_sync_tasks()
|
||
>>> for task in tasks:
|
||
... print(f"{task['order']:2d}. {task['name']}: {task['display_name']}")
|
||
"""
|
||
tasks = sync_registry.list_tasks()
|
||
return [
|
||
{
|
||
"name": t.name,
|
||
"display_name": t.display_name,
|
||
"description": t.description,
|
||
"order": t.order,
|
||
"enabled": t.enabled,
|
||
}
|
||
for t in tasks
|
||
]
|
||
|
||
|
||
if __name__ == "__main__":
|
||
print("=" * 60)
|
||
print("Data Sync Module")
|
||
print("=" * 60)
|
||
print("\nRegistered sync tasks:")
|
||
print("-" * 60)
|
||
|
||
tasks = list_sync_tasks()
|
||
for task in tasks:
|
||
status = "[启用]" if task["enabled"] else "[禁用]"
|
||
print(f" {status} {task['order']:2d}. {task['name']}: {task['display_name']}")
|
||
|
||
print("-" * 60)
|
||
print(f"\nTotal: {len(tasks)} tasks")
|
||
print("\nUsage:")
|
||
print(" # Sync all data types at once (RECOMMENDED)")
|
||
print(" from src.data.sync import sync_all_data")
|
||
print(" result = sync_all_data() # Incremental sync all")
|
||
print(" result = sync_all_data(force_full=True) # Full reload")
|
||
print("")
|
||
print(" # Sync selected data types only")
|
||
print(" result = sync_all_data(selected=['trade_cal', 'pro_bar'])")
|
||
print("")
|
||
print(" # List all available sync tasks")
|
||
print(" tasks = list_sync_tasks()")
|
||
print("")
|
||
print(" # Preview before sync (recommended)")
|
||
print(" preview = preview_sync()")
|
||
print("")
|
||
print(" # Dry run (preview only)")
|
||
print(" result = sync_all(dry_run=True)")
|
||
print("")
|
||
print(" # Actual sync")
|
||
print(" result = sync_all() # Incremental sync")
|
||
print(" result = sync_all(force_full=True) # Full reload")
|
||
print("\n" + "=" * 60)
|
||
|
||
# Run sync_all_data by default
|
||
print("\n[Main] Running sync_all_data()...")
|
||
result = sync_all_data()
|
||
print("\n[Main] Sync completed!")
|
||
print(f"Total data types synced: {len(result)}")
|