# بسته افزایشی tse-dara 0.4.0a1

مبنا: 0.3.1a1. فقط فایل‌های جدید یا تغییرکرده ارسال شده‌اند. این بسته نصب مستقل از صفر نیست.
پوشه tse-dara داخل ZIP را روی پوشه فعلی کپی و ادغام کنید. فقط فایل‌های هم‌نام را جایگزین کنید؛ پوشه قبلی را حذف نکنید.
محیط پایتون و پایگاه SQLite قبلی تغییر نمی‌کنند. هیچ مهاجرت ساختار پایگاه نیاز نیست.
نصاب از BUNDLE.json و اثرانگشت Wheel استفاده می‌کند؛ وجود فایل‌های نصب قدیمی مانع نیست. فایل install.py از نسخه قبلی باقی می‌ماند.
پس از نصب، Kernel ژوپیتر را Restart کنید. تغییر فایل‌های پوشه به‌تنهایی، نسخه بارگذاری‌شده در حافظه را عوض نمی‌کند.

```bat
conda activate "G:\My progect\Python\TSE\venv"
cd /d "G:\My progect\Python\TSE\Lib\tse-dara"
python tools\check_market_patch.py
python install.py
```

خروجی جدولی DataFrame است. توابع گروهی BatchFrames شامل data، errors و requests می‌دهند. ترتیب و ورودی تکراری حفظ می‌شود.
داده ناموجود صفر نیست. وقتی تاریخ یا ارزش معاملات حقیقی‌حقوقی در منبع نیست، از روی قیمت یا زمان دریافت ساخته نمی‌شود.
مقدار شاخص بر حسب واحد شاخص است، نه ریال. اعضای فعلی شاخص جای تاریخچه اعضا قرار نمی‌گیرد.
get_index_intraday فقط جلسه آخر قابل ارائه منبع را می‌گیرد. انتخاب روز دلخواه پشتیبانی نمی‌شود.
get_index_impact آزمایشی است: پاسخ منبع در source_fields حفظ می‌شود و impact_points تا تأیید معنای فیلد عددی، نامعلوم است.
watch_market دریافت دوره‌ای است، نه WebSocket. پیش‌فرض ۱۰ دریافت با فاصله ۱۰ ثانیه است. هیچ کاری بدون اجرای کاربر شروع نمی‌شود.
تحلیل و هوش مصنوعی اضافه نشده‌اند. وابستگی اجباری جدیدی نیز اضافه نشده است.
خرابی ذخیره خودکار نباید نتیجه معتبر دریافت را متوقف کند. save و flush صریح همچنان شکست را اعلام می‌کنند.
کش خام SQLite برای داده‌های جدید فعال است. sync_history و فهرست اصلاحات سطری فعلاً فقط برای تاریخچه قیمت سهام قبلی هستند.
آزمون زنده TSETMC، Windows، Python 3.14 و Pandas 3 در این محیط تأیید نشده‌اند. نمونه‌ها مصنوعی هستند.

```python
import tse_dara
from tse_dara import data
print(tse_dara.__version__)
sample = data.load_sample("market_watch_v1")
display(data.select_columns(sample))
display(data.validate_data(sample, schema="market_watch"))
```

## New API / functions

|Name|Return|
|---|---|
|`get_market_watch`|DataFrame|
|`get_market_order_book`|DataFrame|
|`get_market_overview`|DataFrame|
|`get_market_map`|DataFrame|
|`get_sectors`|DataFrame|
|`get_sector_instruments`|DataFrame|
|`get_key_statistics`|DataFrame|
|`get_client_types`|DataFrame|
|`get_client_type_history`|DataFrame|
|`get_market_client_types`|DataFrame|
|`get_indices`|DataFrame|
|`search_indices`|DataFrame|
|`get_index`|DataFrame|
|`get_index_history`|DataFrame|
|`get_index_intraday`|DataFrame|
|`get_index_members`|DataFrame|
|`get_index_impact`|DataFrame|
|`watch_market`|Iterator / AsyncIterator of DataFrame|
|`get_client_types_many`|BatchFrames(data, errors, requests)|
|`get_client_type_history_many`|BatchFrames(data, errors, requests)|
|`get_index_history_many`|BatchFrames(data, errors, requests)|

## Examples

13_market_client_indices_offline.ipynb: synthetic watch, client-type, indices, file roundtrip and cache.
14_market_client_indices_live.ipynb: RUN_LIVE=False by default; explicit public requests only.
15_market_client_indices_async.ipynb: native top-level await and bounded async iteration.

## Diagnostics
```bat
python tools\check_market_data.py
python tools\check_market_data.py --live --probe-raw
```

The diagnostic JSON includes environment versions, error messages, row counts and at most two records per response. Review it before sharing. No credentials are requested.

## Scope and provenance

All new API paths use the existing bounded HTTP layer and immutable response cache. No raw API keys or credentials are introduced.
`source_fields` is a compact JSON representation of the source row. Decimal values are encoded as text to avoid float precision loss; exact response bytes remain in the raw cache.
Index-effect records are experimental raw-only. There is no confirmed numeric impact mapping or arbitrary-index impact computation.
JSON watch rows may omit each instrument market. An explicit market filter then raises rather than guessing; `backend="legacy"` can be tested explicitly. auto fallback occurs only after a valid empty JSON list.
Unknown activity dates and timestamps remain NA/NaT. Components joined by ins_code are not guaranteed simultaneous. `coverage="raise"` cannot certify these public full-market data.
New histories fetch the available response and filter start/end locally; no incremental server history fetching is claimed for client types or indices.
Persisted raw replies can be used offline with the same endpoint/parameters and explicit allow_stale permission. File exports remain supported through data.save/load.
Index catalog identity is current; historical names and constituents are not reconstructed. No survival-bias-free historical universe is promised.
Fixed public legacy text route and JSON paths were reviewed in source; HTTP/auth/schema failures never trigger bypass attempts.
Empty structured tables are valid lack-of-response data, not proof the market was closed or nobody traded.

See docs/MARKET_API_REFERENCE.md for full signatures, parameters, defaults, errors and dependencies. Previous reports are historical baselines, not proof all new services are live-tested.

# Market / client-type / index API reference
Version: 0.4.0a1. Public methods exist on data, Client and AsyncClient.

No dependencies on tsetmc or pytse-client; no analytics or ML added. One-record tabular operations return DataFrame.

Asynchronous methods return the same result after await. watch_market is an async generator, consumed with async for.

All live operations use the existing HTTP budget, retry, payload validation, cache and best-effort storage policy.

## get_market_watch

```python
get_market_watch(*, market: 'Market | str | None' = None, include_order_book: 'bool' = False, include_client_types: 'bool' = False, show_traded: 'bool' = False, backend: 'str' = 'auto', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return the current public market watch as a typed DataFrame. auto falls back to the reviewed legacy text route only when JSON returns a valid empty list. Optional books and client types retain independent provenance; rows are not an atomic snapshot. Empty is not proof of a closed market.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str \| None|None|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|include_order_book|bool|False|Add reported depth 1..5 columns with separate provenance; no forward fill.|
|include_client_types|bool|False|Fetch and join a separate bulk response by exact ID; timestamps may be absent/different.|
|show_traded|bool|False|Return only rows with a reported positive trade_count. Unknown is not treated as proof of no trading.|
|backend|str|'auto'|auto/json/legacy; auto uses legacy only after valid empty JSON, not after auth/HTTP/schema errors.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_market_order_book

```python
get_market_order_book(*, market: 'Market | str | None' = None, backend: 'str' = 'auto', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return reported best-limit levels for the current watch. This is not the full exchange order book or historical depth. Missing levels are not filled. Source timestamps not reported by the feed remain missing.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str \| None|None|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|backend|str|'auto'|auto/json/legacy; auto uses legacy only after valid empty JSON, not after auth/HTTP/schema errors.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_market_overview

```python
get_market_overview(*, market: 'Market | str' = <Market.TSE: 'TSE'>, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return one row of reported market totals and index values. TSE or IFB only. Activity time and overall data time remain separate.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_market_map

```python
get_market_map(*, sector_code: 'str | None' = None, limit: 'int' = 9999, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return the reported market-map data only; no drawing or computed ranking. The source size parameter can truncate output; coverage is not certified.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|sector_code|str \| None|None|Exact short sector code returned by get_sectors(), preserving leading zeros.|
|limit|int|9999|Requested server output bound; not a coverage guarantee. Index impact other than the reviewed limit 7 is unverified.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_sectors

```python
get_sectors(*, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return sector codes/names with the four source counters preserved as source_c1..source_c4. Their undocumented bucket meanings are not guessed.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_sector_instruments

```python
get_sector_instruments(sector_code: 'str', *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return current related-company quotes for an exact sector code. This is industry grouping, not evidence of corporate ownership.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|sector_code|str|required|Exact short sector code returned by get_sectors(), preserving leading zeros.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_key_statistics

```python
get_key_statistics(*, ins_code: 'str | int | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return all reported parameter-code/value pairs (potentially a large response). ins_code filtering is local after the bulk response. reported_value stays text: undocumented units and metrics are not guessed.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|ins_code|str \| int \| None|None|Exact positive integer identifier; on bulk key statistics this is a local filter.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_client_types

```python
get_client_types(instrument: 'InstrumentLike', *, day: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return latest or one specified day of natural/legal counts, volumes and reported values as a DataFrame. Missing values and dates are not inferred. DDD source fields are kept separate from individual/institutional.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|instrument|InstrumentLike|required|Symbol string or explicit InstrumentRef. A bare numeric string is not inferred as ins_code.|
|day|DateLike \| None|None|Optional explicit single Gregorian/Jalali day; latest intraday index endpoint only supports None.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_client_type_history

```python
get_client_type_history(instrument: 'InstrumentLike', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return full available client-type history, then filter locally to inclusive dates, sorted ascending. Current identity does not certify historical identity or point-in-time availability.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|instrument|InstrumentLike|required|Symbol string or explicit InstrumentRef. A bare numeric string is not inferred as ins_code.|
|start|DateLike \| None|None|Inclusive date, ISO YYYY-MM-DD string or timezone-naive midnight Pandas Timestamp. None means available start.|
|end|DateLike \| None|None|Inclusive date, ISO string or timezone-naive midnight Pandas Timestamp. None means available end.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_market_client_types

```python
get_market_client_types(*, market: 'Market | str | None' = None, backend: 'str' = 'auto', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return the bulk client-type response. With market selected, intersect with current watch identities (one extra component); without a filter, keep every returned ins_code. No date/value/market is guessed when absent.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str \| None|None|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|backend|str|'auto'|auto/json/legacy; auto uses legacy only after valid empty JSON, not after auth/HTTP/schema errors.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_indices

```python
get_indices(*, market: 'Market | str | None' = <Market.TSE: 'TSE'>, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return index codes, names and latest reported values. market=None explicitly requests TSE and IFB catalogs separately. Unit is points, never currency.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## search_indices

```python
search_indices(query: 'str', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, limit: 'int | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Search normalized current index names; never choose the first match implicitly. A local limit does not change server pagination.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|query|str|required|Nonempty text to search. Search does not guess which result the user meant.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|limit|int \| None|None|Positive local display limit; None keeps all returned matches. Does not change server paging.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index

```python
get_index(index: 'str | int | InstrumentRef', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Resolve exactly one index from the current catalog by exact name or code, returning a one-row DataFrame. Ambiguous names raise. Use get_indices(market=None) to inspect available codes.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|index|str \| int \| InstrumentRef|required|Exact index code (string/int/InstrumentRef) or exact normalized catalog name. No first-match guess.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index_history

```python
get_index_history(index: 'str | int | InstrumentRef', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return daily index close/high/low in points, ascending with inclusive date filtering. Open and volume are not invented. A full response is fetched before local filtering.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|index|str \| int \| InstrumentRef|required|Exact index code (string/int/InstrumentRef) or exact normalized catalog name. No first-match guess.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|start|DateLike \| None|None|Inclusive date, ISO YYYY-MM-DD string or timezone-naive midnight Pandas Timestamp. None means available start.|
|end|DateLike \| None|None|Inclusive date, ISO string or timezone-naive midnight Pandas Timestamp. None means available end.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index_intraday

```python
get_index_intraday(index: 'str | int | InstrumentRef', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, day: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return index observations for the latest session available from the public endpoint. day=None only; selecting a historical session is not supported and raises before HTTP. Equal-time points preserve source order.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|index|str \| int \| InstrumentRef|required|Exact index code (string/int/InstrumentRef) or exact normalized catalog name. No first-match guess.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|day|DateLike \| None|None|Optional explicit single Gregorian/Jalali day; latest intraday index endpoint only supports None.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index_members

```python
get_index_members(index: 'str | int | InstrumentRef', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, as_of: 'DateLike | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

Return current constituent quotes, not historical membership or index weights. as_of is unsupported and raises before HTTP. Quote dates are not membership effective dates.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|index|str \| int \| InstrumentRef|required|Exact index code (string/int/InstrumentRef) or exact normalized catalog name. No first-match guess.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|as_of|DateLike \| None|None|Only None is supported; historical membership raises before HTTP.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index_impact

```python
get_index_impact(*, market: 'Market | str' = <Market.TSE: 'TSE'>, limit: 'int' = 7, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'
```

EXPERIMENTAL: fetch the reported total-market index-effect records and preserve every source field in source_fields. impact_points/unit remain unknown until the live economic mapping is verified. This does not compute index impact or address arbitrary indices.

**Status:** experimental_raw_only

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|market|Market \| str|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|limit|int|7|Requested server output bound; not a coverage guarantee. Index impact other than the reviewed limit 7 is unverified.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** pd.DataFrame
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## watch_market

```python
watch_market(*, interval: 'float' = 10.0, max_updates: 'int | None' = 10, market: 'Market | str | None' = None, include_order_book: 'bool' = False, include_client_types: 'bool' = False, show_traded: 'bool' = False, backend: 'str' = 'auto') -> 'Iterator[pd.DataFrame]'
```

Yield freshly fetched full snapshots with bounded polling, not WebSocket deltas.

A one-second local lower bound is not an exchange rate-limit promise.
max_updates=None opts into indefinite polling. Cancel/close the iterator
or interrupt execution to stop; exceptions propagate, no infinite retry.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|interval|float|10.0|Polling sleep seconds after the previous returned snapshot; local minimum 1 second, not an exchange limit.|
|max_updates|int \| None|10|Maximum yielded snapshots (default 10); None explicitly opts into indefinite polling.|
|market|Market \| str \| None|None|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|include_order_book|bool|False|Add reported depth 1..5 columns with separate provenance; no forward fill.|
|include_client_types|bool|False|Fetch and join a separate bulk response by exact ID; timestamps may be absent/different.|
|show_traded|bool|False|Return only rows with a reported positive trade_count. Unknown is not treated as proof of no trading.|
|backend|str|'auto'|auto/json/legacy; auto uses legacy only after valid empty JSON, not after auth/HTTP/schema errors.|

**Returns:** Iterator[pd.DataFrame]
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError
**Dependencies:** pandas, Python standard library

## get_client_types_many

```python
get_client_types_many(instruments: 'Sequence[InstrumentLike] | pd.Series | pd.Index | np.ndarray', *, day: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, on_error: 'str' = 'raise', policy: 'FetchPolicy | str | None' = None) -> 'BatchFrames'
```

Sequential ordered batch with data/errors/requests tables. Input duplicates
and empty successes have separate request rows. on_error=raise includes
partial_result; collect reports per-item errors without claiming completeness.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|instruments|Sequence[InstrumentLike] \| pd.Series \| pd.Index \| np.ndarray|required|Nonempty ordered list/tuple, Pandas Series/Index or a one-dimensional NumPy array. Duplicates preserved; nulls rejected.|
|day|DateLike \| None|None|Optional explicit single Gregorian/Jalali day; latest intraday index endpoint only supports None.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|on_error|str|'raise'|'raise' stops with partial_result; 'collect' records errors without losing other inputs.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** BatchFrames
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_client_type_history_many

```python
get_client_type_history_many(instruments: 'Sequence[InstrumentLike] | pd.Series | pd.Index | np.ndarray', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, on_error: 'str' = 'raise', policy: 'FetchPolicy | str | None' = None) -> 'BatchFrames'
```

Sequential ordered batch with data/errors/requests tables. Input duplicates
and empty successes have separate request rows. on_error=raise includes
partial_result; collect reports per-item errors without claiming completeness.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|instruments|Sequence[InstrumentLike] \| pd.Series \| pd.Index \| np.ndarray|required|Nonempty ordered list/tuple, Pandas Series/Index or a one-dimensional NumPy array. Duplicates preserved; nulls rejected.|
|start|DateLike \| None|None|Inclusive date, ISO YYYY-MM-DD string or timezone-naive midnight Pandas Timestamp. None means available start.|
|end|DateLike \| None|None|Inclusive date, ISO string or timezone-naive midnight Pandas Timestamp. None means available end.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|on_error|str|'raise'|'raise' stops with partial_result; 'collect' records errors without losing other inputs.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** BatchFrames
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

## get_index_history_many

```python
get_index_history_many(indices: 'Sequence[str | int | InstrumentRef] | pd.Series | pd.Index | np.ndarray', *, market: 'Market | str | None' = <Market.TSE: 'TSE'>, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, on_error: 'str' = 'raise', policy: 'FetchPolicy | str | None' = None) -> 'BatchFrames'
```

Sequential ordered batch with data/errors/requests tables. Input duplicates
and empty successes have separate request rows. on_error=raise includes
partial_result; collect reports per-item errors without claiming completeness.

**Status:** implemented

|Parameter|Type|Default|Meaning|
|---|---|---|---|
|indices|Sequence[str \| int \| InstrumentRef] \| pd.Series \| pd.Index \| np.ndarray|required|Ordered index names/codes, including Series/Index or a one-dimensional array; duplicates preserved.|
|market|Market \| str \| None|<Market.TSE: 'TSE'>|TSE/IFB/BASE enum or documented string. Support depends on endpoint; index/overview support TSE/IFB only. None never certifies historical coverage.|
|start|DateLike \| None|None|Inclusive date, ISO YYYY-MM-DD string or timezone-naive midnight Pandas Timestamp. None means available start.|
|end|DateLike \| None|None|Inclusive date, ISO string or timezone-naive midnight Pandas Timestamp. None means available end.|
|calendar|Calendar|'gregorian'|'gregorian' or 'jalali' for date strings. Python date/Pandas Timestamp always mean Gregorian dates.|
|include_jdate|bool|False|Add a textual Jalali date column. It does not change the primary Gregorian date column.|
|on_error|str|'raise'|'raise' stops with partial_result; 'collect' records errors without losing other inputs.|
|policy|FetchPolicy \| str \| None|None|FetchPolicy, None, or shorthand 'auto'/'online'/'offline'. Offline shorthand does not authorize stale data.|

**Returns:** BatchFrames
**Exceptions:** InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError
**Dependencies:** pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite

# DataFrame schemas

Every schema also carries source/fetch time, row/observation IDs, quality flags, source_fields, cache state and a manifest in attrs["tse_dara"]. Unknown fields are nullable.

## market_watch

Natural key: ('ins_code',)
|Columns|Type|
|---|---|
|ins_code, symbol, name, market, raw_flow, sector_code, instrument_id, instrument_type, currency, quote_unit, quantity_unit, timestamp_kind|string|
|open_price, high_price, low_price, last_price, closing_price, previous_reference_price, volume, turnover, base_volume, shares_outstanding, eps, pe, min_allowed_price, max_allowed_price|Float64 / Decimal for exact|
|trade_count|Int64|
|date|datetime64[ns]|
## market_order_book

Natural key: ('ins_code', 'depth')
|Columns|Type|
|---|---|
|ins_code, symbol, reference_id, currency, quote_unit, quantity_unit, timestamp_kind|string|
|bid_price, ask_price, bid_volume, ask_volume|Float64 / Decimal for exact|
|depth, bid_order_count, ask_order_count|Int64|
|date|datetime64[ns]|
## market_overview

Natural key: ('market',)
|Columns|Type|
|---|---|
|market, state, raw_state, currency, index_unit|string|
|market_value, market_value_base, volume, turnover, index_value, index_change, equal_weight_index_value, equal_weight_index_change|Float64 / Decimal for exact|
|trade_count|Int64|
|date, data_date|datetime64[ns]|
|data_timestamp|datetime64[ns, UTC]|
## client_types

Natural key: ('ins_code', 'date')
|Columns|Type|
|---|---|
|ins_code, symbol, market, currency, quote_unit, quantity_unit, timestamp_kind|string|
|individual_buy_volume, individual_buy_value, individual_sell_volume, individual_sell_value, institutional_buy_volume, institutional_buy_value, institutional_sell_volume, institutional_sell_value, buy_ddd_volume|Float64 / Decimal for exact|
|individual_buy_count, individual_sell_count, institutional_buy_count, institutional_sell_count, buy_ddd_count|Int64|
|date|datetime64[ns]|
## indices

Natural key: ('index_code',)
|Columns|Type|
|---|---|
|index_code, name, market, unit, timestamp_kind|string|
|value, high, low, change, change_percent|Float64 / Decimal for exact|
|source_c1, source_c2, source_c3, source_c4|Int64|
|date|datetime64[ns]|
## index_history

Natural key: ('index_code', 'date')
|Columns|Type|
|---|---|
|index_code, name, market, unit|string|
|value, high, low|Float64 / Decimal for exact|
|date|datetime64[ns]|
## index_intraday

Natural key: ()
|Columns|Type|
|---|---|
|index_code, name, market, unit, timestamp_kind|string|
|value, high, low, change, change_percent|Float64 / Decimal for exact|
|source_position|Int64|
|date|datetime64[ns]|
## index_members

Natural key: ('index_code', 'ins_code')
|Columns|Type|
|---|---|
|index_code, ins_code, symbol, name, market, raw_flow, currency, quote_unit, quantity_unit, timestamp_kind, membership_basis|string|
|open_price, high_price, low_price, last_price, closing_price, previous_reference_price, volume, turnover, shares_outstanding|Float64 / Decimal for exact|
|trade_count|Int64|
|date|datetime64[ns]|
## index_impact

Natural key: ()
|Columns|Type|
|---|---|
|market, ins_code, symbol, name, impact_field, unit|string|
|impact_points|Float64 / Decimal for exact|
|source_position|Int64|
|date|datetime64[ns]|
## sector_summary

Natural key: ('sector_code',)
|Columns|Type|
|---|---|
|sector_code, name|string|
|source_c1, source_c2, source_c3, source_c4|Int64|
## sector_instruments

Natural key: ('sector_code', 'ins_code')
|Columns|Type|
|---|---|
|sector_code, ins_code, symbol, name, market, raw_flow, currency, quote_unit, quantity_unit, timestamp_kind|string|
|open_price, high_price, low_price, last_price, closing_price, previous_reference_price, volume, turnover|Float64 / Decimal for exact|
|trade_count|Int64|
|date|datetime64[ns]|
## key_statistics

Natural key: ('ins_code', 'parameter_code', 'date')
|Columns|Type|
|---|---|
|ins_code, parameter_code, reported_value, unit|string|
|date|datetime64[ns]|
## market_map

Natural key: ('ins_code',)
|Columns|Type|
|---|---|
|ins_code, symbol, name, sector_name, currency, quote_unit, quantity_unit, timestamp_kind|string|
|open_price, high_price, low_price, last_price, closing_price, previous_reference_price, volume, turnover, market_cap, price_change_percent, source_percent|Float64 / Decimal for exact|
|trade_count|Int64|
|date|datetime64[ns]|