tse-dara 0.5.0a1

Data only. Sources reviewed; live endpoints not verified by these synthetic tests.

search_instruments

Search symbols without silently selecting the first match. Returns a typed DataFrame, including for no matches. A limit only limits displayed results; it is not a server pagination parameter.

search_instruments(query: 'str', *, market: 'Market | None' = None, include_inactive: 'bool' = True, limit: 'int | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_instrument

Resolve one symbol or explicit InstrumentRef and verify its identity. Raises AmbiguousInstrumentError for multiple exact matches; use candidates or search_instruments to choose an ins_code. Historical identity and ISIN-only lookup remain unsupported.

get_instrument(instrument: 'InstrumentLike', *, market: 'Market | None' = None, as_of: 'date | None' = None, known_at: 'datetime | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'InstrumentRecord'

Output: InstrumentRecord

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_quote

Fetch the latest report as an immutable Quote with source and retrieval timestamps. A last report may be from a past trading day. Use an explicit offline policy to permit stale cached data; autosave errors are reported separately.

get_quote(instrument: 'InstrumentLike', *, freshness: 'FreshnessPolicy | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'Quote'

Output: Quote

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_price

Return a Decimal price. field is last, closing or previous_reference. Missing price raises MissingValueError and unverified price units raise UnsupportedQuoteUnitError. Use get_quote/get_quote_frame to retain time and unit metadata.

get_price(instrument: 'InstrumentLike', *, field: 'str' = 'last', freshness: 'FreshnessPolicy | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'Decimal'

Output: Decimal

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, MissingValueError, UnsupportedQuoteUnitError

get_quotes

Fetch an ordered batch to a DataFrame. Accepts list/tuple, Series, Index or a 1D NumPy array. Duplicates and input order are preserved. on_error=collect records per-item errors; raise attaches partial_result to BatchDataError. No concurrency is implied.

get_quotes(instruments: 'Sequence[InstrumentLike] | pd.Series | pd.Index | np.ndarray', *, on_error: 'str' = 'raise', freshness: 'FreshnessPolicy | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, BatchDataError

get_history

Raw daily history, ascending and inclusive. No rows are forward-filled. The full available endpoint response is fetched/cached, then filtered locally. ``source`` adjustments, stitched identities and ``as_of`` are reserved but raise explicit errors until their evidence is implemented.

get_history(instrument: 'InstrumentLike', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', adjustment: 'str' = 'none', series: 'str' = 'listing', as_of: 'datetime | None' = None, policy: 'FetchPolicy | str | None' = None, include_jdate: 'bool' = False) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_history_many

Bounded sequential batch. Each input, even repeated/empty, gets a report row.

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

Output: BatchFrames

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError

iter_history

Yield local calendar chunks. The underlying full HTTP response is NOT streamed. Skips chunks without rows; yields one typed empty frame if the whole selected range is empty. Each frame records its actual and chunk range.

iter_history(instrument: 'InstrumentLike', *, start: 'DateLike', end: 'DateLike', calendar: 'Calendar' = 'gregorian', adjustment: 'str' = 'none', chunk_days: 'int' = 366, policy: 'FetchPolicy | str | None' = None, include_jdate: 'bool' = False) -> 'Iterator[pd.DataFrame]'

Output: Iterator[pd.DataFrame]

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

to_gregorian

to_gregorian(value: 'DateLike', *, calendar: 'Calendar' = 'jalali') -> 'date'

Output: date

Errors: InvalidArgumentError

to_jalali

to_jalali(value: 'DateLike') -> 'str'

Output: str

Errors: InvalidArgumentError

capabilities

Return the implemented, conditional and deferred capability matrix. A source-reviewed endpoint is not a live-service guarantee.

capabilities() -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

storage_status

Return in-memory storage counters without querying the database. Queued work is not durable until committed.

storage_status() -> 'StorageStatus'

Output: StorageStatus

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

get_write_receipt

Read the receipt status for this process. Unknown IDs raise UnknownReceiptError. A queued receipt does not prove disk durability.

get_write_receipt(receipt_id: 'str') -> 'WriteReceipt'

Output: WriteReceipt

Errors: UnknownReceiptError

flush

Explicitly wait up to timeout seconds for queued persistence. With raise_on_error=True incomplete or failed storage raises StorageError/StorageFlushTimeout. Normal automatic saving never waits for this call.

flush(*, timeout: 'float' = 5.0, raise_on_error: 'bool' = True) -> 'FlushReport'

Output: FlushReport

Errors: StorageError, StorageFlushTimeout, ConfigurationError

close

Close the default client. Explicitly flush first to require durable writes. The selected configuration is retained; configure() can replace it after close.

close(*, flush_timeout: 'float' = 1.0) -> 'FlushReport'

Output: FlushReport

Errors: ConfigurationError

get_quote_frame

A one-row Pandas quote with the same checks as get_quote; no second HTTP call.

get_quote_frame(instrument: 'InstrumentLike', *, freshness: 'FreshnessPolicy | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_instrument_frame

Resolve exactly one instrument and return its typed one-row DataFrame.

get_instrument_frame(instrument: 'InstrumentLike', *, market: 'Market | None' = None, as_of: 'date | None' = None, known_at: 'datetime | None' = None, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

configure

Configure the lazy module-level client without HTTP or creating a database. Call before using data.get_*; if a default client already exists, close it explicitly with data.close() first. This avoids silently losing queued work or changing the configuration of an in-flight request. Omitted settings use ClientConfig defaults (or the explicitly supplied config).

configure(config: 'ClientConfig | None' = None, *, source: 'str | None' = None, mode: 'str | None' = None, storage: 'bool | None' = None, data_dir: 'str | Path | None' = None, numeric: 'str | None' = None) -> 'ClientConfig'

Output: ClientConfig

Errors: ConfigurationError

get_config

Return immutable default settings without creating a Client or any I/O.

get_config() -> 'ClientConfig'

Output: ClientConfig

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

save

Save a self-describing snapshot; return only after successful commit. ``metadata=False`` omits df.attrs, not structural type/checksum information. MultiIndex/unsupported object values are rejected. No network requests. CSV + sidecar replace is not one filesystem transaction: a crash between replacements is detected by load's SHA256 check, never silently accepted.

save(df: 'pd.DataFrame', path: 'str | Path', *, format: 'str | None' = None, dataset: 'str' = 'user_data', metadata: 'bool' = True, overwrite: 'bool' = False, safe_text: 'bool' = True) -> 'WriteReceipt'

Output: WriteReceipt

Errors: InvalidArgumentError, FileExistsDataError, StorageError, OptionalDependencyError

load

Read a Dara archive and verify its structure/content. This is not a signature. For arbitrary externally-created files use pandas readers, then validate. ``verify=False`` allows deliberate value edits, not code execution or a different schema. CSV still requires its sidecar for dtype restoration.

load(path: 'str | Path', *, format: 'str | None' = None, dataset: 'str' = 'user_data', schema=None, verify: 'bool' = True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, StorageError, OptionalDependencyError

sync_history

Explicit reconciliation into the local history index. full=True rechecks old corrections; overlap_days controls the tail window. wait=True may wait for storage. on_storage_error=report preserves fetched data with failure information; raise demands success. SyncResult.data is only this fetch, not the whole database.

sync_history(instrument: 'InstrumentLike', *, full: 'bool' = False, overlap_days: 'int' = 14, full_refresh_days: 'float' = 7, wait: 'bool' = True, timeout: 'float' = 30.0, on_storage_error: 'str' = 'report') -> 'SyncResult'

Output: SyncResult

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

load_stored_history

Read the versioned local history index; never sends HTTP. Dates are inclusive. as_of is a local observation/commit cutoff, not proof of historical public availability. Raises OfflineDataUnavailableError when no usable indexed data exists.

load_stored_history(instrument: 'InstrumentLike', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, as_of: 'datetime | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: OfflineDataUnavailableError, StorageError, InvalidArgumentError, AmbiguousInstrumentError

history_status

Return per-instrument counts, ranges and latest fetch state from the local index. Explicit disk read; no HTTP. Counts do not certify full market history.

history_status() -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: StorageError

get_history_revisions

Return locally observed economic revisions in the requested inclusive range. This is local evidence, not all revisions ever published by the exchange.

get_history_revisions(instrument: 'InstrumentLike', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: StorageError, OfflineDataUnavailableError, InvalidArgumentError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

reindex_history

Explicitly rebuild missing normalized history from cached responses of previous releases, without HTTP. Existing history is not deleted. Return a dictionary report; durable storage can raise StorageError.

reindex_history() -> 'dict'

Output: dict

Errors: StorageError

schema_info

Return column names, expected dtypes and meanings for an implemented schema. Parameters ---------- schema : str, default 'daily_bars' One of daily_bars, quote, quotes.batch, instruments. numeric : {'analysis', 'exact'}, default 'analysis' Floating nullable columns or Decimal object columns for prices/quantities. Returns ------- pandas.DataFrame column, dtype, required, description. It is a description, not market data.

schema_info(schema: 'str' = 'daily_bars', *, numeric: 'str' = 'analysis') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError

validate_data

Report schema/value issues without changing data or contacting TSETMC. The report columns are severity, rule, column, count, row_positions, message. row_positions are zero-based positions (not possibly duplicated index labels). At most ten example positions are kept per rule. Warnings do not certify or invalidate financial truth. This function is NOT a point-in-time/leakage audit.

validate_data(df: 'pd.DataFrame', *, schema: 'str | None' = None, raise_on_error: 'bool' = False, check_order: 'bool' = True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError

normalize_data

Normalize only present known fields; never invent source/time/zero values. ``columns`` is an explicit old-name -> standard-name mapping. Date strings use the explicitly supplied calendar. Naive real timestamps require timezone. Floating-point identifiers are rejected even when they look integral: original digits may already be lost. Unknown columns are preserved, rows are not dropped, duplicate keys are left for validate_data(), and the input/index are preserved unless sort=True reorders rows. No investment calculation is performed.

normalize_data(df: 'pd.DataFrame', *, schema: 'str' = 'daily_bars', columns: 'Mapping[str, str] | None' = None, calendar: 'Calendar' = 'gregorian', numeric: 'str' = 'analysis', timezone: 'str | None' = None, sort: 'bool' = False) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError

select_columns

Select explicit columns, or the documented 'compact'/'full' presentation. Compact output is a view for users, not a provenance-complete archive. Full metadata is copied, and any removed evidence columns are listed in it. Unknown/duplicate column names raise InvalidArgumentError instead of being ignored.

select_columns(df: 'pd.DataFrame', columns: 'Sequence[str] | str' = 'compact') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError

frame_metadata

Return a deep copy of df.attrs['tse_dara']; absent evidence stays unknown.

frame_metadata(df: 'pd.DataFrame') -> 'dict'

Output: dict

Errors: InvalidArgumentError

api_reference

Return signatures, inputs, outputs, errors and dependencies for this release. name is an optional exact public function/class name. The catalog includes implemented API only; the HTML roadmap has separate not-yet-implemented plans.

api_reference(name: 'str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError

validate

Roadmap-compatible validation entry point. Returns row_id, rule, severity, message and additional grouped diagnostic columns. A grouped issue may have no single row_id; count and row_positions then describe it. strict=True raises DataQualityError with this same report. This verifies a structural contract, not source correctness or completeness.

validate(df: 'pd.DataFrame', *, schema: 'str', strict: 'bool' = True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError

normalize

Roadmap normalization entry point for already canonical column names. source='canonical' is the currently reviewed mapping. Raw external API mappings are not inferred; use normalize_data(columns=...) for an explicit user mapping and then validate it. All unknown sources fail explicitly.

normalize(df: 'pd.DataFrame', *, schema: 'str', source: 'str', strict: 'bool' = True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, UnsupportedCapabilityError

load_sample

Load explicit synthetic data with no database access or real network. Names: daily_prices_v1, quote_v1, market_watch_v1, client_types_v1, indices_v1 and index_history_v1. These are teaching/test values, never current market prices, and they cannot become live data through fallback.

load_sample(name: 'str' = 'daily_prices_v1') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError

get_market_watch

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.

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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_market_order_book

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_market_overview

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_market_map

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_sectors

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_sector_instruments

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_key_statistics

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

get_client_types

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_client_type_history

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.

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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_market_client_types

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_indices

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError

search_indices

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

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_index

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_index_history

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.

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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_index_intraday

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.

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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_index_members

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.

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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_index_impact

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.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

watch_market

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.

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]'

Output: Iterator[pd.DataFrame]

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError

get_client_types_many

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.

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'

Output: BatchFrames

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError

get_client_type_history_many

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.

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'

Output: BatchFrames

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError

get_index_history_many

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.

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'

Output: BatchFrames

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError

Client

Identity, quotes and raw daily history client. Construct freely; close explicitly or use ``with``. Part 3 adds file interchange and local reconciliation; adjustments, analytics and ML remain deferred. ``transport`` is a test/development hook, not a TSETMC authentication mechanism. A Client is not intended for concurrent use from multiple OS threads.

Client(*, config: 'ClientConfig | None' = None, source: 'str | None' = None, mode: 'str | None' = None, storage: 'bool | None' = None, data_dir: 'str | Path | None' = None, numeric: 'str | None' = None, credentials=None, transport: 'httpx.BaseTransport | None' = None, _namespace: 'str' = 'public')

Output: Client

Errors: ConfigurationError, UnsupportedCapabilityError

AsyncClient

Use within one event loop and async context manager. No hidden asyncio.run().

AsyncClient(*, config: 'ClientConfig | None' = None, source: 'str | None' = None, mode: 'str | None' = None, storage: 'bool | None' = None, data_dir: 'str | Path | None' = None, numeric: 'str | None' = None, credentials=None, transport: 'httpx.AsyncBaseTransport | None' = None, _namespace: 'str' = 'public')

Output: AsyncClient

Errors: ConfigurationError, UnsupportedCapabilityError

ClientConfig

ClientConfig(*, source: "Literal['public', 'official']" = 'public', mode: "Literal['auto', 'online', 'offline']" = 'auto', storage: 'StorageConfig | None' = None, network: 'NetworkConfig | None' = None, numeric: "Literal['analysis', 'exact']" = 'analysis', timezone: 'str' = 'Asia/Tehran', strict_schema: 'bool' = True)

ClientConfig(*, source: "Literal['public', 'official']" = 'public', mode: "Literal['auto', 'online', 'offline']" = 'auto', storage: 'StorageConfig | None' = None, network: 'NetworkConfig | None' = None, numeric: "Literal['analysis', 'exact']" = 'analysis', timezone: 'str' = 'Asia/Tehran', strict_schema: 'bool' = True) -> None

Output: None

Errors: ConfigurationError

NetworkConfig

NetworkConfig(*, connect_timeout: 'float' = 5.0, read_timeout: 'float' = 20.0, operation_timeout: 'float' = 60.0, max_concurrency: 'int' = 4, max_retries: 'int' = 2, requests_per_second: 'float' = 0.5, request_budget: 'int' = 100, max_response_bytes: 'int' = 33554432, trust_env: 'bool' = True)

NetworkConfig(*, connect_timeout: 'float' = 5.0, read_timeout: 'float' = 20.0, operation_timeout: 'float' = 60.0, max_concurrency: 'int' = 4, max_retries: 'int' = 2, requests_per_second: 'float' = 0.5, request_budget: 'int' = 100, max_response_bytes: 'int' = 33554432, trust_env: 'bool' = True) -> None

Output: None

Errors: ConfigurationError

StorageConfig

StorageConfig(*, enabled: 'bool' = True, backend: "Literal['sqlite']" = 'sqlite', path: 'str | Path | None' = None, queue_max_jobs: 'int' = 128, queue_max_bytes: 'int' = 67108864, queue_overflow: "Literal['drop_new']" = 'drop_new', read_timeout: 'float' = 0.05, offline_read_timeout: 'float' = 30.0, busy_timeout: 'float' = 0.1, failure_cooldown: 'float' = 60.0, raw_capture: 'bool' = True)

StorageConfig(*, enabled: 'bool' = True, backend: "Literal['sqlite']" = 'sqlite', path: 'str | Path | None' = None, queue_max_jobs: 'int' = 128, queue_max_bytes: 'int' = 67108864, queue_overflow: "Literal['drop_new']" = 'drop_new', read_timeout: 'float' = 0.05, offline_read_timeout: 'float' = 30.0, busy_timeout: 'float' = 0.1, failure_cooldown: 'float' = 60.0, raw_capture: 'bool' = True) -> None

Output: None

Errors: ConfigurationError

FreshnessPolicy

FreshnessPolicy(*, max_age: 'timedelta | None' = None, allow_stale: 'bool' = False, max_stale: 'timedelta | None' = None, max_source_age: 'timedelta | None' = None)

FreshnessPolicy(*, max_age: 'timedelta | None' = None, allow_stale: 'bool' = False, max_stale: 'timedelta | None' = None, max_source_age: 'timedelta | None' = None) -> None

Output: None

Errors: ConfigurationError

FetchPolicy

FetchPolicy(*, mode: "Literal['auto', 'online', 'offline'] | None" = None, freshness: 'FreshnessPolicy | None' = None, coverage: "Literal['raise', 'report']" = 'report', allow_official_offline: 'bool' = False)

FetchPolicy(*, mode: "Literal['auto', 'online', 'offline'] | None" = None, freshness: 'FreshnessPolicy | None' = None, coverage: "Literal['raise', 'report']" = 'report', allow_official_offline: 'bool' = False) -> None

Output: None

Errors: ConfigurationError

get_adjustments

Reported price-adjustment events and price ratios. Reasons and complete corporate-action coverage are unknown; this is not a total-return algorithm.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_share_capital_history

Reported old/new share counts, not legal capital-increase classifications. All observed rows are retained.

get_share_capital_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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_dividends

Dividend history from the legacy text route. Payment/ex dates are not inferred; failed or HTML responses raise.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_adjusted_history

Source-adjusted chart history, separate from raw history. Source method tsetmc_chart_a1; anchor is the last returned date. No total-return or point-in-time guarantee. Missing turnover/count/reference price stay missing.

get_adjusted_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'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_shareholders

Latest reported major shareholders. Empty does not prove that no major holders exist.

get_shareholders(instrument: 'InstrumentLike', *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_shareholder_history

History of one holder of one instrument; holder_id comes from get_shareholders, not the holding_ref. days is 1..3650; date filtering is local.

get_shareholder_history(instrument: 'InstrumentLike', holder_id: 'str | int', *, days: 'int' = 90, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_disclosures

Disclosure metadata linked by TSETMC. Does not download or parse financial-statement attachments. limit is 1..1000; dates filter the returned subset only.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_messages

Reported instrument supervisor messages, with source timestamp and original text.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_trades

Reported executions, current or per explicit calendar day. Same-second trades are not deduplicated. Cancellation remains unknown; only as_reported is supported. Max 31 days by default, configurable up to 366.

get_trades(instrument: 'InstrumentLike', *, day: 'DateLike | None' = None, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, max_days: 'int' = 31, cancellation: 'str' = 'as_reported', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_order_book

Current reported best limits (up to five depths), not a full exchange order book. Missing source timestamps stay missing.

get_order_book(instrument: 'InstrumentLike', *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_order_book_history

Historical best-limit updates. Sequence/reference and source position are preserved. No fill-forward or fictional complete snapshots; empty days do not prove holidays.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_instrument_states

Reported state/price-limit records for one day. No day means the last trading date reported by the quote, not today. Empty is not interpreted as open/unrestricted.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_thresholds

Reported state/price-limit records for one day. No day means the last trading date reported by the quote, not today. Empty is not interpreted as open/unrestricted.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_boards

Board codes from the reviewed reference HTML table. A replaced page raises rather than returning a false empty registry.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_instruments

Current observed watch instrument list only. include_inactive=True and changed_since require a historical registry and raise; suspended instruments may still be in the current watch.

get_instruments(*, market: 'Market | str | None' = None, include_inactive: 'bool' = False, changed_since: 'DateLike | None' = None, backend: 'str' = 'auto', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_funds

Registered funds by category name/code; None explicitly fetches the ten reviewed categories. registration_no is not an ins_code.

get_funds(category: 'str | None' = 'stock', *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_fund

Fund detail as a one-row frame with raw fields retained. Use the registration_no from get_funds.

get_fund(registration_no: 'str | int', *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_fund_nav_history

Reported NAV stats; unit/currency not supplied by source remain unknown, not assumed from stock prices.

get_fund_nav_history(registration_no: 'str | int', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'Calendar' = 'gregorian', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_options

Public option-chain pairs expanded into one row per put/call contract. Underlying filter is optional and local. No option pricing or inferred Greeks.

get_options(underlying: 'InstrumentLike | None' = None, *, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_futures

Current futures snapshot from the separate public tse.ir exchange gateway (not TSETMC CDN). Source must be tse_exchange. Fields with unverified meanings remain in source_fields. No history or commodity-exchange completeness guarantee.

get_futures(*, source: 'str' = 'tse_exchange', policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

history

تاریخچه با رابط ساده و تقویم خودکار محدود.

history(instrument: 'InstrumentLike', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', adjustment: 'str' = 'none', include_jdate: 'bool' = False, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

market

Simple alias for get_market_watch; no financial analysis.

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

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

index_history

Simple index-history alias with explicit auto-calendar policy.

index_history(index: 'str | int', *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', include_jdate: 'bool' = False, market: 'Market | str | None' = <Market.TSE: 'TSE'>, policy: 'FetchPolicy | str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

datasets

List locally stored response families, without HTTP.

datasets() -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

storage_info

Inspect local storage health and file sizes, without HTTP.

storage_info() -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

query

Read locally stored data only. Never a live request; cached results retain time and stale flags.

query(instrument: 'InstrumentLike', *, dataset: 'str' = 'history', start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', include_jdate: 'bool' = False) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

backup

پشتیبان سازگار SQLite با WAL؛ عملیات صریح.

backup(path: 'str | Path', *, overwrite: 'bool' = False, timeout: 'float' = 30.0, flush: 'bool' = True) -> 'dict'

Output: dict

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

download

دریافت گروهی، قابل ادامه و همراه گزارش خطا.

download(symbols, *, dataset: 'str' = 'history', start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', update: 'bool' = True, store: 'bool | None' = None, on_error: 'str' = 'collect', checkpoint_dir: 'str | Path | None' = None, resume: 'bool' = True, resume_max_age: 'float' = 3600.0, include_jdate: 'bool' = False, progress=None, policy: 'FetchPolicy | str | None' = None) -> 'BatchFrames'

Output: BatchFrames(data: DataFrame, requests: DataFrame, errors: DataFrame, manifest: dict)

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

update

Update raw histories with overlap/correction handling. Default resume=False checks anew rather than reusing a job snapshot.

update(symbols, *, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', on_error: 'str' = 'collect', checkpoint_dir: 'str | Path | None' = None, resume: 'bool' = False, progress=None) -> 'BatchFrames'

Output: BatchFrames(data: DataFrame, requests: DataFrame, errors: DataFrame, manifest: dict)

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

download_market

Plan bounded downloads for the current watch universe. dry_run=True performs only watch retrieval; historical universe is not reconstructed.

download_market(*, dataset: 'str' = 'history', market: 'Market | str | None' = None, limit: 'int' = 100, start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', dry_run: 'bool' = True, on_error: 'str' = 'collect', checkpoint_dir: 'str | Path | None' = None) -> 'pd.DataFrame | BatchFrames'

Output: pd.DataFrame (dry_run=True) | BatchFrames (dry_run=False)

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_trades_many

Trades for multiple inputs with explicit errors, not silent dropping.

get_trades_many(instruments, *, start, end=None, calendar='gregorian', include_jdate=False, on_error='collect', policy=None) -> 'BatchFrames'

Output: BatchFrames(data: DataFrame, requests: DataFrame, errors: DataFrame, manifest: dict)

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

get_order_book_updates

Historical best-limit updates, not full snapshots.

get_order_book_updates(instrument, *, start, end=None, calendar='gregorian', include_jdate=False, max_days=31, policy=None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

export

Save a self-describing snapshot; return only after successful commit. ``metadata=False`` omits df.attrs, not structural type/checksum information. MultiIndex/unsupported object values are rejected. No network requests. CSV + sidecar replace is not one filesystem transaction: a crash between replacements is detected by load's SHA256 check, never silently accepted.

export(df: 'pd.DataFrame', path: 'str | Path', *, format: 'str | None' = None, dataset: 'str' = 'user_data', metadata: 'bool' = True, overwrite: 'bool' = False, safe_text: 'bool' = True) -> 'WriteReceipt'

Output: WriteReceipt

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

export_many

Export separate files with safe deterministic filenames; no path traversal. Returns one receipt/error row per group and format. Does not delete other files.

export_many(value, directory, *, formats=('csv',), group_by='symbol', overwrite=False, on_error='collect') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

download_many

Ordered data job with reports and opt-in disk checkpoints. Uses existing bounded network budget; partial success is explicit.

download_many(symbols, *, dataset: 'str' = 'history', start: 'DateLike | None' = None, end: 'DateLike | None' = None, calendar: 'str' = 'auto', update: 'bool' = True, store: 'bool | None' = None, on_error: 'str' = 'collect', checkpoint_dir: 'str | Path | None' = None, resume: 'bool' = True, resume_max_age: 'float' = 3600.0, include_jdate: 'bool' = False, progress=None, policy: 'FetchPolicy | str | None' = None) -> 'BatchFrames'

Output: BatchFrames(data: DataFrame, requests: DataFrame, errors: DataFrame, manifest: dict)

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

setup

تنظیم ساده ارتباط بدون تغییر پنهانی تنظیمات امنیتی.

setup(*, network='environment', allow_direct=False, probe=False, storage=None, data_dir=None, mode=None, numeric=None) -> 'ClientConfig'

Output: ClientConfig

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

check_connection

Probe one reviewed small endpoint with explicit connection profiles. network: environment/direct/auto. auto tries direct ONLY when allow_direct=True. Does not alter configuration, disable certificate validation, or expose proxy URLs.

check_connection(*, network='environment', allow_direct=False, timeout=10.0) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError

diagnose

Version/dependency report without network by default; no credentials or proxy URLs.

diagnose(*, live=False, network='environment', allow_direct=False) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

to_pandas

Obtain a caller-owned DataFrame; no automatic import of optional engines. Supports DataFrame, a Dara object with to_frame(), records, or BatchFrames.data. Does not invent provenance for external data.

to_pandas(value, *, copy=True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

set_date_index

Use a date or (ins_code,date) index, preserving identifier strings. Multi-instrument frames automatically retain ins_code in the index.

set_date_index(df: 'pd.DataFrame', *, column='date', calendar='gregorian', by=None, sort=True, verify_unique=True) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

select

Filter without mutating input. Omitted columns retain all evidence.

select(df: 'pd.DataFrame', columns=None, *, symbols=None, start=None, end=None, calendar='auto', date_column='date') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

concat

Concatenate schema-compatible tables, preserving component provenance. Unknown schema remains unknown. Raw and adjusted data are never mixed silently.

concat(frames: 'Sequence[pd.DataFrame]', *, verify_keys=None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

coverage

پوشش مشاهده‌شده؛ نه تضمین کمال تاریخچه.

coverage(df: 'pd.DataFrame', *, expected_sessions=None, start=None, end=None, calendar='auto') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

missing_sessions

Compare to caller-supplied sessions. Missing means no record, not a holiday or halt.

missing_sessions(df: 'pd.DataFrame', *, expected_sessions, date_column='date') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

compare_sources

Compare two supplied tables without fetching sources or replacing values. Currency/adjustment mismatch raises. Differences are evidence, not a verdict.

compare_sources(left: 'pd.DataFrame', right: 'pd.DataFrame', *, keys=('ins_code', 'date'), columns=None, atol=0.0, rtol=0.0) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

examples

Runnable usage snippets. Network examples are labeled; no snippet is executed.

examples(name: 'str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

help

Persian-aware API catalog, returned as a DataFrame without printing or network.

help(name: 'str | None' = None) -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)

columns

Alias for schema_info; no duplicate column registry.

columns(schema: 'str' = 'daily_bars', *, numeric='analysis') -> 'pd.DataFrame'

Output: pd.DataFrame

Errors: InvalidArgumentError, DataQualityError, StorageError (explicit I/O)