Metadata-Version: 2.4
Name: pydara
Version: 0.6.0a1
Summary: Dara financial data modules: TSE quotes, history, typed exports and versioned local storage
Author: Dara contributors
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: pandas<4,>=2.2
Requires-Dist: platformdirs<5,>=4
Requires-Dist: tzdata>=2024.1
Provides-Extra: excel
Requires-Dist: openpyxl<4,>=3.1.5; extra == "excel"
Provides-Extra: parquet
Requires-Dist: pyarrow>=19; extra == "parquet"
Provides-Extra: files
Requires-Dist: openpyxl<4,>=3.1.5; extra == "files"
Requires-Dist: pyarrow>=19; extra == "files"
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Provides-Extra: notebook
Requires-Dist: ipykernel>=6; extra == "notebook"
Requires-Dist: nbformat>=5; extra == "notebook"
Requires-Dist: nbclient>=0.10; extra == "notebook"
Dynamic: license-file

# Dara

Release **0.6.0a1**. Dara is a modular Python library for financial data.
The PyPI distribution is named **`pydara`**; its Python import is **`dara`**.
The currently implemented public module is **`dara.tse`**, providing TSETMC
quotes, instrument lookup, history, market data, sync/async workflows, Pandas
outputs, versioned SQLite storage and typed file exports.

## Install

Requires Python 3.12 or newer. After publication on PyPI:

```console
python -m pip install --upgrade pydara==0.6.0a1
```

Optional Excel, Parquet and notebook support:

```console
python -m pip install --upgrade "pydara[files,notebook]==0.6.0a1"
```

For a local release bundle, activate your Python environment and run
`python install.py` (`--core-only` omits optional file/notebook dependencies).
Restart the Jupyter kernel after installation or upgrade.

## Use

```python
from dara import tse

# Synthetic teaching data; no external request.
sample = tse.load_sample()
reference = tse.api_reference('instrument')

# Real data: network access or an eligible cache entry is required.
matches = tse.instrument(symbol="فولاد", on_multiple="all")
history = tse.history("فولاد", start="1403-01-01", end="1403-12-30")
```

```python
from dara.tse import Client, AsyncClient
from dara.tse.exceptions import DaraError
```

Instrument lookup defaults to all matching rows. `on_multiple="first"` returns
the first source-ordered match; `"error"` rejects ambiguity.
`on_conflict="error"` checks supplied constraints. `"ins_code"` explicitly
prioritizes a supplied instrument code.

## Scope and data contracts

The TSE module includes public quotes/history, market watch, client types,
indices, reported trades/books/states/thresholds, ownership/share counts,
adjustment events, source-adjusted chart data, fund/NAV data, messages and
options. Availability depends on the source endpoint. The separate futures
exchange gateway is experimental. Current catalog coverage is not a complete
historical instrument registry. Source-adjusted data does not certify total
return or point-in-time history.

Analysis, ML, Bitcoin, exchange rates, gold and other countries' markets are
planned extensions. They are not implemented modules in this release.

Importing `dara` creates no network connection, database or worker thread.
Explicit offline use is `tse.FetchPolicy.offline(allow_stale=True)`.
A queued storage receipt is not durable storage. Preserve the JSON sidecar
when copying a CSV Dara archive.

## Migration from tse-dara

Replace `from tse_dara import data` with `from dara import tse`, and use
`tse.history(...)`, `tse.instrument(...)`, etc. Alternatively,
`from dara import tse as data` keeps existing local variable names.
Exceptions move to `dara.tse.exceptions`. The old Python namespace is not shipped.

The existing default cache path and the legacy `tse_dara` metadata key and
`tse-dara-frame` storage marker are retained for stored-data compatibility.
No user database is deleted or migrated by this rename.
See [migration instructions](docs/MIGRATION_FA.md).

## Documentation and development

- [Persian guide](README_FA.md)
- [API reference](docs/API_REFERENCE.md)
- [Roadmap](docs/ROADMAP_FA.md)
- [Third-party notices](THIRD_PARTY_NOTICES.md)

```console
python -m pip install -e ".[test,files]" build twine
python tools/generate_api_reference.py
python -m build --wheel --outdir dist
python tools/update_bundle.py
python -m pytest -q
```

Offline/synthetic tests verify local contracts and do not certify live source
accuracy or endpoint availability. The code is MIT licensed; data rights are
separate from the code license.
