stock-analysis-plugin 0.2.4 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -11
- package/package.json +1 -1
- package/pi/index.ts +185 -9
- package/skills/event-driven/SKILL.md +6 -0
- package/skills/growth-quality/SKILL.md +6 -0
- package/skills/stock-analysis/SKILL.md +22 -0
- package/skills/stock-screener/SKILL.md +18 -0
- package/skills/strategy-backtest/SKILL.md +2 -0
- package/tools/_cache.py +61 -0
- package/tools/capabilities.py +9 -0
- package/tools/diagnostics.py +6 -0
- package/tools/screener.py +54 -2
- package/tools/stock_data.py +241 -99
- package/tools/value_data.py +1368 -0
|
@@ -0,0 +1,1368 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Dated valuation, ownership, fund and dividend data for low-frequency research."""
|
|
3
|
+
|
|
4
|
+
import argparse
|
|
5
|
+
import json
|
|
6
|
+
import os
|
|
7
|
+
import re
|
|
8
|
+
import sys
|
|
9
|
+
from datetime import date, timedelta
|
|
10
|
+
from io import StringIO
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
from urllib.parse import unquote
|
|
13
|
+
from xml.etree import ElementTree
|
|
14
|
+
|
|
15
|
+
import numpy as np
|
|
16
|
+
import pandas as pd
|
|
17
|
+
|
|
18
|
+
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
19
|
+
from _cache import DAY, cached
|
|
20
|
+
from _subproc import scrub_secrets, socket_timeout, utf8_stdio
|
|
21
|
+
from stock_data import _A_INDEX_RE, _cn_code, _yf_hk_symbol, detect_market, normalize_stock_code
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def records(frame):
|
|
25
|
+
if frame is None:
|
|
26
|
+
raise ValueError("provider returned no dataset")
|
|
27
|
+
return json.loads(frame.to_json(orient="records", date_format="iso"))
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def dataset(key, fetch):
|
|
31
|
+
return cached(key, DAY, lambda: records(fetch()))
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def number(value):
|
|
35
|
+
value = pd.to_numeric(value, errors="coerce")
|
|
36
|
+
return float(value) if pd.notna(value) and np.isfinite(value) else None
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def iso(value):
|
|
40
|
+
parsed = pd.to_datetime(value, errors="coerce")
|
|
41
|
+
if pd.notna(parsed) and parsed.tzinfo is not None:
|
|
42
|
+
parsed = parsed.tz_convert("Asia/Shanghai")
|
|
43
|
+
return parsed.date().isoformat() if pd.notna(parsed) else None
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def capture(result, key, fetch):
|
|
47
|
+
try:
|
|
48
|
+
result[key] = fetch()
|
|
49
|
+
except Exception as exc:
|
|
50
|
+
result.setdefault("warnings", []).append(f"{key}: unavailable ({type(exc).__name__})")
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def stock_identity(symbol):
|
|
54
|
+
market = detect_market(symbol)
|
|
55
|
+
if _A_INDEX_RE.fullmatch(symbol):
|
|
56
|
+
raise ValueError("explicit index symbol is not a stock; use index_valuation")
|
|
57
|
+
if market == "A":
|
|
58
|
+
return market, _cn_code(symbol)[2:]
|
|
59
|
+
if market == "HK" and re.fullmatch(r"\d{1,5}\.HK", symbol, re.I):
|
|
60
|
+
return market, symbol.split(".")[0].zfill(5)
|
|
61
|
+
raise ValueError("an A/HK stock symbol is required")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def valuation_summary(history, field):
|
|
65
|
+
dated = [r for r in history if r.get("date") and number(r.get(field)) is not None]
|
|
66
|
+
dated.sort(key=lambda r: r["date"])
|
|
67
|
+
valid = pd.Series([number(r[field]) for r in dated if number(r[field]) > 0], dtype=float)
|
|
68
|
+
current = number(dated[-1][field]) if dated else None
|
|
69
|
+
return {
|
|
70
|
+
"current": current,
|
|
71
|
+
"as_of": dated[-1]["date"] if dated else None,
|
|
72
|
+
"samples": len(valid),
|
|
73
|
+
"window_start": dated[0]["date"] if dated else None,
|
|
74
|
+
"window_end": dated[-1]["date"] if dated else None,
|
|
75
|
+
"percentile": round(float(valid.le(current).mean() * 100), 4)
|
|
76
|
+
if len(valid) and current is not None and current > 0
|
|
77
|
+
else None,
|
|
78
|
+
"percentile_method": "percentage of positive observations <= current",
|
|
79
|
+
"bands": {str(q): round(float(valid.quantile(q / 100)), 4) for q in [10, 25, 50, 75, 90]} if len(valid) else {},
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def valuation_history(args):
|
|
84
|
+
import akshare as ak
|
|
85
|
+
|
|
86
|
+
market, symbol = stock_identity(args.symbol)
|
|
87
|
+
if not 1 <= args.years <= 10:
|
|
88
|
+
raise ValueError("valuation history requires an A/HK symbol and years in 1..10")
|
|
89
|
+
fetch = ak.stock_zh_valuation_baidu if market == "A" else ak.stock_hk_valuation_baidu
|
|
90
|
+
period = "近一年" if args.years == 1 else "近三年" if args.years <= 3 else "近五年" if args.years <= 5 else "近十年"
|
|
91
|
+
if market == "HK" and args.years > 3:
|
|
92
|
+
period = "全部"
|
|
93
|
+
result = {"symbol": args.symbol, "market": market, "source": "baidu", "requested_years": args.years}
|
|
94
|
+
series = {}
|
|
95
|
+
for field, indicator in [("pe_ttm", "市盈率(TTM)"), ("pb", "市净率")]:
|
|
96
|
+
capture(
|
|
97
|
+
series,
|
|
98
|
+
field,
|
|
99
|
+
lambda indicator=indicator: dataset(
|
|
100
|
+
f"valuation:{market}:{symbol}:{indicator}:{period}",
|
|
101
|
+
lambda: fetch(symbol=symbol, indicator=indicator, period=period),
|
|
102
|
+
),
|
|
103
|
+
)
|
|
104
|
+
merged = {}
|
|
105
|
+
cutoff = (date.today() - timedelta(days=365.25 * args.years)).isoformat()
|
|
106
|
+
for field in ("pe_ttm", "pb"):
|
|
107
|
+
for row in series.get(field, []):
|
|
108
|
+
stamp = iso(row.get("date"))
|
|
109
|
+
if stamp and stamp >= cutoff:
|
|
110
|
+
merged.setdefault(stamp, {"date": stamp})[field] = number(row.get("value"))
|
|
111
|
+
history = sorted(merged.values(), key=lambda r: r["date"])
|
|
112
|
+
if not history:
|
|
113
|
+
raise ValueError("no valuation history available")
|
|
114
|
+
result.update(history=history, metrics={field: valuation_summary(history, field) for field in ("pe_ttm", "pb")})
|
|
115
|
+
if series.get("warnings"):
|
|
116
|
+
result["warnings"] = series["warnings"]
|
|
117
|
+
return result
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
INDEX_NAMES = {
|
|
121
|
+
"000300": "沪深300",
|
|
122
|
+
"000905": "中证500",
|
|
123
|
+
"000852": "中证1000",
|
|
124
|
+
"000906": "中证800",
|
|
125
|
+
"000016": "上证50",
|
|
126
|
+
"000985": "中证全指",
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def lixinger_index_history(code, start, end):
|
|
131
|
+
import requests
|
|
132
|
+
|
|
133
|
+
def fetch():
|
|
134
|
+
response = requests.post(
|
|
135
|
+
"https://open.lixinger.com/api/cn/index/fundamental",
|
|
136
|
+
json={
|
|
137
|
+
"token": os.environ["LIXINGER_TOKEN"],
|
|
138
|
+
"stockCodes": [code],
|
|
139
|
+
"startDate": start,
|
|
140
|
+
"endDate": end,
|
|
141
|
+
"metricsList": ["pe_ttm.mcw", "pb.mcw"],
|
|
142
|
+
},
|
|
143
|
+
timeout=20,
|
|
144
|
+
)
|
|
145
|
+
response.raise_for_status()
|
|
146
|
+
payload = response.json()
|
|
147
|
+
if payload.get("code") != 1:
|
|
148
|
+
raise ValueError("Lixinger index data unavailable; check token permissions")
|
|
149
|
+
rows = [
|
|
150
|
+
{"date": iso(r.get("date")), "pe_ttm": number(r.get("pe_ttm.mcw")), "pb": number(r.get("pb.mcw"))}
|
|
151
|
+
for r in payload.get("data", [])
|
|
152
|
+
if r.get("stockCode") == code
|
|
153
|
+
]
|
|
154
|
+
if not rows or not any(r["date"] and (r["pe_ttm"] is not None or r["pb"] is not None) for r in rows):
|
|
155
|
+
raise ValueError("Lixinger returned no usable index history")
|
|
156
|
+
return rows
|
|
157
|
+
|
|
158
|
+
return cached(f"lixinger-index:{code}:{start}:{end}", DAY, fetch)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def index_valuation(args):
|
|
162
|
+
import akshare as ak
|
|
163
|
+
|
|
164
|
+
code = args.symbol.lower().removeprefix("sh").removeprefix("sz")
|
|
165
|
+
code = next((code for code, name in INDEX_NAMES.items() if name == args.symbol), code).upper()
|
|
166
|
+
name = INDEX_NAMES.get(code, args.symbol)
|
|
167
|
+
if not 1 <= args.years <= 10:
|
|
168
|
+
raise ValueError("years must be in 1..10")
|
|
169
|
+
result = {"symbol": code, "name": name, "source": "legulegu", "requested_years": args.years}
|
|
170
|
+
merged = {}
|
|
171
|
+
cutoff = (pd.Timestamp(date.today()) - pd.DateOffset(years=args.years)).date().isoformat()
|
|
172
|
+
for field, fn, column in [("pe_ttm", ak.stock_index_pe_lg, "滚动市盈率"), ("pb", ak.stock_index_pb_lg, "市净率")]:
|
|
173
|
+
section = {}
|
|
174
|
+
capture(
|
|
175
|
+
section,
|
|
176
|
+
"rows",
|
|
177
|
+
lambda fn=fn, field=field: dataset(f"index-valuation:{name}:{field}", lambda: fn(symbol=name)),
|
|
178
|
+
)
|
|
179
|
+
for row in section.get("rows", []):
|
|
180
|
+
stamp = iso(row.get("日期"))
|
|
181
|
+
if stamp and cutoff <= stamp <= date.today().isoformat():
|
|
182
|
+
merged.setdefault(stamp, {"date": stamp})[field] = number(row.get(column))
|
|
183
|
+
result.setdefault("warnings", []).extend(section.get("warnings", []))
|
|
184
|
+
if not any(number(r.get("pe_ttm")) is not None for r in merged.values()) and re.fullmatch(
|
|
185
|
+
r"\d{6}|H\d{5}", code, re.I
|
|
186
|
+
):
|
|
187
|
+
section = {}
|
|
188
|
+
capture(
|
|
189
|
+
section,
|
|
190
|
+
"history",
|
|
191
|
+
lambda: dataset(
|
|
192
|
+
f"csi-history:{code}:{args.years}",
|
|
193
|
+
lambda: ak.stock_zh_index_hist_csindex(
|
|
194
|
+
symbol=code, start_date=cutoff.replace("-", ""), end_date=date.today().strftime("%Y%m%d")
|
|
195
|
+
),
|
|
196
|
+
),
|
|
197
|
+
)
|
|
198
|
+
for row in section.get("history", []):
|
|
199
|
+
stamp = iso(row.get("日期"))
|
|
200
|
+
pe = number(row.get("滚动市盈率"))
|
|
201
|
+
if stamp and cutoff <= stamp <= date.today().isoformat() and pe is not None:
|
|
202
|
+
merged.setdefault(stamp, {"date": stamp})["pe_ttm"] = pe
|
|
203
|
+
capture(
|
|
204
|
+
section,
|
|
205
|
+
"recent",
|
|
206
|
+
lambda: dataset(f"csi-valuation:{code}", lambda: ak.stock_zh_index_value_csindex(symbol=code)),
|
|
207
|
+
)
|
|
208
|
+
for row in section.get("recent", []):
|
|
209
|
+
stamp = iso(row.get("日期"))
|
|
210
|
+
if stamp and cutoff <= stamp <= date.today().isoformat():
|
|
211
|
+
merged.setdefault(stamp, {"date": stamp}).update(
|
|
212
|
+
pe=number(row.get("市盈率1")), dividend_yield=number(row.get("股息率1"))
|
|
213
|
+
)
|
|
214
|
+
result["source"] = (
|
|
215
|
+
"legulegu/csindex" if any(number(r.get("pb")) is not None for r in merged.values()) else "csindex"
|
|
216
|
+
)
|
|
217
|
+
result["pe_basis"] = "CSI PE1, total shares"
|
|
218
|
+
result["historical_pe_basis"] = "CSI published rolling PE, not reconstructed from current constituents"
|
|
219
|
+
result.setdefault("warnings", []).extend(section.get("warnings", []))
|
|
220
|
+
result["metric_sources"] = {
|
|
221
|
+
field: "csindex" if field == "pe_ttm" and "historical_pe_basis" in result else "legulegu"
|
|
222
|
+
for field in ("pe_ttm", "pb")
|
|
223
|
+
if any(number(r.get(field)) is not None for r in merged.values())
|
|
224
|
+
}
|
|
225
|
+
missing = [field for field in ("pe_ttm", "pb") if field not in result["metric_sources"]]
|
|
226
|
+
if missing and os.environ.get("LIXINGER_TOKEN") and re.fullmatch(r"\d{6}|H\d{5}", code, re.I):
|
|
227
|
+
section = {}
|
|
228
|
+
capture(section, "rows", lambda: lixinger_index_history(code, cutoff, date.today().isoformat()))
|
|
229
|
+
for row in section.get("rows", []):
|
|
230
|
+
if row["date"] and cutoff <= row["date"] <= date.today().isoformat():
|
|
231
|
+
for field in missing:
|
|
232
|
+
if row[field] is not None:
|
|
233
|
+
merged.setdefault(row["date"], {"date": row["date"]})[field] = row[field]
|
|
234
|
+
for field in missing:
|
|
235
|
+
if any(number(r.get(field)) is not None for r in merged.values()):
|
|
236
|
+
result["metric_sources"][field] = "lixinger"
|
|
237
|
+
result["lixinger_basis"] = "provider-defined total-market-cap-weighted (mcw) index valuation"
|
|
238
|
+
result.setdefault("warnings", []).extend(section.get("warnings", []))
|
|
239
|
+
if "lixinger" in result["metric_sources"].values():
|
|
240
|
+
result["source"] = "/".join(sorted(set(result["metric_sources"].values())))
|
|
241
|
+
if "pb" not in result["metric_sources"]:
|
|
242
|
+
result.setdefault("warnings", []).append(
|
|
243
|
+
"historical PB unavailable; optional LIXINGER_TOKEN enables an additional provider; no estimate substituted"
|
|
244
|
+
)
|
|
245
|
+
if not merged:
|
|
246
|
+
raise ValueError("no index valuation data available")
|
|
247
|
+
history = sorted(merged.values(), key=lambda r: r["date"])
|
|
248
|
+
fields = ("pe_ttm", "pb", "pe", "dividend_yield") if "pe_basis" in result else ("pe_ttm", "pb")
|
|
249
|
+
result.update(history=history, metrics={field: valuation_summary(history, field) for field in fields})
|
|
250
|
+
if not result.get("warnings"):
|
|
251
|
+
result.pop("warnings", None)
|
|
252
|
+
return result
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def hk_board_meetings(board):
|
|
256
|
+
import requests
|
|
257
|
+
|
|
258
|
+
url = f"https://www.hkex-is.hk/wwwroot/link/{'ebmn' if board == 'main' else 'ebmngem'}.htm"
|
|
259
|
+
|
|
260
|
+
def fetch():
|
|
261
|
+
response = requests.get(url, timeout=20)
|
|
262
|
+
response.raise_for_status()
|
|
263
|
+
frames = pd.read_html(StringIO(response.text), header=0, converters={"Code": str}, keep_default_na=False)
|
|
264
|
+
frame = next((f for f in frames if {"BM Date", "Code", "Purpose", "Period"}.issubset(f.columns)), None)
|
|
265
|
+
if frame is None:
|
|
266
|
+
raise ValueError("HKEX board-meeting table unavailable")
|
|
267
|
+
rows = []
|
|
268
|
+
for row in frame.to_dict("records"):
|
|
269
|
+
code = str(row["Code"]).strip()
|
|
270
|
+
purpose = str(row["Purpose"]).strip()
|
|
271
|
+
if not re.fullmatch(r"\d{1,5}", code) or not re.search(r"\bRES(?:ULTS)?\b", purpose, re.I):
|
|
272
|
+
continue
|
|
273
|
+
stamp = iso(pd.to_datetime(str(row["BM Date"]).strip(), format="%d/%m/%Y", errors="coerce"))
|
|
274
|
+
if not stamp:
|
|
275
|
+
raise ValueError("invalid HKEX board-meeting date")
|
|
276
|
+
period = str(row["Period"])
|
|
277
|
+
match = re.search(r"\d{2}/\d{2}/\d{2}(?!\d)", period)
|
|
278
|
+
report_date = iso(pd.to_datetime(match.group(), format="%d/%m/%y", errors="coerce")) if match else None
|
|
279
|
+
rows.append(
|
|
280
|
+
{
|
|
281
|
+
"symbol": code.zfill(5) + ".HK",
|
|
282
|
+
"scheduled_date": stamp,
|
|
283
|
+
"report_date": report_date,
|
|
284
|
+
"period_description": period,
|
|
285
|
+
"purpose": purpose,
|
|
286
|
+
"actual_date": None,
|
|
287
|
+
"confirmation": "official_board_meeting_notice",
|
|
288
|
+
"date_kind": "scheduled_board_meeting",
|
|
289
|
+
"source_url": url,
|
|
290
|
+
}
|
|
291
|
+
)
|
|
292
|
+
return rows
|
|
293
|
+
|
|
294
|
+
return cached(f"hk-board-meetings:{board}", DAY, fetch)
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
def earnings_calendar(args):
|
|
298
|
+
import akshare as ak
|
|
299
|
+
|
|
300
|
+
stamp = iso(args.report_date)
|
|
301
|
+
suffix = {"03-31": "一季", "06-30": "半年报", "09-30": "三季", "12-31": "年报"}
|
|
302
|
+
if not 1 <= args.top <= 500 or (args.report_date and not stamp):
|
|
303
|
+
raise ValueError("report_date must be a valid date and top must be in 1..500")
|
|
304
|
+
if args.symbol and detect_market(args.symbol) == "HK":
|
|
305
|
+
import yfinance as yf
|
|
306
|
+
|
|
307
|
+
_, hk_code = stock_identity(args.symbol)
|
|
308
|
+
sections = {}
|
|
309
|
+
for board in ("main", "gem"):
|
|
310
|
+
capture(sections, board, lambda board=board: hk_board_meetings(board))
|
|
311
|
+
events = [
|
|
312
|
+
r
|
|
313
|
+
for board in ("main", "gem")
|
|
314
|
+
for r in sections.get(board, [])
|
|
315
|
+
if r["symbol"] == hk_code + ".HK"
|
|
316
|
+
and r["scheduled_date"] >= date.today().isoformat()
|
|
317
|
+
and (not stamp or r["report_date"] == stamp)
|
|
318
|
+
]
|
|
319
|
+
events = list({(r["scheduled_date"], r["purpose"], r["report_date"]): r for r in events}.values())
|
|
320
|
+
events.sort(key=lambda r: r["scheduled_date"])
|
|
321
|
+
|
|
322
|
+
def fetch():
|
|
323
|
+
frame = yf.Ticker(_yf_hk_symbol(args.symbol)).get_earnings_dates(limit=12)
|
|
324
|
+
if frame is None:
|
|
325
|
+
raise ValueError("HK earnings schedule unavailable")
|
|
326
|
+
return sorted({iso(d) for d in frame.index if iso(d)})
|
|
327
|
+
|
|
328
|
+
if not events:
|
|
329
|
+
capture(sections, "dates", lambda: cached(f"hk-earnings-schedule:{_yf_hk_symbol(args.symbol)}", DAY, fetch))
|
|
330
|
+
provider_events = [
|
|
331
|
+
{
|
|
332
|
+
"symbol": args.symbol,
|
|
333
|
+
"scheduled_date": d,
|
|
334
|
+
"actual_date": None,
|
|
335
|
+
"report_date": None,
|
|
336
|
+
"confirmation": "provider_only",
|
|
337
|
+
"date_kind": "provider_earnings_schedule",
|
|
338
|
+
}
|
|
339
|
+
for d in sections.get("dates", [])
|
|
340
|
+
if d >= date.today().isoformat()
|
|
341
|
+
]
|
|
342
|
+
if not stamp and not events:
|
|
343
|
+
events = provider_events
|
|
344
|
+
return {
|
|
345
|
+
"symbol": args.symbol,
|
|
346
|
+
"market": "HK",
|
|
347
|
+
"source": "HKEX board-meeting notices"
|
|
348
|
+
if any(r["confirmation"] == "official_board_meeting_notice" for r in events)
|
|
349
|
+
else "yfinance earnings schedule",
|
|
350
|
+
"report_date_requested": stamp,
|
|
351
|
+
"disclosures": events[: args.top],
|
|
352
|
+
"disclosures_total": len(events),
|
|
353
|
+
"forecasts": [],
|
|
354
|
+
"forecasts_total": 0,
|
|
355
|
+
"unverified_schedules": provider_events[: args.top] if stamp else [],
|
|
356
|
+
"warnings": sections.get("warnings", [])
|
|
357
|
+
+ [
|
|
358
|
+
"official dates are scheduled board meetings approving results, not actual disclosure dates; notice list may not be exhaustive",
|
|
359
|
+
"provider-only schedules have unverified fiscal periods and are not assigned to requested report_date",
|
|
360
|
+
],
|
|
361
|
+
"as_of": date.today().isoformat(),
|
|
362
|
+
}
|
|
363
|
+
if not stamp or stamp[5:] not in suffix:
|
|
364
|
+
raise ValueError("report_date must be a quarter end for A-share earnings calendars")
|
|
365
|
+
symbol = ""
|
|
366
|
+
if args.symbol:
|
|
367
|
+
market, symbol = stock_identity(args.symbol)
|
|
368
|
+
if market != "A":
|
|
369
|
+
raise ValueError("earnings calendar covers A shares only")
|
|
370
|
+
result = {"report_date": stamp, "source": "cninfo/eastmoney"}
|
|
371
|
+
capture(
|
|
372
|
+
result,
|
|
373
|
+
"disclosures",
|
|
374
|
+
lambda: dataset(
|
|
375
|
+
f"disclosure:{stamp}",
|
|
376
|
+
lambda: ak.stock_report_disclosure(market="沪深京", period=stamp[:4] + suffix[stamp[5:]]),
|
|
377
|
+
),
|
|
378
|
+
)
|
|
379
|
+
capture(
|
|
380
|
+
result, "forecasts", lambda: dataset(f"forecast:{stamp}", lambda: ak.stock_yjyg_em(date=stamp.replace("-", "")))
|
|
381
|
+
)
|
|
382
|
+
for key in ("disclosures", "forecasts"):
|
|
383
|
+
rows = result.get(key, [])
|
|
384
|
+
if symbol:
|
|
385
|
+
rows = [r for r in rows if str(r.get("股票代码", "")).zfill(6) == symbol]
|
|
386
|
+
output = []
|
|
387
|
+
for row in rows:
|
|
388
|
+
item = {"symbol": str(row.get("股票代码", "")).zfill(6), "name": row.get("股票简称")}
|
|
389
|
+
if key == "disclosures":
|
|
390
|
+
revised = [iso(row.get(c)) for c in ("首次预约", "初次变更", "二次变更", "三次变更")]
|
|
391
|
+
item.update(
|
|
392
|
+
scheduled_date=next((d for d in reversed(revised) if d), None),
|
|
393
|
+
actual_date=iso(row.get("实际披露")),
|
|
394
|
+
original_scheduled_date=revised[0],
|
|
395
|
+
scheduled_date_revisions=[
|
|
396
|
+
{"revision": i, "scheduled_date": d} for i, d in enumerate(revised[1:], 1) if d
|
|
397
|
+
],
|
|
398
|
+
)
|
|
399
|
+
else:
|
|
400
|
+
item.update(
|
|
401
|
+
announcement_date=iso(row.get("公告日期")),
|
|
402
|
+
forecast_type=row.get("预告类型"),
|
|
403
|
+
indicator=row.get("预测指标"),
|
|
404
|
+
forecast_value=number(row.get("预测数值")),
|
|
405
|
+
change_pct=number(row.get("业绩变动幅度")),
|
|
406
|
+
reason=row.get("业绩变动原因"),
|
|
407
|
+
)
|
|
408
|
+
output.append(item)
|
|
409
|
+
result[key + "_total"] = len(output)
|
|
410
|
+
result[key] = output[: args.top]
|
|
411
|
+
if result.get("warnings") and not result["disclosures"] and not result["forecasts"]:
|
|
412
|
+
raise ValueError("earnings calendar sources unavailable")
|
|
413
|
+
return result
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def southbound_holdings(symbol):
|
|
417
|
+
import requests
|
|
418
|
+
|
|
419
|
+
def fetch():
|
|
420
|
+
response = requests.get("https://www.hkexnews.hk/sdw/search/mutualmarket.aspx?t=hk", timeout=20)
|
|
421
|
+
response.raise_for_status()
|
|
422
|
+
tag = re.search(r"<input\b[^>]*\bname=[\"\']txtShareholdingDate[\"\'][^>]*>", response.text, re.I)
|
|
423
|
+
stamp = iso(re.search(r"\bvalue=[\"\']([^\"\']+)", tag.group()).group(1)) if tag else None
|
|
424
|
+
if not stamp:
|
|
425
|
+
raise ValueError("HKEX disclosure date unavailable")
|
|
426
|
+
frame = pd.read_html(StringIO(response.text), attrs={"id": "mutualmarket-result"})[0]
|
|
427
|
+
output = []
|
|
428
|
+
for row in frame.itertuples(index=False, name=None):
|
|
429
|
+
cells = [str(v).split(":", 1)[-1].strip() for v in row]
|
|
430
|
+
code = cells[0].zfill(5)
|
|
431
|
+
output.append(
|
|
432
|
+
{
|
|
433
|
+
"symbol": code + ".HK",
|
|
434
|
+
"name": cells[1],
|
|
435
|
+
"shares": number(cells[2].replace(",", "")),
|
|
436
|
+
"holding_pct": number(cells[3].rstrip("%")),
|
|
437
|
+
}
|
|
438
|
+
)
|
|
439
|
+
return {"as_of": stamp, "rows": output}
|
|
440
|
+
|
|
441
|
+
result = cached("hkex-southbound", DAY, fetch)
|
|
442
|
+
code = symbol.split(".")[0].zfill(5) + ".HK"
|
|
443
|
+
hit = next((r for r in result["rows"] if r["symbol"] == code), None)
|
|
444
|
+
return {
|
|
445
|
+
"as_of": result["as_of"],
|
|
446
|
+
"source": "HKEX Stock Connect shareholding",
|
|
447
|
+
**(
|
|
448
|
+
hit
|
|
449
|
+
or {
|
|
450
|
+
"symbol": code,
|
|
451
|
+
"shares": None,
|
|
452
|
+
"holding_pct": None,
|
|
453
|
+
"note": "not present in published Stock Connect list",
|
|
454
|
+
}
|
|
455
|
+
),
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def northbound_holdings(symbol, report_date=""):
|
|
460
|
+
import requests
|
|
461
|
+
|
|
462
|
+
exchange = _cn_code(symbol)[:2]
|
|
463
|
+
if exchange not in ("sh", "sz"):
|
|
464
|
+
raise ValueError("Stock Connect holdings cover Shanghai/Shenzhen securities only")
|
|
465
|
+
if report_date and (not iso(report_date) or iso(report_date)[5:] not in ("03-31", "06-30", "09-30", "12-31")):
|
|
466
|
+
raise ValueError("report_date must be a quarter end")
|
|
467
|
+
|
|
468
|
+
def fetch():
|
|
469
|
+
if exchange == "sh":
|
|
470
|
+
response = requests.get(
|
|
471
|
+
"https://query.sse.com.cn/commonSoaQuery.do",
|
|
472
|
+
params={
|
|
473
|
+
"sqlId": "FW_HGTZL_HGTSCSJ_HGTZQCYSL_L",
|
|
474
|
+
"tradeDate": report_date.replace("-", ""),
|
|
475
|
+
"secCodeName": symbol,
|
|
476
|
+
"isPagination": "true",
|
|
477
|
+
"pageHelp.pageSize": 20,
|
|
478
|
+
"pageHelp.pageNo": 1,
|
|
479
|
+
},
|
|
480
|
+
headers={"Referer": "https://www.sse.com.cn/"},
|
|
481
|
+
timeout=20,
|
|
482
|
+
)
|
|
483
|
+
response.raise_for_status()
|
|
484
|
+
payload = response.json()
|
|
485
|
+
rows = payload.get("result", [])
|
|
486
|
+
if payload.get("actionErrors") or payload.get("pageHelp", {}).get("pageCount", 0) > 1:
|
|
487
|
+
raise ValueError("incomplete SSE holdings response")
|
|
488
|
+
matches = [r for r in rows if str(r.get("secCode", "")).strip() == symbol]
|
|
489
|
+
if len(matches) != 1:
|
|
490
|
+
raise ValueError("official northbound holdings unavailable for this security/quarter")
|
|
491
|
+
row = matches[0]
|
|
492
|
+
stamp = iso(row.get("tradeDate"))
|
|
493
|
+
shares = number(str(row.get("totalHoldings")).replace(",", ""))
|
|
494
|
+
source = "SSE quarterly Stock Connect holdings"
|
|
495
|
+
else:
|
|
496
|
+
|
|
497
|
+
def query(stamp, code):
|
|
498
|
+
response = requests.get(
|
|
499
|
+
"https://www.szse.cn/api/report/ShowReport/data",
|
|
500
|
+
params={
|
|
501
|
+
"SHOWTYPE": "JSON",
|
|
502
|
+
"CATALOGID": "SGT_SGTCGSL",
|
|
503
|
+
"txtDate": f"{stamp[:4]}Q{int(stamp[5:7]) // 3}",
|
|
504
|
+
"txtZqdm": code,
|
|
505
|
+
},
|
|
506
|
+
headers={"Referer": "https://www.szse.cn/"},
|
|
507
|
+
timeout=20,
|
|
508
|
+
)
|
|
509
|
+
response.raise_for_status()
|
|
510
|
+
section = response.json()[0]
|
|
511
|
+
if section.get("error"):
|
|
512
|
+
raise ValueError("SZSE holdings period unavailable")
|
|
513
|
+
return section
|
|
514
|
+
|
|
515
|
+
stamp = report_date
|
|
516
|
+
if not stamp:
|
|
517
|
+
end = date(date.today().year, ((date.today().month - 1) // 3) * 3 + 1, 1) - timedelta(days=1)
|
|
518
|
+
for _ in range(2):
|
|
519
|
+
candidate = end.isoformat()
|
|
520
|
+
if query(candidate, "").get("data"):
|
|
521
|
+
stamp = candidate
|
|
522
|
+
break
|
|
523
|
+
end = date(end.year, end.month - 2, 1) - timedelta(days=1)
|
|
524
|
+
if not stamp:
|
|
525
|
+
raise ValueError("latest published SZSE holdings quarter unavailable")
|
|
526
|
+
section = query(stamp, symbol)
|
|
527
|
+
if section.get("metadata", {}).get("pagecount", 0) > 1:
|
|
528
|
+
raise ValueError("incomplete SZSE holdings response")
|
|
529
|
+
matches = [r for r in section.get("data", []) if str(r.get("zqdm", "")).strip() == symbol]
|
|
530
|
+
if len(matches) != 1:
|
|
531
|
+
raise ValueError("official northbound holdings unavailable for this security/quarter")
|
|
532
|
+
shares = number(str(matches[0].get("cysl")).replace(",", ""))
|
|
533
|
+
source = "SZSE quarterly Stock Connect holdings"
|
|
534
|
+
if (
|
|
535
|
+
not stamp
|
|
536
|
+
or stamp > date.today().isoformat()
|
|
537
|
+
or (report_date and stamp != report_date)
|
|
538
|
+
or shares is None
|
|
539
|
+
or shares < 0
|
|
540
|
+
):
|
|
541
|
+
raise ValueError("invalid official holdings date or quantity")
|
|
542
|
+
return {
|
|
543
|
+
"as_of": stamp,
|
|
544
|
+
"source": source,
|
|
545
|
+
"shares": shares,
|
|
546
|
+
"complete": True,
|
|
547
|
+
"quantity_unit": "fund units" if normalize_stock_code(symbol)["is_etf"] else "shares",
|
|
548
|
+
"note": "exchange-disclosed aggregate Stock Connect quantity for this security; not a top-ten shareholder inference",
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
return cached(f"northbound-official:{symbol}:{report_date or date.today().isoformat()}", DAY, fetch)
|
|
552
|
+
|
|
553
|
+
|
|
554
|
+
def shareholder_structure(args):
|
|
555
|
+
import akshare as ak
|
|
556
|
+
|
|
557
|
+
market, symbol = stock_identity(args.symbol)
|
|
558
|
+
result = {"symbol": args.symbol, "market": market}
|
|
559
|
+
if market == "HK":
|
|
560
|
+
result["southbound"] = southbound_holdings(args.symbol)
|
|
561
|
+
result["note"] = (
|
|
562
|
+
"Southbound holdings are dated CCASS Stock Connect records; not a complete beneficial-owner register"
|
|
563
|
+
)
|
|
564
|
+
return result
|
|
565
|
+
stamp = iso(args.report_date)
|
|
566
|
+
if args.report_date and (not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31")):
|
|
567
|
+
raise ValueError("report_date must be a quarter end")
|
|
568
|
+
capture(
|
|
569
|
+
result,
|
|
570
|
+
"shareholder_counts",
|
|
571
|
+
lambda: dataset(f"holders:{symbol}", lambda: ak.stock_zh_a_gdhs_detail_em(symbol=symbol)),
|
|
572
|
+
)
|
|
573
|
+
rows = result.get("shareholder_counts", [])
|
|
574
|
+
result["shareholder_counts"] = sorted(
|
|
575
|
+
[
|
|
576
|
+
{
|
|
577
|
+
"as_of": iso(r.get("股东户数统计截止日")),
|
|
578
|
+
"announcement_date": iso(r.get("股东户数公告日期")),
|
|
579
|
+
"holders": number(r.get("股东户数-本次")),
|
|
580
|
+
"change": number(r.get("股东户数-增减")),
|
|
581
|
+
"change_pct": number(r.get("股东户数-增减比例")),
|
|
582
|
+
}
|
|
583
|
+
for r in rows
|
|
584
|
+
],
|
|
585
|
+
key=lambda r: r["as_of"] or "",
|
|
586
|
+
reverse=True,
|
|
587
|
+
)
|
|
588
|
+
if not stamp:
|
|
589
|
+
from stock_data import cmd_financials
|
|
590
|
+
|
|
591
|
+
financials = cmd_financials(argparse.Namespace(symbol=symbol, periods=1, annual=False))
|
|
592
|
+
stamp = iso(financials.get("report_date"))
|
|
593
|
+
if not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31"):
|
|
594
|
+
result.setdefault("warnings", []).append(
|
|
595
|
+
"top_float_shareholders: report_date required when latest disclosed financial report is unavailable"
|
|
596
|
+
)
|
|
597
|
+
else:
|
|
598
|
+
result["report_date"] = stamp
|
|
599
|
+
capture(
|
|
600
|
+
result,
|
|
601
|
+
"top_float_shareholders",
|
|
602
|
+
lambda: dataset(
|
|
603
|
+
f"top-float:{symbol}:{stamp}",
|
|
604
|
+
lambda: ak.stock_gdfx_free_top_10_em(symbol=_cn_code(symbol), date=stamp.replace("-", "")),
|
|
605
|
+
),
|
|
606
|
+
)
|
|
607
|
+
result["top_float_shareholders"] = [
|
|
608
|
+
{
|
|
609
|
+
"name": r.get("股东名称"),
|
|
610
|
+
"shares": number(r.get("持股数")),
|
|
611
|
+
"float_holding_pct": number(r.get("占总流通股本持股比例")),
|
|
612
|
+
"change": r.get("增减"),
|
|
613
|
+
"change_pct": number(r.get("变动比率")),
|
|
614
|
+
"report_date": stamp,
|
|
615
|
+
}
|
|
616
|
+
for r in result.get("top_float_shareholders", [])
|
|
617
|
+
]
|
|
618
|
+
nominee = [r for r in result["top_float_shareholders"] if (r["name"] or "").strip() == "香港中央结算有限公司"]
|
|
619
|
+
result["northbound"] = {
|
|
620
|
+
"as_of": stamp,
|
|
621
|
+
"source": "disclosed top float shareholder register",
|
|
622
|
+
"shares": sum(r["shares"] for r in nominee)
|
|
623
|
+
if nominee and all(r["shares"] is not None for r in nominee)
|
|
624
|
+
else None,
|
|
625
|
+
"note": "HKSCC nominee disclosure; absence from top ten is not zero holdings. Daily northbound stock holding disclosure is no longer assumed.",
|
|
626
|
+
}
|
|
627
|
+
result["northbound_nominee"] = result["northbound"]
|
|
628
|
+
capture(result, "northbound", lambda: northbound_holdings(symbol, args.report_date))
|
|
629
|
+
if (
|
|
630
|
+
not result["shareholder_counts"]
|
|
631
|
+
and not result.get("top_float_shareholders")
|
|
632
|
+
and not result.get("northbound", {}).get("complete")
|
|
633
|
+
):
|
|
634
|
+
raise ValueError("shareholder sources unavailable")
|
|
635
|
+
return result
|
|
636
|
+
|
|
637
|
+
|
|
638
|
+
def hk_dividend_ranking(report_date=""):
|
|
639
|
+
import requests
|
|
640
|
+
|
|
641
|
+
stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
|
|
642
|
+
if not stamp or stamp[5:] != "12-31":
|
|
643
|
+
raise ValueError("HK dividend ranking requires an annual year-end report_date")
|
|
644
|
+
|
|
645
|
+
def fetch():
|
|
646
|
+
headers = {"Referer": "https://www.hkex.com.hk/", "User-Agent": "Mozilla/5.0"}
|
|
647
|
+
response = requests.get(
|
|
648
|
+
"https://www.hkex.com.hk/Listing/Sustainability/Shareholder-Value-in-Focus/Dividend-Yield-Ratio?sc_lang=en",
|
|
649
|
+
headers=headers,
|
|
650
|
+
timeout=20,
|
|
651
|
+
)
|
|
652
|
+
response.raise_for_status()
|
|
653
|
+
block = re.search(r"LabCI\.getToken\s*=\s*function\s*\(\)\s*\{(.*?)\}", response.text, re.S)
|
|
654
|
+
token_match = re.search(r'return\s+"([^"]+)"', re.sub(r"//[^\n]*", "", block.group(1))) if block else None
|
|
655
|
+
if not token_match:
|
|
656
|
+
raise ValueError("HKEX public dividend feed unavailable")
|
|
657
|
+
rows = []
|
|
658
|
+
years = None
|
|
659
|
+
total = None
|
|
660
|
+
page = 1
|
|
661
|
+
while total is None or len(rows) < total:
|
|
662
|
+
try:
|
|
663
|
+
response = requests.get(
|
|
664
|
+
"https://www1.hkex.com.hk/hkexwidget/data/getcapitalefficiencylist",
|
|
665
|
+
params={
|
|
666
|
+
"token": unquote(token_match.group(1)),
|
|
667
|
+
"type": "DYR",
|
|
668
|
+
"sector": "null",
|
|
669
|
+
"hsi": 0,
|
|
670
|
+
"page": page,
|
|
671
|
+
"limit": 3000,
|
|
672
|
+
"sort": 1,
|
|
673
|
+
"dir": 1,
|
|
674
|
+
"lang": "eng",
|
|
675
|
+
"callback": "stockrank",
|
|
676
|
+
"qid": 1,
|
|
677
|
+
},
|
|
678
|
+
headers=headers,
|
|
679
|
+
timeout=20,
|
|
680
|
+
)
|
|
681
|
+
except requests.RequestException:
|
|
682
|
+
raise ValueError("HKEX dividend feed request failed") from None
|
|
683
|
+
if response.status_code != 200:
|
|
684
|
+
raise ValueError("HKEX dividend feed unavailable")
|
|
685
|
+
match = re.fullmatch(r"\s*stockrank\((.*)\);?\s*", response.text, re.S)
|
|
686
|
+
if not match:
|
|
687
|
+
raise ValueError("unexpected HKEX dividend feed")
|
|
688
|
+
data = json.loads(match.group(1))["data"]
|
|
689
|
+
if (
|
|
690
|
+
data.get("responsecode") != "000"
|
|
691
|
+
or not isinstance(data.get("totalCount"), int)
|
|
692
|
+
or not 0 < data["totalCount"] <= 100000
|
|
693
|
+
):
|
|
694
|
+
raise ValueError("invalid HKEX dividend feed")
|
|
695
|
+
if total is not None and (total != data["totalCount"] or years != data.get("year")):
|
|
696
|
+
raise ValueError("HKEX dividend pages changed during fetch")
|
|
697
|
+
total, years = data["totalCount"], data["year"]
|
|
698
|
+
if not data["datalist"]:
|
|
699
|
+
raise ValueError("incomplete HKEX dividend ranking")
|
|
700
|
+
rows.extend(data["datalist"])
|
|
701
|
+
page += 1
|
|
702
|
+
if len(rows) != total or len({r["sym"] for r in rows}) != total or stamp[:4] not in years:
|
|
703
|
+
raise ValueError("incomplete HKEX ranking or requested year unavailable")
|
|
704
|
+
column = years.index(stamp[:4]) + 1
|
|
705
|
+
items = []
|
|
706
|
+
for row in rows:
|
|
707
|
+
if not re.fullmatch(r"\d{1,5}", row["sym"]) or len(row["data"]) != len(years) + 1:
|
|
708
|
+
raise ValueError("invalid HKEX dividend row")
|
|
709
|
+
value = number(row["data"][column])
|
|
710
|
+
if value is not None:
|
|
711
|
+
items.append(
|
|
712
|
+
{
|
|
713
|
+
"symbol": row["sym"].zfill(5) + ".HK",
|
|
714
|
+
"name": row["nm"],
|
|
715
|
+
"dividend_yield": value,
|
|
716
|
+
"yield_year": stamp[:4],
|
|
717
|
+
"source_latest_period": row.get("period"),
|
|
718
|
+
}
|
|
719
|
+
)
|
|
720
|
+
return {
|
|
721
|
+
"market": "HK",
|
|
722
|
+
"report_date": stamp,
|
|
723
|
+
"source": "HKEX/LSEG",
|
|
724
|
+
"items": items,
|
|
725
|
+
"yield_basis": "provider fiscal-year dividend yield ratio, percent; not current-price TTM cash yield",
|
|
726
|
+
}
|
|
727
|
+
|
|
728
|
+
return cached(f"hk-dividend-ranking:{stamp}", DAY, fetch)
|
|
729
|
+
|
|
730
|
+
|
|
731
|
+
def dividend_ranking(report_date="", market="A"):
|
|
732
|
+
import akshare as ak
|
|
733
|
+
|
|
734
|
+
if market == "HK":
|
|
735
|
+
return hk_dividend_ranking(report_date)
|
|
736
|
+
if market != "A":
|
|
737
|
+
raise ValueError("dividend rankings cover A/HK only")
|
|
738
|
+
stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
|
|
739
|
+
if not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31"):
|
|
740
|
+
raise ValueError("dividend report_date must be a quarter end")
|
|
741
|
+
rows = dataset(f"dividend-ranking:{stamp}", lambda: ak.stock_fhps_em(date=stamp.replace("-", "")))
|
|
742
|
+
return {
|
|
743
|
+
"report_date": stamp,
|
|
744
|
+
"source": "eastmoney",
|
|
745
|
+
"yield_basis": "provider report-period cash dividend yield, percent",
|
|
746
|
+
"items": [
|
|
747
|
+
{
|
|
748
|
+
"symbol": str(r.get("代码", "")).zfill(6),
|
|
749
|
+
"name": r.get("名称"),
|
|
750
|
+
"dividend_yield": number(r.get("现金分红-股息率")),
|
|
751
|
+
"ex_date": iso(r.get("除权除息日")),
|
|
752
|
+
"announcement_date": iso(r.get("最新公告日期")),
|
|
753
|
+
"status": r.get("方案进度"),
|
|
754
|
+
}
|
|
755
|
+
for r in rows
|
|
756
|
+
if r.get("方案进度") == "实施分配" and number(r.get("现金分红-股息率")) is not None
|
|
757
|
+
],
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
|
|
761
|
+
def dividends(args):
|
|
762
|
+
if not 1 <= args.years <= 20 or not 1 <= args.top <= 500:
|
|
763
|
+
raise ValueError("years must be in 1..20 and top in 1..500")
|
|
764
|
+
if args.mode == "ranking":
|
|
765
|
+
if args.symbol:
|
|
766
|
+
raise ValueError("ranking covers all A shares; omit symbol")
|
|
767
|
+
result = dividend_ranking(args.report_date, getattr(args, "market", "A"))
|
|
768
|
+
result["items"] = sorted(result["items"], key=lambda r: r["dividend_yield"], reverse=True)[: args.top]
|
|
769
|
+
return result
|
|
770
|
+
market, symbol = stock_identity(args.symbol)
|
|
771
|
+
import akshare as ak
|
|
772
|
+
from _subproc import run_tool
|
|
773
|
+
|
|
774
|
+
today = date.today()
|
|
775
|
+
result = {
|
|
776
|
+
"symbol": args.symbol,
|
|
777
|
+
"market": market,
|
|
778
|
+
"as_of": today.isoformat(),
|
|
779
|
+
"yield_basis": "cash paid per share in trailing 365 days / latest price, before tax; nominal source cash amounts",
|
|
780
|
+
}
|
|
781
|
+
if market == "A":
|
|
782
|
+
rows = dataset(f"dividends:{symbol}", lambda: ak.stock_fhps_detail_em(symbol=symbol))
|
|
783
|
+
events = [
|
|
784
|
+
{
|
|
785
|
+
"report_date": iso(r.get("报告期")),
|
|
786
|
+
"ex_date": iso(r.get("除权除息日")),
|
|
787
|
+
"record_date": iso(r.get("股权登记日")),
|
|
788
|
+
"announcement_date": iso(r.get("最新公告日期")),
|
|
789
|
+
"cash_per_share": number(r.get("现金分红-现金分红比例")) / 10
|
|
790
|
+
if number(r.get("现金分红-现金分红比例")) is not None
|
|
791
|
+
else None,
|
|
792
|
+
"status": r.get("方案进度"),
|
|
793
|
+
}
|
|
794
|
+
for r in rows
|
|
795
|
+
]
|
|
796
|
+
if args.mode == "calendar":
|
|
797
|
+
return {
|
|
798
|
+
"symbol": args.symbol,
|
|
799
|
+
"market": market,
|
|
800
|
+
"source": "eastmoney",
|
|
801
|
+
"as_of": today.isoformat(),
|
|
802
|
+
"calendar": [r for r in events if r.get("ex_date") and r["ex_date"] > today.isoformat()],
|
|
803
|
+
}
|
|
804
|
+
quote = run_tool("stock_data.py", ["quote", symbol]) or {}
|
|
805
|
+
price = number(quote.get("price"))
|
|
806
|
+
result.update(source="eastmoney", currency="CNY", price=price, price_as_of=quote.get("as_of"))
|
|
807
|
+
else:
|
|
808
|
+
import yfinance as yf
|
|
809
|
+
|
|
810
|
+
sources = {}
|
|
811
|
+
capture(
|
|
812
|
+
sources,
|
|
813
|
+
"calendar",
|
|
814
|
+
lambda: dataset(f"hk-dividend-calendar:{symbol}", lambda: ak.stock_hk_dividend_payout_em(symbol=symbol)),
|
|
815
|
+
)
|
|
816
|
+
calendar = [
|
|
817
|
+
{
|
|
818
|
+
"ex_date": iso(r.get("除净日")),
|
|
819
|
+
"payment_date": iso(r.get("发放日")),
|
|
820
|
+
"announcement_date": iso(r.get("最新公告日期")),
|
|
821
|
+
"plan": r.get("分红方案"),
|
|
822
|
+
"fiscal_year": r.get("财政年度"),
|
|
823
|
+
}
|
|
824
|
+
for r in sources.get("calendar", [])
|
|
825
|
+
]
|
|
826
|
+
if args.mode == "calendar":
|
|
827
|
+
if sources.get("warnings"):
|
|
828
|
+
raise ValueError("HK dividend calendar unavailable")
|
|
829
|
+
return {
|
|
830
|
+
"symbol": args.symbol,
|
|
831
|
+
"market": market,
|
|
832
|
+
"source": "eastmoney",
|
|
833
|
+
"as_of": today.isoformat(),
|
|
834
|
+
"calendar": [r for r in calendar if r.get("ex_date") and r["ex_date"] > today.isoformat()],
|
|
835
|
+
}
|
|
836
|
+
ticker = yf.Ticker(_yf_hk_symbol(args.symbol))
|
|
837
|
+
|
|
838
|
+
def cash_history():
|
|
839
|
+
raw = ticker.dividends
|
|
840
|
+
frame = (
|
|
841
|
+
raw.to_frame("cash_per_share")
|
|
842
|
+
if isinstance(raw, pd.Series)
|
|
843
|
+
else raw.rename(columns={"Dividends": "cash_per_share"})
|
|
844
|
+
)
|
|
845
|
+
return frame.reset_index()
|
|
846
|
+
|
|
847
|
+
capture(sources, "cash", lambda: dataset(f"hk-dividend-cash:{symbol}", cash_history))
|
|
848
|
+
capture(sources, "quote", lambda: ticker.info)
|
|
849
|
+
paid = sources.get("cash", [])
|
|
850
|
+
info = sources.get("quote") or {}
|
|
851
|
+
if sources.get("warnings"):
|
|
852
|
+
result["warnings"] = sources["warnings"]
|
|
853
|
+
if not paid and not calendar:
|
|
854
|
+
raise ValueError("HK dividend sources unavailable")
|
|
855
|
+
events = [
|
|
856
|
+
{
|
|
857
|
+
"ex_date": iso(r.get("Date")),
|
|
858
|
+
"cash_per_share": number(r.get("cash_per_share")),
|
|
859
|
+
"currency": r.get("currency") or info.get("currency"),
|
|
860
|
+
"status": "paid",
|
|
861
|
+
}
|
|
862
|
+
for r in paid
|
|
863
|
+
]
|
|
864
|
+
price = number(info.get("currentPrice") or info.get("regularMarketPrice"))
|
|
865
|
+
result.update(source="yfinance cash / eastmoney calendar", currency=info.get("currency"), price=price)
|
|
866
|
+
result["calendar"] = [r for r in calendar if r["ex_date"] and r["ex_date"] > today.isoformat()]
|
|
867
|
+
cutoff = (today - timedelta(days=365.25 * args.years)).isoformat()
|
|
868
|
+
events = sorted(
|
|
869
|
+
[
|
|
870
|
+
r
|
|
871
|
+
for r in events
|
|
872
|
+
if not (r.get("ex_date") or r.get("report_date")) or (r.get("ex_date") or r["report_date"]) >= cutoff
|
|
873
|
+
],
|
|
874
|
+
key=lambda r: r.get("ex_date") or r.get("report_date") or "",
|
|
875
|
+
reverse=True,
|
|
876
|
+
)
|
|
877
|
+
paid_events = [
|
|
878
|
+
r
|
|
879
|
+
for r in events
|
|
880
|
+
if r["status"] in ("实施分配", "paid") and (not r.get("ex_date") or r["ex_date"] <= today.isoformat())
|
|
881
|
+
]
|
|
882
|
+
incomplete_history = any(
|
|
883
|
+
not r.get("ex_date") or r["cash_per_share"] is None or r["cash_per_share"] < 0 for r in paid_events
|
|
884
|
+
)
|
|
885
|
+
ttm_cutoff = (today - timedelta(days=365)).isoformat()
|
|
886
|
+
incomplete_ttm = any(
|
|
887
|
+
not r.get("ex_date") or (r["ex_date"] > ttm_cutoff and (r["cash_per_share"] is None or r["cash_per_share"] < 0))
|
|
888
|
+
for r in paid_events
|
|
889
|
+
)
|
|
890
|
+
implemented = [
|
|
891
|
+
r for r in paid_events if r.get("ex_date") and r["cash_per_share"] is not None and r["cash_per_share"] > 0
|
|
892
|
+
]
|
|
893
|
+
ttm = [r for r in implemented if r["ex_date"] > ttm_cutoff]
|
|
894
|
+
cash_by_currency = {}
|
|
895
|
+
for row in ttm:
|
|
896
|
+
currency = row.get("currency") or result.get("currency") or "unknown"
|
|
897
|
+
cash_by_currency[currency] = round(cash_by_currency.get(currency, 0) + row["cash_per_share"], 6)
|
|
898
|
+
currency_match = result.get("currency") and all(currency == result["currency"] for currency in cash_by_currency)
|
|
899
|
+
cash = sum(r["cash_per_share"] for r in ttm) if currency_match and events and not incomplete_ttm else None
|
|
900
|
+
if incomplete_history:
|
|
901
|
+
result.setdefault("warnings", []).append(
|
|
902
|
+
"paid dividend dates or cash amounts are missing/invalid; totals and streak are unknown where affected"
|
|
903
|
+
)
|
|
904
|
+
if not events:
|
|
905
|
+
result.setdefault("warnings", []).append("no dividend history returned; absence is not interpreted as zero")
|
|
906
|
+
elif not currency_match:
|
|
907
|
+
result.setdefault("warnings", []).append(
|
|
908
|
+
"cash dividend and quote currencies differ or are unknown; no FX conversion was assumed"
|
|
909
|
+
)
|
|
910
|
+
years = {int(r["ex_date"][:4]) for r in implemented}
|
|
911
|
+
anchor = today.year if today.year in years else today.year - 1
|
|
912
|
+
consecutive = 0
|
|
913
|
+
while anchor - consecutive in years:
|
|
914
|
+
consecutive += 1
|
|
915
|
+
result.update(
|
|
916
|
+
history=events,
|
|
917
|
+
cash_per_share_ttm=round(cash, 6) if cash is not None else None,
|
|
918
|
+
cash_per_share_ttm_by_currency=None if incomplete_ttm else cash_by_currency,
|
|
919
|
+
dividend_yield_ttm=round(cash / price * 100, 4) if cash is not None and price and price > 0 else None,
|
|
920
|
+
consecutive_payment_years=consecutive if events and not incomplete_history else None,
|
|
921
|
+
consecutive_years_end=anchor,
|
|
922
|
+
history_years_requested=args.years,
|
|
923
|
+
)
|
|
924
|
+
if market == "A":
|
|
925
|
+
result["calendar"] = [r for r in events if r.get("ex_date") and r["ex_date"] > today.isoformat()]
|
|
926
|
+
return result
|
|
927
|
+
|
|
928
|
+
|
|
929
|
+
def tracking_error(nav, benchmark):
|
|
930
|
+
if not nav or not benchmark:
|
|
931
|
+
return {
|
|
932
|
+
"annualized_tracking_error_pct": None,
|
|
933
|
+
"observations": 0,
|
|
934
|
+
"note": "fund NAV or benchmark history unavailable",
|
|
935
|
+
}
|
|
936
|
+
fund = pd.DataFrame(nav).drop_duplicates("date").set_index("date").sort_index()
|
|
937
|
+
index = pd.DataFrame(benchmark).drop_duplicates("date").set_index("date").sort_index()
|
|
938
|
+
fund_returns = pd.to_numeric(fund["daily_return_pct"], errors="coerce") / 100
|
|
939
|
+
close = pd.to_numeric(index["close"], errors="coerce")
|
|
940
|
+
index_returns = close.pct_change(fill_method=None)
|
|
941
|
+
try:
|
|
942
|
+
import exchange_calendars as xcals
|
|
943
|
+
|
|
944
|
+
calendar = xcals.get_calendar("XSHG")
|
|
945
|
+
previous = {
|
|
946
|
+
stamp: calendar.previous_session(stamp).date().isoformat()
|
|
947
|
+
for stamp in fund.index.union(index.index)
|
|
948
|
+
if calendar.is_session(stamp)
|
|
949
|
+
}
|
|
950
|
+
except Exception:
|
|
951
|
+
return {"annualized_tracking_error_pct": None, "observations": 0, "note": "ETF trading calendar unavailable"}
|
|
952
|
+
matched = (
|
|
953
|
+
pd.concat(
|
|
954
|
+
[
|
|
955
|
+
fund_returns.rename("fund"),
|
|
956
|
+
index_returns.rename("benchmark"),
|
|
957
|
+
fund.index.to_series().shift().rename("fund_previous"),
|
|
958
|
+
index.index.to_series().shift().rename("benchmark_previous"),
|
|
959
|
+
pd.Series(previous).rename("session_previous"),
|
|
960
|
+
],
|
|
961
|
+
axis=1,
|
|
962
|
+
)
|
|
963
|
+
.replace([np.inf, -np.inf], np.nan)
|
|
964
|
+
.dropna()
|
|
965
|
+
)
|
|
966
|
+
matched = matched[
|
|
967
|
+
(matched["fund_previous"] == matched["session_previous"])
|
|
968
|
+
& (matched["benchmark_previous"] == matched["session_previous"])
|
|
969
|
+
]
|
|
970
|
+
active = matched["fund"] - matched["benchmark"]
|
|
971
|
+
return {
|
|
972
|
+
"annualized_tracking_error_pct": round(float(active.std(ddof=1) * np.sqrt(252) * 100), 4)
|
|
973
|
+
if len(active) >= 2
|
|
974
|
+
else None,
|
|
975
|
+
"observations": len(active),
|
|
976
|
+
"window_start": matched.index[0] if len(active) else None,
|
|
977
|
+
"window_end": matched.index[-1] if len(active) else None,
|
|
978
|
+
"basis": "daily published NAV growth minus benchmark close return; sample std, 252 trading days; only matching consecutive ETF trading-session intervals, no missing-date fill",
|
|
979
|
+
}
|
|
980
|
+
|
|
981
|
+
|
|
982
|
+
def fund_size_history(symbol):
|
|
983
|
+
import requests
|
|
984
|
+
|
|
985
|
+
def fetch():
|
|
986
|
+
response = requests.get(f"https://fund.eastmoney.com/pingzhongdata/{symbol}.js", timeout=15)
|
|
987
|
+
response.raise_for_status()
|
|
988
|
+
match = re.search(r"\bData_fluctuationScale\s*=\s*(.*?);", response.text, re.S)
|
|
989
|
+
if not match:
|
|
990
|
+
raise ValueError("fund scale history unavailable")
|
|
991
|
+
data = json.loads(match.group(1))
|
|
992
|
+
if len(data["categories"]) != len(data["series"]):
|
|
993
|
+
raise ValueError("fund scale dates and observations do not match")
|
|
994
|
+
return [
|
|
995
|
+
{"date": iso(stamp), "aum_cny": number(row.get("y")) * 1e8}
|
|
996
|
+
for stamp, row in zip(data["categories"], data["series"], strict=True)
|
|
997
|
+
if iso(stamp) and number(row.get("y")) is not None
|
|
998
|
+
]
|
|
999
|
+
|
|
1000
|
+
return cached(f"etf-size:{symbol}", DAY, fetch)
|
|
1001
|
+
|
|
1002
|
+
|
|
1003
|
+
def etf_basket(symbol):
|
|
1004
|
+
import requests
|
|
1005
|
+
|
|
1006
|
+
def fetch():
|
|
1007
|
+
if symbol.startswith("5"):
|
|
1008
|
+
response = requests.get(
|
|
1009
|
+
"https://query.sse.com.cn/etfDownload/downloadETF2Bulletin.do",
|
|
1010
|
+
params={"fundCode": symbol},
|
|
1011
|
+
headers={"Referer": "https://www.sse.com.cn/"},
|
|
1012
|
+
timeout=20,
|
|
1013
|
+
)
|
|
1014
|
+
source = "SSE PCF"
|
|
1015
|
+
else:
|
|
1016
|
+
response = requests.get(
|
|
1017
|
+
"https://www.szse.cn/api/report/ShowReport/data",
|
|
1018
|
+
params={
|
|
1019
|
+
"SHOWTYPE": "JSON",
|
|
1020
|
+
"CATALOGID": "sgshqd",
|
|
1021
|
+
"txtJCorDH": symbol,
|
|
1022
|
+
"txtStart": (date.today() - timedelta(days=30)).isoformat(),
|
|
1023
|
+
"txtEnd": date.today().isoformat(),
|
|
1024
|
+
},
|
|
1025
|
+
headers={"Referer": "https://www.szse.cn/"},
|
|
1026
|
+
timeout=20,
|
|
1027
|
+
)
|
|
1028
|
+
response.raise_for_status()
|
|
1029
|
+
dates = re.findall(rf"pcf_{re.escape(symbol)}_(\d{{8}})", json.dumps(response.json()))
|
|
1030
|
+
dates = [d for d in dates if iso(d) and iso(d) <= date.today().isoformat()]
|
|
1031
|
+
if not dates:
|
|
1032
|
+
raise ValueError("no published SZSE PCF found")
|
|
1033
|
+
response = requests.get(
|
|
1034
|
+
f"https://reportdocs.static.szse.cn/files/text/ETFDown/pcf_{symbol}_{max(dates)}.xml", timeout=20
|
|
1035
|
+
)
|
|
1036
|
+
source = "SZSE PCF"
|
|
1037
|
+
response.raise_for_status()
|
|
1038
|
+
if b"<!DOCTYPE" in response.content.upper() or b"<!ENTITY" in response.content.upper():
|
|
1039
|
+
raise ValueError("unexpected PCF XML declarations")
|
|
1040
|
+
root = ElementTree.fromstring(response.content)
|
|
1041
|
+
for node in root.iter():
|
|
1042
|
+
node.tag = node.tag.split("}")[-1]
|
|
1043
|
+
if root.tag not in ("SSEPortfolioCompositionFile", "PCFFile"):
|
|
1044
|
+
raise ValueError("unexpected PCF document")
|
|
1045
|
+
fund_code = root.findtext("FundInstrumentID") or root.findtext("SecurityID")
|
|
1046
|
+
stamp = iso(root.findtext("TradingDay"))
|
|
1047
|
+
unit = number(root.findtext("CreationRedemptionUnit"))
|
|
1048
|
+
components = root.findall(".//Component")
|
|
1049
|
+
count = number(root.findtext("TotalRecordNum") or root.findtext("RecordNumber") or root.findtext("RecordNum"))
|
|
1050
|
+
if (
|
|
1051
|
+
fund_code != symbol
|
|
1052
|
+
or not stamp
|
|
1053
|
+
or stamp > date.today().isoformat()
|
|
1054
|
+
or not unit
|
|
1055
|
+
or unit <= 0
|
|
1056
|
+
or count != len(components)
|
|
1057
|
+
or not components
|
|
1058
|
+
):
|
|
1059
|
+
raise ValueError("incomplete or mismatched PCF document")
|
|
1060
|
+
rows = []
|
|
1061
|
+
for node in components:
|
|
1062
|
+
code = node.findtext("InstrumentID") or node.findtext("UnderlyingSecurityID")
|
|
1063
|
+
quantity = number(node.findtext("Quantity") or node.findtext("ComponentShare"))
|
|
1064
|
+
if not code or quantity is None or quantity < 0:
|
|
1065
|
+
raise ValueError("invalid PCF component")
|
|
1066
|
+
rows.append(
|
|
1067
|
+
{
|
|
1068
|
+
"code": code,
|
|
1069
|
+
"name": node.findtext("InstrumentName") or node.findtext("UnderlyingSymbol"),
|
|
1070
|
+
"quantity_per_unit": quantity,
|
|
1071
|
+
"exchange_code": node.findtext("UnderlyingSecurityID")
|
|
1072
|
+
if root.tag == "SSEPortfolioCompositionFile"
|
|
1073
|
+
else node.findtext("UnderlyingSecurityIDSource"),
|
|
1074
|
+
"cash_substitution_flag": node.findtext("SubstitutionFlag") or node.findtext("SubstituteFlag"),
|
|
1075
|
+
"creation_premium_rate": number(
|
|
1076
|
+
node.findtext("CreationPremiumRate") or node.findtext("PremiumRatio")
|
|
1077
|
+
),
|
|
1078
|
+
"redemption_discount_rate": number(
|
|
1079
|
+
node.findtext("RedemptionDiscountRate") or node.findtext("DiscountRatio")
|
|
1080
|
+
),
|
|
1081
|
+
"substitution_cash_amount": number(node.findtext("SubstitutionCashAmount")),
|
|
1082
|
+
"creation_cash_substitute": number(node.findtext("CreationCashSubstitute")),
|
|
1083
|
+
"redemption_cash_substitute": number(node.findtext("RedemptionCashSubstitute")),
|
|
1084
|
+
}
|
|
1085
|
+
)
|
|
1086
|
+
return {
|
|
1087
|
+
"source": source,
|
|
1088
|
+
"as_of": stamp,
|
|
1089
|
+
"previous_trading_day": iso(root.findtext("PreTradingDay")),
|
|
1090
|
+
"creation_redemption_unit": unit,
|
|
1091
|
+
"previous_nav": {
|
|
1092
|
+
"as_of": iso(root.findtext("PreTradingDay")),
|
|
1093
|
+
"nav_per_unit": number(root.findtext("NAV")),
|
|
1094
|
+
"nav_per_creation_unit": number(root.findtext("NAVperCU")),
|
|
1095
|
+
},
|
|
1096
|
+
"previous_cash_component": number(root.findtext("PreCashComponent") or root.findtext("CashComponent")),
|
|
1097
|
+
"estimated_cash_component": number(
|
|
1098
|
+
root.findtext("EstimatedCashComponent") or root.findtext("EstimateCashComponent")
|
|
1099
|
+
),
|
|
1100
|
+
"cash_unit": "CNY per creation/redemption unit",
|
|
1101
|
+
"max_cash_substitution_ratio": number(root.findtext("MaxCashRatio")),
|
|
1102
|
+
"creation_redemption_switch": root.findtext("CreationRedemptionSwitch"),
|
|
1103
|
+
"creation_flag": root.findtext("Creation"),
|
|
1104
|
+
"redemption_flag": root.findtext("Redemption"),
|
|
1105
|
+
"record_count": len(rows),
|
|
1106
|
+
"complete": True,
|
|
1107
|
+
"components": rows,
|
|
1108
|
+
"basis": "complete published creation/redemption basket, not actual fund holdings; quantities per creation unit, rates are fractions",
|
|
1109
|
+
}
|
|
1110
|
+
|
|
1111
|
+
return cached(f"etf-basket:{symbol}:{date.today().isoformat()}", DAY, fetch)
|
|
1112
|
+
|
|
1113
|
+
|
|
1114
|
+
def fund_disclosed_equities(symbol):
|
|
1115
|
+
import requests
|
|
1116
|
+
from akshare.utils import demjson
|
|
1117
|
+
from bs4 import BeautifulSoup
|
|
1118
|
+
|
|
1119
|
+
limit = 10000
|
|
1120
|
+
|
|
1121
|
+
def fetch(stamp):
|
|
1122
|
+
response = requests.get(
|
|
1123
|
+
"https://fundf10.eastmoney.com/FundArchivesDatas.aspx",
|
|
1124
|
+
params={"type": "jjcc", "code": symbol, "topline": limit, "year": stamp[:4], "month": str(int(stamp[5:7]))},
|
|
1125
|
+
headers={"Referer": f"https://fundf10.eastmoney.com/ccmx_{symbol}.html"},
|
|
1126
|
+
timeout=20,
|
|
1127
|
+
)
|
|
1128
|
+
response.raise_for_status()
|
|
1129
|
+
text = response.text
|
|
1130
|
+
payload = demjson.decode(text[text.index("{") : text.rindex("}") + 1])
|
|
1131
|
+
soup = BeautifulSoup(payload["content"], "lxml")
|
|
1132
|
+
for block in soup.select("div.boxitem"):
|
|
1133
|
+
heading = block.find("h4")
|
|
1134
|
+
link = heading.find("a", href=True) if heading else None
|
|
1135
|
+
if not heading or not link or not link["href"].endswith(f"/{symbol}.html"):
|
|
1136
|
+
continue
|
|
1137
|
+
match = re.search(r"\d{4}-\d{2}-\d{2}", heading.get_text())
|
|
1138
|
+
if not match or match.group() != stamp:
|
|
1139
|
+
continue
|
|
1140
|
+
table = block.find("table")
|
|
1141
|
+
if table is None:
|
|
1142
|
+
raise ValueError("disclosed equity table unavailable")
|
|
1143
|
+
frame = pd.read_html(StringIO(str(table)), converters={"股票代码": str})[0]
|
|
1144
|
+
frame.columns = [re.sub(r"\s+", "", str(c)) for c in frame.columns]
|
|
1145
|
+
value_column = next((c for c in frame.columns if c in ("持仓市值(万元)", "持仓市值(万元人民币)")), None)
|
|
1146
|
+
if not {"股票代码", "股票名称", "占净值比例", "持股数(万股)"}.issubset(frame.columns) or not value_column:
|
|
1147
|
+
raise ValueError("unknown disclosed equity units/schema")
|
|
1148
|
+
if frame.empty or len(frame) >= limit:
|
|
1149
|
+
raise ValueError("empty or potentially truncated disclosed equity table")
|
|
1150
|
+
positions = []
|
|
1151
|
+
for row in frame.to_dict("records"):
|
|
1152
|
+
quantity = number(str(row["持股数(万股)"]).replace(",", ""))
|
|
1153
|
+
value = number(str(row[value_column]).replace(",", ""))
|
|
1154
|
+
positions.append(
|
|
1155
|
+
{
|
|
1156
|
+
"code": str(row["股票代码"]),
|
|
1157
|
+
"name": str(row["股票名称"]) if pd.notna(row["股票名称"]) else None,
|
|
1158
|
+
"weight_pct": number(str(row["占净值比例"]).replace("%", "")),
|
|
1159
|
+
"quantity_shares": quantity * 10000 if quantity is not None else None,
|
|
1160
|
+
"market_value_cny": value * 10000 if value is not None else None,
|
|
1161
|
+
}
|
|
1162
|
+
)
|
|
1163
|
+
return {
|
|
1164
|
+
"source": "eastmoney periodic equity report",
|
|
1165
|
+
"as_of": stamp,
|
|
1166
|
+
"is_realtime": False,
|
|
1167
|
+
"position_count": len(positions),
|
|
1168
|
+
"equity_positions": positions,
|
|
1169
|
+
"coverage": "all received source-table equity rows, not total fund assets; source completeness is not independently verified",
|
|
1170
|
+
"source_url": f"https://fundf10.eastmoney.com/ccmx_{symbol}.html",
|
|
1171
|
+
}
|
|
1172
|
+
raise ValueError("requested semiannual/annual equity report not available")
|
|
1173
|
+
|
|
1174
|
+
end = date(date.today().year, ((date.today().month - 1) // 6) * 6 + 1, 1) - timedelta(days=1)
|
|
1175
|
+
requested = end.isoformat()
|
|
1176
|
+
for _ in range(2):
|
|
1177
|
+
stamp = end.isoformat()
|
|
1178
|
+
try:
|
|
1179
|
+
result = cached(f"fund-equity-report:{symbol}:{stamp}", DAY, lambda stamp=stamp: fetch(stamp))
|
|
1180
|
+
return {**result, "requested_report_date": requested}
|
|
1181
|
+
except Exception:
|
|
1182
|
+
end = date(end.year, end.month - 5, 1) - timedelta(days=1)
|
|
1183
|
+
raise ValueError("latest disclosed semiannual/annual equity report unavailable")
|
|
1184
|
+
|
|
1185
|
+
|
|
1186
|
+
def etf_details(args):
|
|
1187
|
+
import akshare as ak
|
|
1188
|
+
from _subproc import run_tool
|
|
1189
|
+
|
|
1190
|
+
symbol = _cn_code(args.symbol)[2:]
|
|
1191
|
+
if detect_market(args.symbol) != "A" or not normalize_stock_code(symbol)["is_etf"] or not 10 <= args.days <= 252:
|
|
1192
|
+
raise ValueError("ETF details requires an A-share ETF code and days in 10..252")
|
|
1193
|
+
result = {
|
|
1194
|
+
"symbol": symbol,
|
|
1195
|
+
"market": "A",
|
|
1196
|
+
"source": "eastmoney",
|
|
1197
|
+
"holdings_basis": "latest disclosed fund portfolio, not a complete live creation/redemption basket",
|
|
1198
|
+
}
|
|
1199
|
+
end = date.today()
|
|
1200
|
+
start = end - timedelta(days=args.days * 2)
|
|
1201
|
+
capture(
|
|
1202
|
+
result,
|
|
1203
|
+
"nav_history",
|
|
1204
|
+
lambda: dataset(
|
|
1205
|
+
f"etf-nav:{symbol}:{args.days}",
|
|
1206
|
+
lambda: ak.fund_etf_fund_info_em(
|
|
1207
|
+
fund=symbol, start_date=start.strftime("%Y%m%d"), end_date=end.strftime("%Y%m%d")
|
|
1208
|
+
),
|
|
1209
|
+
),
|
|
1210
|
+
)
|
|
1211
|
+
nav = sorted(
|
|
1212
|
+
[
|
|
1213
|
+
{
|
|
1214
|
+
"date": iso(r.get("净值日期")),
|
|
1215
|
+
"nav": number(r.get("单位净值")),
|
|
1216
|
+
"daily_return_pct": number(r.get("日增长率")),
|
|
1217
|
+
}
|
|
1218
|
+
for r in result.get("nav_history", [])
|
|
1219
|
+
if iso(r.get("净值日期"))
|
|
1220
|
+
],
|
|
1221
|
+
key=lambda r: r["date"],
|
|
1222
|
+
)[-args.days :]
|
|
1223
|
+
result["nav_history"] = nav
|
|
1224
|
+
latest = nav[-1] if nav else {}
|
|
1225
|
+
result.update(nav=latest.get("nav"), nav_date=latest.get("date"))
|
|
1226
|
+
quote = run_tool("stock_data.py", ["quote", symbol]) or {}
|
|
1227
|
+
quote_date = iso(quote.get("as_of"))
|
|
1228
|
+
price = number(quote.get("price"))
|
|
1229
|
+
result.update(
|
|
1230
|
+
price=price,
|
|
1231
|
+
price_as_of=quote.get("as_of"),
|
|
1232
|
+
fund_shares=number(quote.get("fund_shares")),
|
|
1233
|
+
iopv=number(quote.get("iopv")),
|
|
1234
|
+
iopv_premium_discount_pct=number(quote.get("premium_discount_rate")),
|
|
1235
|
+
premium_discount_pct=round((price / latest["nav"] - 1) * 100, 4)
|
|
1236
|
+
if quote_date
|
|
1237
|
+
and quote_date == latest.get("date")
|
|
1238
|
+
and price is not None
|
|
1239
|
+
and latest.get("nav")
|
|
1240
|
+
and latest["nav"] > 0
|
|
1241
|
+
else None,
|
|
1242
|
+
premium_basis="last price / published NAV only when dates match; positive=premium",
|
|
1243
|
+
)
|
|
1244
|
+
if result["premium_discount_pct"] is None:
|
|
1245
|
+
result.setdefault("warnings", []).append("premium: quote/NAV dates differ or date/value unavailable")
|
|
1246
|
+
capture(result, "size_history", lambda: fund_size_history(symbol))
|
|
1247
|
+
sizes = sorted(result.get("size_history", []), key=lambda r: r["date"])
|
|
1248
|
+
result["size_history"] = sizes
|
|
1249
|
+
result["size_change_pct"] = (
|
|
1250
|
+
round((sizes[-1]["aum_cny"] / sizes[-2]["aum_cny"] - 1) * 100, 4)
|
|
1251
|
+
if len(sizes) >= 2 and sizes[-2]["aum_cny"] > 0
|
|
1252
|
+
else None
|
|
1253
|
+
)
|
|
1254
|
+
capture(
|
|
1255
|
+
result,
|
|
1256
|
+
"holdings",
|
|
1257
|
+
lambda: dataset(f"etf-holdings:{symbol}", lambda: ak.fund_portfolio_hold_em(symbol=symbol, date="")),
|
|
1258
|
+
)
|
|
1259
|
+
rows = result.get("holdings", [])
|
|
1260
|
+
if rows:
|
|
1261
|
+
latest_quarter = max(str(r.get("季度", "")) for r in rows)
|
|
1262
|
+
result["holdings"] = [
|
|
1263
|
+
{
|
|
1264
|
+
"code": str(r.get("股票代码", "")),
|
|
1265
|
+
"name": r.get("股票名称"),
|
|
1266
|
+
"weight_pct": number(r.get("占净值比例")),
|
|
1267
|
+
"report_period": r.get("季度"),
|
|
1268
|
+
}
|
|
1269
|
+
for r in rows
|
|
1270
|
+
if str(r.get("季度", "")) == latest_quarter
|
|
1271
|
+
]
|
|
1272
|
+
result["holdings_code_basis"] = "original reported security codes; foreign exchange/market is not inferred"
|
|
1273
|
+
capture(result, "basket", lambda: etf_basket(symbol))
|
|
1274
|
+
if getattr(args, "include_full_holdings", False):
|
|
1275
|
+
capture(result, "disclosed_equity_report", lambda: fund_disclosed_equities(symbol))
|
|
1276
|
+
if args.benchmark:
|
|
1277
|
+
benchmark = "sh" + args.benchmark if args.benchmark in INDEX_NAMES else args.benchmark
|
|
1278
|
+
benchmark_rows = run_tool("stock_data.py", ["kline", benchmark, "--count", str(args.days + 5)])
|
|
1279
|
+
result["tracking_error"] = tracking_error(nav, benchmark_rows if isinstance(benchmark_rows, list) else [])
|
|
1280
|
+
result["tracking_error"]["benchmark"] = benchmark
|
|
1281
|
+
if benchmark.lower().startswith(("sh", "sz")):
|
|
1282
|
+
code = benchmark[2:]
|
|
1283
|
+
capture(
|
|
1284
|
+
result,
|
|
1285
|
+
"benchmark_constituents",
|
|
1286
|
+
lambda: dataset(f"index-constituents:{code}", lambda: ak.index_stock_cons_csindex(symbol=code)),
|
|
1287
|
+
)
|
|
1288
|
+
if "benchmark_constituents" in result:
|
|
1289
|
+
result["benchmark_constituents"] = [
|
|
1290
|
+
{
|
|
1291
|
+
"code": r.get("成分券代码"),
|
|
1292
|
+
"name": r.get("成分券名称"),
|
|
1293
|
+
"exchange": r.get("交易所名称"),
|
|
1294
|
+
"as_of": iso(r.get("日期")),
|
|
1295
|
+
}
|
|
1296
|
+
for r in result["benchmark_constituents"]
|
|
1297
|
+
]
|
|
1298
|
+
else:
|
|
1299
|
+
result["tracking_error"] = {
|
|
1300
|
+
"annualized_tracking_error_pct": None,
|
|
1301
|
+
"note": "provide benchmark to compute tracking error; benchmark is never guessed",
|
|
1302
|
+
}
|
|
1303
|
+
if (
|
|
1304
|
+
not nav
|
|
1305
|
+
and not sizes
|
|
1306
|
+
and not result.get("holdings")
|
|
1307
|
+
and not result.get("basket", {}).get("complete")
|
|
1308
|
+
and not result.get("disclosed_equity_report")
|
|
1309
|
+
):
|
|
1310
|
+
raise ValueError("ETF detail sources unavailable")
|
|
1311
|
+
return result
|
|
1312
|
+
|
|
1313
|
+
|
|
1314
|
+
def main():
|
|
1315
|
+
parser = argparse.ArgumentParser(description="Value-investing datasets and dated historical context")
|
|
1316
|
+
sub = parser.add_subparsers(dest="command")
|
|
1317
|
+
for command in ("valuation_history", "index_valuation"):
|
|
1318
|
+
p = sub.add_parser(command)
|
|
1319
|
+
p.add_argument("symbol")
|
|
1320
|
+
p.add_argument("--years", type=int, default=5)
|
|
1321
|
+
p = sub.add_parser("earnings_calendar")
|
|
1322
|
+
p.add_argument("--symbol", default="")
|
|
1323
|
+
p.add_argument("--report-date", default="")
|
|
1324
|
+
p.add_argument("--top", type=int, default=50)
|
|
1325
|
+
p = sub.add_parser("shareholder_structure")
|
|
1326
|
+
p.add_argument("symbol")
|
|
1327
|
+
p.add_argument("--report-date", default="")
|
|
1328
|
+
p = sub.add_parser("etf_details")
|
|
1329
|
+
p.add_argument("symbol")
|
|
1330
|
+
p.add_argument("--benchmark", default="")
|
|
1331
|
+
p.add_argument("--days", type=int, default=60)
|
|
1332
|
+
p.add_argument(
|
|
1333
|
+
"--include-full-holdings", action="store_true", help="Fetch latest disclosed semiannual/annual equity table"
|
|
1334
|
+
)
|
|
1335
|
+
p = sub.add_parser("dividends")
|
|
1336
|
+
p.add_argument("--symbol", default="")
|
|
1337
|
+
p.add_argument("--mode", choices=["history", "calendar", "ranking"], default="history")
|
|
1338
|
+
p.add_argument("--market", choices=["A", "HK"], default="A", help="Ranking market; history/calendar use symbol")
|
|
1339
|
+
p.add_argument("--report-date", default="")
|
|
1340
|
+
p.add_argument("--years", type=int, default=10)
|
|
1341
|
+
p.add_argument("--top", type=int, default=20)
|
|
1342
|
+
try:
|
|
1343
|
+
args = parser.parse_args()
|
|
1344
|
+
handlers = {
|
|
1345
|
+
"valuation_history": valuation_history,
|
|
1346
|
+
"index_valuation": index_valuation,
|
|
1347
|
+
"earnings_calendar": earnings_calendar,
|
|
1348
|
+
"shareholder_structure": shareholder_structure,
|
|
1349
|
+
"etf_details": etf_details,
|
|
1350
|
+
"dividends": dividends,
|
|
1351
|
+
}
|
|
1352
|
+
if args.command not in handlers:
|
|
1353
|
+
raise ValueError("a subcommand is required")
|
|
1354
|
+
with socket_timeout(20):
|
|
1355
|
+
result = handlers[args.command](args)
|
|
1356
|
+
print(json.dumps(result, ensure_ascii=False, allow_nan=False))
|
|
1357
|
+
except SystemExit as exc:
|
|
1358
|
+
if exc.code:
|
|
1359
|
+
print(json.dumps({"error": "invalid CLI arguments"}))
|
|
1360
|
+
raise
|
|
1361
|
+
except Exception as exc:
|
|
1362
|
+
print(json.dumps({"error": scrub_secrets(str(exc))}, ensure_ascii=False))
|
|
1363
|
+
sys.exit(1)
|
|
1364
|
+
|
|
1365
|
+
|
|
1366
|
+
if __name__ == "__main__":
|
|
1367
|
+
utf8_stdio()
|
|
1368
|
+
main()
|