y-not-finance 1.8.3
Financial data library for prices and index constituents
License: MIT
Requires Python: >=3.8
Keywords: finance, stocks, constituents, yahoo-finance, data

# Y-Not-Finance

A comprehensive Python library for fetching financial data, combining Yahoo Finance price data with stock index constituents from multiple sources.

## Features

### 📈 Prices (Yahoo Finance)
- **Multi-ticker concurrent fetching** - Fetch data for multiple stocks simultaneously
- **Automatic retry with exponential backoff** - Resilient to API rate limits
- **Flexible intervals** - Support for intraday (1m, 5m, 15m, 30m, 1h) and daily+ (1d, 1wk, 1mo) data
- **Multiple fields** - Open, High, Low, Close, Volume, Adjusted Close
- **Date range filtering** - Easy-to-use range strings like "1mo", "3mo", "1y"

### 📅 Events (Yahoo Finance)
- **Dividends and splits**
- **Multi-ticker support** - Retrieve events across multiple tickers
- **Consistent output** - Returns DataFrame with date index and ticker columns

### 🏢 Constituents (Web Scrapers)
- **Multiple indexes** - S&P 500, NASDAQ, Dow Jones, TSX, and market cap tiers
- **Unified API** - Single function to access all data sources
- **Company names included** - Get both ticker symbols and full company names
- **Automatic pagination** - Handles large datasets seamlessly

### 🗂️ Constituents (Historical Data)
- **Daily S&P 500 constituents** - 1980-01-01 to 2025-12-31
- **Intraday OHLC** - Precomputed 2024 dataset
- **Fast access** - Downloads once and reads from cached Parquet

## Installation

```bash
pip install -e .
```

Or install from requirements:
```bash
pip install -r requirements.txt
```

## Quick Start

### Fetch Price Data

```python
from y_not_finance import YahooFinanceClient

# Initialize the client
client = YahooFinanceClient()

# Single ticker
df = client.get_prices("AAPL", range_str="1mo")

# Multiple tickers
df = client.get_prices(["AAPL", "MSFT", "GOOGL"], range_str="3mo", fields="close")

# Multiple fields
df = client.get_prices(
    ["AAPL", "MSFT"],
    range_str="1y",
    interval="1d",
    fields=["open", "high", "low", "close", "volume"]
)
```

### Fetch Events Data

```python
from y_not_finance import YahooFinanceClient

client = YahooFinanceClient()

# Get dividends
dividends_df = client.get_events("AAPL", range_str="5y", event_type="dividends")

# Get splits
splits_df = client.get_events("AAPL", range_str="5y", event_type="splits")
```

### Fetch Index Constituents

```python
from y_not_finance import get_constituents

# Get S&P 500 constituents
tickers = get_constituents("^SPX", info=True)

# Get TSX constituents
tickers = get_constituents("^GSPTSE", include_benchmark=True)

# Get mega cap stocks
tickers = get_constituents("megacaps")
```

### Fetch Historical Constituents

```python
from y_not_finance.constituents.historical import (
    get_historical_constituents,
    get_intraday_ohlc,
)

# Daily S&P 500 constituents (full history)
df = get_historical_constituents()

# Constituents on a specific date
df_date = get_historical_constituents(date="2024-01-15")

# Intraday OHLC data for 2024
ohlc_df = get_intraday_ohlc()
```

### Combined Usage

```python
from y_not_finance import YahooFinanceClient, get_constituents

# Get index constituents
sp500_tickers = get_constituents("^SPX")

# Fetch prices for all constituents
client = YahooFinanceClient()
df = client.get_prices(
    list(sp500_tickers.keys()),
    range_str="1mo",
    fields="adjclose"
)
```

## Package Structure

```
y_not_finance/
├── __init__.py                 # Main package API
│
├── yahoo_finance/              # Yahoo Finance provider
│   ├── client.py               # YahooFinanceClient (prices + events)
│   ├── core/                   # Shared infrastructure
│   │   ├── http_client.py
│   │   └── exceptions.py
│   ├── prices/                 # Price parsing and constants
│   └── events/                 # Events parsing helpers
│
└── constituents/               # Index constituents provider
    ├── historical/             # Historical constituents + intraday data
    │   ├── client.py            # get_historical_constituents(), get_intraday_ohlc()
    │   └── README.md            # Module documentation
    └── scrapers/               # Web scrapers
```

See [ARCHITECTURE.md](ARCHITECTURE.md) for full structure and design rationale.

## Documentation

- [API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture overview
- [CONTRIBUTING.md](CONTRIBUTING.md) - Development guidelines
- [CHANGELOG.md](CHANGELOG.md) - Version history

## Supported Indexes

| Key | Index Name | Source |
|-----|-----------|--------|
| ^SPX | S&P 500 Index | StockAnalysis.com |
| ^DJI | Dow Jones Industrial Average | StockAnalysis.com |
| ^IXIC | NASDAQ Composite | StockAnalysis.com |
| ^GSPTSE | S&P/TSX Composite (Canada) | Globe and Mail |
| megacaps | Mega Cap Stocks | StockAnalysis.com |
| largecaps | Large Cap Stocks | StockAnalysis.com |
| midcaps | Mid Cap Stocks | StockAnalysis.com |
| smallcaps | Small Cap Stocks | StockAnalysis.com |
| microcaps | Micro Cap Stocks | StockAnalysis.com |
| nanocaps | Nano Cap Stocks | StockAnalysis.com |

## Examples

See the [examples/](examples/) directory for comprehensive usage examples:
- `combined_usage.py` - Complete demonstration of all features
- `basic_usage.py` - Simple price fetching
- `financial_analysis.py` - Analysis workflows
- `data_export.py` - Export to CSV/Excel

Run an example:
```bash
python examples/combined_usage.py
```

## Requirements

- Python 3.8+
- numpy
- pandas
- requests

Optional:
- pyarrow (for Parquet export in examples)

See [requirements.txt](requirements.txt) for complete dependencies.

## License

See [LICENSE](LICENSE) file for details.

## Changelog

### Version 1.0.0
- Complete restructure into modular package
- Separated prices and constituents into submodules
- Improved code organization following best practices
- Added comprehensive documentation
- Enhanced error handling and logging