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.
@@ -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()