etf-flow 0.1.0__py3-none-any.whl

etf_flow/__init__.py

@@ -0,0 +1,172 @@
+"""ETF Flow - 高性能 ETF 资金流动跟踪、成分股被动买盘测算与利好选股推荐量化库.
+
+统一顶层模块导出 (Python Library Public API).
+"""
+
+from __future__ import annotations
+
+# 1. 标的池与分类 (Universe)
+from etf_flow.universe import (
+    ETFMeta,
+    TRACKED_ETFS,
+    ETF_MAP,
+    get_tracked_codes,
+    get_dynamic_etf_universe,
+    get_sector_etf_mapping,
+    classify_etf,
+)
+
+# 2. 每日 PCF 100% 成分股穿透 (PCF)
+from etf_flow.pcf import (
+    PCFConstituent,
+    fetch_and_cache_etf_pcf,
+    get_pcf_stock_weights,
+    build_full_pcf_index,
+)
+
+# 3. 沪深双交易所官方定盘份额对账 (Scale)
+from etf_flow.scale import (
+    fetch_sse_etf_shares,
+    fetch_szse_etf_shares,
+    get_dual_exchange_etf_shares,
+    get_etf_share_deltas,
+)
+
+# 4. 法定季报与持仓时序穿透 (Holdings)
+from etf_flow.holdings import (
+    StockHoldingInETF,
+    StockETFProfile,
+    fetch_etf_portfolio_holdings,
+    build_stock_etf_index,
+)
+
+# 5. 日K定盘折溢价时序与一二级套利沉淀 (Arbitrage)
+from etf_flow.arbitrage import (
+    SettledDailyPremium,
+    ArbitrageSettlementSignal,
+    get_settled_etf_nav_and_close,
+    fetch_official_etf_nav_history,
+    get_settled_premium_history,
+    analyze_settled_arbitrage_flow,
+    scan_market_arbitrage_settlement,
+)
+
+# 6. 流动性冲击度与承接天数模型 (Impact)
+from etf_flow.impact import (
+    StockImpactMetrics,
+    get_stock_adv20,
+    calculate_stock_liquidity_impact,
+    format_kdata_symbol,
+)
+
+# 7. 指数定期调样“前置预判”引擎 (Rebalance)
+from etf_flow.rebalance import (
+    RebalanceCandidate,
+    IndexRebalanceForecast,
+    calculate_rebalance_countdown,
+    predict_index_rebalance,
+    render_rebalance_markdown,
+)
+
+# 8. 资金性质归因与踩踏反噬哨兵 (Sentinel)
+from etf_flow.sentinel import (
+    CapitalAttribution,
+    LiquidityTrapAlert,
+    attribute_etf_capital_flow,
+    detect_liquidity_trap,
+)
+
+# 9. 核心选股推荐与多因子评分 (Recommender)
+from etf_flow.recommender import (
+    StockRecommendation,
+    calculate_etf_flow_delta,
+    scan_and_recommend_stocks,
+    render_recommendations_markdown,
+)
+
+# 10. 事件研究回测引擎 (Backtest)
+from etf_flow.backtest import (
+    EventStudySample,
+    CapacityDecayPoint,
+    EventStudyResult,
+    EventStudyEngine,
+    calculate_real_event_car,
+    render_event_study_markdown,
+)
+
+# 11. 腾讯高速行情通道 (Tencent)
+from etf_flow.tencent import (
+    TencentQuote,
+    get_tencent_quotes,
+    to_tencent_symbol,
+)
+
+__version__ = "2.1.0"
+
+__all__ = [
+    # Universe
+    "ETFMeta",
+    "TRACKED_ETFS",
+    "ETF_MAP",
+    "get_tracked_codes",
+    "get_dynamic_etf_universe",
+    "get_sector_etf_mapping",
+    "classify_etf",
+    # PCF
+    "PCFConstituent",
+    "fetch_and_cache_etf_pcf",
+    "get_pcf_stock_weights",
+    "build_full_pcf_index",
+    # Scale
+    "fetch_sse_etf_shares",
+    "fetch_szse_etf_shares",
+    "get_dual_exchange_etf_shares",
+    "get_etf_share_deltas",
+    # Holdings
+    "StockHoldingInETF",
+    "StockETFProfile",
+    "fetch_etf_portfolio_holdings",
+    "build_stock_etf_index",
+    # Arbitrage
+    "SettledDailyPremium",
+    "ArbitrageSettlementSignal",
+    "get_settled_etf_nav_and_close",
+    "fetch_official_etf_nav_history",
+    "get_settled_premium_history",
+    "analyze_settled_arbitrage_flow",
+    "scan_market_arbitrage_settlement",
+    # Impact
+    "StockImpactMetrics",
+    "get_stock_adv20",
+    "calculate_stock_liquidity_impact",
+    "format_kdata_symbol",
+    # Rebalance
+    "RebalanceCandidate",
+    "IndexRebalanceForecast",
+    "calculate_rebalance_countdown",
+    "predict_index_rebalance",
+    "render_rebalance_markdown",
+    # Sentinel
+    "CapitalAttribution",
+    "LiquidityTrapAlert",
+    "attribute_etf_capital_flow",
+    "detect_liquidity_trap",
+    # Recommender
+    "StockRecommendation",
+    "calculate_etf_flow_delta",
+    "scan_and_recommend_stocks",
+    "render_recommendations_markdown",
+    # Backtest
+    "EventStudySample",
+    "CapacityDecayPoint",
+    "EventStudyResult",
+    "EventStudyEngine",
+    "calculate_real_event_car",
+    "render_event_study_markdown",
+    # Tencent
+    "TencentQuote",
+    "get_tencent_quotes",
+    "to_tencent_symbol",
+    # Version
+    "__version__",
+]

etf_flow/api.py

@@ -0,0 +1,251 @@
+"""ETF Tracker - REST API & OpenAPI 微服务网关 (PRD F5.3).
+
+提供基于 FastAPI 的高性能微服务接口：
+1. GET /api/v1/health: 服务健康检查与 18:30 官方定盘时钟状态；
+2. GET /api/v1/universe: 获取全市场动态/核心 ETF 标的池；
+3. GET /api/v1/recommendations: 获取最新推荐池 (支持 top_n, scenario 过滤)；
+4. GET /api/v1/stock/{code}/profile: 获取指定个股的完整 ETF 挂钩穿透画像；
+5. GET /api/v1/etf/{code}/flow: 获取单只 ETF 的份额变动与买盘传导；
+6. GET /api/v1/arbitrage/{code}: 获取单只 ETF 的日K定盘折溢价时序与套利沉淀分析；
+7. GET /api/v1/backtest/event-study: 运行事件研究回测并返回 CAR 时序与容量衰减指标。
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from pydantic import BaseModel
+
+import kdata
+from etf_flow.arbitrage import (
+    analyze_settled_arbitrage_flow,
+    scan_market_arbitrage_settlement,
+)
+from etf_flow.backtest import EventStudyEngine
+from etf_flow.holdings import build_stock_etf_index
+from etf_flow.recommender import scan_and_recommend_stocks
+from etf_flow.scale import get_etf_share_deltas
+from etf_flow.universe import (
+    TRACKED_ETFS,
+    get_dynamic_etf_universe,
+    get_tracked_codes,
+)
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(
+    title="ETF Tracker 量化接口网关",
+    description="全市场 ETF 资金流动穿透、成分股被动买盘测算、折溢价套利沉淀与事件研究回测 API",
+    version="2.1.0",
+)
+
+
+@app.get("/")
+def root() -> Dict[str, Any]:
+    """API 根路径导航."""
+    return {
+        "service": "ETF Tracker REST API Gateway",
+        "version": "2.1.0",
+        "docs_url": "/docs",
+        "settled_bar_principle": "立足每日 18:30 官方定盘日K及以上周期，杜绝盘中未结算噪音",
+    }
+
+
+@app.get("/api/v1/health")
+def get_health() -> Dict[str, Any]:
+    """系统健康检查与交易定盘时钟状态."""
+    today_str = date.today().isoformat()
+    is_trade = kdata.is_trade_date(today_str)
+    now_hour = datetime.now().hour
+    now_minute = datetime.now().minute
+    is_settled = (now_hour > 18) or (now_hour == 18 and now_minute >= 30)
+
+    return {
+        "status": "healthy",
+        "date": today_str,
+        "is_trade_date": is_trade,
+        "current_time": datetime.now().strftime("%H:%M:%S"),
+        "settled_clock_status": "已定盘 (权威定盘数据生效)" if is_settled else "待18:30官方定盘",
+    }
+
+
+@app.get("/api/v1/universe")
+def get_universe(
+    category: str = Query("all", description="分类: all | broad | sector"),
+    dynamic: bool = Query(False, description="是否返回动态全市场池 (>800只候选)"),
+) -> Dict[str, Any]:
+    """获取当前跟踪的 ETF 标的池."""
+    if dynamic:
+        pool = get_dynamic_etf_universe(category=category)
+    else:
+        codes = get_tracked_codes(category)
+        pool = [e for e in TRACKED_ETFS if e.code in codes]
+
+    items = [
+        {
+            "code": e.code,
+            "name": e.name,
+            "category": e.category,
+            "benchmark": e.benchmark,
+            "scale_yi": getattr(e, "scale_yi", 0.0),
+            "industry": getattr(e, "industry", ""),
+        }
+        for e in pool
+    ]
+    return {
+        "total": len(items),
+        "category": category,
+        "dynamic": dynamic,
+        "items": items,
+    }
+
+
+@app.get("/api/v1/recommendations")
+def get_recommendations(
+    top_n: int = Query(5, ge=1, le=50, description="推荐数量"),
+    scenario: Optional[int] = Query(None, ge=1, le=5, description="场景筛选 (1~5)"),
+    min_elasticity: float = Query(300.0, description="最低单亿申购弹性 (万元/亿)"),
+) -> Dict[str, Any]:
+    """全市场扫描 ETF 资金流动并输出最新利好股票推荐池 (PRD F5.3)."""
+    try:
+        recs = scan_and_recommend_stocks(
+            top_n=top_n,
+            scenario_filter=scenario,
+            min_elasticity=min_elasticity,
+        )
+        return {
+            "success": True,
+            "count": len(recs),
+            "scenario_filter": scenario,
+            "recommendations": [r.__dict__ for r in recs],
+        }
+    except Exception as e:
+        logger.error("扫描推荐股票异常: %s", e)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/stock/{code}/profile")
+def get_stock_profile(code: str) -> Dict[str, Any]:
+    """获取指定个股的完整 ETF 挂钩穿透画像 (PRD F5.3)."""
+    clean_code = str(code).strip().replace("sh.", "").replace("sz.", "").replace("bj.", "")
+    try:
+        stock_index = build_stock_etf_index(tracked_etfs=TRACKED_ETFS, use_pcf=True)
+        profile = stock_index.get(clean_code)
+        if not profile:
+            name = (
+                kdata.get_name_from_code(f"sh.{clean_code}" if clean_code.startswith("6") else f"sz.{clean_code}")
+                or clean_code
+            )
+            return {
+                "stock_code": clean_code,
+                "stock_name": name,
+                "linked_etf_count": 0,
+                "total_weight_sum": 0.0,
+                "max_weight": 0.0,
+                "holdings": [],
+                "message": "当前未在核心跟踪 ETF 的重仓或 PCF 篮子中出现",
+            }
+
+        holdings_data = [
+            {
+                "etf_code": h.etf_code,
+                "etf_name": h.etf_name,
+                "category": h.category,
+                "weight_pct": h.weight_pct,
+                "prev_weight_pct": h.prev_weight_pct,
+                "delta_weight_pct": h.delta_weight_pct,
+                "shares_wan": h.shares_wan,
+                "mkt_val_wan": h.mkt_val_wan,
+                "latest_quarter": str(h.latest_quarter),
+                "source": getattr(h, "source", "quarterly"),
+            }
+            for h in profile.holdings
+        ]
+        return {
+            "stock_code": profile.stock_code,
+            "stock_name": profile.stock_name,
+            "linked_etf_count": profile.linked_etf_count,
+            "total_weight_sum": round(profile.total_weight_sum, 2),
+            "max_weight": round(profile.max_weight, 2),
+            "max_delta_weight": round(profile.max_delta_weight, 2),
+            "holdings": holdings_data,
+        }
+    except Exception as e:
+        logger.error("查询个股 %s 穿透画像异常: %s", clean_code, e)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/etf/{code}/flow")
+def get_etf_flow(code: str) -> Dict[str, Any]:
+    """查询单只 ETF 的日频官方份额变动与买盘流动测算."""
+    clean_code = str(code).strip()
+    try:
+        deltas = get_etf_share_deltas([clean_code])
+        flow_info = deltas.get(clean_code, {})
+        return {
+            "etf_code": clean_code,
+            "date": date.today().isoformat(),
+            "shares_info": flow_info,
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/arbitrage/{code}")
+def get_etf_arbitrage(code: str) -> Dict[str, Any]:
+    """查询单只 ETF 的日K收盘折溢价时序与一二级市场申赎套利沉淀信号 (PRD F1.3)."""
+    clean_code = str(code).strip()
+    try:
+        sig = analyze_settled_arbitrage_flow(clean_code)
+        return {
+            "etf_code": sig.etf_code,
+            "etf_name": sig.etf_name,
+            "settled_date": sig.settled_date,
+            "latest_close": sig.latest_close,
+            "latest_nav": sig.latest_nav,
+            "latest_premium_rate_pct": sig.latest_premium_rate_pct,
+            "avg_premium_rate_3d": sig.avg_premium_rate_3d,
+            "signal_type": sig.signal_type,
+            "signal_desc": sig.signal_desc,
+            "streak_days": sig.streak_days,
+            "arbitrage_pressure_wan": sig.arbitrage_pressure_wan,
+            "constituents_impact_desc": sig.constituents_impact_desc,
+            "risk_level": sig.risk_level,
+            "history": [h.__dict__ for h in sig.history],
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/backtest/event-study")
+def get_event_study(
+    event_type: str = Query("A", description="事件类型: A | B | C"),
+) -> Dict[str, Any]:
+    """运行事件研究回测并返回超额收益 CAR、胜率与容量衰减曲线 (PRD F4.1)."""
+    try:
+        engine = EventStudyEngine()
+        res = engine.run_event_study(event_type=event_type)
+        return {
+            "event_type": res.event_type,
+            "event_title": res.event_title,
+            "total_events": res.total_events,
+            "benchmark": res.benchmark,
+            "car_timeline": {
+                "T+1": res.mean_car_t1,
+                "T+3": res.mean_car_t3,
+                "T+5": res.mean_car_t5,
+                "T+10": res.mean_car_t10,
+                "T+20": res.mean_car_t20,
+            },
+            "win_rate_pct": res.win_rate_pct,
+            "profit_loss_ratio": res.profit_loss_ratio,
+            "max_drawdown_pct": res.max_drawdown_pct,
+            "capacity_decay": [c.__dict__ for c in res.capacity_decay],
+            "samples": [s.__dict__ for s in res.samples],
+            "summary_desc": res.summary_desc,
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))