doertail Earnings Blocker
Filter stock signals that fall within an earnings announcement window (±N days). Earnings reports often produce sharp price gaps that invalidate short-term technical signals like RSI breakdowns or moving-average crosses. Blocking signals near earnings is a common, low-cost risk management gate in quant systems.
Data source: yfinance Ticker.calendar.
Note: Not financial advice. yfinance data may lag the official issuer calendar.
When to use
- A user is building or running a scanner/screener and wants to exclude stocks with upcoming earnings.
- A user asks whether a specific ticker has earnings within the next few days.
- A user wants to add an earnings-aware safeguard to an existing trading pipeline.
- A user is debugging false signals that turned out to be earnings-related gaps.
When NOT to use
- The user wants a full earnings analysis (consensus estimates, beat/miss history, analyst sentiment)
→ use the
earnings-previewstyle skills instead. - Index ETFs (SPY, QQQ, etc.) — they have no earnings dates.
Step 1: Ensure yfinance is available
import subprocess, sys
try:
import yfinance # noqa: F401
except ImportError:
subprocess.check_call([sys.executable, "-m", "pip", "install", "-q", "yfinance"])
Step 2: Use the helper
The provided helper (earnings_blocker.py) gives two functions:
from earnings_blocker import is_near_earnings, filter_by_earnings
# Single-ticker check
info = is_near_earnings("NVDA", days=2)
# → {"is_near": True, "date": "2026-05-21", "days_until": -1}
# Bulk filter (parallelized, ~5 workers)
candidates = [{"ticker": "AAPL", "close": 200.0},
{"ticker": "NVDA", "close": 140.0}]
passed, blocked = filter_by_earnings(candidates, days=2)
# `passed` keeps the safe ones; each candidate now has an "earnings" key.
Return shape
| Key | Type | Meaning |
|---|---|---|
is_near |
bool | True if the closest earnings date is within ±days |
date |
str | None | Closest earnings date in YYYY-MM-DD |
days_until |
int | None | Days from today (negative = past, positive = future) |
When data cannot be retrieved, is_near=False is returned (safe default — if uncertain, let the signal pass).
Step 3: Recommended days window
| Window | Use case |
|---|---|
days=1 |
Tight filter — only block day-before / day-after |
days=2 (default) |
Balanced — covers the announcement and the immediate reaction day |
days=5 |
Conservative — wider buffer for pre-earnings drift |
days=7+ |
Very conservative — may miss too many opportunities |
Step 4: Respond to the user
If the user asked about a single ticker:
AAPL's next earnings is scheduled for 2026-07-31 (D+70). It is not within the ±2-day window — signal is OK.
If the user is filtering a list:
Of 12 candidates, 1 was blocked due to earnings:
- NVDA: 2026-05-21 (D-1)
Remaining 11 passed the earnings gate.
Caveats to mention
- yfinance can lag the official earnings calendar by hours.
- If the ticker is delisted or new,
calendarmay be empty — treated as PASS. - Earnings can be re-scheduled; recheck within 24 hours of trading.
Real-world example
This skill was extracted from the quant-scanner project, where it acts as filter 6a in a multi-strategy pipeline: between universe scan and news-sentiment analysis. In one live run (2026-05-22), it correctly blocked Deere & Co. (DE) one day after its earnings report, preventing a mean-reversion false signal.