stock-analysis-plugin 0.2.4 → 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.
@@ -5,20 +5,24 @@ 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
11
13
  import time
12
- from datetime import datetime, timedelta
14
+ from datetime import date, datetime, timedelta
13
15
  from pathlib import Path
14
16
 
15
17
  sys.path.insert(0, str(Path(__file__).resolve().parent))
18
+ from _cache import DAY, WEEK, cached # noqa: E402
16
19
  from _subproc import run_tool, scrub_secrets, socket_timeout, utf8_stdio # noqa: E402
17
20
 
18
21
  # Explicitly exchange-prefixed A-share codes (sh600519 / sz000858 / bj920001).
19
22
  # Bare 6-digit codes are always stocks; the prefix is the disambiguation escape
20
23
  # hatch for index codes (sh000001 = 上证指数, not 平安银行).
21
24
  _A_PREFIXED_RE = re.compile(r"(?:sh|sz|bj)\d{6}", re.IGNORECASE)
25
+ _A_INDEX_RE = re.compile(r"(?:sh000\d{3}|sz399\d{3})", re.IGNORECASE)
22
26
 
23
27
 
24
28
  def detect_market(symbol: str) -> str:
@@ -140,7 +144,7 @@ def _kline_efinance(symbol: str, period: str, count: int) -> list:
140
144
  import efinance as ef
141
145
 
142
146
  freq_map = {"daily": 101, "weekly": 102, "monthly": 103}
143
- df = ef.stock.get_quote_history(symbol, klt=freq_map.get(period, 101))
147
+ df = ef.stock.get_quote_history(symbol, klt=freq_map.get(period, 101), fqt=1)
144
148
  if df is None or df.empty:
145
149
  raise ValueError("efinance returned empty data")
146
150
  col_map = {
@@ -204,6 +208,7 @@ def _kline_baostock(symbol: str, period: str, count: int) -> list:
204
208
  for c in ["open", "high", "low", "close", "volume"]:
205
209
  if c in df.columns:
206
210
  df[c] = pd.to_numeric(df[c], errors="coerce")
211
+ df["volume"] /= 100 # Baostock uses shares; the A-share CLI contract uses lots.
207
212
  keep = [c for c in ["date", "open", "high", "low", "close", "volume", "turnover", "change_pct"] if c in df.columns]
208
213
  df = df[keep].tail(count)
209
214
  return [_clean_row(r) for r in df.to_dict("records")]
@@ -276,6 +281,7 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
276
281
  """Build the quote row from one Tencent `~`-separated payload (already split).
277
282
  Shared by _quote_tencent (single) and _tencent_batch_quotes (snapshot leg)."""
278
283
  f += [""] * (50 - len(f)) # pad optional tail fields (pe/pb/market_cap/volume_ratio…) on short payloads
284
+ hk = detect_market(symbol) == "HK"
279
285
  turnover = _parse_float(f[37])
280
286
  market_cap = _parse_float(f[45])
281
287
  return {
@@ -284,42 +290,50 @@ def _tencent_payload_row(f: list, symbol: str) -> dict:
284
290
  "price": _parse_float(f[3]),
285
291
  "change": _parse_float(f[31]),
286
292
  "change_pct": _parse_float(f[32]),
287
- "volume": _parse_float(f[6]), # 手, same as akshare
288
- "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,
289
295
  "high": _parse_float(f[33]),
290
296
  "low": _parse_float(f[34]),
291
297
  "open": _parse_float(f[5]),
292
298
  "prev_close": _parse_float(f[4]),
293
299
  "market_cap": market_cap * 1e8 if market_cap is not None else None,
294
300
  "pe": _parse_float(f[39]),
295
- "pb": _parse_float(f[46]),
296
- "turnover_rate": _parse_float(f[38]),
297
- "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]),
298
305
  "amplitude": _parse_float(f[43]),
299
306
  }
300
307
 
301
308
 
302
309
  def _quote_tencent(symbol: str) -> dict:
303
- """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.
304
311
 
305
- Units differ from akshare: turnover arrives in 万元 and market_cap in 亿元 —
306
- 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."""
307
314
  import requests
308
315
 
309
- 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()
310
323
  f = _gbk_var_payload(resp.content).split("~")
311
324
  if len(f) < 35 or not f[1]:
312
325
  raise ValueError(f"tencent returned no quote for {symbol}")
313
- 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}")
314
329
  if normalize_stock_code(symbol)["is_etf"]:
315
330
  row["is_etf"] = True
316
- return _clean_row(row)
331
+ return row
317
332
 
318
333
 
319
334
  def _kline_tencent(symbol: str, period: str, count: int) -> list:
320
335
  """Tencent kline via web.ifzq.gtimg.cn. Rows are [date, open, close, high, low,
321
- volume(手)] ascending; qfq-adjusted like akshare. When a symbol has no qfq series
322
- (e.g. BSE codes) the endpoint returns the raw `day/week/month` key instead."""
336
+ volume(手)] ascending; raw series are accepted only for explicit indices."""
323
337
  import requests
324
338
 
325
339
  p_map = {"daily": "day", "weekly": "week", "monthly": "month"}
@@ -334,9 +348,9 @@ def _kline_tencent(symbol: str, period: str, count: int) -> list:
334
348
  if data.get("code") != 0:
335
349
  raise ValueError(f"tencent kline failed: {data.get('msg', '')}")
336
350
  node = data.get("data", {}).get(code, {})
337
- rows = node.get(f"qfq{p}") or node.get(p)
351
+ rows = node.get(p) if _A_INDEX_RE.fullmatch(symbol) else node.get(f"qfq{p}")
338
352
  if not rows:
339
- raise ValueError("tencent kline returned empty data")
353
+ raise ValueError("tencent kline returned empty data for required adjustment")
340
354
  return [
341
355
  _clean_row(
342
356
  {
@@ -429,8 +443,8 @@ def _sanitize(obj):
429
443
  import numpy as np
430
444
  import pandas as pd
431
445
 
432
- if isinstance(obj, (pd.Timestamp, datetime)):
433
- return obj.strftime("%Y-%m-%d")
446
+ if isinstance(obj, (pd.Timestamp, datetime, date)):
447
+ return None if pd.isna(obj) else obj.strftime("%Y-%m-%d")
434
448
  if isinstance(obj, (np.integer,)):
435
449
  return int(obj)
436
450
  if isinstance(obj, (np.floating,)):
@@ -450,24 +464,22 @@ def _clean_row(d: dict) -> dict:
450
464
 
451
465
 
452
466
  def kline_a(symbol: str, period: str, count: int) -> list:
453
- """A-share kline with failover: akshare → tushare → efinance → tencent → sina → pytdx → baostock.
467
+ """A-share qfq kline: akshare → tushare → efinance → tencent → baostock.
454
468
 
455
- Explicitly-prefixed symbols (sh000001, typically indices) skip the eastmoney
456
- sources — they take bare 6-digit codes only and would fail slowly first."""
457
- if _A_PREFIXED_RE.fullmatch(symbol):
469
+ Explicit indices keep raw points; unadjusted stock sources never enter the chain."""
470
+ if _A_INDEX_RE.fullmatch(symbol):
458
471
  sources = [
459
472
  ("tencent", lambda: _kline_tencent(symbol, period, count)),
460
473
  ("sina", lambda: _kline_sina(symbol, period, count)),
461
474
  ("baostock", lambda: _kline_baostock(symbol, period, count)),
462
475
  ]
463
476
  else:
477
+ symbol = symbol[2:] if _A_PREFIXED_RE.fullmatch(symbol) else symbol
464
478
  sources = [
465
479
  ("akshare", lambda: _kline_akshare(symbol, period, count)),
466
480
  ("tushare", lambda: _kline_tushare(symbol, period, count)),
467
481
  ("efinance", lambda: _kline_efinance(symbol, period, count)),
468
482
  ("tencent", lambda: _kline_tencent(symbol, period, count)),
469
- ("sina", lambda: _kline_sina(symbol, period, count)),
470
- ("pytdx", lambda: _kline_pytdx(symbol, period, count)),
471
483
  ("baostock", lambda: _kline_baostock(symbol, period, count)),
472
484
  ]
473
485
  with socket_timeout(25):
@@ -515,7 +527,7 @@ def _kline_akshare(symbol: str, period: str, count: int) -> list:
515
527
 
516
528
 
517
529
  def _kline_tushare(symbol: str, period: str, count: int) -> list:
518
- """Tushare kline via HTTP API. Requires TUSHARE_TOKEN."""
530
+ """Tushare qfq kline via daily factors or the adjusted week/month endpoint."""
519
531
  import os
520
532
 
521
533
  import pandas as pd
@@ -525,23 +537,29 @@ def _kline_tushare(symbol: str, period: str, count: int) -> list:
525
537
  if not token:
526
538
  raise ValueError("TUSHARE_TOKEN not set")
527
539
 
528
- api_name_map = {"daily": "daily", "weekly": "weekly", "monthly": "monthly"}
540
+ if normalize_stock_code(symbol)["is_etf"]:
541
+ raise ValueError("tushare stock adjustment does not cover ETFs")
529
542
  end = datetime.now()
530
543
  start = end - timedelta(days=count * 7 if period == "weekly" else count * 31 if period == "monthly" else count * 2)
531
544
 
532
- ts_code = f"{symbol}.SH" if symbol.startswith(("6", "9", "5")) else f"{symbol}.SZ"
545
+ ts_code = f"{symbol}.{_cn_code(symbol)[:2].upper()}"
546
+ params = {
547
+ "ts_code": ts_code,
548
+ "start_date": start.strftime("%Y%m%d"),
549
+ "end_date": end.strftime("%Y%m%d"),
550
+ }
551
+ prices = ["open", "high", "low", "close"]
552
+ if period != "daily":
553
+ params["freq"] = "week" if period == "weekly" else "month"
554
+ fields = prices if period == "daily" else [f"{c}_qfq" for c in prices]
533
555
 
534
556
  resp = requests.post(
535
557
  "http://api.tushare.pro",
536
558
  json={
537
- "api_name": api_name_map.get(period, "daily"),
559
+ "api_name": "daily" if period == "daily" else "stk_week_month_adj",
538
560
  "token": token,
539
- "params": {
540
- "ts_code": ts_code,
541
- "start_date": start.strftime("%Y%m%d"),
542
- "end_date": end.strftime("%Y%m%d"),
543
- },
544
- "fields": "trade_date,open,high,low,close,vol,amount,pct_chg",
561
+ "params": params,
562
+ "fields": ",".join(["trade_date", *fields, "vol", "amount", "pct_chg"]),
545
563
  },
546
564
  timeout=15,
547
565
  )
@@ -550,12 +568,36 @@ def _kline_tushare(symbol: str, period: str, count: int) -> list:
550
568
  raise ValueError(f"tushare returned no data: {data.get('msg', '')}")
551
569
 
552
570
  df = pd.DataFrame(data["data"]["items"], columns=data["data"]["fields"])
571
+ if not set(fields).issubset(df.columns):
572
+ raise ValueError("tushare returned incomplete adjusted prices")
573
+ df[fields] = df[fields].apply(pd.to_numeric, errors="coerce")
574
+ if period == "daily":
575
+ factor_resp = requests.post(
576
+ "http://api.tushare.pro",
577
+ json={"api_name": "adj_factor", "token": token, "params": params, "fields": "trade_date,adj_factor"},
578
+ timeout=15,
579
+ ).json()
580
+ if factor_resp.get("code") != 0 or not factor_resp.get("data", {}).get("items"):
581
+ raise ValueError("tushare returned no adjustment factors")
582
+ factors = pd.DataFrame(factor_resp["data"]["items"], columns=factor_resp["data"]["fields"])
583
+ factors["adj_factor"] = pd.to_numeric(factors["adj_factor"], errors="coerce")
584
+ if not (factors["adj_factor"].gt(0) & factors["adj_factor"].lt(float("inf"))).all():
585
+ raise ValueError("tushare returned invalid adjustment factors")
586
+ latest_factor = factors.sort_values("trade_date").iloc[-1]["adj_factor"]
587
+ df = df.merge(factors, on="trade_date", how="left", validate="one_to_one")
588
+ if df["adj_factor"].isna().any():
589
+ raise ValueError("tushare adjustment factors missing for price dates")
590
+ df[prices] = df[prices].mul(df["adj_factor"] / latest_factor, axis=0)
591
+ else:
592
+ df = df.drop(columns=prices, errors="ignore")
593
+ df = df.rename(columns={f"{c}_qfq": c for c in prices})
594
+ if not df[prices].abs().lt(float("inf")).all().all():
595
+ raise ValueError("tushare returned invalid adjusted prices")
553
596
  col_map = {"trade_date": "date", "vol": "volume", "amount": "turnover", "pct_chg": "change_pct"}
554
597
  df = df.rename(columns=col_map)
555
598
  df = df.sort_values("date")
556
- for c in ["open", "high", "low", "close", "volume"]:
557
- if c in df.columns:
558
- df[c] = pd.to_numeric(df[c], errors="coerce")
599
+ if "volume" in df.columns:
600
+ df["volume"] = pd.to_numeric(df["volume"], errors="coerce")
559
601
  keep = [c for c in ["date", "open", "high", "low", "close", "volume", "turnover", "change_pct"] if c in df.columns]
560
602
  df = df[keep].tail(count)
561
603
  return [_clean_row(r) for r in df.to_dict("records")]
@@ -632,41 +674,6 @@ def _pytdx_connect(api) -> None:
632
674
  raise ConnectionError(f"pytdx failed to connect to any TDX server ({'; '.join(errors)})")
633
675
 
634
676
 
635
- def _kline_pytdx(symbol: str, period: str, count: int) -> list:
636
- """pytdx kline from TDX market servers. No credentials needed."""
637
- from pytdx.hq import TdxHq_API
638
-
639
- market = 1 if symbol.startswith(("6", "9", "5")) else 0
640
- freq_map = {"daily": 9, "weekly": 5, "monthly": 6}
641
-
642
- api = TdxHq_API()
643
- try:
644
- _pytdx_connect(api)
645
- data = api.get_security_bars(freq_map.get(period, 9), market, symbol, 0, count)
646
- finally:
647
- api.disconnect()
648
-
649
- if not data:
650
- raise ValueError("pytdx returned empty data")
651
-
652
- rows = []
653
- for bar in data:
654
- rows.append(
655
- _clean_row(
656
- {
657
- "date": bar["datetime"][:10],
658
- "open": bar["open"],
659
- "high": bar["high"],
660
- "low": bar["low"],
661
- "close": bar["close"],
662
- "volume": bar["vol"],
663
- "turnover": bar.get("amount"),
664
- }
665
- )
666
- )
667
- return rows[-count:]
668
-
669
-
670
677
  def _quote_pytdx(symbol: str) -> dict:
671
678
  """pytdx realtime quote from TDX market servers."""
672
679
  from pytdx.hq import TdxHq_API
@@ -871,7 +878,7 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
871
878
  "function": fn_map.get(period, fn_map["daily"]),
872
879
  "symbol": symbol,
873
880
  "apikey": api_key,
874
- "outputsize": "compact",
881
+ "outputsize": "full" if count > 100 else "compact",
875
882
  },
876
883
  timeout=20,
877
884
  )
@@ -885,14 +892,19 @@ def _kline_alphavantage(symbol: str, period: str, count: int) -> list:
885
892
 
886
893
  rows = []
887
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
888
900
  rows.append(
889
901
  _clean_row(
890
902
  {
891
903
  "date": date_str,
892
- "open": float(vals["1. open"]),
893
- "high": float(vals["2. high"]),
894
- "low": float(vals["3. low"]),
895
- "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,
896
908
  "volume": int(vals.get("6. volume", vals.get("5. volume", 0))),
897
909
  }
898
910
  )
@@ -966,6 +978,9 @@ def cmd_kline(args):
966
978
  try:
967
979
  if market == "A":
968
980
  data = kline_a(args.symbol, args.period, args.count)
981
+ if data:
982
+ adjusted = "none" if _A_INDEX_RE.fullmatch(args.symbol) else "qfq"
983
+ data = [dict(row, adjusted=adjusted) for row in data]
969
984
  else:
970
985
  data = kline_yf(args.symbol, args.period, args.count)
971
986
  return data
@@ -1130,7 +1145,17 @@ def _quote_finnhub(symbol: str) -> dict:
1130
1145
 
1131
1146
 
1132
1147
  def quote_yf(symbol: str) -> dict:
1133
- """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
+ )
1134
1159
  return _yf_failover(
1135
1160
  symbol,
1136
1161
  lambda: _quote_yfinance(symbol),
@@ -1363,17 +1388,46 @@ def _financials_a_row(r) -> dict:
1363
1388
  )
1364
1389
 
1365
1390
 
1366
- def financials_a(symbol: str, periods: int = 1) -> dict:
1391
+ def _cached_frame(key, fetch):
1392
+ import pandas as pd
1393
+
1394
+ rows = cached(key, DAY, lambda: [_clean_row(r) for r in fetch().to_dict("records")])
1395
+ return pd.DataFrame(rows)
1396
+
1397
+
1398
+ def _yf_info(symbol, ticker):
1399
+ def fetch():
1400
+ info = ticker.info
1401
+ if not isinstance(info, dict) or not any(
1402
+ info.get(k) for k in ("shortName", "longName", "currency", "exchange")
1403
+ ):
1404
+ raise ValueError("Yahoo basic information unavailable")
1405
+ return info
1406
+
1407
+ return cached(f"yf-basic-info:{_yf_hk_symbol(symbol)}", DAY, fetch)
1408
+
1409
+
1410
+ def _financials_a_frame(symbol):
1367
1411
  import akshare as ak
1368
1412
 
1413
+ df = _cached_frame(
1414
+ f"financial-source:{symbol}", lambda: _akshare_retry(ak.stock_financial_analysis_indicator, symbol=symbol)
1415
+ )
1416
+ return df.sort_values("日期", ascending=False) if "日期" in df.columns else df
1417
+
1418
+
1419
+ def financials_a(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1369
1420
  try:
1370
- df = _akshare_retry(ak.stock_financial_analysis_indicator, symbol=symbol)
1421
+ df = _financials_a_frame(symbol)
1422
+ if annual and not df.empty:
1423
+ df = df[df["日期"].astype(str).str.endswith("12-31")]
1371
1424
  if df is None or df.empty:
1372
1425
  # error + note coexist (additive): consumers check either key
1373
1426
  return {"symbol": symbol, "error": "No financial data", "note": "No financial data"}
1374
1427
  result = {"symbol": symbol, **_financials_a_row(df.iloc[0])}
1375
1428
  if periods > 1:
1376
1429
  result["periods"] = [_financials_a_row(r) for r in df.head(periods).to_dict("records")]
1430
+ result["available_periods"] = len(result["periods"])
1377
1431
  return result
1378
1432
  except Exception:
1379
1433
  return {"symbol": symbol, "error": "Financial data unavailable", "note": "Financial data unavailable"}
@@ -1386,30 +1440,48 @@ def _yf_financial_periods(t, periods: int) -> list:
1386
1440
  fin = t.financials
1387
1441
  if fin is None or fin.empty:
1388
1442
  return []
1389
- return [
1390
- _clean_row(
1391
- {
1392
- "period_end": col,
1393
- "total_revenue": fin[col].get("Total Revenue"),
1394
- "net_income": fin[col].get("Net Income"),
1395
- }
1443
+ rows = []
1444
+ for col in list(fin.columns)[:periods]:
1445
+ revenue = _sanitize(_parse_float(fin[col].get("Total Revenue")))
1446
+ profit = _sanitize(_parse_float(fin[col].get("Net Income")))
1447
+ gross = _sanitize(_parse_float(fin[col].get("Gross Profit")))
1448
+ rows.append(
1449
+ _clean_row(
1450
+ {
1451
+ "period_end": col,
1452
+ "total_revenue": revenue,
1453
+ "net_income": profit,
1454
+ "net_profit_margin": profit / revenue * 100
1455
+ if profit is not None and revenue and revenue > 0
1456
+ else None,
1457
+ "gross_margin": gross / revenue * 100
1458
+ if gross is not None and revenue and revenue > 0
1459
+ else None,
1460
+ }
1461
+ )
1396
1462
  )
1397
- for col in list(fin.columns)[:periods]
1398
- ]
1463
+ return rows
1399
1464
  except Exception:
1400
1465
  return []
1401
1466
 
1402
1467
 
1403
- def financials_yf(symbol: str, periods: int = 1) -> dict:
1468
+ def financials_yf(symbol: str, periods: int = 1, annual: bool = False) -> dict:
1404
1469
  import yfinance as yf
1405
1470
 
1406
1471
  t = yf.Ticker(_yf_hk_symbol(symbol))
1407
- info = t.info
1472
+ warnings = []
1473
+ try:
1474
+ info = _yf_info(symbol, t)
1475
+ except Exception:
1476
+ info = {}
1477
+ warnings.append("Yahoo snapshot unavailable")
1408
1478
  result = _clean_row(
1409
1479
  {
1410
1480
  "symbol": symbol,
1411
1481
  "name": info.get("shortName"),
1482
+ "currency": info.get("financialCurrency"),
1412
1483
  "market_cap": info.get("marketCap"),
1484
+ "market_cap_currency": info.get("currency"),
1413
1485
  "pe": info.get("trailingPE"),
1414
1486
  "forward_pe": info.get("forwardPE"),
1415
1487
  "pb": info.get("priceToBook"),
@@ -1421,20 +1493,94 @@ def financials_yf(symbol: str, periods: int = 1) -> dict:
1421
1493
  "dividend_yield": info.get("dividendYield"),
1422
1494
  }
1423
1495
  )
1424
- if periods > 1:
1425
- history = _yf_financial_periods(t, periods)
1496
+ if warnings:
1497
+ result["warnings"] = warnings
1498
+ if periods > 1 or (annual and detect_market(symbol) == "HK"):
1499
+ history = cached(f"yf-income-history:{_yf_hk_symbol(symbol)}", DAY, lambda: _yf_financial_periods(t, 40))[
1500
+ :periods
1501
+ ]
1502
+ if detect_market(symbol) == "HK" and annual:
1503
+ try:
1504
+ import akshare as ak
1505
+
1506
+ hk_symbol = _yf_hk_symbol(symbol).split(".")[0].zfill(5)
1507
+ df = _cached_frame(
1508
+ f"hk-annual-indicators:{hk_symbol}",
1509
+ lambda: _akshare_retry(
1510
+ ak.stock_financial_hk_analysis_indicator_em, symbol=hk_symbol, indicator="年度"
1511
+ ),
1512
+ )
1513
+ if df.empty:
1514
+ raise ValueError("HK annual indicators unavailable")
1515
+ if df is not None and not df.empty:
1516
+ df = df.sort_values("REPORT_DATE", ascending=False)
1517
+ history = [
1518
+ _clean_row(
1519
+ {
1520
+ "report_date": str(r.get("REPORT_DATE"))[:10],
1521
+ "roe": r.get("ROE_AVG"),
1522
+ "gross_margin": r.get("GROSS_PROFIT_RATIO"),
1523
+ "net_profit_margin": r.get("NET_PROFIT_RATIO"),
1524
+ "currency": r.get("CURRENCY"),
1525
+ }
1526
+ )
1527
+ for r in df.head(periods).to_dict("records")
1528
+ ]
1529
+ except Exception:
1530
+ result.setdefault("warnings", []).append(
1531
+ "HK annual indicators unavailable; available Yahoo history retained"
1532
+ )
1426
1533
  if history:
1427
1534
  result["periods"] = history
1535
+ result["available_periods"] = len(history)
1536
+ result["requested_periods"] = periods
1537
+ result["history_units"] = {"roe": "percent", "gross_margin": "percent", "net_profit_margin": "percent"}
1538
+ if not info and not result.get("periods"):
1539
+ result["error"] = "Financial data unavailable"
1428
1540
  return result
1429
1541
 
1430
1542
 
1431
1543
  def cmd_financials(args):
1432
1544
  periods = getattr(args, "periods", 1)
1433
- if periods < 1:
1434
- return {"error": f"periods must be a positive integer, got {periods}"}
1545
+ if not 1 <= periods <= 40:
1546
+ return {"error": f"periods must be between 1 and 40, got {periods}"}
1547
+ annual = getattr(args, "annual", False)
1435
1548
  market = detect_market(args.symbol)
1436
1549
  try:
1437
- return financials_a(args.symbol, periods) if market == "A" else financials_yf(args.symbol, periods)
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
1581
+ return (
1582
+ financials_a(args.symbol, periods, annual) if market == "A" else financials_yf(args.symbol, periods, annual)
1583
+ )
1438
1584
  except Exception as e:
1439
1585
  return {"error": str(e)}
1440
1586
 
@@ -2050,6 +2196,12 @@ def sector_constituents_a(sector: str, board_type: str = "auto") -> dict:
2050
2196
 
2051
2197
 
2052
2198
  def cmd_sector_constituents(args):
2199
+ return cached(
2200
+ f"sector-constituents:{args.sector.strip()}:{args.board_type}", WEEK, lambda: _sector_constituents(args)
2201
+ )
2202
+
2203
+
2204
+ def _sector_constituents(args):
2053
2205
  # argparse 保证属性存在;空串仍可传入
2054
2206
  sector = args.sector.strip()
2055
2207
  if not sector:
@@ -2058,9 +2210,6 @@ def cmd_sector_constituents(args):
2058
2210
  # Sector names are user input — hash them instead of sanitizing, so names that
2059
2211
  # differ only in whitespace/punctuation (创新药 vs 创新 药) can't collide.
2060
2212
  cache_key = hashlib.sha256(f"{sector}|{board_type}".encode()).hexdigest()[:16]
2061
- cached = _disk_cache_get(cache_key)
2062
- if cached is not None:
2063
- return cached
2064
2213
  try:
2065
2214
  result = sector_constituents_a(sector, board_type)
2066
2215
  except Exception as e:
@@ -2164,13 +2313,17 @@ def _stock_boards_cninfo(symbol: str) -> list:
2164
2313
  def _stock_boards_from_cache(symbol: str) -> list:
2165
2314
  """Reverse lookup against the get_sector_constituents disk cache — the honest
2166
2315
  fallback when eastmoney blocks the caller's IP and xueqiu has no token (the two
2167
- live A-share sources are both eastmoney-flavored). Reads every unexpired
2168
- constituents payload in the cache dir and returns one entry per cached sector
2316
+ live A-share sources are both eastmoney-flavored). Reads week-lived user-directory entries plus legacy temporary payloads,
2317
+ and returns one entry per cached sector
2169
2318
  containing the symbol. Cold cache → []; malformed cache files are skipped
2170
2319
  (_disk_cache_get returns None on expiry, bad JSON, or read errors)."""
2320
+ from itertools import chain
2321
+
2322
+ from _cache import cached_values
2323
+
2171
2324
  boards = []
2172
- for path in _DATA_CACHE_DIR.glob("*.json"):
2173
- data = _disk_cache_get(path.stem)
2325
+ legacy = (_disk_cache_get(path.stem) for path in _DATA_CACHE_DIR.glob("*.json"))
2326
+ for data in chain(legacy, cached_values("sector-constituents", WEEK)):
2174
2327
  if not isinstance(data, dict):
2175
2328
  continue
2176
2329
  sector = data.get("sector")
@@ -2178,7 +2331,9 @@ def _stock_boards_from_cache(symbol: str) -> list:
2178
2331
  continue
2179
2332
  for row in data.get("constituents") or []:
2180
2333
  if isinstance(row, dict) and str(row.get("code")) == symbol:
2181
- boards.append(_board_entry(sector, "cache", data.get("board_type", "")))
2334
+ board = _board_entry(sector, "cache", data.get("board_type", ""))
2335
+ if board not in boards:
2336
+ boards.append(board)
2182
2337
  break
2183
2338
  return boards
2184
2339
 
@@ -2223,6 +2378,12 @@ def _resolve_leg_down(name: str) -> bool:
2223
2378
 
2224
2379
 
2225
2380
  def resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2381
+ if info_map is not None:
2382
+ return _resolve_stock_sectors(symbol, info_map)
2383
+ return cached(f"stock-sectors:{symbol}", WEEK, lambda: _resolve_stock_sectors(symbol, info_map))
2384
+
2385
+
2386
+ def _resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2226
2387
  """Reverse map: stock → boards it belongs to (A/HK). Sources are merged (a single
2227
2388
  source failing is not fatal — the others' boards are still returned) rather than
2228
2389
  first-hit failover: each source covers a different flavor (industry vs concept).
@@ -2299,6 +2460,8 @@ def resolve_stock_sectors(symbol: str, info_map=None) -> dict:
2299
2460
  result["error"] = error
2300
2461
  return result
2301
2462
  result["sectors"] = deduped
2463
+ if errors:
2464
+ result["warnings"] = errors
2302
2465
  return result
2303
2466
 
2304
2467
 
@@ -2317,7 +2480,10 @@ def cmd_stock_info(args):
2317
2480
  result["is_etf"] = True
2318
2481
  info_map = None
2319
2482
  try:
2320
- df = _akshare_retry(ak.stock_individual_info_em, symbol=args.symbol)
2483
+ df = _cached_frame(
2484
+ f"a-basic-info:{args.symbol}",
2485
+ lambda: _akshare_retry(ak.stock_individual_info_em, symbol=args.symbol),
2486
+ )
2321
2487
  if df is not None and not df.empty:
2322
2488
  info_map = {}
2323
2489
  for _, row in df.iterrows():
@@ -2329,26 +2495,33 @@ def cmd_stock_info(args):
2329
2495
  result["float_shares"] = info_map.get("流通股")
2330
2496
  result["total_market_cap"] = info_map.get("总市值")
2331
2497
  result["float_market_cap"] = info_map.get("流通市值")
2498
+ else:
2499
+ result.setdefault("warnings", []).append("basic information unavailable")
2332
2500
  except Exception:
2333
- pass
2501
+ result.setdefault("warnings", []).append("basic information unavailable")
2334
2502
  try:
2335
2503
  # boards 复用 resolve_stock_sectors;info_map 透传避免东财二次拉取
2336
2504
  resolved = resolve_stock_sectors(args.symbol, info_map=info_map)
2337
2505
  boards = [s["name"] for s in resolved.get("sectors", [])]
2338
2506
  if boards:
2339
2507
  result["boards"] = boards[:10]
2508
+ if resolved.get("error") or resolved.get("warnings"):
2509
+ result.setdefault("warnings", []).append("sector mapping incomplete")
2340
2510
  except Exception:
2341
- pass
2511
+ result.setdefault("warnings", []).append("sector mapping unavailable")
2342
2512
  if is_etf:
2343
2513
  try:
2344
2514
  # ETF 最新净值(天天基金-场内基金历史净值明细)。窄日期窗口 → 单页返回
2345
2515
  end = datetime.now()
2346
2516
  start = end - timedelta(days=30)
2347
- nav_df = _akshare_retry(
2348
- ak.fund_etf_fund_info_em,
2349
- fund=args.symbol,
2350
- start_date=start.strftime("%Y%m%d"),
2351
- end_date=end.strftime("%Y%m%d"),
2517
+ nav_df = _cached_frame(
2518
+ f"etf-basic-nav:{args.symbol}",
2519
+ lambda: _akshare_retry(
2520
+ ak.fund_etf_fund_info_em,
2521
+ fund=args.symbol,
2522
+ start_date=start.strftime("%Y%m%d"),
2523
+ end_date=end.strftime("%Y%m%d"),
2524
+ ),
2352
2525
  )
2353
2526
  if nav_df is not None and not nav_df.empty:
2354
2527
  latest = nav_df.iloc[-1]
@@ -2357,14 +2530,16 @@ def cmd_stock_info(args):
2357
2530
  nav_date = latest.get("净值日期")
2358
2531
  if nav_date is not None:
2359
2532
  result["nav_date"] = str(nav_date)[:10] # datetime.date/Timestamp → ISO date
2533
+ else:
2534
+ result.setdefault("warnings", []).append("ETF NAV unavailable")
2360
2535
  except Exception:
2361
- pass
2536
+ result.setdefault("warnings", []).append("ETF NAV unavailable")
2362
2537
  return _clean_row(result)
2363
2538
  else:
2364
2539
  import yfinance as yf
2365
2540
 
2366
2541
  t = yf.Ticker(_yf_hk_symbol(args.symbol))
2367
- info = t.info
2542
+ info = _yf_info(args.symbol, t)
2368
2543
  return _clean_row(
2369
2544
  {
2370
2545
  "symbol": args.symbol,
@@ -2532,7 +2707,7 @@ def cmd_fundamental_context(args):
2532
2707
  result["valuation"] = {}
2533
2708
 
2534
2709
  try:
2535
- df = _akshare_retry(ak.stock_financial_analysis_indicator, symbol=args.symbol)
2710
+ df = _financials_a_frame(args.symbol)
2536
2711
  if df is not None and len(df) >= 1:
2537
2712
  r0 = df.iloc[0]
2538
2713
  profitability = {
@@ -2940,6 +3115,32 @@ def cmd_margin_trading(args):
2940
3115
  msg = f"margin detail fetch failed for all {len(trade_days)} day(s): {'; '.join(failures)}"
2941
3116
  return {"symbol": args.symbol, "error": msg}
2942
3117
  return {"symbol": args.symbol, "error": f"no margin trading data for {args.symbol} (可能不是两融标的)"}
3118
+ if getattr(args, "include_ratio", False):
3119
+ try:
3120
+ with socket_timeout(25):
3121
+ history = (
3122
+ _failover(
3123
+ [
3124
+ ("akshare", lambda: _kline_akshare(bare, "daily", days + 10)),
3125
+ ("efinance", lambda: _kline_efinance(bare, "daily", days + 10)),
3126
+ ("baostock", lambda: _kline_baostock(bare, "daily", days + 10)),
3127
+ ],
3128
+ label=f"margin_turnover:{bare}",
3129
+ )
3130
+ or []
3131
+ )
3132
+ turnovers = {str(r.get("date"))[:10]: _sanitize(_parse_float(r.get("turnover"))) for r in history}
3133
+ except Exception:
3134
+ turnovers = {}
3135
+ for row in rows:
3136
+ turnover = turnovers.get(row["date"])
3137
+ buy = _sanitize(_parse_float(row.get("margin_buy")))
3138
+ row["turnover"] = turnover
3139
+ row["margin_buy_ratio_pct"] = (
3140
+ round(buy / turnover * 100, 4) if buy is not None and turnover and turnover > 0 else None
3141
+ )
3142
+ if row["margin_buy_ratio_pct"] is None:
3143
+ row["margin_buy_ratio_note"] = "matching-date CNY turnover unavailable"
2943
3144
  return rows
2944
3145
  except Exception as e:
2945
3146
  return {"error": str(e)}
@@ -3032,6 +3233,7 @@ def main():
3032
3233
  p_fin = sub.add_parser("financials")
3033
3234
  p_fin.add_argument("symbol")
3034
3235
  p_fin.add_argument("--periods", type=int, default=1)
3236
+ p_fin.add_argument("--annual", action="store_true", help="Select annual reports; periods=10 requests ten years")
3035
3237
 
3036
3238
  p_snap = sub.add_parser("market_snapshot")
3037
3239
  p_snap.add_argument("--market", default="A", choices=["A", "HK", "US"])
@@ -3076,6 +3278,7 @@ def main():
3076
3278
  p_margin = sub.add_parser("margin_trading")
3077
3279
  p_margin.add_argument("symbol")
3078
3280
  p_margin.add_argument("--days", type=int, default=10)
3281
+ p_margin.add_argument("--include-ratio", action="store_true", help="Add same-day margin buys / CNY turnover")
3079
3282
 
3080
3283
  p_nb = sub.add_parser("northbound_flow")
3081
3284
  p_nb.add_argument("--days", type=int, default=10)
@@ -3111,6 +3314,8 @@ def main():
3111
3314
  with contextlib.redirect_stdout(sys.stderr):
3112
3315
  result = dispatch[args.command](args)
3113
3316
  output(result)
3317
+ if isinstance(result, dict) and "error" in result:
3318
+ sys.exit(1)
3114
3319
 
3115
3320
 
3116
3321
  if __name__ == "__main__":