Metadata-Version: 2.5
Name: dataras
Version: 0.2.0
Summary: Official Python SDK for the Dataras market-data API
Project-URL: Homepage, https://dataras.ir
Project-URL: Documentation, https://dataras.ir
Project-URL: Bug Tracker, https://dataras.ir
Author-email: Dataras <info@dataras.ir>
License-Expression: MIT
License-File: LICENSE
Keywords: dataras,finance,iran,market-data,sdk,stock-market
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pyarrow>=14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: nbsphinx>=0.9; extra == 'docs'
Requires-Dist: pypandoc-binary>=1.13; extra == 'docs'
Requires-Dist: sphinx-intl>=2.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=8.0; extra == 'docs'
Provides-Extra: export
Requires-Dist: pyarrow>=14; extra == 'export'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# Dataras Python SDK

Official Python client for the Dataras market-data API.

## Install

```bash
uv add dataras
# or
pip install dataras
```

`pandas` is included so `export="pandas"` works out of the box.
For Parquet files (`export="parquet"`), also install:

```bash
pip install 'dataras[export]'
```

## Quickstart

```python
from dataras import DatarasClient

with DatarasClient() as client:
    client.auth.login("YOUR_USERNAME", "YOUR_PASSWORD")
    page = client.reference.list_tickers(search="فولاد", limit=10)
    for ticker in page.results:
        print(ticker.ticker, ticker.name)

    # Timeseries / fundamental accept ISIN via ticker/isin, or trading symbol:
    df = client.ohlc.list_bars(
        symbol="فولاد",
        multiplier=1,
        timespan="day",
        from_="2026-01-01",
        to="2026-01-31",
        export="pandas",
    )
    meta = client.fundamental.list_meta(
        type="balance_sheet",
        symbol="فولاد",
        export="pandas",
    )
```

### Date ranges

- Custom OHLC bars (`ohlc.list_bars` / `iter_bars` / `download_bars`) need both
  `from_` and `to`.
- For IME ticker history, bond payments and fund history, omitting both dates
  returns the full allowed date window for your account (no date filter for
  unrestricted accounts). For long histories, page with `iter_*`, set `limit`,
  or pass explicit dates.

### Funds

```python
with DatarasClient() as client:
    client.auth.login("YOUR_USERNAME", "YOUR_PASSWORD")
    funds = client.funds.list_funds(search="آگاه", export="pandas")
    daily = client.funds.list_daily("2026-07-21", export="pandas")
    history = client.funds.list_history(daily.iloc[0]["isin"], export="pandas")
```

Default base URL is `https://api.dataras.ir` — you do not need to pass `base_url`.
Override only when needed:

```python
client = DatarasClient(base_url="https://staging.example.com")
```

Environment variables (opt-in via `DatarasClient.from_env()`):

- `DATARAS_BASE_URL` (optional; defaults to `https://api.dataras.ir`)
- `DATARAS_ACCESS_TOKEN`
- `DATARAS_API_KEY`
- `DATARAS_API_KEY_HEADER` (required when using an API key; header name is not yet in the OpenAPI contract)

## Async

```python
from dataras import AsyncDatarasClient

async with AsyncDatarasClient(access_token="...") as client:
    page = await client.reference.list_tickers(search="فولاد")
```

## Documentation

Build the English documentation site:

```bash
uv sync --extra docs
cd docs && make en
```

Generate coverage manifests and validate OpenAPI documentation status:

```bash
uv run python scripts/generate_doc_manifests.py
uv run python scripts/check_docs_coverage.py
```

See `docs/DOCUMENTATION_AUDIT.md` for architecture notes and known gaps.
