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't read a HK-listed ticker's index_growth as Hang Seng growth.
  • Inside earnings the new --estimates growth fields are fractions but the older earnings_dates.surprise_pct is still percent — easy to swap.
  • Inside options rows: change_pct is percent but implied_vol is a fraction (5.2 daily move; 0.25 = 25% IV).
  • analyst.upgrades_downgrades enum case is inconsistent (Yahoo quirk): action lowercase (up / down / main / init / reit); price_target_action capitalized (Raises / Lowers / Maintains / Announces / Adjusts).

  Sanity heuristic: any "yield" > 1.0 is the percent variant; any 3y/5y avg-return < 0.5 is the fraction (CAGR) variant. When in doubt, prefer trailing_annual_dividend_yield (always fraction).

• Trading currency vs reporting currency. fast_info.currency and info.currency return the trading currency (the currency you'd buy the stock in — USD for AAPL, USD for ADRs like TM/BABA/PBR, HKD for 0700.HK). financials.currency returns the reporting currency (what the financial statements are denominated in — USD for AAPL but JPY for TM, CNY for BABA/0700.HK, BRL for PBR). For most direct-listed US/EU equities they match; for ADRs and some cross-border listings they don't. When mixing modes, don't assume fast_info.currency and financials.currency agree — check both. See references/financials.md for the per-ticker examples.
• DST. ET (America/New_York) is DST-aware. yfinance ISO timestamps carry the correct UTC offset, so data is fine. Only worry about DST when translating ET to a user's local timezone in prose (e.g., 09:30 ET = 21:30 Beijing summer / 22:30 winter).
• Escape $ as \$ in prose. Many markdown renderers (including Claude Code's) treat $...$ as a math-mode delimiter and will swallow the digits between two unescaped dollar signs (e.g. $237.30 may render as .30). Always write \$237.30 instead.

Identifiers (tickers and exchanges)

• Ticker suffixes for non-US markets. Hong Kong: 0700.HK. Shenzhen: 000001.SZ. Shanghai: 600519.SS. London: BARC.L. Tokyo: 7203.T. Korea: 005930.KS. Frankfurt: BMW.DE. If a user gives a bare HK/CN ticker, ask or guess the suffix.
• exchange codes are short Yahoo identifiers, not human names. NMS → Nasdaq, NYQ → NYSE, PCX → NYSE Arca, HKG → HKEX, JPX → Tokyo, LSE → London, GER → Xetra (Frankfurt). Decode before showing to the user — render "AAPL (Nasdaq)" not "AAPL (NMS)". Full code table (TSX / ASX / KRX / NSE / BSE / SIX / Borsa / Shanghai / Shenzhen / Cboe BZX) in references/exchanges.md. Don't infer from ticker suffix — both fast_info and info return exchange explicitly.

Calling conventions (errors, retries, output)

• Retry semantics. Each script wraps its Yahoo call with exponential backoff + jitter (3 attempts, base ~0.5s) on rate_limit and network errors only — not_found (delisted / wrong suffix) never retries. Per-mode latency, batching guidance, options --expiry 2-HTTP doubling, the history batched exception, and sustained-429 worst cases all live in references/performance.md.
• error_kind and attempts on results. Failed tickers carry error, error_kind ∈ {rate_limit, not_found, network, unknown}, and attempts (how many tries before giving up). Use error_kind to decide retry at the request level: rate_limit ⇒ wait & try later; not_found ⇒ ticker is bad, don't bother; network/unknown ⇒ one more try but escalate if persistent. Successful results also include attempts only when > 1 — useful for spotting tickers that took a retry to succeed.

• Output formats. Every script accepts --format json|ndjson|csv. Default json is pretty-printed; ndjson is one JSON object per line (parse-by-line); csv uses \n line endings (Unix tools). Per-mode CSV row schema, discriminator columns, and any nested-only fields dropped from CSV live in each references/<mode>.md "Output schema" section.

  Three row-shape families:

  • One row per ticker. fast_info and all --summary modes (history / info / earnings / financials / holders / options / insiders / analyst / fund_holdings / sec_filings / valuation). Strict 1:1 ticker ↔ row.
  • Row per event (with symbol repeating across rows for one ticker). Default modes of history (one row per bar), earnings (per earnings_date), news (per article), holders / insiders / analyst / fund_holdings / sec_filings / options / valuation (per record / contract / period; uses record_class / leg / holder_class / period_label discriminator columns). Tickers with no data or an error still emit a single carry row carrying symbol + note + meta fields so they aren't silently dropped.
  • Single envelope, ticker-free. screener (one screen call → one set of quotes), calendars (one envelope per --type, or a list of envelopes for --type all / multi-type), sectors / market (one envelope per positional key, with multiple sections flattened via record_class). NDJSON drops envelope and emits one record per line; CSV emits one row per record. Envelope metadata (total / predefined / title) is JSON-only. On error / no-match, NDJSON / CSV emit a single carry line / row. screener adds a symbols format (one ticker per line) for xargs piping into per-ticker modes.

  Two CSV defaults vary: info and financials have nested-only defaults and only emit CSV under --summary. One combo rejected by argparse: calendars --format csv --full (raw Yahoo keys break column stability — use --format ndjson --full instead).

• note field convention. Several modes expose a per-result note string carrying ambiguous-but-successful state, distinct from error (which only appears on failure). Cross-mode invariants:

  1. note and error never co-occur in one result dict; both appear as columns in CSVs that emit note, so neither gets dropped from tabular output.
  2. note and coverage_note are mutually exclusive in modes that expose both. Distinct action implications: note = no data / ambiguous cause, chain fast_info to disambiguate; coverage_note = real data with thin event coverage, the empty fields ARE the answer (don't re-fetch).
  3. Two modes use note for "zero matches", not ambiguity. screener / calendars set note when the screen / date window returned no rows — the empty result IS the answer; no fast_info chain needed. CSV / NDJSON emit a single carrying row.

  Modes with a coverage_note companion (real data, thin coverage):

  • earnings — IPO fall-through (calendar empty, estimates populated).
  • insiders / analyst — non-US primary listings get partial Yahoo coverage (per-event / grade-change feed is US-centric); ADRs still get full coverage.
  • sectors — --section requested that doesn't apply to the kind (e.g. --section industries on an industry).

  Modes with an analogous-but-distinct companion field:

  • sec_filings.filter_note — Yahoo returned data, but local --type / --since / --days filters reduced the displayed list to zero. Different from coverage_note (which is about Yahoo-side coverage gaps, not client-side filtering). Mutually exclusive with note.
  • sectors.section_errors — per-section transient HTTP failure (other sections in the same envelope succeeded). Independent from coverage_note (which is a kind-mismatch detected without HTTP).

  fund_holdings is special: its note carries the resolved quote_type inline, so callers don't need the fast_info chain to disambiguate. Per-mode note triggers and recommended next steps live in the matching references/<mode>.md ("Empty / non-applicable result" subsection where present, otherwise under "Mode-specific caveats").

• Cache staleness. yfinance maintains a persistent SQLite cache at ~/.cache/py-yfinance/... and can return stale prices on repeat calls within a session. For genuinely live data, the first call of a session is freshest; for repeat polling, expect lag.
• Unofficial. yfinance is unaffiliated with Yahoo and its endpoints can break at any time. If a script returns nothing for a ticker that should exist, the upstream API may have changed — don't keep retrying.