Metadata-Version: 2.4
Name: tse-dara
Version: 0.5.0a4
Summary: Direct TSETMC data access: quotes, history, typed exports and resilient versioned local storage
Author: tse-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

# tse-dara

Release **0.5.0a4**. Direct public TSETMC data access with Pandas outputs,
sync/async clients, versioned local storage and typed file exports.

## Installation

Requires Python 3.12 or newer. Install or upgrade the current alpha release:

```console
python -m pip install --upgrade "tse-dara==0.5.0a4"
```

For optional Excel/Parquet exports and notebook support:

```console
python -m pip install --upgrade "tse-dara[files,notebook]==0.5.0a4"
```

Restart an existing notebook kernel after upgrading. Existing users do not need
to merge patch files or delete their database when installing from PyPI.

## Instrument lookup policies

`data.instrument(...)` and `data.resolve_instrument(...)` return DataFrames.
`on_multiple="all"` returns all matches by default; `"first"` selects the first
source-ordered match and `"error"` rejects multiple matches.
`on_conflict="error"` checks supplied constraints against the resolved instrument;
`"ins_code"` explicitly prioritizes a supplied instrument code.

```python
from tse_dara import data

# Synthetic data: does not require a network request.
sample = data.load_sample()

# Current instrument data: requires network access or eligible cached data.
matches = data.instrument(symbol="فولاد", on_multiple="all")
```

See PATCH_INSTRUMENT_POLICY_FA.md for the matching/conflict contract.

## Data workflows and extended feeds

- Simple history/market/index_history aliases with conservative calendar inference.
- Explicit network setup and bounded consent-based connectivity diagnostics.
- Pandas selection/index/concat and coverage/comparison helpers.
- Native sync/async workflows share one job generator. Optional typed resumable
  checkpoints retain failed-item reports; fresh policy bypasses resume snapshots.
- Local dataset catalog, queries, and explicit WAL-consistent SQLite backup.
- Reported trades/books/states/thresholds, ownership, share counts, adjustment events,
  source-adjusted chart data, fund/NAV data, messages/disclosures/dividends, options.
- Futures use a labeled experimental secondary exchange gateway.
- No analytics/ML. No migration/deletion of the existing working SQLite database.
- Autosave submission failures have a failed receipt instead of invalidating fetched data.

Limits and contracts: PATCH_0_5_FA.md, docs/RELEASE_0_5_API_FA.html.
Test results: reports/release_0_5/ (source review/synthetic tests are not live certification).

## Historical release notes

The following notes describe earlier releases and their original local patch
delivery. Use the installation instructions above for the current PyPI release.

# 0.4.0a1 market data extension

مبنا: 0.3.1a1. فقط فایل‌های جدید یا تغییرکرده ارسال شده‌اند. این بسته نصب مستقل از صفر نیست.

See [market guide](docs/MARKET_GUIDE_FA.html) and [API](docs/MARKET_API_REFERENCE.md).

# tse-dara

Release **0.3.1a1**, a unified alpha distribution of Parts 1–3 plus a data-interface and Pandas contract review. Direct public TSETMC requests; no runtime dependency on pytse-client or tsetmc.

## Scope

Existing quotes, raw daily history, sync/async clients, versioned SQLite history and file archives are preserved. This release adds simple one-row DataFrame getters, ordered Pandas batch input, explicit freshness helpers, local schema/normalization/validation tools, synthetic samples and a reference generated from actual signatures.

It does **not** implement analytics, ML, market watch, indices, client-type endpoints, corporate-action adjustment, historical identity chains, official JWT access, or PostgreSQL. The architecture HTML is a plan, not a declaration of supported features. See docs/BLUEPRINT_DATA_COVERAGE.md.

## Historical local bundle installation

```console
python install.py
```

The installer reads the single local wheel from BUNDLE.json and invokes pip with files/notebook extras. Missing dependencies need internet. Use `python install.py --core-only` explicitly when Excel/Parquet/notebooks are not required. Never delete your Conda environment or cache database to upgrade. Restart the notebook kernel afterwards.

The local bundle is not a self-contained offline wheelhouse.

## Examples

```python
from tse_dara import data

# Synthetic teaching data, no external HTTP or database
df = data.load_sample()
report = data.validate_data(df)
compact = data.select_columns(df)

# Real data: makes a network request or uses an eligible cache entry
quote_df = data.get_quote_frame("فولاد")
history = data.get_history("فولاد", start="1403-01-01",
                           end="1403-12-30", calendar="jalali")

# Documentation without a network request
reference = data.api_reference("get_history")
columns = data.schema_info("daily_bars")
```

Offline quote use is explicit: `policy=data.FetchPolicy.offline(allow_stale=True)`. The shortcut `policy="offline"` does not permit stale data. Use `FetchPolicy.fresh()` for a network read with max_age=0; online mode alone may use fresh cache.

`get_quotes` and `get_history_many` accept a list/tuple, Series, Index or 1D NumPy array. Input order and duplicates are preserved. Null entries are rejected before fetching. Raw numeric strings are not inferred as instrument IDs; use `InstrumentRef.by_ins_code`.

## Persistence

Best-effort autosave failures do not invalidate successfully fetched data. A queued receipt is not durable storage. Explicit `save`, `load`, `flush` and `sync_history(wait=True)` report failures. Existing 0.3.0a2 SQLite schemas and cache paths are retained; no destructive migration is introduced.

`save/load` use typed Dara archives. Preserve the JSON sidecar with CSV. They are not a generic parser for arbitrary external files. Use Pandas readers with explicit identifier dtypes, then normalize_data with an explicit column mapping for external data. Never treat a floating identifier as recoverable original text.

## References and examples

- START_HERE_FA.html: Persian getting-started guide.
- docs/DATA_REVIEW_REPORT_FA.html: complete current review and actual API/model documentation.
- docs/API_REFERENCE_FA.md and API_REFERENCE.md: real signatures, defaults, outputs, main exceptions and dependencies.
- docs/MODELS_REFERENCE_FA.md: actual runtime dataclasses and enums.
- docs/ROADMAP_REVIEW_FA.md: next data-only stages.
- docs/design_v0_2/USER_SUPPLIED_REPORT.html: original uploaded architecture, unchanged.
- examples/10_data_usability_offline.ipynb and 11_pandas_validation.ipynb: new offline notebooks.
- examples/12_data_review_live.ipynb: optional real-network test, disabled by default.
- tools/check_data_usability.py: offline check; `--live` explicitly opts into external requests.

## Verification

See reports/review_031/VERIFICATION.json for actual checks and limitations. Tests run on Linux/Python 3.13.5/Pandas 2.2.3, not Windows/Python 3.14/Pandas 3. Parquet tests require pyarrow; skipped tests are not successes. The GitHub matrix is supplied configuration and is not an executed Windows test report. Historical reports are preserved in separate directories.

Structural validation does not establish source accuracy, historical coverage, official publication time or absence of all forms of future-data leakage. No live-price number is bundled as a current quote.

## Development

```console
python -m pip install -e ".[test,notebook]"
python tools/generate_api_reference.py
python tools/build.py
python tools/update_bundle.py
python -m pytest -q
```

Generating the optional HTML documentation requires mistune, a documentation-only dependency, not a runtime dependency. Retain exactly one current wheel under dist/.

License: MIT; third-party notices are in THIRD_PARTY_NOTICES.md. Data-access and redistribution rights are separate from the code license.
