Skip to content

Commit

Permalink
Merge pull request #2115 from ericpien/docs
Browse files Browse the repository at this point in the history 
Adding Sphinx Documentation
  • Loading branch information
@ValueRaider
ValueRaider authored Nov 6, 2024
2 parents 664a4b4 + 3e647a8 commit 1e15302
Show file tree
Hide file tree
Showing 47 changed files with 1,624 additions and 501 deletions.
Binary file added .DS_Store
View file
Binary file not shown.
53 changes: 53 additions & 0 deletions .github/workflows/deploy_doc.yml
View file
Original file line number Diff line number Diff line change
@@ -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 }}
8 changes: 7 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,10 @@ test.ipynb
env/
venv/
ENV/
site/

# Documentation
/doc/build/
/doc/_build/
/doc/source/reference/api
!yfinance.css
!/doc/source/development/assets/branches.png
305 changes: 10 additions & 295 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,19 +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)

---

- [Installation](#installation)
- [Quick start](#quick-start)
- [Advanced](#logging)
- [Wiki](https://github.com/ranaroussi/yfinance/wiki)
- [Contribute](#developers-want-to-contribute)

---
## Documentation
The official documentation is available on [ranaroussi.github.io/yfinance](https://ranaroussi.github.io/yfinance/index.html)

## Installation

Expand All @@ -67,292 +64,10 @@ $ pip install "yfinance[optional]"

[Required dependencies](./requirements.txt) , [all dependencies](./setup.py#L62).

---

## 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:
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
```

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`.

```python
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
```

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.

### Sector and Industry

The `Sector` and `Industry` modules allow you to access the US market information.

To initialize, use the relevant sector or industry key as below. (Complete mapping of the keys is available in `const.py`.)

```python
import yfinance as yf
The list of changes can be found in the [changelog](https://github.com/ranaroussi/yfinance/blob/main/CHANGELOG.rst)

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
```

The modules can be chained with Ticker as below.
```python
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()
```

### Market Screener
The `Screener` module allows you to screen the market based on specified queries.

#### Query Construction
To create a query, you can use the `EquityQuery` class to construct your filters step by step. The queries support operators: `GT` (greater than), `LT` (less than), `BTWN` (between), `EQ` (equals), and logical operators `AND` and `OR` for combining multiple conditions.

#### Screener
The `Screener` class is used to execute the queries and return the filtered results. You can set a custom body for the screener or use predefined configurations.

<!-- TODO: link to Github Pages for more including list of predefined bodies, supported fields, operands, and sample code -->

### 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

Install the `nospam` packages for smarter scraping using `pip` (see [Installation](#installation)). These packages help cache calls such that Yahoo is not spammed with requests.

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.

```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.
```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

### 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()`:

```python
import yfinance as yf
yf.set_tz_cache_location("custom/cache/location")
...
```

---

## Developers: want to contribute?

`yfinance` relies on community to investigate bugs and contribute code. Developer guide: https://github.com/ranaroussi/yfinance/discussions/1084

---
Expand Down
Loading

0 comments on commit 1e15302

Please sign in to comment.