Earnings blocker

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-preview style 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, calendar may 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.