stock-analysis-plugin 0.2.4 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/tools/screener.py CHANGED
@@ -73,6 +73,13 @@ def merge_filters(config: dict | None) -> dict:
73
73
 
74
74
  def apply_filters(df: pd.DataFrame, filters: dict) -> pd.DataFrame:
75
75
  conditions = []
76
+ for bound, op in [("dividend_yield_min", "min"), ("dividend_yield_max", "max")]:
77
+ if bound in filters:
78
+ if "dividend_yield" not in df.columns:
79
+ return df.iloc[0:0].copy()
80
+ conditions.append(
81
+ df["dividend_yield"] >= filters[bound] if op == "min" else df["dividend_yield"] <= filters[bound]
82
+ )
76
83
  if "pe" in df.columns:
77
84
  conditions.append(df["pe"] >= filters["pe_min"])
78
85
  conditions.append(df["pe"] <= filters["pe_max"])
@@ -121,7 +128,10 @@ def compute_scores(df: pd.DataFrame) -> pd.DataFrame:
121
128
  value_parts.append(100 - _minmax(df["pe"]))
122
129
  if "pb" in df.columns:
123
130
  value_parts.append(100 - _minmax(df["pb"]))
124
- df["value_score"] = sum(value_parts) / max(len(value_parts), 1)
131
+ if "dividend_yield" in df.columns:
132
+ df["dividend_score"] = _minmax(df["dividend_yield"])
133
+ value_parts.append(df["dividend_score"])
134
+ df["value_score"] = pd.concat(value_parts, axis=1).mean(axis=1) if value_parts else 0.0
125
135
 
126
136
  # Momentum: higher change_pct and volume_ratio → higher score
127
137
  mom_parts = []
@@ -304,6 +314,20 @@ def _apply_l2(candidates: list, market: str, multiplier: float) -> None:
304
314
 
305
315
 
306
316
  def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict:
317
+ filters = merge_filters(config)
318
+ dividend_requested = any(k.startswith("dividend_yield_") for k in filters) or (config or {}).get("sort_by") in (
319
+ "dividend_yield",
320
+ "dividend_score",
321
+ )
322
+ if dividend_requested and market not in ("A", "HK"):
323
+ return {"error": "dividend screening currently covers A/HK only", "market": market}
324
+ for key in ("dividend_yield_min", "dividend_yield_max"):
325
+ if key in filters and (
326
+ isinstance(filters[key], bool)
327
+ or not isinstance(filters[key], (int, float))
328
+ or not np.isfinite(filters[key])
329
+ ):
330
+ return {"error": f"{key} must be a finite number in percent units", "market": market}
307
331
  raw = fetch_snapshot(market)
308
332
  if isinstance(raw, dict) and "error" in raw:
309
333
  return raw
@@ -330,7 +354,30 @@ def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict
330
354
  if existing:
331
355
  df = df.dropna(subset=existing)
332
356
 
333
- filters = merge_filters(config)
357
+ dividend_meta = {}
358
+ if dividend_requested:
359
+ try:
360
+ from value_data import dividend_ranking
361
+
362
+ ranked = dividend_ranking(report_date=(config or {}).get("dividend_report_date", ""), market=market)
363
+
364
+ def dividend_key(symbol):
365
+ return symbol.split(".")[0].lstrip("0") if market == "HK" else symbol
366
+
367
+ yields = {dividend_key(r["symbol"]): r["dividend_yield"] for r in ranked["items"]}
368
+ df["dividend_yield"] = df["symbol"].map(dividend_key).map(yields)
369
+ dividend_meta = {
370
+ "dividend_factor": {
371
+ "report_date": ranked["report_date"],
372
+ "yield_basis": ranked.get("yield_basis", "provider report-period cash dividend yield, percent"),
373
+ "missing": "unknown; excluded by dividend filters",
374
+ }
375
+ }
376
+ except Exception:
377
+ return {
378
+ "error": "dividend data unavailable; requested dividend criterion was not applied",
379
+ "market": market,
380
+ }
334
381
  df = apply_filters(df, filters)
335
382
  filtered_count = len(df)
336
383
 
@@ -344,6 +391,7 @@ def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict
344
391
  "candidates": [],
345
392
  "market_sentiment": sentiment,
346
393
  "l2_enabled": l2_enabled,
394
+ **dividend_meta,
347
395
  }
348
396
 
349
397
  df = compute_scores(df)
@@ -374,6 +422,7 @@ def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict
374
422
  "pb",
375
423
  "market_cap",
376
424
  "volume_ratio",
425
+ "dividend_yield",
377
426
  ]:
378
427
  v = _finite(row.get(field))
379
428
  if v is not None:
@@ -386,6 +435,8 @@ def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict
386
435
  "composite": None if composite is None else round(composite, 1),
387
436
  "final": None if composite is None else round(composite * multiplier, 1),
388
437
  }
438
+ if "dividend_score" in row:
439
+ entry["scores"]["dividend"] = _finite(round(float(row["dividend_score"]), 1))
389
440
  candidates.append(entry)
390
441
 
391
442
  if l2_enabled:
@@ -403,6 +454,7 @@ def screen(market: str, top: int, config: dict | None, l2: bool = False) -> dict
403
454
  "candidates": candidates,
404
455
  "market_sentiment": sentiment,
405
456
  "l2_enabled": l2_enabled,
457
+ **dividend_meta,
406
458
  }
407
459
 
408
460