Metadata-Version: 2.4
Name: safin
Version: 0.2.0
Summary: safin SDK — sunset shim. The hosted API was retired on 2026-05-06.
Project-URL: Sunset, https://github.com/bluedoor-ai/safin/blob/main/SUNSET.md
Project-URL: Source, https://github.com/bluedoor-ai/safin
Author-email: BlueDoor <sam@bluedoor.sh>
License: MIT
Keywords: finance,market-data,safin,seeking-alpha,stocks,sunset
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# safin Python SDK

> **🛑 Sunset (2026-05-06).** `safin>=0.2.0` is a sunset shim — instantiating
> `Client()` raises `RuntimeError`. Version 0.1.0 is yanked. See
> [SUNSET.md](https://github.com/bluedoor-ai/safin/blob/main/SUNSET.md) for
> rationale and defrost criteria.

Python SDK for `safin`, the hosted Seeking Alpha market-data API.

```bash
pip install safin
```

```python
from safin import Client

sa = Client(contact="you@example.com")

quote = sa.quote("GRAB")
ratios = sa.metrics_ratios("GRAB", fields=["pe_ratio", "ps_ratio"])
valuation = sa.valuation("GRAB")
history = sa.historical_prices("GRAB", start="2026-04-01", end="2026-05-05")
chain = sa.options_chain(ticker_id=605799, expiration_date="2026-05-15")
```

The default base URL is the verified Worker deployment:

```text
https://safin-api.crombiesamuel.workers.dev
```

Override it with `SAFIN_BASE_URL` or `Client(base_url=...)`. The configured
custom domain target is `https://api.safin.bluedoor.sh` once DNS is live.

## Public Methods

- Discovery: `health()`, `endpoints()`, `openapi()`
- Quotes: `quote(symbol)`, `quotes(symbols)`, `quotes_by_id(sa_ids)`
- Options: `options_by_symbols(symbols)`, `options_chain(ticker_id, expiration_date)`, `options_expirations(symbol)`
- Metrics and fundamentals: `metrics_ratios(symbol)`, `metrics_market(symbol)`, `symbol_data(symbol)`, `valuation(symbol)`, `estimates(ticker_id)`, `fundamentals(symbol)`, `fundamentals_metrics(symbol)`
- History and ownership: `historical_prices(symbol)`, `shares(symbol)`
- News: `news(symbol)`

All methods return the hosted API's JSON envelope as a `dict`.

## Identity

- Anonymous: works without configuration.
- Contact tier: `Client(contact="you@example.com")` sends `X-Safin-Contact`.
- Manual API key tier: `Client(api_key="...")` sends `Authorization: Bearer ...`.

Environment variables: `SAFIN_BASE_URL`, `SAFIN_CONTACT`, `SAFIN_API_KEY`.
