Yfinance

yfinance

Python scripts wrapping yfinance, one per mode:

• scripts/fast_info.py — current quote; optional --with-isin for opt-in ISIN lookup (slow ~1-5 s/ticker, spotty hit rate, see references/fast_info.md)
• scripts/history.py — historical OHLCV; full bars, --summary aggregates, --events-only corporate-action rows, --shares shares-outstanding time series (equity-only), or --metadata snapshot
• scripts/info.py — profile + fundamentals + analyst; full grouped sections or --summary flat dict
• scripts/earnings.py — upcoming + recent earnings dates with EPS estimates / actuals / surprise
• scripts/financials.py — annual / quarterly / TTM income statement, balance sheet, and cash flow
• scripts/news.py — recent Yahoo Finance news headlines per ticker
• scripts/holders.py — insider / institutional ownership rollup + top-10 institutional and mutual-fund holders
• scripts/options.py — option chain (calls + puts for one expiry); pair with --moneyness for an ATM-band slice + ATM/PCR summary
• scripts/insiders.py — Form 4 insider transactions (last ~24 mo) + 6-month buy/sell rollup + current roster
• scripts/analyst.py — analyst recommendations time series (0m / -1m / -2m / -3m bucket counts) + per-event grade-change feed with embedded price-target moves
• scripts/screener.py — market-wide discovery via Yahoo predefined screens or custom AND/OR queries; ≤250 quotes per call. Ticker-free — produces tickers from a filter, doesn't take one
• scripts/fund_holdings.py — ETF / mutual-fund holdings, weightings (sector / asset / bond-rating), expense ratio + AUM, fund-level P/E / P/B / duration. Fund-only
• scripts/sec_filings.py — SEC filings list (10-K / 10-Q / 8-K / DEF 14A / 20-F / 6-K / SC 13G/A / etc.) with date / type / URL / exhibits; ~75–120 filings per ticker. SEC-registered securities only (US-listed equities + ADRs)
• scripts/calendars.py — market-wide event calendars (earnings / IPO / splits / economic) over a date window. Ticker-free — discovery mode for "what's happening this week"; distinct from per-ticker earnings.py
• scripts/sectors.py — Yahoo's sector / industry hierarchy (11 sectors → ~150 industries → companies / ETFs / funds). Ticker-free — keys are sector / industry strings (technology, semiconductors)
• scripts/market.py — market-wide pulse across 8 Yahoo regions (US, GB, ASIA, EUROPE, RATES, COMMODITIES, CURRENCIES, CRYPTOCURRENCIES). Ticker-free — keys are region strings
• scripts/valuation.py — historical valuation time series (Current + last 5 quarter-end snapshots × 9 metrics: market_cap, enterprise_value, trailing_pe, forward_pe, peg_ratio, price_to_sales, price_to_book, ev_to_revenue, ev_to_ebitda). Equity-only; complements info.valuation (current snapshot) with the temporal dimension. HTML scrape — see references/valuation.md fragility caveat

Shared NaN/Inf-safe converters live in scripts/helpers.py. A scripts/smoke.py test exercises every mode wrapper against representative tickers — run after editing schema or when yfinance API drift is suspected: uv run --with 'yfinance>=1.3,<2' --with 'lxml' python <SKILL_DIR>/scripts/smoke.py (the lxml extra is needed only by earnings.py's HTML scrape; harmless for the others). All scripts use argparse (run with --help for inline usage) and run under uv so yfinance installs into a managed temp env, no side-effects on the user's system Python.

This SKILL.md is the router: pick a mode below, copy the invocation, then Read the matching references/<mode>.md for the field schema, full CLI flags, output examples, presentation guidance, and mode-specific caveats. The reference files are loaded only when needed so the entry doc stays small as functionality grows.

When to use which mode

Quote-type applicability. Different modes apply to different asset types. The bucket determines what happens on inapplicable input — full per-mode empty-result semantics live in the matching references/<mode>.md ("Empty / non-applicable result" subsection where present, otherwise under "Mode-specific caveats").

Both fast_info and info return quote_type explicitly when you're unsure which bucket a ticker falls in.

Routing by question shape:

"S&P 500 P/E" or any index-fundamental question isn't answerable through info (or the other modes) — yfinance has no fundamentals for indexes; you'd need a different data source.

Routing by question shape (continued):

A single user request can need multiple modes. "What's AAPL trading at, how much is it up YTD, and what's its P/E?" → fast_info for the live price, history --period ytd --summary for the YTD return, info for the P/E.

Discovery → details two-step. When the user wants to find tickers by criteria and drill in, run screener first to produce the ticker list, then chain a per-ticker mode (info / financials / analyst / etc.) over the result. screener projects ~28 fields per quote — plenty for ranking and selection, but not the full per-ticker depth. Treat screener as the funnel, not the destination.

Catch-all rule. If the user is open-ended ("tell me about NVDA", "what's up with TSLA?") and you can't pin them to a row above, default to fast_info first — it's the cheapest and answers "where is it trading, how big is it, what's the recent range" in one call. Add info only if the user follows up about sector / fundamentals / analyst views, or if the original question already mentions those.

If the user asks "find me X" / "screen for X" / "top movers" / "best ETFs" and you don't yet have a ticker list, jump to screener (predefined or custom) — none of the other modes can answer the discovery shape.

If the user asks "what's happening this week" / "who's reporting" / "earnings calendar" / "upcoming IPOs" / "macro events" — that's market-wide event discovery, jump to calendars --type earnings|ipo|splits|economic. Per-ticker earnings.py can't answer this without a ticker list (no inverse direction); calendars is date-bounded and ticker-free.

If the user asks "what's in the X sector" / "top stocks in Y industry" / "industries under sector Z" / "best ETFs / mutual funds for sector W" — that's hierarchy navigation, jump to sectors <key>. Distinct from screener: sectors browses Yahoo's curated taxonomy (predefined top_companies / top_etfs / industries lists); screener filters with custom predicates. Use --list-sectors / --list-industries to discover canonical keys before the main fetch if a key isn't obvious.

If the user asks "is the market open" / "how is Asia trading" / "what's the macro tape" / "compare US vs Europe today" — that's live region pulse, jump to market <key>. Distinct from calendars (event timeline, date-bounded) and sectors (curated hierarchy of one US-listed taxonomy): market is the cross-region live snapshot. Use --list-markets to enumerate the 8 keys.

Invocations

One canonical invocation per mode. For the full menu of flags (intraday / extended-hours / --summary / --limit / --format csv / etc.), Read the matching references/<mode>.md "Run" section.

# fast_info — current quote (flags: --with-isin)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/fast_info.py AAPL MSFT TSLA

# history — historical OHLCV (flags: --period, --interval, --prepost, --summary, --events-only, --shares, --metadata, --tail)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/history.py AAPL

# info — profile + fundamentals + analyst (flags: --summary)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/info.py AAPL MSFT

# earnings — upcoming + recent earnings dates (flags: --summary, --estimates, --future-only). NOTE: needs extra `--with 'lxml'`.
uv run --with 'yfinance>=1.3,<2' --with 'lxml' python <SKILL_DIR>/scripts/earnings.py AAPL

# financials — income / balance / cashflow (flags: --period {annual,quarterly,ttm}, --statement {income,balance,cashflow}, --summary)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/financials.py AAPL

# news — Yahoo Finance headlines (flags: --limit, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/news.py AAPL

# holders — ownership rollup + top inst / mutualfund (flags: --summary, --limit, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/holders.py AAPL

# options — option chain, ONE expiry (flags: --moneyness N, --expiry YYYY-MM-DD, --summary, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/options.py --moneyness 5 AAPL

# insiders — Form 4 + 6-mo rollup + roster (flags: --summary, --limit, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/insiders.py AAPL

# analyst — recommendations + grade-change feed (flags: --summary, --limit, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/analyst.py AAPL

# screener — market-wide discovery, ONE envelope per call, ≤250 quotes (flags: --predefined NAME, --query JSON|@file, --quote-type, --sort-field, --count, --list-predefined, --list-fields, --format {csv,symbols}, --full)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/screener.py --predefined day_gainers --count 10

# fund_holdings — ETF / mutual-fund holdings, fund-only (flags: --summary, --limit, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/fund_holdings.py SPY

# sec_filings — SEC filings list (flags: --type 10-K,10-Q,8-K,..., --limit, --since YYYY-MM-DD, --days N, --summary, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/sec_filings.py AAPL

# calendars — market-wide event calendar, ticker-free (flags: --type {earnings,ipo,splits,economic,all} or comma-separated like `earnings,ipo`, --days, --past-days, --start, --end, --market-cap, --no-most-active, --limit, --summary, --full, --format)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/calendars.py

# sectors — Yahoo's sector/industry hierarchy, ticker-free (flags: --section overview,top_companies,... or `all`, --kind {auto,sector,industry}, --summary, --limit, --list-sectors, --list-industries [SECS], --peers KEY, --full, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/sectors.py technology

# market — market-wide pulse across 8 regions, ticker-free (flags: --section {clock,summary,all}, --summary, --limit, --list-markets, --full, --format csv)
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/market.py US

# valuation — historical valuation snapshots (flags: --summary, --format csv). Equity-only. HTML scrape — fragile.
uv run --with 'yfinance>=1.3,<2' python <SKILL_DIR>/scripts/valuation.py AAPL

<SKILL_DIR> is the absolute path of the directory containing this SKILL.md. Substitute it once when running.

Cost / latency

Rough per-ticker cost: fast_info / news / holders / insiders / sec_filings 0.3–1.5 s (sec_filings is one quoteSummary call — similar shape to news), fund_holdings ~0.7–1.5 s (single quoteSummary call but fetches 4 modules at once — see references/performance.md), history ~0.5–4 s, info / earnings / financials / options / analyst / valuation ~1–5 s (valuation is an HTML scrape of the Yahoo key-statistics page — 1 HTTP per ticker, no batching path). screener and calendars are per-call, not per-ticker — screener is 1 HTTP returning ≤ 250 quotes (1–3 s typical), so the marginal cost of a wider screen is 0. calendars is 1 HTTP per call (1–2 s) except earnings with the default most-active filter, which costs 2 HTTP (the prescreen for the most-active list runs first). sectors is 1 HTTP per key regardless of --section count — verified 2026-05: yfinance hits one Yahoo endpoint per yf.Sector(key) / yf.Industry(key) and caches all sections on the instance, so --section overview, --section all, and --summary (which auto-expands to all- applicable) cost the same network-wise per key. --section only affects projection / output cost. Cross-key fan-out is serial: N keys = N HTTP, ~0.6–2 s per key, so a 5-sector --summary is ~5 HTTP / ~3–10 s. --list-sectors / --list-industries / --peers are 0 HTTP (pure local lookup). market is 2 HTTP per region (markettime + marketSummary; yfinance interleaves both fetches in _parse_data to keep them time-aligned, so --section doesn't reduce HTTP — only projection cost). N regions = 2N HTTP, serial, ~1.5–3 s per region. --list-markets is 0 HTTP.

analyst makes 3 HTTP per ticker (recommendations, upgrades_downgrades, and fast_info for quote_type — each from a different endpoint or module group, so none share a backend request; the fast_info call is the disambiguator that lets the all-empty note path be answered inline without a follow-up call).

All modes are serial (total ≈ N × per-ticker) except history — it batches N≥2 through yf.download in one threaded HTTP call, so 10 tickers cost ~1–2 s instead of ~5–15 s. One wrinkle: history --metadata is the exception within history itself — it routes per-ticker through Ticker.history() (cheapest possible window, period=1d) because yf.download doesn't reliably populate per-ticker history_metadata state. So a 10-ticker --metadata call is N HTTP, ~3–8 s, not the batched 1-HTTP path. history --shares is the second per-ticker exception inside history: Ticker.get_shares_full is a distinct Yahoo timeseries endpoint with no yf.download equivalent, so multi-ticker shares mode is also a serial loop — 10 tickers ≈ N HTTP, ~5–15 s (get_shares_full is slightly slower per call than the metadata path). --summary and --events-only still go through the batched path for N≥2. --summary does not reduce latency; it's a post-fetch projection that only shrinks output JSON (use it to save context tokens, not time). Same applies to --shares --summary — the aggregate runs after the per-ticker fetch, so latency matches default --shares. When a question is answerable by multiple modes, pick the cheapest — don't call info for a field already in fast_info (e.g. market_cap); don't call financials for AAPL's P/E (that's in info).

A 10-ticker info / financials / earnings batch (~15–30 s) is the most common path to trip Yahoo's 429 rate-limit. Drop batch size to ~5 and pause between calls if you see retries — attempts > 1 on a result flags a retry happened. For the full per-mode latency table, retry worst-cases, the earnings --estimates cumulative-sleep math, and options 1-HTTP vs 2-HTTP rules, see references/performance.md.

Setup

See references/setup.md for uv install, the lxml dependency rationale (only earnings.py / smoke.py need it), and the version-pin reasoning.

Cross-cutting caveats

These apply to every mode. Mode-specific caveats live in the matching references/<mode>.md. Grouped into three concerns:

Data formats (interpreting the numbers)

• Numeric units are not consistent across — or within — modes. Don't guess a number's unit from the field name. Per-field unit tables and any non-obvious normalizations (e.g. fund_holdings inverting Yahoo's 1/ratio P/E, dividing percents by 100) live in each references/<mode>.md "Output schema" / "Unit landmines" section. High-level map:

  • Percent (16.43 = 16.43%): fast_info.change_pct, history --summary.change_pct, info.dividend.five_year_avg_dividend_yield, info.fund.ytd_return, options[*].change_pct, earnings_dates.surprise_pct.
  • Fraction (0.272 = 27.2%, multiply ×100 for display): most info margins / growth / returns / payout, financials --summary.*_growth_yoy, earnings --estimates growths, holders *_pct / pct_held, insiders pct_*, analyst --summary.buy_pct_*, fund_holdings expense_ratio / weights / sectors / bond_ratings, options[*].implied_vol and options --summary.atm_*_iv, info.dividend.trailing_annual_dividend_yield, info.fund.three_year_avg_return / five_year_avg_return (CAGR).
  • Likert 1–5 (1=strong_buy, 5=strong_sell, lower is more bullish): analyst --summary.consensus_score_*, info.recommendation_mean. Don't accidentally render as a percentage.

  Cross-mode landmines (the only ones the router needs to flag — rest live in each reference):

  • info.fund.total_assets is in whole units; fund_holdings.operations.total_net_assets_millions is in MILLIONS. 1e6× difference for the same metric — pick one mode and stick with it.
  • earnings --estimates ADR rows: eps_currency (trading ccy) and revenue_currency (home reporting ccy) are separate fields, not duplicates (TM EPS in USD, revenue in JPY). Read both.
  • earnings --estimates[*].index_growth is the same number globally (Yahoo-internal benchmark, not locale- or sector-aware). Don'

…(truncated)