tomatocream/learn-trading
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add API references, mapping corrections, and verification script

Browse Source 
- Add yfinance.org and defeatbeta-api.org reference docs
- Fix defeatbeta_mapping.org: deprecated yfinance property names
  (quarterly_financials→quarterly_income_stmt, financials→income_stmt),
  longName vs longBusinessSummary conceptual mismatch, cashflow note typo
- Add Mapping Limitations section with live verification results (AAPL):
  DuckDB 1.4.3 incompatibility, format differences, coverage gaps
- Add docs/test_mapping.py as runnable mapping verification script
- Add offline.py, persistent_cache.py, download_data.py, warmup_cache.py
  for offline/cached defeatbeta usage
- Add aapl_yfinance.py exploration script and quant.py scaffold
- Add .envrc (uv layout) and update pyproject.toml + uv.lock

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Wong Ding Feng
2026-04-26 15:33:21 +08:00
parent b71a8e77b0
commit b5bf689e72
16 changed files with 3650 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/yfinance.org
+302
View File
@@ -0,0 +1,302 @@
#+title: yfinance API Reference
#+subtitle: Version 1.3.0
#+author: Ran Aroussi
#+date: 2026-04-25
* Overview
yfinance offers a Pythonic way to fetch financial & market data from Yahoo! Finance.
** Installation
#+begin_src sh
pip install yfinance
#+end_src
** Quick Start
#+begin_src python
import yfinance as yf
# Single ticker
dat = yf.Ticker("MSFT")
dat.info
dat.history(period='1mo')
dat.option_chain(dat.options[0]).calls
# Multiple tickers
tickers = yf.Tickers('MSFT AAPL GOOG')
tickers.tickers['MSFT'].info
yf.download(['MSFT', 'AAPL', 'GOOG'], period='1mo')
# Funds
spy = yf.Ticker('SPY').funds_data
spy.description
spy.top_holdings
#+end_src
* Top-Level Functions
| Function | Description |
|--------------------------------+-------------------------------------------|
| ~yf.download(tickers, ...)~ | Download market data for multiple tickers |
| ~yf.enable_debug_mode()~ | Enable verbose debug logging |
| ~yf.set_tz_cache_location(path)~ | Set timezone cache directory |
| ~yf.screen(query)~ | Run equity/fund/ETF screener queries |
* Config
| Setting | Description |
|---------------------------------+----------------------|
| ~yf.config.debug.logging = True~ | Enable debug logging |
| ~yf.config.user_agent = 'custom'~ | Custom user agent |
* Ticker(symbol)
** Price History
| Property/Method | Returns |
|---------------------------------------------+--------------------------------------|
| ~.history(period, start, end, interval, ...)~ | OHLCV DataFrame |
| ~.get_history_metadata()~ | Dict with currency, exchange, etc. |
| ~.get_dividends()~ | Dividend history (Series) |
| ~.dividends~ | Cached dividend history |
| ~.get_splits()~ | Stock split history (Series) |
| ~.splits~ | Cached split history |
| ~.get_actions()~ | Dividends + splits combined (Series) |
| ~.actions~ | Cached actions history |
| ~.get_capital_gains()~ | Capital gains distributions (Series) |
| ~.capital_gains~ | Cached capital gains |
| ~.get_shares_full()~ | Full shares outstanding history |
** Info & News
| Property/Method | Returns |
|-------------------------------+----------------------------------|
| ~.get_info()~ / ~.info~ | Full company info dict |
| ~.get_fast_info()~ / ~.fast_info~ | Quick-access key metrics |
| ~.get_news()~ / ~.news~ | Recent news articles (DataFrame) |
| ~.isin~ | ISIN identifier |
| ~.get_isin()~ | ISIN as string |
** Financial Statements
| Property/Method | Returns |
|------------------------+-----------------------------------------|
| ~.income_stmt~ | Annual income statement |
| ~.quarterly_income_stmt~ | Quarterly income statement |
| ~.ttm_income_stmt~ | Trailing-twelve-months income statement |
| ~.balance_sheet~ | Annual balance sheet |
| ~.cashflow~ | Annual cash flow statement |
| ~.quarterly_cashflow~ | Quarterly cash flow |
| ~.ttm_cashflow~ | TTM cash flow |
| ~.get_income_stmt()~ | Alias for income_stmt |
| ~.get_balance_sheet()~ | Alias for balance_sheet |
| ~.get_cashflow()~ | Alias for cashflow |
** Earnings & Calendar
| Property/Method | Returns |
|-----------------------+--------------------------------------|
| ~.earnings~ | Annual earnings summary |
| ~.calendar~ | Upcoming earnings/dividends dates |
| ~.get_earnings_dates()~ | Historical & upcoming earnings dates |
| ~.earnings_dates~ | Cached earnings dates |
| ~.get_sec_filings()~ | SEC filing history |
| ~.sec_filings~ | Cached SEC filings |
** Analysis & Estimates
| Property/Method | Returns |
|--------------------------------+------------------------------------|
| ~.get_recommendations()~ | Historical analyst recommendations |
| ~.recommendations~ | Cached recommendations |
| ~.get_recommendations_summary()~ | Summary of buy/hold/sell |
| ~.recommendations_summary~ | Cached summary |
| ~.get_upgrades_downgrades()~ | Analyst upgrades/downgrades |
| ~.upgrades_downgrades~ | Cached upgrades/downgrades |
| ~.get_sustainability()~ | ESG scores |
| ~.sustainability~ | Cached ESG |
| ~.get_analyst_price_targets()~ | Price target estimates |
| ~.analyst_price_targets~ | Cached price targets |
| ~.get_earnings_estimate()~ | Earnings estimates |
| ~.earnings_estimate~ | Cached earnings estimates |
| ~.get_revenue_estimate()~ | Revenue estimates |
| ~.revenue_estimate~ | Cached revenue estimates |
| ~.get_earnings_history()~ | Earnings surprise history |
| ~.earnings_history~ | Cached earnings history |
| ~.get_eps_trend()~ | EPS trend revisions |
| ~.eps_trend~ | Cached EPS trend |
| ~.get_eps_revisions()~ | EPS revision counts |
| ~.eps_revisions~ | Cached EPS revisions |
| ~.get_growth_estimates()~ | Growth rate estimates |
| ~.growth_estimates~ | Cached growth estimates |
** Holdings & Insider Activity
| Property/Method | Returns |
|---------------------------------------------------------+-----------------------------------|
| ~.get_funds_data()~ / ~.funds_data~ | Fund info (for ETFs/mutual funds) |
| ~.get_insider_purchases()~ / ~.insider_purchases~ | Insider purchase records |
| ~.get_insider_transactions()~ / ~.insider_transactions~ | Insider trade history |
| ~.get_insider_roster_holders()~ / ~.insider_roster_holders~ | Insider roster |
| ~.get_major_holders()~ / ~.major_holders~ | Ownership breakdown |
| ~.get_institutional_holders()~ / ~.institutional_holders~ | Institutional holders |
| ~.get_mutualfund_holders()~ / ~.mutualfund_holders~ | Mutual fund holders |
** Options
| Method | Returns |
|---------------------+-------------------------------------|
| ~.options~ | Tuple of available expiration dates |
| ~.option_chain(date)~ | Calls & puts DataFrame for a date |
| | |
* Tickers('SYM1 SYM2 ...')
Multiple tickers class.
| Property | Returns |
|---------------------------+----------------------------------|
| ~.tickers['SYM'].info~ | Access individual Ticker objects |
| ~.tickers['SYM'].history()~ | Get history per ticker |
* Market(market_code)
Market summary class.
| Method/Property | Returns |
|-----------------+---------------------------|
| ~.status~ | Market open/closed status |
| ~.summary()~ | Market summary data |
* Calendars
Calendar events class.
| Method | Returns |
|--------------+-------------------|
| ~.earnings()~ | Earnings calendar |
| ~.dividends()~ | Dividend calendar |
| ~.splits()~ | Splits calendar |
| ~.ipo()~ | IPO calendar |
* Search(query)
Search class for quotes and news.
| Property/Method | Returns |
|-----------------+----------------------|
| ~.quotes~ | Search result quotes |
| ~.news~ | Search result news |
| ~.lists~ | Watchlists/lists |
| ~.nav~ | Navigation results |
| ~.research~ | Research reports |
| ~.get_quotes()~ | Fetch quotes |
| ~.get_news()~ | Fetch news |
* Lookup(query)
Ticker lookup class.
| Method | Returns |
|---------------+------------------------|
| ~.get_quotes()~ | Lookup matching quotes |
* WebSocket(symbols, ...)
Live streaming data (synchronous).
| Method | Description |
|-----------------------+---------------------------|
| ~.connect()~ | Open WebSocket connection |
| ~.subscribe(symbols)~ | Subscribe to symbols |
| ~.unsubscribe(symbols)~ | Unsubscribe from symbols |
| ~.close()~ | Close connection |
* AsyncWebSocket(symbols, ...)
Live streaming data (asynchronous).
Same methods as ~WebSocket~, but async.
* Sector(sector_key)
Sector information class.
| Property/Method | Returns |
|-----------------+--------------------------|
| ~.key~ | Sector identifier |
| ~.name~ | Sector name |
| ~.symbol~ | Associated ETF symbol |
| ~.top_etfs~ | Top ETFs in sector |
| ~.top_companies~ | Top companies in sector |
| ~.industries~ | Industries within sector |
* Industry(industry_key)
Industry information class.
| Property/Method | Returns |
|-----------------+---------------------------|
| ~.key~ | Industry identifier |
| ~.name~ | Industry name |
| ~.sector_key~ | Parent sector |
| ~.top_companies~ | Top companies in industry |
* Query Builders (Screener)
| Class | Description |
|------------------+------------------------------------|
| ~EquityQuery~ | Build equity filter queries |
| ~FundQuery~ | Build mutual fund filter queries |
| ~ETFQuery~ | Build ETF filter queries |
| ~yf.screen(query)~ | Execute a query and return results |
* download() Parameters
#+begin_src python
yf.download(
tickers, # str or list of tickers
period="1mo", # 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
start=None, # datetime or str "YYYY-MM-DD"
end=None,
interval="1d", # 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo
group_by="column", # "column" or "ticker"
auto_adjust=False,
back_adjust=False,
repair=False, # Enable price repair
keepna=False,
proxy=None,
timeout=10,
threads=True,
progress=True,
)
#+end_src
* Advanced Features
** Logging
Enable debug logging:
#+begin_src python
yf.config.debug.logging = True
#+end_src
** Caching
- Persistent cache is enabled by default
- Set custom cache location: ~yf.set_tz_cache_location(path)~
** Price Repair
- Enable with ~repair=True~ in ~download()~ or ~history()~
- Fixes NaN values, bad splits, and dividend adjustments
- Dividend repair also available
** Multi-Level Column Index
- When downloading multiple tickers, columns are MultiIndex
- ~group_by="column"~ or ~group_by="ticker"~
* Legal Disclaimer
Yahoo!, Y!Finance, and Yahoo! finance are registered trademarks of Yahoo, Inc.
yfinance is /not/ affiliated, endorsed, or vetted by Yahoo, Inc. It's an open-source tool that uses Yahoo's publicly available APIs, and is intended for research and educational purposes.
You should refer to Yahoo!'s terms of use for details on your rights to use the actual data downloaded. The Yahoo! finance API is intended for personal use only.