راهنمای شروع

tse-dara — نسخه یکپارچه 0.3.1a1

دامنه این تحویل

این نسخه برای تثبیت و ساده‌سازی بخش داده موجود است، نه تکمیل همه سرویس‌های نقشه راه. هیچ الگوریتم تحلیل، اندیکاتور یا یادگیری ماشین اضافه نشده است. قابلیت‌های قیمت، تاریخچه خام، دریافت گروهی، ذخیره خودکار، بازیابی آفلاین، اصلاحات تاریخچه و خروجی فایل‌های قسمت‌های اول تا سوم حفظ شده‌اند. اصلاح Windows برای fsync نیز محفوظ است.

سند اصلی ارسالی در docs/design_v0_2/USER_SUPPLIED_REPORT.html بدون تغییر نگهداری شده است. docs/ROADMAP_REVIEW_FA.md طرح را با پیاده‌سازی واقعی مقایسه می‌کند. سند طراحی پیشین، به‌تنهایی مدرک پیاده‌سازی نیست.

نصب یک‌باره یا ارتقا

پوشه tse-dara این ZIP را در محل دلخواه استخراج کن؛ برای جلوگیری از باقی‌ماندن فایل نصب قدیمی، از پوشه تمیزِ استخراج‌شده استفاده کن. محیط پایتون و پایگاه داده قبلی را حذف نکن.

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

نصاب فقط Wheel همین بسته را نصب می‌کند. برای قابلیت‌های Excel و Parquet و Notebook، وابستگی‌های اختیاری را در همان مرحله درخواست می‌کند. نصب کاملاً آفلاین نیست؛ اگر وابستگی‌ای موجود نباشد، اینترنت لازم است. برای نصب فقط هسته: python install.py --core-only.

نسخه عمومی PyPI در این تحویل منتشر نشده است. از نام بسته به‌تنهایی برای نصب استفاده نکن. پس از نصب Kernel ژوپیتر را Restart کن و سپس بررسی کن:

import sys
import tse_dara
print(sys.executable)
print(tse_dara.__version__)
print(tse_dara.__file__)

نسخه باید 0.3.1a1 باشد. تغییر نسخه به حذف یا مهاجرت پایگاه SQLite قبلی نیاز ندارد.

تغییرهای اصلی

• get_quotes() و get_history_many() علاوه بر list و tuple، ورودی pandas.Series، pandas.Index و آرایه یک‌بعدی NumPy می‌پذیرند. ترتیب و تکرار ورودی حفظ می‌شود. null، جدول دوبعدی، مجموعه بی‌ترتیب و شناسه عددیِ مبهم پیش از درخواست شبکه رد می‌شوند.
• get_quote_frame() و get_instrument_frame() مستقیماً DataFrame می‌دهند. get_quote() همچنان مدل Quote و get_price() همچنان Decimal می‌دهد؛ رفتار قدیمی عوض نشده است.
• Client(numeric="exact") میان‌بری برای تنظیم پروفایل عددی است. در حالت معمول جدول‌ها Float64/Int64 nullable دارند و شناسه‌ها رشته باقی می‌مانند.
• FetchPolicy.offline(allow_stale=True) استفاده صریح از کش قدیمی را ساده می‌کند. policy="offline" نیز اکنون پذیرفته می‌شود، اما اجازه استفاده از داده منقضی را خودکار صادر نمی‌کند.
• FetchPolicy.fresh() کش را برای درخواست تازه کنار می‌گذارد. این با policy="online" متفاوت است؛ حالت online ممکن است کش تازه را استفاده کند.
• تاریخ‌های pd.Timestamp فقط اگر نیمه‌شب و بدون منطقه زمانی باشند در ورودی تاریخ روزانه پذیرفته می‌شوند. تقویم این شیء همیشه میلادی است؛ رشته شمسی نیازمند calendar="jalali" است.
• زمان‌های ستون‌های مرکزی به datetime64[ns, UTC] یکدست شده‌اند. این تغییر، اختلاف پیش‌فرض دقت زمانی میان نسخه‌های Pandas را کم می‌کند؛ به معنی آزمون عملی همه نسخه‌ها نیست.
• حفظ نوع رشته هنگام ذخیره و بازیابی دقیق‌تر شده و ورودی غلط مسیر یا قالب، خطای عمومی قابل فهم کتابخانه می‌دهد.
• مرجع امضای واقعی توابع داخل بسته و از طریق data.api_reference() در دسترس است.

نمونه ساده و بدون تغییر به کد قدیمی

from tse_dara import data

price = data.get_price("فولاد")
quote_df = data.get_quote_frame("فولاد")
history = data.get_history("فولاد", include_jdate=True)

برای نمایش خلوت‌تر بدون تغییر جدول اصلی:

display(data.select_columns(history, "compact"))

نمای compact بعضی ستون‌های شناسنامه را حذف می‌کند و در متادیتا این موضوع را اعلام می‌کند. برای آرشیو کامل، جدول اصلی را ذخیره کن؛ نمای خلوت جای مدرک منشأ داده نیست.

تنظیمات ساده پیش از اولین دریافت

from tse_dara import data

data.configure(
    data_dir=r"G:\My progect\Python\TSE\dara-data",
    numeric="analysis",
    storage=True,
)

configure فایل یا شبکه ایجاد نمی‌کند. اگر قبلاً از توابع مستقیم data استفاده کرده‌ای، ابتدا report = data.close() را اجرا و تکمیل ذخیره را بررسی کن؛ سپس تنظیمات جدید را اعمال کن. مسیر جدید، اطلاعات مسیر قدیمی را خودکار جابه‌جا نمی‌کند. تغییر تنظیمات Client مستقل، کلاینت‌های دیگر را عوض نمی‌کند.

دریافت گروهی با Pandas

import pandas as pd
from tse_dara import data

symbols = pd.Series(["فولاد", "شستا", "فولاد"], dtype="string")
quotes = data.get_quotes(symbols, on_error="collect")
batch = data.get_history_many(symbols, on_error="collect")
display(quotes)
display(batch.requests)
display(batch.errors)

ورودی تکراری، سطر/گزارش مستقل دارد. برای تاریخچه گروهی، batch.data جدول داده و batch.errors جدول خطاهاست. on_error="collect" اجازه انتخاب تصادفی نماد مبهم را نمی‌دهد.

آفلاین و داده قدیمی

from tse_dara.data import Client, FetchPolicy

with Client() as client:
    quote = client.get_quote(
        "فولاد",
        policy=FetchPolicy.offline(allow_stale=True),
    )
    print(quote.last_price, quote.trade_date)
    print(quote.meta.quality_flags)

این دستور اینترنت ندارد، اما باید قبلاً پاسخ لازم در همین مسیر و همین فضای کش ذخیره شده باشد. stale_cached_response و StaleDataWarning خطای برنامه نیستند؛ می‌گویند داده قدیمی است. تاریخ منبع با زمان دریافت داده تفاوت دارد. قیمت آفلاین به قیمت لحظه‌ای تبدیل نمی‌شود.

کار با جدول و کنترل کیفیت

schema = data.schema_info("daily_bars")
issues = data.validate_data(history)
metadata = data.frame_metadata(history)

display(schema)
display(issues)

گزارش خالی یعنی قواعد ساختاری اجراشده ایرادی پیدا نکرده‌اند، نه اینکه داده بورس از نظر اقتصادی یا تاریخی قطعاً کامل است. این ابزار آزمون نشت اطلاعات آینده یا تحلیل سرمایه‌گذاری نیست.

برای تبدیل جدول خارجی، نام‌ها را خودت صریح تعیین کن:

normalized = data.normalize_data(
    external_df,
    columns={"نماد": "symbol", "تاریخ": "date", "پایانی": "closing_price"},
    calendar="jalali",
)

ستون‌های ناشناخته و رکوردها حفظ می‌شوند. مقدار گمشده پر نمی‌شود؛ شناسه float به‌دروغ بازیابی نمی‌شود؛ سطر تکراری حذف و قیمت منفی بریده نمی‌شود. وجود نقص را با validate_data() بررسی کن. برای timestamp بدون timezone، پارامتر timezone لازم است.

ذخیره

data.save(history, "folad.csv", overwrite=True)
restored = data.load("folad.csv")

CSV به فایل همراه .csv.dara.json نیاز دارد. Excel و Parquet و SQLite خروجی نیز شناسنامه دارند. data.load() خواننده آرشیو Dara است، نه مفسر خودکار فایل دلخواه؛ فایل خارجی را با Pandas بخوان و سپس با نگاشت صریح عادی‌سازی کن.

شکست ذخیره خودکار، نتیجه معتبر دریافت را متوقف نمی‌کند. اما save/load/flush عملیات صریح هستند و شکست را اعلام می‌کنند. صف حافظه، دوام روی دیسک نیست.

از کدام دفترچه شروع کنیم؟

10_data_usability_offline.ipynb: مثال کامل امکانات ساده‌شده با داده مصنوعی.

11_pandas_validation.ipynb: نمونه کنترل نوع، نگاشت ستون، خطاها و حفظ ورودی.

12_data_review_live.ipynb: آزمون اختیاری روی سرور واقعی؛ پیش‌فرض دریافت زنده خاموش است.

هر ۹ دفترچه قبلی حفظ شده‌اند. دفترچه‌های نمونه قیمت واقعی بازار نشان نمی‌دهند و کش نمونه از کش واقعی جداست.

هنوز آماده نیست

فهرست کامل و تاریخی تمام ابزارها، اتصال شناسه‌های قدیمی، دریافت بر اساس ISIN، تعدیل تأییدشده، API رسمی دارای حساب، دیده‌بان، شاخص‌ها، حقیقی‌حقوقی، مظنه، ریزمعاملات، صندوق‌ها و اطلاعیه‌ها هنوز به عنوان قابلیت‌های کامل در این نسخه عرضه نشده‌اند. مرحله بعد پیشنهادی، خانواده داده‌های بازار P08 پس از تثبیت آزمون‌های همین نسخه است.

توابع تحلیل و هوش مصنوعی بنا به درخواست فعلی اضافه نشده‌اند. پرونده اصلی طراحی آن‌ها به‌عنوان سابقه باقی مانده، اما وابستگی ML نصب نمی‌شود.

آزمون و حدود تأیید

آمار دقیق و محیط آزمون نهایی در reports/review_031/VERIFICATION.json ثبت می‌شود. آزمون‌های خودکار شبکه واقعی را مسدود می‌کنند. نبود خطا در نمونه‌های ساختگی، سلامت همیشگی API بورس را ثابت نمی‌کند. اگر آزمون Pandas 3، Windows یا Parquet اجرا نشده باشد، در گزارش صریحاً اجرا‌نشده درج می‌شود.

بازبینی نقشه راه

بازبینی سند معماری و برنامه تکمیل بخش داده

نسخه کد این تحویل: 0.3.1a1 — مبنا: بسته یکپارچه 0.3.0a2 و فایل HTML معماری نسخه ۰٫۲ که کاربر فرستاد.

نتیجه اصلی

سند ارسالی، صریحاً «طرح پیشنهادی؛ نه بسته پیاده‌سازی‌شده» است. بنابراین وجود ۱۲۷ قرارداد در سند به معنی وجود ۱۲۷ تابع آماده در بسته نیست. این نسخه به درخواست کاربر، تحلیل و هوش مصنوعی را گسترش نمی‌دهد. تمرکز آن بستن شکاف‌های تجربه کاربر و Pandas در قابلیت‌های داده‌ای است که قبلاً اجرا شده‌اند.

مبنای فعلی کتابخانه قیمت، هویت، تاریخچه خام، ذخیره و بازیابی و همگام‌سازی محلی است. خانواده‌های دیده‌بان، شاخص، حقیقی‌حقوقی، ریزمعاملات، مالکیت و صندوق در سند برنامه دارند، اما هنوز همگی پیاده‌سازی نشده‌اند. این تحویل ادعای تکمیل کل بخش data نقشه راه را ندارد.

آنچه از سند حفظ شد

بخش ۶ معماری و قواعد Pandas: خروجی جدول مستقیم DataFrame، شناسه رشته‌ای، تعداد صحیح nullable، قیمت تحلیل‌پذیر nullable، timestamp دارای UTC و شناسنامه داده. داده ناموجود صفر نشده و داده کاربر بدون درخواست تغییر نمی‌کند.

بخش ۷ و ذخیره‌سازی: تحویل نتیجه معتبر مستقل از موفقیت نوشتن خودکار است. queue در حافظه با دوام روی دیسک متفاوت است. save و flush صریح حق دارند خطا بدهند.

بخش ۸ سیاست دسترسی: خواندن آفلاین شبکه ندارد؛ قیمت کهنه بدون اجازه صریح جای قیمت تازه معرفی نمی‌شود. انتخاب حالت ساده نباید این قاعده را تضعیف کند.

بخش ۱۰ دو رابط اجرا: Client و AsyncClient منطق پردازش یکسان دارند. برای نمونه، افزودن پشتیبانی Series در هر دو اجرا و با آزمون مشترک انجام شده، نه با تبدیل Async به asyncio.run در ژوپیتر.

مرز هویت و اطلاعات مالی: شناسه صفر در پاسخ قیمت فقط همان حالت ثبت‌شده سرویس قیمت است؛ شناسه متناقض و نماد مبهم همچنان خطاست. اتصال نماد قدیمی و جدید یا تعدیل بی‌روش، با ظاهر کاربرپسند توجیه نمی‌شود.

اصلاح‌ها و افزوده‌های این نسخه

این نام‌های کمکی افزوده شده‌اند تا اصل قراردادهای سند قابل استفاده شود؛ همه آن‌ها عیناً در سند اولیه نام‌گذاری نشده بودند. فایل BLUEPRINT_DATA_COVERAGE.json تفاوت نام و دامنه را نشان می‌دهد.

مرز ابزارهای کنترل کیفیت

validate با قرارداد C071 هم‌راستا است: خروجی شامل row_id، rule، severity و message است و strict=True روی خطای ساختاری استثنا می‌دهد. در خطای گروهی، row_id یگانه ممکن است خالی باشد؛ count و نمونه موقعیت‌های سطر، دامنه خطا را توضیح می‌دهند. گزارش، کنترل کیفیت منبع یا نشت آینده را تضمین نمی‌کند.

normalize تنها نگاشت source="canonical" را عرضه می‌کند. منبع خام ناشناخته یا نگاشت حدسی به خطا منتهی می‌شود. normalize_data نگاشت دلخواه و صریح نام ستون را می‌پذیرد، اما منشأ داده خارجی را تأیید نمی‌کند.

frame_metadata نسخه مستقل دیکشنری متادیتا را برمی‌گرداند؛ معادل کامل مدل FrameManifest طرح نیست. هیچ بازیابی جادویی شناسنامه پس از عملیات دلخواه Pandas ادعا نشده است.

تکلیف مراحل بعدی، بدون افزودن تحلیل و هوش مصنوعی

P07.2 تا P07.6، ساخت کندل تحلیلی P09.4، نسبت‌های بنیادی P10.5 و بخش مدل‌سازی P11 فعلاً کنار گذاشته شده‌اند. این کنارگذاشتن مطابق درخواست فعلی است، نه حذف از تاریخچه طرح. ثبت زمان و منشأ داده در data حفظ می‌شود، چون کیفیت داده مستقل از داشتن مدل هوش مصنوعی اهمیت دارد.

قراردادهای هنوز محدود یا پیاده‌سازی‌نشده

get_instrument برای ISIN مستقل یا هویت تاریخی کامل آماده نیست. get_history برای adjustment='source'، سری متصل continuous_verified و بازسازی آنلاین as_of خطای صریح دارد. iter_history قطعه‌بندی محلی پاسخ کامل است، نه stream نامحدود شبکه. load_stored_history(as_of=...) انتخاب بر اساس شواهد محلی دریافت/ثبت است، نه اثبات نسخه در دسترس بازار در گذشته.

افزودن یک تابع نمایشی که فقط NotImplementedError بدهد، تکمیل قابلیت محسوب نمی‌شود. توابع جدید در مرجع runtime فقط در صورت داشتن پیاده‌سازی واقعی درج می‌شوند؛ محدودیت گزینه‌های همان تابع نیز کنار آن‌ها نوشته می‌شود.

روش آزمون و دامنه اطمینان

تغییرهای موجود با پاسخ‌های مصنوعی، شبکه مسدود، آزمون حفظ dtype، roundtrip فایل، ورودی‌های گروهی Pandas، سیاست آفلاین، برابری Sync/Async و عدم تغییر داده ورودی سنجیده می‌شوند. اصلاح Windows fsync از نسخه قبلی حفظ و آزمون آن تکرار می‌شود. هیچ آماری از گزارش‌های قدیمی به‌عنوان نتیجه آزمون این نسخه معرفی نمی‌شود.

فایل workflow ماتریس Windows/Linux و Python 3.12 تا 3.14 در بسته وجود دارد، اما وجود workflow به معنی اجرای موفق آن در GitHub نیست. نتیجه همین محیط در گزارش جاری جداگانه ثبت می‌شود. Parquet و Pandas 3 اگر نصب‌پذیر نباشند، با عبارت آزموده‌نشده معرفی می‌شوند.

تصمیم انتشار

این بسته 0.3.1a1 است: ارتقای آزمایشیِ رابط داده، نه ادعای پایداری 1.0 و نه وعده پوشش همه APIهای بورس. یک پوشه و یک Wheel دارد. کتابخانه و فایل‌های داده قبلی نباید دستی حذف شوند. داده‌های SQLite قالب تازه‌ای پیدا نکرده‌اند؛ این تغییر مهاجرت یا حذف داده لازم ندارد.

مرجع توابع موجود

مرجع فارسی رابط اجرایی بخش داده

نسخه کد: 0.3.1a1

این مرجع از امضاهای واقعی فایل‌های کد ساخته شده است. وجود پارامتر رزرو به معنی پشتیبانی از آن گزینه نیست. جدول پوشش نقشه راه، جدا از امکانات اجرایی نگهداری می‌شود. نمادها و اعداد مثال‌های آفلاین مصنوعی‌اند. کنترل ساختار جدول، تضمین صحت اقتصادی یا کفایت آن برای بازآزمایی تاریخی نیست.

قواعد مشترک

تابع‌های جدولی DataFrame هستند؛ Quote و Decimal خروجی‌های غیرجدولی ثابت‌اند. خطای ذخیره خودکار، دریافت معتبر را باطل نمی‌کند؛ save/load/flush عملیات صریح‌اند. رابط عادی بدون await و AsyncClient با await است.

search_instruments

جست‌وجوی نماد و برگرداندن جدول نتایج؛ بدون انتخاب حدسی اولین نتیجه.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

get_instrument

حل هویت یکتای نماد یا شناسه صریح؛ نتیجه مبهم خطاست.

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

خروجی: InstrumentRecord استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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_quote

گزارش قیمت با زمان، واحد و شناسنامه؛ مستقل از تاریخچه.

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

خروجی: Quote استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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_price

دریافت یک قیمت Decimal؛ برای حفظ زمان و واحد از get_quote استفاده شود.

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

خروجی: Decimal استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, MissingValueError, UnsupportedQuoteUnitError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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_quotes

قیمت چند نماد با حفظ ترتیب ورودی و گزارش خطای هر مورد.

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'

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, BatchDataError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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_history

تاریخچه روزانه خام یک شناسه در قالب DataFrame مرتب‌شده.

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'

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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_many

تاریخچه چند نماد در BatchFrames با جدول داده، درخواست‌ها و خطاها.

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'

خروجی: BatchFrames استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError, BatchDataError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Bounded sequential batch. Each input, even repeated/empty, gets a report row.

iter_history

تقسیم محلی پاسخ تاریخچه به بازه‌های کوچک؛ نه صفحه‌بندی یا stream شبکه.

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

خروجی: Iterator[pd.DataFrame] استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

to_gregorian

تبدیل تاریخ مطابق قرارداد date و تقویم صریح.

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

خروجی: date استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring:

to_jalali

تبدیل تاریخ مطابق قرارداد date و تقویم صریح.

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

خروجی: str استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring:

capabilities

نمایش وضعیت قابلیت‌های همین نسخه؛ بدون شبکه یا ساخت کلاینت.

capabilities() -> 'pd.DataFrame'

خروجی: pd.DataFrame استثناهای اصلی: وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Return the implemented, conditional and deferred capability matrix. A source-reviewed endpoint is not a live-service guarantee.

storage_status

وضعیت ذخیره خودکار؛ وابسته به موفقیت دریافت قیمت نیست.

storage_status() -> 'StorageStatus'

خروجی: StorageStatus استثناهای اصلی: وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Return in-memory storage counters without querying the database. Queued work is not durable until committed.

get_write_receipt

خواندن آخرین وضعیت رسید نوشتن در این فرایند.

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

خروجی: WriteReceipt استثناهای اصلی: UnknownReceiptError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Read the receipt status for this process. Unknown IDs raise UnknownReceiptError. A queued receipt does not prove disk durability.

flush

انتظار محدود برای ثبت صف؛ queued با ذخیره قطعی یکسان نیست.

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

خروجی: FlushReport استثناهای اصلی: StorageError, StorageFlushTimeout, ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

close

بستن منابع با مهلت تخلیه صف؛ گزارش complete بررسی شود.

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

خروجی: FlushReport استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: Close the default client. Explicitly flush first to require durable writes.

The selected configuration is retained; configure() can replace it after close.

get_quote_frame

گزارش قیمت تک‌ردیفی Pandas همراه زمان و واحد.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: A one-row Pandas quote with the same checks as get_quote; no second HTTP call.

get_instrument_frame

همان شناسایی معتبر ابزار در قالب 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'

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Resolve exactly one instrument and return its typed one-row DataFrame.

configure

تنظیم کلاینت پیش‌فرض پیش از اولین دریافت؛ بدون شبکه و ساخت پایگاه.

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'

خروجی: ClientConfig استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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).

get_config

خواندن تنظیمات فعلی بدون ساخت کلاینت یا دسترسی به شبکه.

get_config() -> 'ClientConfig'

خروجی: ClientConfig استثناهای اصلی: وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: Return immutable default settings without creating a Client or any I/O.

save

خروجی صریح CSV/Excel/Parquet/SQLite همراه ساختار بازیابی؛ شکست ذخیره خطاست.

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'

خروجی: WriteReceipt استثناهای اصلی: InvalidArgumentError, FileExistsDataError, StorageError, OptionalDependencyError وابستگی‌ها: pandas, Python standard library, openpyxl only for Excel, pyarrow only for Parquet, sqlite3 for SQLite همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

load

بازیابی آرشیو Dara؛ معادل خواننده عمومی هر فایل خارجی نیست.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, StorageError, OptionalDependencyError وابستگی‌ها: pandas, Python standard library, openpyxl only for Excel, pyarrow only for Parquet, sqlite3 for SQLite همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

sync_history

همگام‌سازی صریح تاریخچه با بازبینی انتهایی/کامل و گزارش مستقل ذخیره.

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'

خروجی: SyncResult استثناهای اصلی: InvalidArgumentError, NetworkError, ApiError, SchemaMismatchError, DataQualityError, UnknownInstrumentError, AmbiguousInstrumentError, StaleDataError, OfflineDataUnavailableError وابستگی‌ها: pandas, Python standard library, HTTPX for network, platformdirs, tzdata, optional best-effort SQLite همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

load_stored_history

خواندن تاریخچه ذخیره‌شده از SQLite بدون درخواست بورس.

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'

خروجی: pd.DataFrame استثناهای اصلی: OfflineDataUnavailableError, StorageError, InvalidArgumentError, AmbiguousInstrumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

history_status

جدول وضعیت و دامنه تاریخچه ثبت‌شده محلی.

history_status() -> 'pd.DataFrame'

خروجی: pd.DataFrame استثناهای اصلی: StorageError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

get_history_revisions

بازخوانی نسخه‌های ثبت‌شده رکوردهای تاریخچه.

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

خروجی: pd.DataFrame استثناهای اصلی: StorageError, OfflineDataUnavailableError, InvalidArgumentError, UnsupportedCapabilityError, PointInTimeUnavailableError, CoverageError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: Return locally observed economic revisions in the requested inclusive range. This is local evidence, not all revisions ever published by the exchange.

reindex_history

فهرست‌سازی تاریخچه پاسخ‌های قبلاً ذخیره‌شده؛ بدون دریافت مجدد اینترنتی.

reindex_history() -> 'dict'

خروجی: dict استثناهای اصلی: StorageError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: دارد؛ همان معنا و نوع خروجی. عملیات بدون I/O مانند capabilities همگام‌اند. شرح دقیق اجرایی از docstring: 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.

schema_info

نام، نوع، الزام و معنای ستون‌های شمای پیاده‌سازی‌شده.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

validate_data

گزارش ساختار و مقادیر مسئله‌دار؛ نه تأیید اقتصادی منبع یا کشف جامع نشت آینده.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, DataQualityError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

normalize_data

عادی‌سازی محلی انواع و نام‌های صریح؛ بدون حذف، پرکردن یا ایجاد داده مالی حدسی.

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'

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

select_columns

انتخاب کنترل‌شده ستون‌های نمایشی یا صریح، بدون تغییر ورودی.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

frame_metadata

نسخه مستقل اطلاعات df.attrs؛ نبود اطلاعات به unknown تبدیل می‌شود.

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

خروجی: dict استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: Return a deep copy of df.attrs['tse_dara']; absent evidence stays unknown.

api_reference

مرجع قابل جست‌وجوی توابع پیاده‌سازی‌شده از داخل پایتون.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

validate

ورودی سازگار با نام قرارداد نقشه راه؛ strict=True برای خطای اعتبارسنجی.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, DataQualityError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

normalize

نام قرارداد نقشه راه؛ در این نسخه فقط source=canonical، نه نگاشت خودکار APIهای دیگر.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError, DataQualityError, UnsupportedCapabilityError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

load_sample

داده مصنوعی آموزشی با نشانه synthetic؛ بدون HTTP واقعی و بدون SQLite.

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

خروجی: pd.DataFrame استثناهای اصلی: InvalidArgumentError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: Load explicit synthetic data with no database access or real network.

Names: daily_prices_v1 and quote_v1. These are teaching/test values, never current market prices, and they cannot become live data through fallback.

Client

کلاینت عادی؛ ساخت آن درخواست شبکه نمی‌فرستد. برای کاربرد معمول نیاز به await نیست.

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

خروجی: Client استثناهای اصلی: ConfigurationError, UnsupportedCapabilityError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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.

AsyncClient

کلاینت Async بومی؛ مدل‌ها و parser با رابط عادی مشترک‌اند.

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

خروجی: AsyncClient استثناهای اصلی: ConfigurationError, UnsupportedCapabilityError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: Use within one event loop and async context manager. No hidden asyncio.run().

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) -> None

خروجی: ClientConfig استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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)

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' = 8388608, trust_env: 'bool' = True) -> None

خروجی: NetworkConfig استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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' = 8388608, trust_env: 'bool' = True)

StorageConfig

تنظیمات صف و SQLite بهترین‌تلاش؛ خرابی ذخیره خودکار دریافت را باطل نمی‌کند.

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

خروجی: StorageConfig استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: 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)

FreshnessPolicy

سیاست سن پاسخ و سن منبع؛ اجازه داده قدیمی باید صریح باشد.

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

خروجی: FreshnessPolicy استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: FreshnessPolicy(*, max_age: 'timedelta | None' = None, allow_stale: 'bool' = False, max_stale: 'timedelta | None' = None, max_source_age: 'timedelta | None' = None)

FetchPolicy

سیاست دریافت همان فراخوانی؛ mode، freshness و coverage.

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

خروجی: FetchPolicy استثناهای اصلی: ConfigurationError وابستگی‌ها: pandas, Python standard library همتای AsyncClient: ندارد/نیازی نیست؛ تابع محلی یا نوع تنظیمات است. شرح دقیق اجرایی از docstring: FetchPolicy(*, mode: "Literal['auto', 'online', 'offline'] | None" = None, freshness: 'FreshnessPolicy | None' = None, coverage: "Literal['raise', 'report']" = 'report', allow_official_offline: 'bool' = False)

متدهای کمکی نوع‌ها

این متدها برخلاف getterهای شبکه‌ای، خودشان داده بازار دریافت نمی‌کنند.

FetchPolicy.offline

ساخت سیاست آفلاین؛ allow_stale=False پیش‌فرض ایمن است.

FetchPolicy.offline(*, allow_stale: 'bool' = False, max_stale: 'timedelta | None' = None, coverage: "Literal['raise', 'report']" = 'report') -> 'FetchPolicy'

FetchPolicy.fresh

ساخت سیاست دریافت تازه با max_age=0 و بدون fallback قدیمی.

FetchPolicy.fresh(*, coverage: "Literal['raise', 'report']" = 'report') -> 'FetchPolicy'

InstrumentRef.by_ins_code

ساخت مرجع صریح شناسه داخلیِ رشته‌ای.

InstrumentRef.by_ins_code(value: 'str', *, market: 'Market | None' = None) -> 'InstrumentRef'

InstrumentRef.by_symbol

ساخت مرجع صریح نام نماد.

InstrumentRef.by_symbol(value: 'str', *, market: 'Market | None' = None) -> 'InstrumentRef'

InstrumentRef.by_isin

ساخت نوع مرجع ISIN؛ حل شبکه‌ای ISIN هنوز پشتیبانی نشده است.

InstrumentRef.by_isin(value: 'str', *, market: 'Market | None' = None) -> 'InstrumentRef'

InstrumentRecord.to_frame

تبدیل اطلاعات هویتی به DataFrame، بدون شبکه.

InstrumentRecord.to_frame(self) -> 'pd.DataFrame'

InstrumentRecord.to_ref

ساخت مرجع دقیق از شناسه ابزار دریافت‌شده.

InstrumentRecord.to_ref(self) -> 'InstrumentRef'

Quote.to_frame

تبدیل Quote به DataFrame با numeric مشخص، بدون درخواست مجدد.

Quote.to_frame(self, *, numeric: "Literal['analysis', 'exact']" = 'analysis') -> 'pd.DataFrame'

مدل‌های واقعی

مدل‌های اجرایی و نوع‌های خروجی

نسخه 0.3.1a1

این فهرست از dataclassها و enumهای خود کد ساخته شده، نه از مدل‌های پیشنهادی نقشه راه. Frozen بودن مدل‌های دارای DataFrame تنها مانع نسبت‌دادن دوباره صفت است؛ کاربر همچنان مالک جدول خود است.

InstrumentRef

RecordMeta

InstrumentRecord

Quote

WriteReceipt

StorageStatus

FlushReport

BatchFrames

SyncPlan

SyncResult

ClientConfig

NetworkConfig

StorageConfig

FreshnessPolicy

FetchPolicy

Market

TSE, IFB, BASE, DERIVATIVES, ENERGY, COMMODITY این enum به‌تنهایی وجود endpoint یا پشتیبانی همه بازارها را تضمین نمی‌کند.

QuoteUnit

PRICE, PERCENT, INDEX_POINTS, UNKNOWN این enum به‌تنهایی وجود endpoint یا پشتیبانی همه بازارها را تضمین نمی‌کند.

QuantityUnit

SHARE, CONTRACT, UNIT, MWH, UNKNOWN این enum به‌تنهایی وجود endpoint یا پشتیبانی همه بازارها را تضمین نمی‌کند.

ردیابی همه قراردادهای داده

Data blueprint coverage

Source contracts: 90. This is a scope comparison, not a claim of live endpoint verification. Original source has been preserved verbatim. Analytics/ML remain deferred at the user's request.