Metadata-Version: 2.4
Name: xfinance
Version: 0.3.0
Summary: The definitive open-source yfinance alternative — multi-source, failover-capable, fully normalized
License: Apache-2.0
Keywords: finance,financial-data,fundamentals,market-data,options,stocks,yfinance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pybreaker>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: all
Requires-Dist: diskcache>=5.6.0; extra == 'all'
Requires-Dist: duckdb>=0.10.0; extra == 'all'
Requires-Dist: polars>=0.20.0; extra == 'all'
Requires-Dist: pyarrow>=14.0.0; extra == 'all'
Requires-Dist: websockets>=12.0; extra == 'all'
Provides-Extra: cache
Requires-Dist: diskcache>=5.6.0; extra == 'cache'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-recording>=0.13.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: vcrpy>=6.0.0; extra == 'dev'
Provides-Extra: duckdb
Requires-Dist: duckdb>=0.10.0; extra == 'duckdb'
Requires-Dist: pyarrow>=14.0.0; extra == 'duckdb'
Provides-Extra: polars
Requires-Dist: polars>=0.20.0; extra == 'polars'
Provides-Extra: websocket
Requires-Dist: websockets>=12.0; extra == 'websocket'
Description-Content-Type: text/markdown

# findata

**A multi-source, failover-capable Python financial data library.**

findata delivers yfinance's beloved simplicity with 10× the reliability through automatic failover across multiple data sources, intelligent three-tier caching, and a community plugin architecture.

## Why findata?

| Problem with yfinance | findata solution |
|---|---|
| Breaks 2–4×/year when Yahoo changes endpoints | Circuit-breaker failover to SEC, ECB, Binance |
| No built-in caching; hammers APIs on every call | Three-tier cache (memory → diskcache → Parquet) |
| No rate limiting; users get IP-blocked | Per-source adaptive rate limiters |
| Silent failures (empty DataFrames) | Rich exceptions with source provenance |
| Single unofficial API | 5+ sources, plugin architecture for more |

## Quick start

```bash
pip install findata
```

```python
import findata

# One line — works immediately, no API keys needed
df = findata.prices("AAPL", period="1mo")

# Multi-source with validation
client = findata.Client(sources=["yahoo", "sec", "ecb"])
df = client.prices("AAPL", start="2024-01-01", validate=True)

# Async batch fetching
import asyncio

async def main():
    async with findata.AsyncClient() as client:
        data = await client.prices(["AAPL", "GOOGL", "MSFT"], period="1y")

asyncio.run(main())

# Fundamentals from SEC EDGAR (free, no key needed)
info = findata.info("AAPL")

# Forex from ECB (free, no key, no rate limits)
fx = findata.forex("USD/EUR", period="1y")

# Crypto from Binance public API (free, no key)
btc = findata.prices("BTC/USDT", period="30d")
```

## Optional extras

```bash
pip install findata[cache]    # diskcache for persistent local caching
pip install findata[duckdb]   # DuckDB + Parquet for historical storage
pip install findata[polars]   # Polars DataFrame output
pip install findata[all]      # Everything
```

## Data sources (v0.1)

| Source | Data | Auth | Rate limit |
|---|---|---|---|
| Yahoo Finance | Prices, options, info | None (unofficial) | ~950 req/session |
| SEC EDGAR | Fundamentals, filings | None | 10 req/s |
| ECB / Frankfurter | Forex | None | No limit |
| Binance | Crypto OHLCV | None | 1200 req/min |
| CoinGecko | Crypto info | None (free tier) | 30 req/min |

See [DATA_SOURCES.md](DATA_SOURCES.md) for full terms-of-service details and risk tiers.

## Community plugins

Add new sources as pip-installable packages:

```toml
# In your plugin's pyproject.toml
[project.entry-points."findata.sources"]
tradingview = "findata_tradingview:TradingViewSource"
```

A new source adapter can be implemented in under 100 lines by implementing the `DataSource` protocol.

## Legal notice

findata fetches data on behalf of users as a client library. Users are responsible for complying with each data provider's terms of service. Government data (SEC EDGAR) is in the public domain. See [DATA_SOURCES.md](DATA_SOURCES.md) for source-specific guidance.

## License

Apache 2.0
