stock-analysis-plugin 0.2.5 → 0.2.6

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.
@@ -10,9 +10,12 @@ host decides when to record and when to evaluate.
10
10
  """
11
11
 
12
12
  import argparse
13
+ import contextlib
13
14
  import json
15
+ import math
14
16
  import os
15
17
  import sys
18
+ import tempfile
16
19
  from datetime import datetime
17
20
  from pathlib import Path
18
21
  from uuid import uuid4
@@ -31,26 +34,108 @@ def _store_path(args) -> Path:
31
34
  return Path(args.store) if args.store else _default_store()
32
35
 
33
36
 
34
- def _load_records(store: Path) -> list:
37
+ def _validate_signal(record):
38
+ if not isinstance(record, dict) or any(
39
+ not isinstance(record.get(field), str) or not record[field] for field in ("id", "symbol", "record_date")
40
+ ):
41
+ raise ValueError("Invalid signal identity/date")
42
+ if record.get("status") not in ("open", "closed") or record.get("direction") not in ("buy", "sell"):
43
+ raise ValueError("Invalid signal status/direction")
44
+ if record.get("source") is not None and not isinstance(record["source"], str):
45
+ raise ValueError("Signal source must be a string")
46
+ if record.get("entry_price") is None or any(
47
+ isinstance(record.get(field), bool)
48
+ or not isinstance(record[field], (int, float))
49
+ or not math.isfinite(record[field])
50
+ or record[field] <= 0
51
+ for field in ("entry_price", "target_price", "stop_price")
52
+ if record.get(field) is not None
53
+ ):
54
+ raise ValueError("Signal prices must be finite and positive")
55
+ horizon = record.get("horizon_days")
56
+ if isinstance(horizon, bool) or not isinstance(horizon, int) or horizon <= 0:
57
+ raise ValueError("Signal horizon_days must be a positive integer")
58
+ try:
59
+ date = datetime.strptime(record["record_date"], "%Y-%m-%d")
60
+ except ValueError as e:
61
+ raise ValueError("Signal date must be YYYY-MM-DD") from e
62
+ if date.strftime("%Y-%m-%d") != record["record_date"]:
63
+ raise ValueError("Signal date must be YYYY-MM-DD")
64
+
65
+
66
+ @contextlib.contextmanager
67
+ def _store_lock(store: Path):
68
+ # Lock a separate file: replacing the JSONL must not replace the lock inode.
69
+ store.parent.mkdir(parents=True, exist_ok=True)
70
+ with store.with_name(store.name + ".lock").open("a+b") as lock:
71
+ if sys.platform == "win32":
72
+ import msvcrt
73
+
74
+ if lock.seek(0, os.SEEK_END) == 0:
75
+ lock.write(b"\0")
76
+ lock.flush()
77
+ lock.seek(0)
78
+ msvcrt.locking(lock.fileno(), msvcrt.LK_LOCK, 1)
79
+ else:
80
+ import fcntl
81
+
82
+ fcntl.flock(lock.fileno(), fcntl.LOCK_EX)
83
+ try:
84
+ yield
85
+ finally:
86
+ if sys.platform == "win32":
87
+ lock.seek(0)
88
+ msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)
89
+ else:
90
+ fcntl.flock(lock.fileno(), fcntl.LOCK_UN)
91
+
92
+
93
+ def _load_records(store: Path, strict: bool = False) -> list:
35
94
  if not store.exists():
36
95
  return []
37
96
  records = []
38
- for line in store.read_text(encoding="utf-8").splitlines():
97
+ for number, line in enumerate(store.read_text(encoding="utf-8").splitlines(), 1):
39
98
  line = line.strip()
40
99
  if line:
41
100
  try:
42
- records.append(json.loads(line))
43
- except json.JSONDecodeError:
101
+ record = json.loads(line)
102
+ except json.JSONDecodeError as e:
103
+ if strict:
104
+ raise ValueError(f"Invalid signal JSON at line {number}; store left unchanged") from e
44
105
  continue
106
+ if strict:
107
+ try:
108
+ _validate_signal(record)
109
+ except ValueError as e:
110
+ raise ValueError(f"Invalid signal record at line {number}; store left unchanged: {e}") from e
111
+ records.append(record)
45
112
  return records
46
113
 
47
114
 
48
115
  def _save_records(store: Path, records: list):
49
- """Atomic rewrite: write <store>.tmp, then os.replace onto the store."""
116
+ """Atomic rewrite; caller holds the store lock."""
50
117
  store.parent.mkdir(parents=True, exist_ok=True)
51
- tmp = store.parent / (store.name + ".tmp")
52
- tmp.write_text("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in records), encoding="utf-8")
53
- os.replace(tmp, store)
118
+ tmp = None
119
+ try:
120
+ with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=store.parent, delete=False) as stream:
121
+ tmp = Path(stream.name)
122
+ stream.write("".join(json.dumps(r, ensure_ascii=False) + "\n" for r in records))
123
+ os.replace(tmp, store)
124
+ finally:
125
+ if tmp:
126
+ with contextlib.suppress(OSError):
127
+ tmp.unlink(missing_ok=True)
128
+
129
+
130
+ def _append_record(store: Path, record: dict):
131
+ """Append one complete JSON line; caller holds the store lock."""
132
+ payload = (json.dumps(record, ensure_ascii=False, default=str, allow_nan=False) + "\n").encode("utf-8")
133
+ with store.open("a+b") as stream:
134
+ if stream.seek(0, os.SEEK_END):
135
+ stream.seek(-1, os.SEEK_END)
136
+ if stream.read(1) != b"\n":
137
+ stream.write(b"\n")
138
+ stream.write(payload)
54
139
 
55
140
 
56
141
  def cmd_record(args):
@@ -78,10 +163,11 @@ def cmd_record(args):
78
163
  }
79
164
  store = _store_path(args)
80
165
  try:
81
- store.parent.mkdir(parents=True, exist_ok=True)
82
- with store.open("a", encoding="utf-8") as f:
83
- f.write(json.dumps(record, ensure_ascii=False) + "\n")
84
- except OSError as e:
166
+ _validate_signal(record)
167
+ with _store_lock(store):
168
+ _load_records(store, strict=True)
169
+ _append_record(store, record)
170
+ except (OSError, ValueError) as e:
85
171
  return {"error": str(e)}
86
172
  return record
87
173
 
@@ -135,9 +221,26 @@ def _kline_count(rec: dict) -> int:
135
221
  return min(max(horizon + 40, elapsed + 15), 800)
136
222
 
137
223
 
224
+ def _valid_bar(bar) -> bool:
225
+ if not isinstance(bar, dict):
226
+ return False
227
+ try:
228
+ date = datetime.strptime(bar["date"], "%Y-%m-%d")
229
+ except (KeyError, TypeError, ValueError):
230
+ return False
231
+ return date.strftime("%Y-%m-%d") == bar["date"] and all(
232
+ isinstance(bar.get(key), (int, float)) and math.isfinite(bar[key]) and bar[key] > 0
233
+ for key in ("high", "low", "close")
234
+ )
235
+
236
+
138
237
  def cmd_evaluate(args):
139
238
  store = _store_path(args)
140
- records = _load_records(store)
239
+ try:
240
+ with _store_lock(store):
241
+ records = _load_records(store, strict=True)
242
+ except (OSError, ValueError) as e:
243
+ return {"error": str(e)}
141
244
  results = []
142
245
  evaluated = closed = 0
143
246
  changed = False
@@ -152,7 +255,12 @@ def cmd_evaluate(args):
152
255
  "stock_data.py",
153
256
  ["kline", rec["symbol"], "--period", "daily", "--count", str(_kline_count(rec))],
154
257
  )
155
- if not isinstance(bars, list):
258
+ if (
259
+ not isinstance(bars, list)
260
+ or not bars
261
+ or any(not _valid_bar(bar) for bar in bars)
262
+ or min(str(b.get("date", ""))[:10] for b in bars) > rec["record_date"]
263
+ ):
156
264
  entry.update({"outcome": "skipped_no_data", "return_pct": None, "exit_date": None})
157
265
  else:
158
266
  ev = _evaluate_bars(rec, bars)
@@ -172,20 +280,35 @@ def cmd_evaluate(args):
172
280
  "return_pct": ret,
173
281
  }
174
282
  )
175
- closed += 1
176
283
  changed = True
177
284
  entry.update({"outcome": outcome, "return_pct": ret, "exit_date": exit_date})
178
285
  results.append(entry)
179
- if changed:
286
+ if results:
180
287
  try:
181
- _save_records(store, records)
182
- except OSError as e:
288
+ updates = {r["id"]: r for r in records if r.get("status") == "closed"}
289
+ with _store_lock(store):
290
+ current = _load_records(store, strict=True)
291
+ merged = [updates.get(r["id"], r) if r.get("status") == "open" else r for r in current]
292
+ if changed:
293
+ _save_records(store, merged)
294
+ persisted = {r["id"]: r for r in merged}
295
+ for entry in results:
296
+ rec = persisted[entry["id"]]
297
+ if rec.get("status") == "closed":
298
+ entry.update({key: rec.get(key) for key in ("outcome", "return_pct", "exit_date")})
299
+ closed += 1
300
+ except (OSError, ValueError) as e:
183
301
  return {"error": str(e)}
184
302
  return {"evaluated": evaluated, "closed": closed, "still_open": evaluated - closed, "results": results}
185
303
 
186
304
 
187
305
  def cmd_summary(args):
188
- records = _load_records(_store_path(args))
306
+ store = _store_path(args)
307
+ try:
308
+ with _store_lock(store):
309
+ records = _load_records(store, strict=True)
310
+ except (OSError, ValueError) as e:
311
+ return {"error": str(e)}
189
312
  filtered = records
190
313
  if args.source:
191
314
  filtered = [r for r in filtered if r.get("source") == args.source]
@@ -5,6 +5,8 @@ import argparse
5
5
  import contextlib
6
6
  import hashlib
7
7
  import json
8
+ import math
9
+ import os
8
10
  import re
9
11
  import sys
10
12
  import tempfile
@@ -206,6 +208,7 @@ def _kline_baostock(symbol: str, period: str, count: int) -> list:
206
208
  for c in ["open", "high", "low", "close", "volume"]:
207
209
  if c in df.columns:
208
210
  df[c] = pd.to_numeric(df[c], errors="coerce")
211
+ df["volume"] /= 100 # Baostock uses shares; the A-share CLI contract uses lots.
209
212
  keep = [c for c in ["date", "open", "high", "low", "close", "volume", "turnover", "change_pct"] if c in df.columns]
210
213
  df = df[keep].tail(count)
211
214
  return [_clean_row(r) for r in df.to_dict("records")]
@@ -278,6 +281,7 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
278
281
  """Build the quote row from one Tencent `~`-separated payload (already split).
279
282
  Shared by _quote_tencent (single) and _tencent_batch_quotes (snapshot leg)."""
280
283
  f += [""] * (50 - len(f)) # pad optional tail fields (pe/pb/market_cap/volume_ratio…) on short payloads
284
+ hk = detect_market(symbol) == "HK"
281
285
  turnover = _parse_float(f[37])
282
286
  market_cap = _parse_float(f[45])
283
287
  return {
@@ -286,36 +290,45 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
286
290
  "price": _parse_float(f[3]),
287
291
  "change": _parse_float(f[31]),
288
292
  "change_pct": _parse_float(f[32]),
289
- "volume": _parse_float(f[6]), # 手, same as akshare
290
- "turnover": turnover * 1e4 if turnover is not None else None,
293
+ "volume": _parse_float(f[6]), # A: 手; HK: shares, same as yfinance
294
+ "turnover": turnover * (1 if hk else 1e4) if turnover is not None else None,
291
295
  "high": _parse_float(f[33]),
292
296
  "low": _parse_float(f[34]),
293
297
  "open": _parse_float(f[5]),
294
298
  "prev_close": _parse_float(f[4]),
295
299
  "market_cap": market_cap * 1e8 if market_cap is not None else None,
296
300
  "pe": _parse_float(f[39]),
297
- "pb": _parse_float(f[46]),
298
- "turnover_rate": _parse_float(f[38]),
299
- "volume_ratio": _parse_float(f[49]),
301
+ # Tencent's HK map labels f[47] DY and f[49] WK52_Low; neither is an A-share ratio.
302
+ "pb": None if hk else _parse_float(f[46]),
303
+ "turnover_rate": None if hk else _parse_float(f[38]),
304
+ "volume_ratio": None if hk else _parse_float(f[49]),
300
305
  "amplitude": _parse_float(f[43]),
301
306
  }
302
307
 
303
308
 
304
309
  def _quote_tencent(symbol: str) -> dict:
305
- """Tencent quote via qt.gtimg.cn. GBK-encoded `v_sh600519="1~name~code~..."` fields.
310
+ """Tencent A/HK quote via qt.gtimg.cn, with a GBK-encoded `~` payload.
306
311
 
307
- Units differ from akshare: turnover arrives in 万元 and market_cap in 亿元 —
308
- both are normalized to 元 to match the rest of the chain."""
312
+ A-share turnover is 万元; HK turnover is already HKD. Market cap is 亿元
313
+ (CNY/HKD respectively); normalize monetary fields to currency units."""
309
314
  import requests
310
315
 
311
- resp = requests.get(f"https://qt.gtimg.cn/q={_cn_code(symbol)}", timeout=10)
316
+ hk = detect_market(symbol) == "HK"
317
+ if hk and not re.fullmatch(r"[0-9]{1,5}\.HK", symbol, re.IGNORECASE):
318
+ raise ValueError(f"invalid HK symbol: {symbol}")
319
+ # Tencent's hk feed is delayed 15 minutes; r_hk uses the same fields for live quotes.
320
+ code = f"r_hk{symbol[:-3].zfill(5)}" if hk else _cn_code(symbol)
321
+ resp = requests.get(f"https://qt.gtimg.cn/q={code}", timeout=10)
322
+ resp.raise_for_status()
312
323
  f = _gbk_var_payload(resp.content).split("~")
313
324
  if len(f) < 35 or not f[1]:
314
325
  raise ValueError(f"tencent returned no quote for {symbol}")
315
- row = _tencent_payload_row(f, symbol)
326
+ row = _clean_row(_tencent_payload_row(f, symbol))
327
+ if hk and (row["price"] is None or row["price"] <= 0):
328
+ raise ValueError(f"tencent returned no quote for {symbol}")
316
329
  if normalize_stock_code(symbol)["is_etf"]:
317
330
  row["is_etf"] = True
318
- return _clean_row(row)
331
+ return row
319
332
 
320
333
 
321
334
  def _kline_tencent(symbol: str, period: str, count: int) -> list:
@@ -865,7 +878,7 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
865
878
  "function": fn_map.get(period, fn_map["daily"]),
866
879
  "symbol": symbol,
867
880
  "apikey": api_key,
868
- "outputsize": "compact",
881
+ "outputsize": "full" if count > 100 else "compact",
869
882
  },
870
883
  timeout=20,
871
884
  )
@@ -879,14 +892,19 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
879
892
 
880
893
  rows = []
881
894
  for date_str, vals in sorted(ts.items()):
895
+ close = float(vals["4. close"])
896
+ adjusted = float(vals.get("5. adjusted close", "nan"))
897
+ if not math.isfinite(close) or not math.isfinite(adjusted) or close <= 0 or adjusted <= 0:
898
+ raise ValueError("alphavantage returned invalid adjustment prices")
899
+ factor = adjusted / close
882
900
  rows.append(
883
901
  _clean_row(
884
902
  {
885
903
  "date": date_str,
886
- "open": float(vals["1. open"]),
887
- "high": float(vals["2. high"]),
888
- "low": float(vals["3. low"]),
889
- "close": float(vals["4. close"]),
904
+ "open": float(vals["1. open"]) * factor,
905
+ "high": float(vals["2. high"]) * factor,
906
+ "low": float(vals["3. low"]) * factor,
907
+ "close": adjusted,
890
908
  "volume": int(vals.get("6. volume", vals.get("5. volume", 0))),
891
909
  }
892
910
  )
@@ -1127,7 +1145,17 @@ def _quote_finnhub(symbol: str) -> dict:
1127
1145
 
1128
1146
 
1129
1147
  def quote_yf(symbol: str) -> dict:
1130
- """HK/US/JP/KR/TW quote. Failover: yfinance → finnhub/longbridge (HK/US) → alphavantage (US only)."""
1148
+ """HK adds Tencent after yfinance; US/JP/KR/TW keep their existing failover chains."""
1149
+ if detect_market(symbol) == "HK":
1150
+ return _failover(
1151
+ [
1152
+ ("yfinance", lambda: _quote_yfinance(symbol)),
1153
+ ("tencent", lambda: _quote_tencent(symbol)),
1154
+ ("finnhub", lambda: _quote_finnhub(symbol)),
1155
+ ("longbridge", lambda: _quote_longbridge(symbol)),
1156
+ ],
1157
+ label=f"quote:{symbol}",
1158
+ )
1131
1159
  return _yf_failover(
1132
1160
  symbol,
1133
1161
  lambda: _quote_yfinance(symbol),
@@ -1451,7 +1479,9 @@ def financials_yf(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1451
1479
  {
1452
1480
  "symbol": symbol,
1453
1481
  "name": info.get("shortName"),
1482
+ "currency": info.get("financialCurrency"),
1454
1483
  "market_cap": info.get("marketCap"),
1484
+ "market_cap_currency": info.get("currency"),
1455
1485
  "pe": info.get("trailingPE"),
1456
1486
  "forward_pe": info.get("forwardPE"),
1457
1487
  "pb": info.get("priceToBook"),
@@ -1517,6 +1547,37 @@ def cmd_financials(args):
1517
1547
  annual = getattr(args, "annual", False)
1518
1548
  market = detect_market(args.symbol)
1519
1549
  try:
1550
+ if market == "HK":
1551
+ if os.environ.get("LIXINGER_TOKEN"):
1552
+ try:
1553
+ from lixinger import financials_hk
1554
+
1555
+ result = financials_hk(args.symbol, periods, annual)
1556
+ snapshot = financials_yf(args.symbol, 1, False)
1557
+ result.update(
1558
+ {
1559
+ key: value
1560
+ for key, value in snapshot.items()
1561
+ if key not in ("warnings", "error") and (not snapshot.get("error") or value is not None)
1562
+ }
1563
+ )
1564
+ result["snapshot_available"] = not snapshot.get("error")
1565
+ result["snapshot_source"] = "yfinance" if result["snapshot_available"] else None
1566
+ if result["snapshot_available"]:
1567
+ result["report_date"] = snapshot.get("report_date")
1568
+ if snapshot.get("warnings"):
1569
+ result.setdefault("warnings", []).extend(snapshot["warnings"])
1570
+ return result
1571
+ except Exception:
1572
+ warning = "Lixinger HK unavailable (permissions/company type/provider); existing sources retained"
1573
+ else:
1574
+ warning = "LIXINGER_TOKEN not configured; extended HK financial history unavailable"
1575
+ result = financials_yf(args.symbol, periods, annual)
1576
+ result.setdefault("warnings", []).append(warning)
1577
+ result.setdefault("source", "yfinance/eastmoney")
1578
+ if len(result.get("periods", [])) < periods:
1579
+ result["warnings"].append("Requested HK financial history incomplete")
1580
+ return result
1520
1581
  return (
1521
1582
  financials_a(args.symbol, periods, annual) if market == "A" else financials_yf(args.symbol, periods, annual)
1522
1583
  )
@@ -3253,6 +3314,8 @@ def main():
3253
3314
  with contextlib.redirect_stdout(sys.stderr):
3254
3315
  result = dispatch[args.command](args)
3255
3316
  output(result)
3317
+ if isinstance(result, dict) and "error" in result:
3318
+ sys.exit(1)
3256
3319
 
3257
3320
 
3258
3321
  if __name__ == "__main__":
@@ -642,13 +642,25 @@ def analyze_multi(symbol: str, period: str, count: int, periods: list) -> dict:
642
642
 
643
643
 
644
644
  def analyze(symbol: str, period: str = "daily", count: int = 120) -> dict:
645
- records = fetch_kline(symbol, period, count)
645
+ return analyze_records(symbol, fetch_kline(symbol, period, count), period)
646
+
647
+
648
+ def analyze_records(symbol: str, records: list, period: str = "daily") -> dict:
646
649
  if isinstance(records, dict) and "error" in records:
647
650
  return records
648
- if not records:
651
+ if not isinstance(records, list) or not records:
649
652
  return {"error": "No kline data returned"}
653
+ if any(not isinstance(row, dict) for row in records):
654
+ return {"error": "Invalid kline rows"}
650
655
 
651
656
  df = to_dataframe(records)
657
+ required = ["date", "close", "high", "low", "volume"]
658
+ if any(field not in df for field in required):
659
+ return {"error": "Missing kline fields"}
660
+ if df["date"].isna().any() or not np.isfinite(df[required[1:]]).all().all():
661
+ return {"error": "Invalid kline values"}
662
+ if (df[["close", "high", "low"]] <= 0).any().any() or (df["volume"] < 0).any():
663
+ return {"error": "Kline prices must be positive and volume nonnegative"}
652
664
  if len(df) < 30:
653
665
  return {"error": f"Insufficient data: {len(df)} rows (need at least 30)"}
654
666
 
@@ -731,6 +743,8 @@ def main():
731
743
  else:
732
744
  result = {"error": f"Unknown command: {args.command}"}
733
745
  print(json.dumps(result, ensure_ascii=False, default=str))
746
+ if "error" in result:
747
+ sys.exit(1)
734
748
 
735
749
 
736
750
  if __name__ == "__main__":
@@ -7,6 +7,7 @@ import os
7
7
  import re
8
8
  import sys
9
9
  from datetime import date, timedelta
10
+ from html import unescape
10
11
  from io import StringIO
11
12
  from pathlib import Path
12
13
  from urllib.parse import unquote
@@ -86,6 +87,36 @@ def valuation_history(args):
86
87
  market, symbol = stock_identity(args.symbol)
87
88
  if not 1 <= args.years <= 10:
88
89
  raise ValueError("valuation history requires an A/HK symbol and years in 1..10")
90
+ warning = None
91
+ if market == "HK":
92
+ if os.environ.get("LIXINGER_TOKEN"):
93
+ try:
94
+ from lixinger import hk_data
95
+
96
+ rows = hk_data(args.symbol, "fundamental", ["pe_ttm", "pb"])
97
+ cutoff = (date.today() - pd.DateOffset(years=args.years)).date().isoformat()
98
+ history = sorted(
99
+ [
100
+ {"date": iso(r.get("date")), "pe_ttm": number(r.get("pe_ttm")), "pb": number(r.get("pb"))}
101
+ for r in rows
102
+ if iso(r.get("date")) and iso(r.get("date")) >= cutoff
103
+ ],
104
+ key=lambda r: r["date"],
105
+ )
106
+ if not history or not all(any(r[field] is not None for r in history) for field in ("pe_ttm", "pb")):
107
+ raise ValueError("Lixinger HK valuation history incomplete")
108
+ return {
109
+ "symbol": args.symbol,
110
+ "market": market,
111
+ "source": "lixinger",
112
+ "requested_years": args.years,
113
+ "history": history,
114
+ "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
115
+ }
116
+ except Exception:
117
+ warning = "Lixinger HK unavailable; Baidu history retained without mixing sources"
118
+ else:
119
+ warning = "LIXINGER_TOKEN not configured; HK history limited to available Baidu data"
89
120
  fetch = ak.stock_zh_valuation_baidu if market == "A" else ak.stock_hk_valuation_baidu
90
121
  period = "近一年" if args.years == 1 else "近三年" if args.years <= 3 else "近五年" if args.years <= 5 else "近十年"
91
122
  if market == "HK" and args.years > 3:
@@ -114,6 +145,8 @@ def valuation_history(args):
114
145
  result.update(history=history, metrics={field: valuation_summary(history, field) for field in ("pe_ttm", "pb")})
115
146
  if series.get("warnings"):
116
147
  result["warnings"] = series["warnings"]
148
+ if warning:
149
+ result.setdefault("warnings", []).append(warning)
117
150
  return result
118
151
 
119
152
 
@@ -1311,6 +1344,125 @@ def etf_details(args):
1311
1344
  return result
1312
1345
 
1313
1346
 
1347
+ ANNOUNCEMENT_CATEGORIES = {
1348
+ "all": ("", ""),
1349
+ "forecast": ("category_yjygjxz_szsh", "业绩预告"),
1350
+ "express": ("", "业绩快报"),
1351
+ "annual": ("category_ndbg_szsh", ""),
1352
+ "interim": ("category_bndbg_szsh", ""),
1353
+ "quarterly": ("category_yjdbg_szsh;category_sjdbg_szsh", ""),
1354
+ "reduction": ("category_gqbd_szsh", "减持"),
1355
+ "issuance": ("category_zf_szsh", ""),
1356
+ "inquiry": ("", "问询"),
1357
+ "dividend": ("category_qyfpxzcs_szsh", ""),
1358
+ }
1359
+
1360
+
1361
+ def announcements(args):
1362
+ import requests
1363
+
1364
+ market, symbol = stock_identity(args.symbol)
1365
+ if market != "A" or not 1 <= args.top <= 500 or args.category not in ANNOUNCEMENT_CATEGORIES:
1366
+ raise ValueError("announcements require an A-share stock, valid category and top in 1..500")
1367
+ end = date.fromisoformat(args.end_date) if args.end_date else date.today()
1368
+ start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1369
+ if start > end:
1370
+ raise ValueError("start_date must not exceed end_date")
1371
+
1372
+ def stock_list():
1373
+ response = requests.get("https://www.cninfo.com.cn/new/data/szse_stock.json", timeout=20)
1374
+ response.raise_for_status()
1375
+ return response.json()["stockList"]
1376
+
1377
+ stocks = cached("cninfo-stocks:A", DAY, stock_list)
1378
+ stock = next((r for r in stocks if r.get("code") == symbol), None)
1379
+ if not stock or not stock.get("orgId"):
1380
+ raise ValueError("stock not found in cninfo A-share directory")
1381
+ category, keyword = ANNOUNCEMENT_CATEGORIES[args.category]
1382
+ payload = {
1383
+ "pageNum": 1,
1384
+ "pageSize": 30,
1385
+ "column": "szse",
1386
+ "tabName": "fulltext",
1387
+ "plate": "",
1388
+ "stock": f"{symbol},{stock['orgId']}",
1389
+ "searchkey": keyword,
1390
+ "category": category,
1391
+ "seDate": f"{start.isoformat()}~{end.isoformat()}",
1392
+ "sortName": "time",
1393
+ "sortType": "desc",
1394
+ "isHLtitle": "false",
1395
+ }
1396
+ rows, seen = [], set()
1397
+ total = 0
1398
+ # shortcut: bounded 17-page query, narrow the date range for more than 500 disclosures.
1399
+ for page in range(1, (args.top + 29) // 30 + 1):
1400
+ payload["pageNum"] = page
1401
+ response = requests.post(
1402
+ "https://www.cninfo.com.cn/new/hisAnnouncement/query",
1403
+ data=payload,
1404
+ headers={"Referer": "https://www.cninfo.com.cn/"},
1405
+ timeout=20,
1406
+ )
1407
+ response.raise_for_status()
1408
+ data = response.json()
1409
+ if "totalAnnouncement" not in data:
1410
+ raise ValueError("cninfo announcement response unavailable")
1411
+ total = int(data["totalAnnouncement"])
1412
+ items = data.get("announcements") or []
1413
+ for row in items:
1414
+ if row.get("secCode") != symbol:
1415
+ continue
1416
+ stamp = iso(pd.to_datetime(row.get("announcementTime"), unit="ms", utc=True))
1417
+ path = row.get("adjunctUrl") or ""
1418
+ if not stamp or not start.isoformat() <= stamp <= end.isoformat() or path in seen:
1419
+ continue
1420
+ if not re.fullmatch(r"finalpage/[\d-]+/[\w.-]+\.pdf", path, re.I):
1421
+ continue
1422
+ seen.add(path)
1423
+ title = unescape(re.sub(r"<[^>]+>", "", row.get("announcementTitle") or ""))
1424
+ inferred = next(
1425
+ (
1426
+ key
1427
+ for key, pattern in [
1428
+ ("forecast", "业绩预告"),
1429
+ ("express", "业绩快报"),
1430
+ ("inquiry", "问询"),
1431
+ ("reduction", "减持"),
1432
+ ("interim", "半年度报告"),
1433
+ ("annual", "年度报告"),
1434
+ ("quarterly", "季度报告"),
1435
+ ("issuance", "发行|增发|定增"),
1436
+ ("dividend", "分红|权益分派|利润分配"),
1437
+ ]
1438
+ if re.search(pattern, title)
1439
+ ),
1440
+ "other",
1441
+ )
1442
+ rows.append(
1443
+ {
1444
+ "title": title,
1445
+ "date": stamp,
1446
+ "category": inferred,
1447
+ "pdf_url": f"https://static.cninfo.com.cn/{path}",
1448
+ }
1449
+ )
1450
+ if not items or page * 30 >= total or len(rows) >= args.top:
1451
+ break
1452
+ return {
1453
+ "symbol": args.symbol,
1454
+ "market": "A",
1455
+ "source": "cninfo",
1456
+ "start_date": start.isoformat(),
1457
+ "end_date": end.isoformat(),
1458
+ "total": total,
1459
+ "announcements": rows[: args.top],
1460
+ "truncated": total > len(rows[: args.top]),
1461
+ "body_extracted": False,
1462
+ "requested_category": args.category,
1463
+ }
1464
+
1465
+
1314
1466
  def main():
1315
1467
  parser = argparse.ArgumentParser(description="Value-investing datasets and dated historical context")
1316
1468
  sub = parser.add_subparsers(dest="command")
@@ -1318,6 +1470,12 @@ def main():
1318
1470
  p = sub.add_parser(command)
1319
1471
  p.add_argument("symbol")
1320
1472
  p.add_argument("--years", type=int, default=5)
1473
+ p = sub.add_parser("announcements")
1474
+ p.add_argument("symbol")
1475
+ p.add_argument("--category", choices=list(ANNOUNCEMENT_CATEGORIES), default="all")
1476
+ p.add_argument("--start-date", default="")
1477
+ p.add_argument("--end-date", default="")
1478
+ p.add_argument("--top", type=int, default=50)
1321
1479
  p = sub.add_parser("earnings_calendar")
1322
1480
  p.add_argument("--symbol", default="")
1323
1481
  p.add_argument("--report-date", default="")
@@ -1342,6 +1500,7 @@ def main():
1342
1500
  try:
1343
1501
  args = parser.parse_args()
1344
1502
  handlers = {
1503
+ "announcements": announcements,
1345
1504
  "valuation_history": valuation_history,
1346
1505
  "index_valuation": index_valuation,
1347
1506
  "earnings_calendar": earnings_calendar,