Update documentation

Adding Sphinx Documentation

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -6,23 +6,13 @@ body:
   - type: markdown
     attributes:
       value: |
-        # IMPORTANT - Read and follow these instructions carefully. Help us help you.
-
-        ### Does issue already exist?
-
-        Use the search tool. Don't annoy everyone by duplicating existing Issues.
+        # !!! IMPORTANT !!! FOLLOW THESE INSTRUCTIONS CAREFULLY !!!
 
         ### Are you up-to-date?
 
-        Upgrade to the latest version and confirm the issue/bug is still there.
+        Upgrade to the latest version: `$ pip install yfinance --upgrade --no-cache-dir`
 
-        `$ pip install yfinance --upgrade --no-cache-dir`
-
-        Confirm by running:
-
-        `import yfinance as yf ; print(yf.__version__)`
-
-        and comparing against [PIP](https://pypi.org/project/yfinance/#history).
+        Confirm latest version by running: `import yfinance as yf ; print(yf.__version__)` and comparing against [PyPI](https://pypi.org/project/yfinance/#history).
 
         ### Does Yahoo actually have the data?
 
@@ -34,6 +24,10 @@ body:
 
         Yahoo Finance free service has rate-limiting https://github.com/ranaroussi/yfinance/discussions/1513. Once limit hit, Yahoo can delay, block, or return bad data -> not a `yfinance` bug.
         
+        ### Does issue already exist?
+
+        Use the search tool. Don't duplicate existing issues.
+        
   - type: markdown
     attributes:
       value: |
@@ -61,7 +55,7 @@ body:
     id: debug-log
     attributes:
       label: "Debug log"
-      description: "Run code with debug logging enabled and post the full output. Instructions: https://github.com/ranaroussi/yfinance/tree/main#logging"
+      description: "Run code with debug logging enabled - `yf.enable_debug_mode()` - and post the full output. Context: https://github.com/ranaroussi/yfinance/tree/main#logging"
     validations:
       required: true
 
@@ -69,7 +63,7 @@ body:
     id: bad-data-proof
     attributes:
       label: "Bad data proof"
-      description: "If you think `yfinance` returning bad data, provide your proof here."
+      description: "If `yfinance` returning bad data, show proof here. Best is screenshot of finance.yahoo.com"
     validations:
       required: false
 

.github/workflows/ci.yml

@@ -8,11 +8,11 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
         with:
           python-version: 3.x
       - run: pip install -r requirements.txt
       - run: pip install mkdocstrings==0.14.0
       - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy --force

.github/workflows/deploy_doc.yml

@@ -0,0 +1,53 @@
+name: Build and Deploy Sphinx Docs
+
+on:
+  push:
+    branches:
+      - docs_markdown
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      BUILD_DIR: "doc/_build/html"
+      DEPLOY_BRANCH: "docs_markdown"
+      DEPLOY_DIR: "docs"
+
+    steps:
+    - name: Check out the repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install Sphinx==8.0.2 pydata-sphinx-theme==0.15.4 Jinja2==3.1.4 sphinx-copybutton==0.5.2
+
+    - name: Build Sphinx documentation
+      run: |
+        sphinx-build -b html doc/source ${{ env.BUILD_DIR }} -v
+
+    - name: List generated HTML files
+      run: |
+        ls -l -R ${{ env.BUILD_DIR }}
+
+    - name: Publish to the Deploy Branch
+      run: |
+        git config --global user.name "github-actions[bot]"
+        git config --global user.email "github-actions[bot]@users.noreply.github.com"
+        
+        git checkout ${{ env.DEPLOY_BRANCH }}
+
+        mkdir -p ${{ env.DEPLOY_DIR }}
+        rm -rf ${{ env.DEPLOY_DIR }}/*
+        cp -r ${{ env.BUILD_DIR }}/* ${{ env.DEPLOY_DIR }}/
+        touch ${{ env.DEPLOY_DIR }}/.nojekyll
+        
+        git add -f ${{ env.DEPLOY_DIR }}
+        git commit -m "Update documentation"
+        git push origin ${{ env.DEPLOY_BRANCH }}

.github/workflows/pyright.yml

@@ -0,0 +1,27 @@
+name: Pyright
+
+on:
+  pull_request:
+    branches:
+      - master
+      - main
+      - dev
+
+jobs:
+  pyright:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pyright
+
+    - name: Run Pyright
+      run: pyright . --level error

.github/workflows/python-publish.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v4
       with:

.github/workflows/ruff.yml

@@ -0,0 +1,13 @@
+name: Ruff
+on:
+  pull_request:
+    branches:
+      - master
+      - main
+      - dev
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1

.gitignore

@@ -10,6 +10,7 @@ build/
 *.html
 *.css
 *.png
+test.ipynb
 
 # Environments
 .env
@@ -17,3 +18,10 @@ build/
 env/
 venv/
 ENV/
+
+# Documentation
+/doc/build/
+/doc/_build/
+/doc/source/reference/api
+!yfinance.css
+!/doc/source/development/assets/branches.png

CHANGELOG.rst

@@ -1,6 +1,142 @@
 Change Log
 ===========
 
+0.2.46
+------
+Fix regression in 0.2.45 #2094
+
+0.2.45
+------
+Features:
+- Screener #2066 @ericpien
+Fixes
+- Tickers keyerror #2068 @antoniouaa
+- IndexError in some history() debug messages #2087
+- improve dividend repair #2090
+Maintenance
+- fix unit tests contextual imports #2067
+- fix typos #2072 @algonell
+- add Pyright type checking #2059 @marco-carvalho
+
+0.2.44
+------
+Features:
+- fetch funds #2041
+- fetch sector & industry #2058
+Fixes:
+- improve dividend repair #2062
+
+0.2.43
+------
+Fix price-repair bug introduced in 0.2.42 #2036
+
+0.2.42
+------
+Features:
+- fetch SEC filings #2009
+- fetch analysis #2023 @Fidasek009
+- price repair extended to dividends & adjust #2031
+Fixes:
+- fix error on empty options chain #1995 @stevenbischoff
+- use dict.get() to safely access key in Holders #2013 @ericpien
+- fix datetime conversion with mixed timezones when ignore_tz is False #2016 @mreiche
+- handle faulty response object when getting news. #2021 @ericpien
+Maintenance:
+- prices: improve exceptions and logging #2000
+
+0.2.41
+------
+Improvements:
+- add keys to financials #1965 #1985
+- fetch Sustainability #1959
+- improve price-repair-zeroes #1990
+Fixes (prices):
+- fetching when period='max' #1967
+- metadata: Fix '1wk is invalid' & repeated calls #1970
+- Pandas warnings #1955 #1981
+- price repair syntax errors #1989
+Maintenance:
+- deprecate Ticker.earnings #1977
+
+0.2.40
+------
+Fix typo in 0.2.39 c7af213
+
+0.2.39
+------
+Fixes:
+- Fix switching session from/to requests_cache #1930
+Price repair:
+- Fix potential for price repair to discard price=0 rows #1874
+- Don't price-repair FX volume=0, is normal #1920
+- Improve 'sudden change' repair for splits & currency  #1931
+Information:
+- Fix help(yf.download) not showing the information about the function #1913 @vittoboa
+- Add more specific error throwing based on PR 1918 #1928 @elibroftw @marcofognog
+Maintenance:
+- Replace dead 'appdirs' package with 'platformdirs' #1896
+- Deprecate 'pandas_datareader', remove a deprecated argument #1897
+- Fix: datetime.datetime.utcnow() is deprecated ... #1922
+
+0.2.38
+------
+Fix holders & insiders #1908
+
+0.2.37
+------
+Small fixes:
+- Fix Pandas warnings #1838 #1844
+- Fix price repair bug, typos, refactor #1866 #1865 #1849
+- Stop disabling logging #1841
+
+0.2.36
+------
+Small fixes:
+- Update README.md for better copy-ability  #1823 
+- Name download() column levels  #1795 
+- Fix history(keepna=False) when repair=True  #1824 
+- Replace empty list with empty pd.Series  #1724 
+- Handle peewee with old sqlite  #1827 
+- Fix JSON error handling  #1830 #1833
+
+0.2.35
+------
+Internal fixes for 0.2.34
+
+0.2.34
+------
+Features:
+- Add Recommendations Trend Summary #1754
+- Add Recommendation upgrades & downgrades #1773
+- Add Insider Roster & Transactions #1772
+- Moved download() progress bar to STDERR #1776
+- PIP optional dependencies #1771
+- Set sensible min versions for optional 'nospam' reqs #1807
+Fixes
+- Fix download() DatetimeIndex on invalid symbols #1779
+- Fix invalid date entering cache DB #1796
+- Fix Ticker.calendar fetch #1790
+- Fixed adding complementary to info #1774
+- Ticker.earnings_dates: fix warning "Value 'NaN' has dtype incompatible with float64" #1810
+- Minor fixes for price repair and related tests #1768
+- Fix price repair div adjust #1798
+- Fix 'raise_errors' argument ignored in Ticker.history() #1806
+Maintenance
+- Fix regression: _get_ticker_tz() args were being swapped. Improve its unit test #1793
+- Refactor Ticker proxy #1711
+- Add Ruff linter checks #1756
+- Resolve Pandas FutureWarnings #1766
+
+0.2.33
+------
+Cookie fixes:
+- fix backup strategy #1759
+- fix Ticker(ISIN) #1760
+
+0.2.32
+------
+Add cookie & crumb to requests #1657
+
 0.2.31
 ------
 - Fix TZ cache exception blocking import #1705 #1709
@@ -240,7 +376,7 @@ Jumping to 0.2 for this big update. 0.1.* will continue to receive bug-fixes
 - Fix timezone handling
 - Fix handling of missing data
 - Clean&format earnings_dates table
-- Add ``.get_earnings_dates()`` to retreive earnings calendar
+- Add ``.get_earnings_dates()`` to retrieve earnings calendar
 - Added ``.get_earnings_history()`` to fetch earnings data
 
 0.1.70
@@ -552,7 +688,7 @@ Jumping to 0.2 for this big update. 0.1.* will continue to receive bug-fixes
 - Removed 5 second wait for every failed fetch
 - Reduced TTL for Yahoo!'s cookie
 - Keeps track of failed downloads and tries to re-download all failed downloads one more time before giving up
-- Added progress bar (can be turned off useing ``progress=False``)
+- Added progress bar (can be turned off using ``progress=False``)
 
 0.0.7
 -------

CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of Conduct
+
+## Submitting a new issue
+
+* Search through existing Issues and Discussions, in case your issue already exists and a solution is being developed.
+* Ensure you read & follow the template form.
+* Consider you may be the best person to investigate and fix.
+
+## Contributing to an existing Issue
+
+* Read the entire thread.
+* Ensure your comment is contributing something new/useful. Remember you can simply react to other comments.
+* Be concise:
+  - use the formatting options
+  - if replying to a big comment, instead of quoting it, link to it

README.md

@@ -28,7 +28,6 @@ Yahoo! finance API is intended for personal use only.**
 <a target="new" href="https://pypi.python.org/pypi/yfinance"><img border=0 src="https://img.shields.io/pypi/v/yfinance.svg?maxAge=60%" alt="PyPi version"></a>
 <a target="new" href="https://pypi.python.org/pypi/yfinance"><img border=0 src="https://img.shields.io/pypi/status/yfinance.svg?maxAge=60" alt="PyPi status"></a>
 <a target="new" href="https://pypi.python.org/pypi/yfinance"><img border=0 src="https://img.shields.io/pypi/dm/yfinance.svg?maxAge=2592000&label=installs&color=%2327B1FF" alt="PyPi downloads"></a>
-<a target="new" href="https://travis-ci.com/github/ranaroussi/yfinance"><img border=0 src="https://img.shields.io/travis/ranaroussi/yfinance/main.svg?maxAge=1" alt="Travis-CI build status"></a>
 <a target="new" href="https://www.codefactor.io/repository/github/ranaroussi/yfinance"><img border=0 src="https://www.codefactor.io/repository/github/ranaroussi/yfinance/badge" alt="CodeFactor"></a>
 <a target="new" href="https://github.com/ranaroussi/yfinance"><img border=0 src="https://img.shields.io/github/stars/ranaroussi/yfinance.svg?style=social&label=Star&maxAge=60" alt="Star this repo"></a>
 <a target="new" href="https://twitter.com/aroussi"><img border=0 src="https://img.shields.io/twitter/follow/aroussi.svg?style=social&label=Follow&maxAge=60" alt="Follow me on twitter"></a>
@@ -36,199 +35,16 @@ Yahoo! finance API is intended for personal use only.**
 
 **yfinance** offers a threaded and Pythonic way to download market data from [Yahoo!Ⓡ finance](https://finance.yahoo.com).
 
-→ Check out this [Blog post](https://aroussi.com/#post/python-yahoo-finance) for a detailed tutorial with code examples.
+## Main Features
+- `Ticker` module: Class for accessing single ticker data.
+- `Tickers` module: Class for handling multiple tickers.
+- `download` Efficiently download market data for multiple tickers.
+- `Sector` and `Industry` modules : Classes for accessing sector and industry information.
+- Market Screening: `EquityQuery` and `Screener` to build query and screen the market.
+- Caching and Smart Scraping
 
-[Changelog »](https://github.com/ranaroussi/yfinance/blob/main/CHANGELOG.rst)
-
----
-
-## Quick Start
-
-### The Ticker module
-
-The `Ticker` module, which allows you to access ticker data in a more Pythonic way:
-
-```python
-import yfinance as yf
-
-msft = yf.Ticker("MSFT")
-
-# get all stock info
-msft.info
-
-# get historical market data
-hist = msft.history(period="1mo")
-
-# show meta information about the history (requires history() to be called first)
-msft.history_metadata
-
-# show actions (dividends, splits, capital gains)
-msft.actions
-msft.dividends
-msft.splits
-msft.capital_gains  # only for mutual funds & etfs
-
-# show share count
-msft.get_shares_full(start="2022-01-01", end=None)
-
-# show financials:
-# - income statement
-msft.income_stmt
-msft.quarterly_income_stmt
-# - balance sheet
-msft.balance_sheet
-msft.quarterly_balance_sheet
-# - cash flow statement
-msft.cashflow
-msft.quarterly_cashflow
-# see `Ticker.get_income_stmt()` for more options
-
-# show holders
-msft.major_holders
-msft.institutional_holders
-msft.mutualfund_holders
-
-# Show future and historic earnings dates, returns at most next 4 quarters and last 8 quarters by default. 
-# Note: If more are needed use msft.get_earnings_dates(limit=XX) with increased limit argument.
-msft.earnings_dates
-
-# show ISIN code - *experimental*
-# ISIN = International Securities Identification Number
-msft.isin
-
-# show options expirations
-msft.options
-
-# show news
-msft.news
-
-# get option chain for specific expiration
-opt = msft.option_chain('YYYY-MM-DD')
-# data available via: opt.calls, opt.puts
-```
-
-If you want to use a proxy server for downloading data, use:
-
-```python
-import yfinance as yf
-
-msft = yf.Ticker("MSFT")
-
-msft.history(..., proxy="PROXY_SERVER")
-msft.get_actions(proxy="PROXY_SERVER")
-msft.get_dividends(proxy="PROXY_SERVER")
-msft.get_splits(proxy="PROXY_SERVER")
-msft.get_capital_gains(proxy="PROXY_SERVER")
-msft.get_balance_sheet(proxy="PROXY_SERVER")
-msft.get_cashflow(proxy="PROXY_SERVER")
-msft.option_chain(..., proxy="PROXY_SERVER")
-...
-```
-
-### Multiple tickers
-
-To initialize multiple `Ticker` objects, use
-
-```python
-import yfinance as yf
-
-tickers = yf.Tickers('msft aapl goog')
-
-# access each ticker using (example)
-tickers.tickers['MSFT'].info
-tickers.tickers['AAPL'].history(period="1mo")
-tickers.tickers['GOOG'].actions
-```
-
-To download price history into one table:
-
-```python
-import yfinance as yf
-data = yf.download("SPY AAPL", period="1mo")
-```
-
-#### `yf.download()` and `Ticker.history()` have many options for configuring fetching and processing. [Review the Wiki](https://github.com/ranaroussi/yfinance/wiki) for more options and detail.
-
-### Logging
-
-`yfinance` now uses the `logging` module to handle messages, default behaviour is only print errors. If debugging, use `yf.enable_debug_mode()` to switch logging to debug with custom formatting.
-
-### Smarter scraping
-
-To use a custom `requests` session (for example to cache calls to the
-API or customize the `User-agent` header), pass a `session=` argument to
-the Ticker constructor.
-
-```python
-import requests_cache
-session = requests_cache.CachedSession('yfinance.cache')
-session.headers['User-agent'] = 'my-program/1.0'
-ticker = yf.Ticker('msft', session=session)
-# The scraped response will be stored in the cache
-ticker.actions
-```
-
-Combine a `requests_cache` with rate-limiting to avoid triggering Yahoo's rate-limiter/blocker that can corrupt data.
-```python
-from requests import Session
-from requests_cache import CacheMixin, SQLiteCache
-from requests_ratelimiter import LimiterMixin, MemoryQueueBucket
-from pyrate_limiter import Duration, RequestRate, Limiter
-class CachedLimiterSession(CacheMixin, LimiterMixin, Session):
-    pass
-
-session = CachedLimiterSession(
-    limiter=Limiter(RequestRate(2, Duration.SECOND*5)),  # max 2 requests per 5 seconds
-    bucket_class=MemoryQueueBucket,
-    backend=SQLiteCache("yfinance.cache"),
-)
-```
-
-### Managing Multi-Level Columns
-
-The following answer on Stack Overflow is for [How to deal with
-multi-level column names downloaded with
-yfinance?](https://stackoverflow.com/questions/63107801)
-
--   `yfinance` returns a `pandas.DataFrame` with multi-level column
-    names, with a level for the ticker and a level for the stock price
-    data
-    -   The answer discusses:
-        -   How to correctly read the the multi-level columns after
-            saving the dataframe to a csv with `pandas.DataFrame.to_csv`
-        -   How to download single or multiple tickers into a single
-            dataframe with single level column names and a ticker column
-
-### `pandas_datareader` override
-
-If your code uses `pandas_datareader` and you want to download data
-faster, you can "hijack" `pandas_datareader.data.get_data_yahoo()`
-method to use **yfinance** while making sure the returned data is in the
-same format as **pandas\_datareader**'s `get_data_yahoo()`.
-
-```python
-from pandas_datareader import data as pdr
-
-import yfinance as yf
-yf.pdr_override() # <== that's all it takes :-)
-
-# download dataframe
-data = pdr.get_data_yahoo("SPY", start="2017-01-01", end="2017-04-30")
-```
-
-### Timezone cache store
-
-When fetching price data, all dates are localized to stock exchange timezone. 
-But timezone retrieval is relatively slow, so yfinance attemps to cache them 
-in your users cache folder. 
-You can direct cache to use a different location with `set_tz_cache_location()`:
-```python
-import yfinance as yf
-yf.set_tz_cache_location("custom/cache/location")
-...
-```
-
----
+## Documentation
+The official documentation is available on [ranaroussi.github.io/yfinance](https://ranaroussi.github.io/yfinance/index.html)
 
 ## Installation
 
@@ -238,35 +54,20 @@ Install `yfinance` using `pip`:
 $ pip install yfinance --upgrade --no-cache-dir
 ```
 
-Test new features by installing betas, provide feedback in [corresponding Discussion](https://github.com/ranaroussi/yfinance/discussions):
+[With Conda](https://anaconda.org/ranaroussi/yfinance).
+
+To install with optional dependencies, replace `optional` with: `nospam` for [caching-requests](#smarter-scraping), `repair` for [price repair](https://github.com/ranaroussi/yfinance/wiki/Price-repair), or `nospam,repair` for both:
+
 ``` {.sourceCode .bash}
-$ pip install yfinance --upgrade --no-cache-dir --pre
+$ pip install "yfinance[optional]"
 ```
 
-To install `yfinance` using `conda`, see
-[this](https://anaconda.org/ranaroussi/yfinance).
+[Required dependencies](./requirements.txt) , [all dependencies](./setup.py#L62).
 
-### Requirements
+The list of changes can be found in the [changelog](https://github.com/ranaroussi/yfinance/blob/main/CHANGELOG.rst)
 
--   [Python](https://www.python.org) \>= 2.7, 3.4+
--   [Pandas](https://github.com/pydata/pandas) \>= 1.3.0
--   [Numpy](http://www.numpy.org) \>= 1.16.5
--   [requests](http://docs.python-requests.org/en/master) \>= 2.31
--   [lxml](https://pypi.org/project/lxml) \>= 4.9.1
--   [appdirs](https://pypi.org/project/appdirs) \>= 1.4.4
--   [pytz](https://pypi.org/project/pytz) \>=2022.5
--   [frozendict](https://pypi.org/project/frozendict) \>= 2.3.4
--   [beautifulsoup4](https://pypi.org/project/beautifulsoup4) \>= 4.11.1
--   [html5lib](https://pypi.org/project/html5lib) \>= 1.1
--   [peewee](https://pypi.org/project/peewee)  \>= 3.16.2
-
-#### Optional (if you want to use `pandas_datareader`)
-
--   [pandas\_datareader](https://github.com/pydata/pandas-datareader)
-    \>= 0.4.0
 
 ## Developers: want to contribute?
-
 `yfinance` relies on community to investigate bugs and contribute code. Developer guide: https://github.com/ranaroussi/yfinance/discussions/1084
 
 ---
@@ -283,12 +84,12 @@ intended for research and educational purposes. You should refer to Yahoo!'s ter
 ([here](https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm),
 [here](https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html), and
 [here](https://policies.yahoo.com/us/en/yahoo/terms/index.htm)) for
-detailes on your rights to use the actual data downloaded.
+details on your rights to use the actual data downloaded.
 
 ---
 
 ### P.S.
 
-Please drop me an note with any feedback you have.
+Please drop me a note with any feedback you have.
 
 **Ran Aroussi**

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

doc/source/_static/yfinance.css

@@ -0,0 +1,4 @@
+/* Hide the "Section Navigation" title */
+p.bd-links__title {
+    display: none;
+}

doc/source/_templates/autosummary/class.rst

@@ -0,0 +1,30 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: attributes
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: methods
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/source/conf.py

@@ -0,0 +1,45 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..')) 
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'yfinance - market data downloader'
+copyright = '2017-2019 Ran Aroussi'
+author = 'Ran Aroussi'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
+              "sphinx.ext.githubpages",
+              "sphinx.ext.autosectionlabel",
+              "sphinx.ext.autosummary",
+              "sphinx_copybutton"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+autoclass_content = 'both'
+autosummary_generate = True
+autodoc_default_options = {
+    'exclude-members': '__init__'
+}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_title = 'yfinance'
+html_theme = 'pydata_sphinx_theme'
+html_theme_options = {
+    "github_url": "https://github.com/ranaroussi/yfinance",
+    "navbar_align": "left"
+}
+html_static_path = ['_static']
+html_css_files = ['yfinance.css']

doc/source/development/contributing.rst

@@ -0,0 +1,109 @@
+********************************
+Contributiong to yfinance
+********************************
+
+`yfinance` relies on the community to investigate bugs and contribute code. Here’s how you can help:
+
+Contributing
+------------
+
+1. Fork the repository on GitHub.
+2. Clone your forked repository:
+
+   .. code-block:: bash
+
+      git clone https://github.com/your-username/yfinance.git
+
+3. Create a new branch for your feature or bug fix:
+
+   .. code-block:: bash
+
+      git checkout -b feature-branch-name
+
+4. Make your changes, commit them, and push your branch to GitHub. To keep the commit history and `network graph <https://github.com/ranaroussi/yfinance/network>`_ compact:
+
+   Use short summaries for commits
+
+   .. code-block:: shell
+
+      git commit -m "short summary" -m "full commit message"
+
+   **Squash** tiny or negligible commits with meaningful ones.
+
+   .. code-block:: shell
+
+      git rebase -i HEAD~2
+      git push --force-with-lease origin <branch-name>
+
+5. Open a pull request on the `yfinance` GitHub page.
+
+For more information, see the `Developer Guide <https://github.com/ranaroussi/yfinance/discussions/1084>`_.
+
+Branches
+---------
+
+To support rapid development without breaking stable versions, this project uses a two-layer branch model:
+
+.. image:: assets/branches.png
+   :alt: Branching Model
+
+`Inspiration <https://miro.medium.com/max/700/1*2YagIpX6LuauC3ASpwHekg.png>`_
+
+- **dev**: New features and some bug fixes are merged here. This branch allows collective testing, conflict resolution, and further stabilization before merging into the stable branch.
+- **main**: Stable branch where PIP releases are created.
+
+By default, branches target **main**, but most contributions should target **dev**. 
+
+**Exceptions**:
+Direct merges to **main** are allowed if:
+
+- `yfinance` is massively broken
+- Part of `yfinance` is broken, and the fix is simple and isolated
+
+Unit Tests
+----------
+
+Tests are written using Python’s `unittest` module. Here are some ways to run tests:
+
+- **Run all price tests**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices
+
+- **Run a subset of price tests**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices.TestPriceRepair
+
+- **Run a specific test**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices.TestPriceRepair.test_ticker_missing
+
+- **Run all tests**:
+
+  .. code-block:: shell
+
+     python -m unittest discover -s tests
+
+Rebasing
+--------------
+
+If asked to move your branch from **main** to **dev**:
+
+1. Ensure all relevant branches are pulled.
+2. Run:
+
+   .. code-block:: shell
+
+      git checkout <your-branch>
+      git rebase --onto dev main <branch-name>
+      git push --force-with-lease origin <branch-name>
+
+Running the GitHub Version of yfinance
+--------------------------------------
+
+To download and run a GitHub version of `yfinance`, refer to `GitHub discussion <https://github.com/ranaroussi/yfinance/discussions/1080>`_

doc/source/development/documentation.rst

@@ -0,0 +1,46 @@
+*************************************
+Contribution to the documentation
+*************************************
+
+.. contents:: Documentation:
+   :local:
+
+About documentation
+------------------------
+* yfinance documentation is written in reStructuredText (rst) and built using Sphinx.
+* The documentation file is in `doc/source/..`.
+* Most of the notes under API References read from class and methods docstrings. These documentations, found in `doc/source/reference/api` is autogenerated by Sphinx and not included in git.
+
+Building documentation locally
+-------------------------------
+To build the documentation locally, follow these steps:
+
+1. **Install Required Dependencies**:
+
+   * Make sure `Sphinx` and any other dependencies are installed. If a `requirements.txt` file is available, you can install dependencies by running:
+   
+   .. code-block:: console
+
+      pip install -r requirements.txt
+   
+
+2. **Build with Sphinx**:
+    
+   * After dependencies are installed, use the sphinx-build command to generate HTML documentation. 
+   * Go to `doc/` directory Run:
+
+   .. code-block:: console
+
+      make clean && make html 
+
+3. **View Documentation Locally**:
+
+   * Open `doc/build/html/index.html` in the browser to view the generated documentation.
+
+Building documentation on main 
+-------------------------------
+The documentation updates are built on merge to `main` branch. This is done via GitHub Actions workflow based on `/yfinance/.github/workflows/deploy_doc.yml`.
+
+1. Reivew the changes locally and push to `dev`.
+
+2. When `dev` gets merged to `main`, GitHub Actions workflow is automated to build documentation.

doc/source/development/index.rst

@@ -0,0 +1,9 @@
+Development
+===============================
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   documentation
+   reporting_bug

doc/source/development/reporting_bug.rst

@@ -0,0 +1,5 @@
+********************************
+Reporting a Bug
+********************************
+
+Open a new issue on our `GitHub <https://github.com/ranaroussi/yfinance/issues>`_.

doc/source/getting_started/index.rst

@@ -0,0 +1,9 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   quick_start
+   legal

doc/source/getting_started/installation.rst

@@ -0,0 +1,17 @@
+********************
+Installation Guide
+********************
+
+Install `yfinance` using `pip`:
+
+.. code-block:: bash
+
+   $ pip install yfinance --upgrade --no-cache-dir
+
+To install with optional dependencies, replace `optional` with: `nospam` for `caching-requests <https://github.com/ranaroussi/yfinance?tab=readme-ov-file#smarter-scraping>`_, `repair` for `price repair <https://github.com/ranaroussi/yfinance/wiki/Price-repair>`_, or `nospam`, `repair` for both:
+
+.. code-block:: bash
+
+   $ pip install "yfinance[optional]"
+
+For required dependencies, check out the `requirements file <./requirements.txt>`_, and for all dependencies, see the `setup.py file <./setup.py#L62>`_.

doc/source/getting_started/legal.rst

@@ -0,0 +1,12 @@
+********************
+Legal Information
+********************
+
+yfinance is distributed under the Apache Software License. See the `LICENSE.txt <../../../../LICENSE.txt>`_ file for details.
+
+Again, 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.
+
+Refer to Yahoo!'s terms of use: 
+
+- `API Terms <https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm>`_
+- `Yahoo Terms <https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html>`_

doc/source/getting_started/quick_start.rst

@@ -0,0 +1,30 @@
+********************
+Quick Start
+********************
+
+The Ticker module allows you to access ticker data in a more Pythonic way:
+
+.. code-block:: python
+
+   import yfinance as yf
+
+   msft = yf.Ticker("MSFT")
+
+   # get all stock info
+   msft.info
+
+   # get historical market data
+   hist = msft.history(period="1mo")
+
+   # show actions (dividends, splits, capital gains)
+   msft.actions
+   msft.dividends
+   msft.splits
+
+To work with multiple tickers, use:
+
+.. code-block:: python
+
+   tickers = yf.Tickers('msft aapl goog')
+   tickers.tickers['MSFT'].info
+   tickers.tickers['AAPL'].history(period="1mo")

doc/source/index.rst

@@ -0,0 +1,30 @@
+yfinance documentation
+==============================================
+
+Download Market Data from Yahoo! Finance's API
+------------------------------------------------
+
+.. admonition:: IMPORTANT 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**
+   (`here <https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm>`__),
+   (`here <https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html>`__),
+   and (`here <https://policies.yahoo.com/us/en/yahoo/terms/index.htm>`__)
+   for details on your rights to use the actual data downloaded.
+   Remember - the Yahoo! finance API is intended for personal use only.
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+   :titlesonly:
+
+   getting_started/index
+   user_guide/index
+   reference/index
+   development/index

doc/source/reference/examples/download.py

@@ -0,0 +1,2 @@
+import yfinance as yf
+data = yf.download("SPY AAPL", period="1mo")

doc/source/reference/examples/funds_data.py

@@ -0,0 +1,18 @@
+import yfinance as yf
+spy = yf.Ticker('SPY')
+data = spy.funds_data
+
+# show fund description
+data.description
+
+# show operational information
+data.fund_overview
+data.fund_operations
+
+# show holdings related information
+data.asset_classes
+data.top_holdings
+data.equity_holdings
+data.bond_holdings
+data.bond_ratings
+data.sector_weightings

doc/source/reference/examples/proxy.py

@@ -0,0 +1,13 @@
+import yfinance as yf
+
+msft = yf.Ticker("MSFT")
+
+msft.history(..., proxy="PROXY_SERVER")
+msft.get_actions(proxy="PROXY_SERVER")
+msft.get_dividends(proxy="PROXY_SERVER")
+msft.get_splits(proxy="PROXY_SERVER")
+msft.get_capital_gains(proxy="PROXY_SERVER")
+msft.get_balance_sheet(proxy="PROXY_SERVER")
+msft.get_cashflow(proxy="PROXY_SERVER")
+msft.option_chain(..., proxy="PROXY_SERVER")
+...

doc/source/reference/examples/sector_industry.py

@@ -0,0 +1,25 @@
+import yfinance as yf
+
+tech = yf.Sector('technology')
+software = yf.Industry('software-infrastructure')
+
+# Common information
+tech.key
+tech.name
+tech.symbol
+tech.ticker
+tech.overview
+tech.top_companies
+tech.research_reports
+
+# Sector information
+tech.top_etfs
+tech.top_mutual_funds
+tech.industries
+
+# Industry information
+software.sector_key
+software.sector_name
+software.top_performing_companies
+software.top_growth_companies
+

doc/source/reference/examples/sector_industry_ticker.py

@@ -0,0 +1,11 @@
+import yfinance as yf
+# Ticker to Sector and Industry
+msft = yf.Ticker('MSFT')
+tech = yf.Sector(msft.info.get('sectorKey'))
+software = yf.Industry(msft.info.get('industryKey'))
+
+# Sector and Industry to Ticker
+tech_ticker = tech.ticker
+tech_ticker.info
+software_ticker = software.ticker
+software_ticker.history()

doc/source/reference/examples/ticker.py

@@ -0,0 +1,77 @@
+import yfinance as yf
+
+msft = yf.Ticker("MSFT")
+
+# get all stock info
+msft.info
+
+# get historical market data
+hist = msft.history(period="1mo")
+
+# show meta information about the history (requires history() to be called first)
+msft.history_metadata
+
+# show actions (dividends, splits, capital gains)
+msft.actions
+msft.dividends
+msft.splits
+msft.capital_gains  # only for mutual funds & etfs
+
+# show share count
+msft.get_shares_full(start="2022-01-01", end=None)
+
+# show financials:
+msft.calendar
+msft.sec_filings
+# - income statement
+msft.income_stmt
+msft.quarterly_income_stmt
+# - balance sheet
+msft.balance_sheet
+msft.quarterly_balance_sheet
+# - cash flow statement
+msft.cashflow
+msft.quarterly_cashflow
+# see `Ticker.get_income_stmt()` for more options
+
+# show holders
+msft.major_holders
+msft.institutional_holders
+msft.mutualfund_holders
+msft.insider_transactions
+msft.insider_purchases
+msft.insider_roster_holders
+
+msft.sustainability
+
+# show recommendations
+msft.recommendations
+msft.recommendations_summary
+msft.upgrades_downgrades
+
+# show analysts data
+msft.analyst_price_targets
+msft.earnings_estimate
+msft.revenue_estimate
+msft.earnings_history
+msft.eps_trend
+msft.eps_revisions
+msft.growth_estimates
+
+# Show future and historic earnings dates, returns at most next 4 quarters and last 8 quarters by default.
+# Note: If more are needed use msft.get_earnings_dates(limit=XX) with increased limit argument.
+msft.earnings_dates
+
+# show ISIN code - *experimental*
+# ISIN = International Securities Identification Number
+msft.isin
+
+# show options expirations
+msft.options
+
+# show news
+msft.news
+
+# get option chain for specific expiration
+opt = msft.option_chain('YYYY-MM-DD')
+# data available via: opt.calls, opt.puts

doc/source/reference/examples/tickers.py

@@ -0,0 +1,8 @@
+import yfinance as yf
+
+tickers = yf.Tickers('msft aapl goog')
+
+# access each ticker using (example)
+tickers.tickers['MSFT'].info
+tickers.tickers['AAPL'].history(period="1mo")
+tickers.tickers['GOOG'].actions

doc/source/reference/index.rst

@@ -0,0 +1,33 @@
+=======================
+API Reference
+=======================
+
+Overview
+--------
+
+The `yfinance` package provides easy access to Yahoo! Finance's API to retrieve market data. It includes classes and functions for downloading historical market data, accessing ticker information, managing cache, and more.
+
+
+Public API
+==========
+
+The following are the publicly available classes, and functions exposed by the `yfinance` package:
+
+- :attr:`Ticker <yfinance.Ticker>`: Class for accessing single ticker data.
+- :attr:`Tickers <yfinance.Tickers>`: Class for handling multiple tickers.
+- :attr:`Sector <yfinance.Sector>`: Domain class for accessing sector information.
+- :attr:`Industry <yfinance.Industry>`: Domain class for accessing industry information.
+- :attr:`download <yfinance.download>`: Function to download market data for multiple tickers.
+- :attr:`EquityQuery <yfinance.EquityQuery>`: Class to build equity market query.
+- :attr:`Screener <yfinance.Screener>`: Class to screen the market using defined query.
+- :attr:`enable_debug_mode <yfinance.enable_debug_mode>`: Function to enable debug mode for logging.
+- :attr:`set_tz_cache_location <yfinance.set_tz_cache_location>`: Function to set the timezone cache location.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   
+   yfinance.ticker_tickers
+   yfinance.sector_industry
+   yfinance.functions

doc/source/reference/yfinance.functions.rst

@@ -0,0 +1,51 @@
+=========================
+Functions and Utilities
+=========================
+
+.. currentmodule:: yfinance
+   
+Download Market Data
+~~~~~~~~~~~~~~~~~~~~~
+The `download` function allows you to retrieve market data for multiple tickers at once.
+
+.. autosummary:: 
+   :toctree: api/
+
+   download
+
+Query Market Data
+~~~~~~~~~~~~~~~~~~~~~
+The `Sector` and `Industry` modules allow you to access the sector and industry information.
+
+.. autosummary:: 
+   :toctree: api/
+
+   EquityQuery
+   Screener
+
+.. seealso::
+   :attr:`EquityQuery.valid_operand_fields <yfinance.EquityQuery.valid_operand_fields>`
+      supported operand values for query
+   :attr:`EquityQuery.valid_eq_operand_map <yfinance.EquityQuery.valid_eq_operand_map>`
+      supported `EQ query operand parameters`
+   :attr:`Screener.predefined_bodies <yfinance.Screener.predefined_bodies>`
+      supported predefined screens
+   
+
+Enable Debug Mode
+~~~~~~~~~~~~~~~~~
+Enables logging of debug information for the `yfinance` package.
+
+.. autosummary:: 
+   :toctree: api/
+
+   enable_debug_mode
+
+Set Timezone Cache Location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the cache location for timezone data.
+
+.. autosummary:: 
+   :toctree: api/
+
+   set_tz_cache_location

doc/source/reference/yfinance.sector_industry.rst

@@ -0,0 +1,32 @@
+=======================
+Sector and Industry
+=======================
+
+.. currentmodule:: yfinance
+
+Class
+------------
+The `Sector` and `Industry` modules provide access to the Sector and Industry information.
+
+.. autosummary::
+   :toctree: api/
+   :recursive:
+
+   Sector
+   Industry
+
+.. seealso::
+   :attr:`Sector.industries <yfinance.Sector.industries>`
+      Map of sector and industry
+
+Sample Code
+------------
+To initialize, use the relevant sector or industry key as below.
+
+.. literalinclude:: examples/sector_industry.py
+   :language: python
+
+The modules can be chained with Ticker as below.
+
+.. literalinclude:: examples/sector_industry_ticker.py
+   :language: python

doc/source/reference/yfinance.ticker_tickers.rst

@@ -0,0 +1,46 @@
+=====================
+Ticker and Tickers
+=====================
+
+.. currentmodule:: yfinance
+
+
+Class
+------------
+The `Ticker` module, allows you to access ticker data in a Pythonic way.
+
+.. autosummary::
+   :toctree: api/
+
+   Ticker
+   Tickers
+
+
+Sample Code
+------------
+The `Ticker` module, allows you to access ticker data in a Pythonic way.
+
+.. literalinclude:: examples/ticker.py
+   :language: python
+
+To initialize multiple `Ticker` objects, use
+
+.. literalinclude:: examples/tickers.py
+   :language: python
+
+For tickers that are ETFs/Mutual Funds, `Ticker.funds_data` provides access to fund related data. 
+
+Funds' Top Holdings and other data with category average is returned as `pd.DataFrame`.
+
+.. literalinclude:: examples/funds_data.py
+   :language: python
+
+If you want to use a proxy server for downloading data, use:
+
+.. literalinclude:: examples/proxy.py
+   :language: python
+
+To initialize multiple `Ticker` objects, use `Tickers` module
+
+.. literalinclude:: examples/tickers.py
+   :language: python

doc/source/user_guide/index.rst

@@ -0,0 +1,11 @@
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   logging
+   proxy
+   smart_scraping
+   persistent_cache
+   multi_level_columns

doc/source/user_guide/logging.rst

@@ -0,0 +1,11 @@
+Logging in yfinance
+===================
+
+`yfinance` uses the `logging` module to handle messages. By default, only errors are logged.
+
+If debugging, you can switch to debug mode with custom formatting using:
+
+.. code-block:: python
+
+   import yfinance as yf
+   yf.enable_debug_mode()

doc/source/user_guide/multi_level_columns.rst

@@ -0,0 +1,13 @@
+******************************
+Managing Multi-Level Columns
+******************************
+
+The following answer on Stack Overflow is for `How to deal with
+multi-level column names downloaded with yfinance? <https://stackoverflow.com/questions/63107801>`_
+
+- `yfinance` returns a `pandas.DataFrame` with multi-level column names, with a level for the ticker and a level for the stock price data
+
+The answer discusses:
+
+- How to correctly read the the multi-level columns after saving the dataframe to a csv with `pandas.DataFrame.to_csv`
+- How to download single or multiple tickers into a singledataframe with single level column names and a ticker column

doc/source/user_guide/persistent_cache.rst

@@ -0,0 +1,16 @@
+******************************
+Persistent Cache Store
+******************************
+
+To reduce Yahoo, yfinance store some data locally: timezones to localize dates, and cookie. Cache location is:
+
+- Windows = C:/Users/\<USER\>/AppData/Local/py-yfinance
+- Linux = /home/\<USER\>/.cache/py-yfinance
+- MacOS = /Users/\<USER\>/Library/Caches/py-yfinance
+
+You can direct cache to use a different location with `set_tz_cache_location()`:
+
+.. code-block:: python
+
+    import yfinance as yf
+    yf.set_tz_cache_location("custom/cache/location")

doc/source/user_guide/proxy.rst

@@ -0,0 +1,11 @@
+*********************
+Using a Proxy Server
+*********************
+
+You can download data via a proxy:
+
+.. code-block:: python
+
+   msft = yf.Ticker("MSFT")
+   msft.history(..., proxy="PROXY_SERVER")
+

doc/source/user_guide/smart_scraping.rst

@@ -0,0 +1,41 @@
+******************************
+Smarter Scraping with Caching
+******************************
+
+
+Install the `nospam` package to cache API calls and reduce spam to Yahoo:
+
+.. code-block:: bash
+
+   pip install yfinance[nospam]
+
+To use a custom `requests` session, pass a `session=` argument to
+the Ticker constructor. This allows for caching calls to the API as well as a custom way to modify requests via  the `User-agent` header.
+
+.. code-block:: python
+
+   import requests_cache
+   session = requests_cache.CachedSession('yfinance.cache')
+   session.headers['User-agent'] = 'my-program/1.0'
+   ticker = yf.Ticker('MSFT', session=session)
+   
+   # The scraped response will be stored in the cache
+   ticker.actions
+
+
+Combine `requests_cache` with rate-limiting to avoid triggering Yahoo's rate-limiter/blocker that can corrupt data.
+
+.. code-block:: python
+
+   from requests import Session
+   from requests_cache import CacheMixin, SQLiteCache
+   from requests_ratelimiter import LimiterMixin, MemoryQueueBucket
+   from pyrate_limiter import Duration, RequestRate, Limiter
+   class CachedLimiterSession(CacheMixin, LimiterMixin, Session):
+      pass
+
+   session = CachedLimiterSession(
+      limiter=Limiter(RequestRate(2, Duration.SECOND*5)),  # max 2 requests per 5 seconds
+      bucket_class=MemoryQueueBucket,
+      backend=SQLiteCache("yfinance.cache"),
+   )

docs/_sources/development/contributing.rst.txt

@@ -0,0 +1,109 @@
+********************************
+Contributiong to yfinance
+********************************
+
+`yfinance` relies on the community to investigate bugs and contribute code. Here’s how you can help:
+
+Contributing
+------------
+
+1. Fork the repository on GitHub.
+2. Clone your forked repository:
+
+   .. code-block:: bash
+
+      git clone https://github.com/your-username/yfinance.git
+
+3. Create a new branch for your feature or bug fix:
+
+   .. code-block:: bash
+
+      git checkout -b feature-branch-name
+
+4. Make your changes, commit them, and push your branch to GitHub. To keep the commit history and `network graph <https://github.com/ranaroussi/yfinance/network>`_ compact:
+
+   Use short summaries for commits
+
+   .. code-block:: shell
+
+      git commit -m "short summary" -m "full commit message"
+
+   **Squash** tiny or negligible commits with meaningful ones.
+
+   .. code-block:: shell
+
+      git rebase -i HEAD~2
+      git push --force-with-lease origin <branch-name>
+
+5. Open a pull request on the `yfinance` GitHub page.
+
+For more information, see the `Developer Guide <https://github.com/ranaroussi/yfinance/discussions/1084>`_.
+
+Branches
+---------
+
+To support rapid development without breaking stable versions, this project uses a two-layer branch model:
+
+.. image:: assets/branches.png
+   :alt: Branching Model
+
+`Inspiration <https://miro.medium.com/max/700/1*2YagIpX6LuauC3ASpwHekg.png>`_
+
+- **dev**: New features and some bug fixes are merged here. This branch allows collective testing, conflict resolution, and further stabilization before merging into the stable branch.
+- **main**: Stable branch where PIP releases are created.
+
+By default, branches target **main**, but most contributions should target **dev**. 
+
+**Exceptions**:
+Direct merges to **main** are allowed if:
+
+- `yfinance` is massively broken
+- Part of `yfinance` is broken, and the fix is simple and isolated
+
+Unit Tests
+----------
+
+Tests are written using Python’s `unittest` module. Here are some ways to run tests:
+
+- **Run all price tests**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices
+
+- **Run a subset of price tests**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices.TestPriceRepair
+
+- **Run a specific test**:
+
+  .. code-block:: shell
+
+     python -m unittest tests.test_prices.TestPriceRepair.test_ticker_missing
+
+- **Run all tests**:
+
+  .. code-block:: shell
+
+     python -m unittest discover -s tests
+
+Rebasing
+--------------
+
+If asked to move your branch from **main** to **dev**:
+
+1. Ensure all relevant branches are pulled.
+2. Run:
+
+   .. code-block:: shell
+
+      git checkout <your-branch>
+      git rebase --onto dev main <branch-name>
+      git push --force-with-lease origin <branch-name>
+
+Running the GitHub Version of yfinance
+--------------------------------------
+
+To download and run a GitHub version of `yfinance`, refer to `GitHub discussion <https://github.com/ranaroussi/yfinance/discussions/1080>`_

docs/_sources/development/documentation.rst.txt

@@ -0,0 +1,46 @@
+*************************************
+Contribution to the documentation
+*************************************
+
+.. contents:: Documentation:
+   :local:
+
+About documentation
+------------------------
+* yfinance documentation is written in reStructuredText (rst) and built using Sphinx.
+* The documentation file is in `doc/source/..`.
+* Most of the notes under API References read from class and methods docstrings. These documentations, found in `doc/source/reference/api` is autogenerated by Sphinx and not included in git.
+
+Building documentation locally
+-------------------------------
+To build the documentation locally, follow these steps:
+
+1. **Install Required Dependencies**:
+
+   * Make sure `Sphinx` and any other dependencies are installed. If a `requirements.txt` file is available, you can install dependencies by running:
+   
+   .. code-block:: console
+
+      pip install -r requirements.txt
+   
+
+2. **Build with Sphinx**:
+    
+   * After dependencies are installed, use the sphinx-build command to generate HTML documentation. 
+   * Go to `doc/` directory Run:
+
+   .. code-block:: console
+
+      make clean && make html 
+
+3. **View Documentation Locally**:
+
+   * Open `doc/build/html/index.html` in the browser to view the generated documentation.
+
+Building documentation on main 
+-------------------------------
+The documentation updates are built on merge to `main` branch. This is done via GitHub Actions workflow based on `/yfinance/.github/workflows/deploy_doc.yml`.
+
+1. Reivew the changes locally and push to `dev`.
+
+2. When `dev` gets merged to `main`, GitHub Actions workflow is automated to build documentation.

docs/_sources/development/index.rst.txt

@@ -0,0 +1,9 @@
+Development
+===============================
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   documentation
+   reporting_bug

docs/_sources/development/reporting_bug.rst.txt

@@ -0,0 +1,5 @@
+********************************
+Reporting a Bug
+********************************
+
+Open a new issue on our `GitHub <https://github.com/ranaroussi/yfinance/issues>`_.

docs/_sources/getting_started/index.rst.txt

@@ -0,0 +1,9 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   quick_start
+   legal

docs/_sources/getting_started/installation.rst.txt

@@ -0,0 +1,17 @@
+********************
+Installation Guide
+********************
+
+Install `yfinance` using `pip`:
+
+.. code-block:: bash
+
+   $ pip install yfinance --upgrade --no-cache-dir
+
+To install with optional dependencies, replace `optional` with: `nospam` for `caching-requests <https://github.com/ranaroussi/yfinance?tab=readme-ov-file#smarter-scraping>`_, `repair` for `price repair <https://github.com/ranaroussi/yfinance/wiki/Price-repair>`_, or `nospam`, `repair` for both:
+
+.. code-block:: bash
+
+   $ pip install "yfinance[optional]"
+
+For required dependencies, check out the `requirements file <./requirements.txt>`_, and for all dependencies, see the `setup.py file <./setup.py#L62>`_.

docs/_sources/getting_started/legal.rst.txt

@@ -0,0 +1,12 @@
+********************
+Legal Information
+********************
+
+yfinance is distributed under the Apache Software License. See the `LICENSE.txt <../../../../LICENSE.txt>`_ file for details.
+
+Again, 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.
+
+Refer to Yahoo!'s terms of use: 
+
+- `API Terms <https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm>`_
+- `Yahoo Terms <https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html>`_

docs/_sources/getting_started/quick_start.rst.txt

@@ -0,0 +1,30 @@
+********************
+Quick Start
+********************
+
+The Ticker module allows you to access ticker data in a more Pythonic way:
+
+.. code-block:: python
+
+   import yfinance as yf
+
+   msft = yf.Ticker("MSFT")
+
+   # get all stock info
+   msft.info
+
+   # get historical market data
+   hist = msft.history(period="1mo")
+
+   # show actions (dividends, splits, capital gains)
+   msft.actions
+   msft.dividends
+   msft.splits
+
+To work with multiple tickers, use:
+
+.. code-block:: python
+
+   tickers = yf.Tickers('msft aapl goog')
+   tickers.tickers['MSFT'].info
+   tickers.tickers['AAPL'].history(period="1mo")

docs/_sources/index.rst.txt

@@ -0,0 +1,30 @@
+yfinance documentation
+==============================================
+
+Download Market Data from Yahoo! Finance's API
+------------------------------------------------
+
+.. admonition:: IMPORTANT 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**
+   (`here <https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm>`__),
+   (`here <https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html>`__),
+   and (`here <https://policies.yahoo.com/us/en/yahoo/terms/index.htm>`__)
+   for details on your rights to use the actual data downloaded.
+   Remember - the Yahoo! finance API is intended for personal use only.
+
+.. toctree::
+   :maxdepth: 3
+   :hidden:
+   :titlesonly:
+
+   getting_started/index
+   user_guide/index
+   reference/index
+   development/index

docs/_sources/reference/api/attributes/yfinance.EquityQuery.valid_eq_operand_map.rst.txt

@@ -0,0 +1,6 @@
+yfinance.EquityQuery.valid\_eq\_operand\_map
+============================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: EquityQuery.valid_eq_operand_map

docs/_sources/reference/api/attributes/yfinance.EquityQuery.valid_operand_fields.rst.txt

@@ -0,0 +1,6 @@
+yfinance.EquityQuery.valid\_operand\_fields
+===========================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: EquityQuery.valid_operand_fields

docs/_sources/reference/api/attributes/yfinance.Industry.key.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.key
+=====================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.key

docs/_sources/reference/api/attributes/yfinance.Industry.name.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.name
+======================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.name

docs/_sources/reference/api/attributes/yfinance.Industry.overview.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.overview
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.overview

docs/_sources/reference/api/attributes/yfinance.Industry.research_reports.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.research\_reports
+===================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.research_reports

docs/_sources/reference/api/attributes/yfinance.Industry.sector_key.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.sector\_key
+=============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.sector_key

docs/_sources/reference/api/attributes/yfinance.Industry.sector_name.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.sector\_name
+==============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.sector_name

docs/_sources/reference/api/attributes/yfinance.Industry.symbol.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.symbol
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.symbol

docs/_sources/reference/api/attributes/yfinance.Industry.ticker.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.ticker
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.ticker

docs/_sources/reference/api/attributes/yfinance.Industry.top_companies.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.top\_companies
+================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.top_companies

docs/_sources/reference/api/attributes/yfinance.Industry.top_growth_companies.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.top\_growth\_companies
+========================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.top_growth_companies

docs/_sources/reference/api/attributes/yfinance.Industry.top_performing_companies.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Industry.top\_performing\_companies
+============================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Industry.top_performing_companies

docs/_sources/reference/api/attributes/yfinance.Screener.body.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Screener.body
+======================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Screener.body

docs/_sources/reference/api/attributes/yfinance.Screener.predefined_bodies.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Screener.predefined\_bodies
+====================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Screener.predefined_bodies

docs/_sources/reference/api/attributes/yfinance.Screener.response.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Screener.response
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Screener.response

docs/_sources/reference/api/attributes/yfinance.Sector.industries.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.industries
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.industries

docs/_sources/reference/api/attributes/yfinance.Sector.key.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.key
+===================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.key

docs/_sources/reference/api/attributes/yfinance.Sector.name.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.name
+====================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.name

docs/_sources/reference/api/attributes/yfinance.Sector.overview.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.overview
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.overview

docs/_sources/reference/api/attributes/yfinance.Sector.research_reports.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.research\_reports
+=================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.research_reports

docs/_sources/reference/api/attributes/yfinance.Sector.symbol.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.symbol
+======================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.symbol

docs/_sources/reference/api/attributes/yfinance.Sector.ticker.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.ticker
+======================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.ticker

docs/_sources/reference/api/attributes/yfinance.Sector.top_companies.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.top\_companies
+==============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.top_companies

docs/_sources/reference/api/attributes/yfinance.Sector.top_etfs.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.top\_etfs
+=========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.top_etfs

docs/_sources/reference/api/attributes/yfinance.Sector.top_mutual_funds.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Sector.top\_mutual\_funds
+==================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Sector.top_mutual_funds

docs/_sources/reference/api/attributes/yfinance.Ticker.actions.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.actions
+=======================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.actions

docs/_sources/reference/api/attributes/yfinance.Ticker.analyst_price_targets.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.analyst\_price\_targets
+=======================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.analyst_price_targets

docs/_sources/reference/api/attributes/yfinance.Ticker.balance_sheet.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.balance\_sheet
+==============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.balance_sheet

docs/_sources/reference/api/attributes/yfinance.Ticker.balancesheet.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.balancesheet
+============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.balancesheet

docs/_sources/reference/api/attributes/yfinance.Ticker.basic_info.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.basic\_info
+===========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.basic_info

docs/_sources/reference/api/attributes/yfinance.Ticker.calendar.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.calendar
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.calendar

docs/_sources/reference/api/attributes/yfinance.Ticker.capital_gains.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.capital\_gains
+==============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.capital_gains

docs/_sources/reference/api/attributes/yfinance.Ticker.cash_flow.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.cash\_flow
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.cash_flow

docs/_sources/reference/api/attributes/yfinance.Ticker.cashflow.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.cashflow
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.cashflow

docs/_sources/reference/api/attributes/yfinance.Ticker.dividends.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.dividends
+=========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.dividends

docs/_sources/reference/api/attributes/yfinance.Ticker.earnings.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.earnings
+========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.earnings

docs/_sources/reference/api/attributes/yfinance.Ticker.earnings_dates.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.earnings\_dates
+===============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.earnings_dates

docs/_sources/reference/api/attributes/yfinance.Ticker.earnings_estimate.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.earnings\_estimate
+==================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.earnings_estimate

docs/_sources/reference/api/attributes/yfinance.Ticker.earnings_history.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.earnings\_history
+=================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.earnings_history

docs/_sources/reference/api/attributes/yfinance.Ticker.eps_revisions.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.eps\_revisions
+==============================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.eps_revisions

docs/_sources/reference/api/attributes/yfinance.Ticker.eps_trend.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.eps\_trend
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.eps_trend

docs/_sources/reference/api/attributes/yfinance.Ticker.fast_info.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.fast\_info
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.fast_info

docs/_sources/reference/api/attributes/yfinance.Ticker.financials.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.financials
+==========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.financials

docs/_sources/reference/api/attributes/yfinance.Ticker.funds_data.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.funds\_data
+===========================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.funds_data

docs/_sources/reference/api/attributes/yfinance.Ticker.growth_estimates.rst.txt

@@ -0,0 +1,6 @@
+yfinance.Ticker.growth\_estimates
+=================================
+
+.. currentmodule:: yfinance
+
+.. autoproperty:: Ticker.growth_estimates