Metadata-Version: 2.5
Name: dataras
Version: 0.3.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="فولاد")
```

## Errors

Every failure raises a `dataras` error with a short message that says what went
wrong and what to do. Unhandled errors show only that message: one line in
Jupyter and the Python shell, your own call line plus the message in a script.

| Error | When | Example message |
|-------|------|-----------------|
| `AuthenticationError` | 401: not logged in, or the token expired | `Not authenticated (401): you are not logged in, or your session or token has expired or is invalid. Log in again, or check your access token or API key.` |
| `PermissionDeniedError` | 403: your account cannot access this data | `Access denied (403): your account does not have permission for this data or date range. Check your subscription or access level, or contact support. [request_id: ABC123]` |
| `NotFoundError` | 404: unknown ticker, ISIN, statement, fund | `Not found (404): the requested item (ticker, ISIN, statement, fund, ...) was not found. Check the identifier.` |
| `ConflictError` | 409 | `Conflict (409): the request conflicts with the current state of the resource. Refresh the data and try again.` |
| `ValidationError` | 422: the server rejected inputs (each field is listed) | `Invalid input (422): the server rejected 1 input(s). Fix the fields below and try again.`<br>`  - day: invalid date format` |
| `RateLimitError` | 429: too many requests | `Too many requests (429): you sent too many requests in a short time. Wait 30 seconds and try again.` |
| `ServerError` | 5xx | `Service unavailable (503): the Dataras service is temporarily unavailable. Try again in a few minutes.` |
| `DatarasConnectionError` | no network, wrong `base_url` | `Could not connect to the Dataras API at https://api.dataras.ir. Check your internet connection and the base_url setting.` |
| `DatarasTimeoutError` | the request took too long | `The request to https://api.dataras.ir/v1/reference/tickers timed out after 30 seconds. Try again, or increase the timeout with DatarasClient(timeout=...).` |
| `DatarasDecodeError` | the API returned something unexpected | `The Dataras API returned data in an unexpected format (Page[Ticker]). Updating the dataras package may fix this; otherwise contact support.` |
| `InvalidInputError` | a bad argument, caught before any request | `page must be a whole number of 1 or more; received '2' (str).` |
| `SymbolResolutionError` | a `symbol` matches no ISIN or several | lists the candidate matches |

Catch a whole family with `DatarasAPIError` (server answered with an error),
`DatarasTransportError` (network) or `DatarasConfigurationError` (setup and
arguments; `InvalidInputError` is also a `ValueError`). Server errors keep
`status_code`, `request_id`, `server_message` (the server's own wording),
`payload` and `retry_after`; give the `request_id` to support.

```python
from dataras import DatarasAPIError, InvalidInputError

try:
    client.reference.list_tickers(page=page)
except InvalidInputError as exc:
    print(exc.parameter, exc)
except DatarasAPIError as exc:
    print(exc.status_code, exc.request_id, exc.server_message)
```

To see the full technical trace (for a bug report), turn on debug mode:
`DATARAS_DEBUG=1` in the environment, `%env DATARAS_DEBUG=1` in a notebook, or
`os.environ["DATARAS_DEBUG"] = "1"` in code. It applies from the next error.

## 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.
