Metadata-Version: 2.4
Name: dataras
Version: 0.1.4
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)

    # Optional: get a pandas DataFrame
    df = client.fundamental.list_meta(
        type="balance_sheet",
        isin="IRTKMOFD0001",
        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.
