۱۲ اکتبر ۲۰۲۶ | نسخه سند ۰٫۲

معماری و مرجع ساخت tse-dara

سه زیرماژول مستقل، Pandas مستقیم، دو رابط اجرا و ذخیره‌سازی خودکار مقاوم در برابر خطا.

۱۲۷ قرارداد عمومی۵۳ همتای Async۱۴ مرحله اجرایی۱۷۰ مدخل مرجع

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

tse-dara — مبنای بازبینی‌شده طراحی

نسخه سند: ۰٫۲ — تاریخ: ۱۲ اکتبر ۲۰۲۶

این تحویل معماری و قرارداد ساخت است، نه کتابخانه قابل نصب یا گزارش موفقیت آزمون زنده. نیازهای جدید در طرح ادغام شده‌اند: سه زیرماژول data/analytics/ml، خروجی مستقیم Pandas، رابط همگام و Async، چهار قالب ذخیره، SQLite خودکار بهترین‌تلاش، کار آفلاین، اصلاح داده‌ها، زمان دسترسی برای ML و انتشار عمومی.

تصمیم اصلی

دریافت معتبر و ذخیره موفق دو نتیجه جدا هستند. شکست ذخیره خودکار نباید دریافت یا تحلیل عادی را متوقف کند. صف حافظه‌ای، ذخیره قطعی نیست؛ تضمین دوام به ذخیره/flush صریح موفق وابسته است. analytics و ml با DataFrame کار می‌کنند و بدون درخواست صریح، اینترنت یا دیسک را مصرف نمی‌کنند.

محتویات

سند کاربرد
01_ARCHITECTURE_FA.md ساختار لایه‌ها، ماژول‌ها و جهت وابستگی
00_TYPES_AND_CONVENTIONS_FA.md نوع‌ها، مدل‌ها، شِما و قواعد مشترک
02_REFERENCE_LIBRARIES_FA.md ۱۷۰ مدخل نسخه‌های تثبیت‌شده دو کتابخانه
03_DATA_API_FA.md قراردادهای دریافت، پاک‌سازی و ذخیره
04_ANALYTICS_API_FA.md قرارداد تحلیل مالی، آماری و تکنیکال
05_ML_API_FA.md قرارداد داده آموزشی، تقسیم زمانی و مدل
06_STORAGE_AND_POINT_IN_TIME_FA.md صف، خرابی دیسک، آفلاین، revision و جلوگیری از نشت آینده
07_ROADMAP_FA.md ۱۴ مرحله و ۹۰ واحد کار قابل تحویل
08_REQUIREMENTS_AND_MIGRATION_FA.md ردیابی تصمیم‌های جدید و ۵۸ قابلیت طرح قبلی
09_COMPARISON_AND_EVIDENCE_FA.md مقایسه خانواده قابلیت‌ها و تصمیم انتقال به Dara
10_INTERNAL_INTERFACES_FA.md قرارداد ۱۸ عملیات داخلی درگاه‌ها
11_EXCEPTIONS_FA.md خانواده‌های خطا
12_SOURCES_AND_LIMITS_FA.md منابع و موارد نامعلوم
13_EXAMPLES_FA.md مثال‌های رابط هدف؛ نه کد قابل اجرای فعلی
READABLE_REPORT.html همه متن‌ها در یک صفحه راست‌به‌چپ، قابل مطالعه آفلاین

داده ساختاریافته

public_api_contracts.json شامل 127 مدخل عمومی (تابع، کلاس یا سازنده) و 53 همتای شبکه‌ای Async است. reference_source_catalog.json همان ۱۷۰ مدخل منبع را نگه می‌دارد؛ آن عدد شمار همه توابع خصوصی یا همه نسخه‌ها نیست. models_and_schemas.json شامل 63 تعریف مدل داده و گزارش است؛ سازنده‌های تنظیمات جداگانه در مرجع API آمده‌اند. official_endpoint_registry.json فهرست مسیرهای متن رسمی ارسالی است؛ داده مستندشده الزاماً آزموده نیست. legacy_task_map.json هر ۶۶ واحد کار قبلی را با متن اصلی و مقصد مرحله جدید حفظ می‌کند.

ترتیب تقدم

نیازمندی‌های جدید کاربر و قراردادهای ۰٫۲ مبنای فعال‌اند. archive/baseline_v0_1.zip فقط سابقه است. در تعارض، TableResult اجباری، اختیاری‌بودن Pandas، بیرون‌بودن analytics/ml و خاموش‌بودن پیش‌فرض ذخیره از ۰٫۱ کنار گذاشته شده‌اند. قابلیت‌ها حذف نشده‌اند؛ نحوه ارائه و مسئولیت‌ها طبق خواسته جدید اصلاح شده‌اند.

حدود اطمینان

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

معماری بازبینی‌شده tse-dara

نسخه سند: ۰٫۲ — ۱۲ اکتبر ۲۰۲۶ — وضعیت: پیشنهاد مهندسی، نه نرم‌افزار پیاده‌سازی‌شده.

۱. تصمیم‌های الزام‌آور و جایگزینی‌های آگاهانه

سه سطح عمومی tse_dara.data، tse_dara.analytics و tse_dara.ml داریم. analytics و ml اکنون بخشی از همین بسته‌اند، نه پروژه‌ای خارج از دامنه. تفکیک داخلی حفظ می‌شود. خروجی اصلی جدول‌ها خود pandas.DataFrame است؛ نیاز اجباری به TableResult.to_pandas و اختیاری‌بودن Pandas از طرح قبلی کنار گذاشته می‌شود. مدل قیمت منفرد Quote و اسکالر Decimal، و گزارش‌های مرکب دارای DataFrame همچنان مجازند. ذخیره‌سازی خودکار پیش‌فرض فعال است، اما بهترین‌تلاش و مستقل از موفقیت دریافت. شرط «ساخت Client بدون I/O» حفظ می‌شود: ایجاد مخزن در اولین عملیات داده، در worker محدود انجام می‌گیرد. ۵۸ قابلیت طراحی قبلی حذف نشده‌اند؛ جدول مهاجرت نشان می‌دهد هرکدام اکنون کجاست. تغییر امضاها در این مرحله تغییر سندِ پیش از انتشار است؛ پس از انتشار پایدار به نسخه‌بندی و مهاجرت نیاز دارد. اصل دریافت مستقیم از TSETMC، دو Provider مستقل عمومی/احرازشده، هویت دقیق نماد، کنترل تعدیل، داده خام، خروجی‌گیری، نمونه آفلاین، آزمون، انتشار عمومی و پشتیبانی مرحله‌ای حفظ شده‌اند.

۲. هدف و مرز دامنه

یک بسته عمومی و متن‌باز سمت کاربر؛ بدون سرور مرکزی اجباری، کلید اشتراکی، وابستگی اجرایی به pytse-client/tsetmc، سفارش‌گذاری واقعی یا تضمین سود/دسترسی نامحدود. data: دریافت، هویت، قرارداد نوع و واحد، پاک‌سازی غیرحدسی، کنترل کیفیت، ذخیره و بازخوانی. analytics: محاسبات مالی، آماری و تکنیکال روی DataFrame؛ بدون شبکه، بدون نوشتن فایل خودکار، بدون تغییر ورودی. ml: آماده‌سازی داده، کنترل دسترس‌پذیری زمانی، تقسیم زمانی، آموزش/ارزیابی/پیش‌بینی روی DataFrame؛ بدون دانلود یا ذخیره پنهانی. پردازش رایج روی CPU است؛ async به خودی خود آموزش مدل یا محاسبات Pandas را سریع نمی‌کند. شتاب‌دهنده‌ها، AutoML، NLP، مدل‌های عمیق و شبیه‌ساز معاملات بازار در مسیر آینده، نه وابستگی اجباری روز اول.

۳. شواهد و آنچه هنوز معلوم نیست

مرجع مقایسه کد دو پروژه در snapshot های ثابت سند 02 است. استانداردهای Pandas، SQLite، HTTPX، scikit-learn و بسته‌بندی در sources.json ثبت شده‌اند [S01–S13]. متن سرویس رسمی که کاربر فرستاده، ورود JWT، نقش دسترسی و کنترل اعتبار را نشان می‌دهد [S14]. بازبودن صفحه اصلی API به معنی حق استفاده از endpoint های داده نیست. قدیمی‌ترین تاریخ، پوشش همه نمادها، بازه/اندازه پاسخ مجاز، تعرفه، حقوق بازتوزیع و تعریف همه فیلدها هنوز آزموده/روشن نیستند. هیچ پیش‌فرض نرم‌افزاری مثل نرخ محلی درخواست، سقف رسمی بورس محسوب نمی‌شود. وجود متد در مرجع ≠ سلامت فعلی endpoint ≠ تکمیل داده ≠ اجازه بازنشر.

۴. جریان وابستگی و مسئولیت

کاربر / کتاب / Notebook
      |
      +--> data.Client / data.AsyncClient
      |        |
      |    خدمات و برنامه‌ریز درخواست
      |        |
      |    Provider انتخاب‌شده --> انتقال HTTP --> TSETMC
      |        |
      |    parser -> NormalizedBatch تغییرناپذیر
      |        +--> validator -> FrameFactory -> DataFrame کاربر
      |        +--> MemoryCache
      |        +--> enqueue_nowait -> PersistenceCoordinator -> SQLite
      |
      +--> analytics(DataFrame) --> DataFrame
      |
      +--> ml(DataFrame / DatasetBundle) --> model / DataFrame / report

_core شامل قرارداد هویت، واحد، زمان، شِما، provenance و خطاست.
analytics و ml به شبکه/ذخیره data وابسته نیستند.

Provider عمومی و رسمی هر دو به یک مجموعه TSETMC وابسته‌اند؛ تنوع adapter، استقلال منبع داده نیست. لایه‌های داخلی از قراردادها استفاده می‌کنند، نه از فایل‌های همدیگر یا نام ستون خام یک endpoint. فقط composition.py پیاده‌سازی‌های واقعی را متصل می‌کند. منطق تبدیل، اعتبارسنجی، برنامه‌ریزی، انتخاب نسخه، dedup و قواعد freshness مشترک است. SyncExecutor و AsyncExecutor فقط عملیات I/O و انتظار را متفاوت انجام می‌دهند؛ دو نسخه متفاوت فرمول تعدیل یا parser نمی‌سازیم.

۵. ساختار دقیق ماژول‌ها

tse-dara/
  pyproject.toml
  README.md
  LICENSE
  CHANGELOG.md
  CONTRIBUTING.md
  SECURITY.md
  .github/
    workflows/{tests,release,docs,live-smoke}.yml
    ISSUE_TEMPLATE/{bug,data-quality,feature}.yml
  src/tse_dara/
    __init__.py                 # بازصادرات محدود سازگار؛ بدون I/O
    py.typed
    _core/
      types.py                 # aliases و enum های مستقل از کد خام منبع
      identifiers.py           # InstrumentRef و روابط هویت
      units.py                 # قیمت، مقدار، ارز و واحد شاخص
      time.py                  # parse صریح تقویم و منطقه زمانی
      schemas.py               # registry نسخه‌دار شِماها
      provenance.py            # RecordMeta/FrameManifest/lineage
      exceptions.py            # خطاهای پایدار عمومی
      diagnostics.py           # رویداد و شمارنده کران‌دار حافظه
    data/
      __init__.py              # facade ساده بدون await
      client.py
      async_client.py
      config.py
      composition.py
      models/
        instruments.py
        quotes.py
        batches.py             # NormalizedBatch/BatchFrames
        requests.py            # RequestSpec/QuerySpec/FetchResult
        reports.py             # receipt, flush, sync و snapshot
      services/
        instruments.py         # حل شناسه دقیق، نه اولین نتیجه
        quotes.py
        history.py
        market.py
        client_types.py
        indices.py
        trades.py
        order_books.py
        ownership.py
        funds.py
        messages.py
        reference.py
        derivatives.py         # آینده، مشروط به اثبات منبع
        energy.py              # آینده، مشروط به اثبات منبع
        planning.py
        sync_executor.py
        async_executor.py
      providers/
        contracts.py
        capabilities.py
        public/
          endpoints.py         # فقط مسیرهای شاهددار
          requests.py
          parsers/
            instruments.py
            quotes.py
            history.py
            market.py
            client_types.py
            indices.py
            trades.py
            order_books.py
            ownership.py
            funds.py
            messages.py
        official/
          endpoints.py
          auth.py              # توکن حافظه‌ای، انقضا، -107، نقش
          envelopes.py         # IsSuccess/Data/Msg با aliases آزموده
          requests.py
          parsers/
            trade.py
            instrument.py
            index.py
            client_type.py
            market_info.py
            derivatives.py
            energy.py
      transport/
        sync_http.py
        async_http.py
        retry.py
        rate_limit.py
        budgets.py
        redaction.py
      normalization/
        columns.py
        persian.py
        numeric.py
        datetime.py
      quality/
        validators.py
        coverage.py
        conflicts.py
      frames/
        factory.py
        metadata.py
        converters.py
      cache/
        memory.py
        policy.py
        keys.py
      storage/
        contracts.py           # DatasetStore/RawStore
        coordinator.py         # یک writer برای هر path/process
        queue.py               # سقف تعداد و حجم
        receipts.py
        sqlite/
          repository.py
          connections.py
          migrations/
          schema.sql
        files/
          csv_io.py
          excel_io.py
          parquet_io.py
          manifests.py
        postgres/
          README.md            # آینده؛ پیاده‌سازی اجباری نیست
      dataset/
        planner.py
        sync.py
        checkpoints.py
        revisions.py
        snapshots.py
      samples/
        manifest.json
        synthetic_daily_v1.json
    analytics/
      __init__.py
      contracts.py
      returns.py
      risk.py
      statistics.py
      portfolio.py
      fundamentals.py
      candles.py
      indicators/
        moving_averages.py
        momentum.py
        volatility.py
    ml/
      __init__.py              # sklearn/GPU را در import پایه بار نکند
      contracts.py
      availability.py
      datasets.py
      features.py
      targets.py
      splits.py
      leakage.py
      preprocessing.py
      baselines.py
      training.py
      evaluation.py
      prediction.py
      persistence.py
      extensions/README.md
  tests/
    unit/{core,data,analytics,ml}/
    contract/
    parity/
    storage_faults/
    revision_time/
    fixtures/
    live/
    packaging/
    book_examples/
  docs/
    architecture/
    api/
    schemas/
    endpoints/
    data_quality/
    tutorials/
    migrations/
    adr/
  examples/
  tools/

این درخت طرح مقصد است؛ در هر مرحله فقط فایل مورد استفاده ساخته می‌شود. پوشه postgres و extensions تا هنگام نیاز یک یادداشت دامنه دارند، نه کد نمایشی که ظاهراً کار می‌کند.

۶. قراردادهای Pandas

تمام خروجی‌های جدولی استاندارد DataFrame‌اند. Quote و قیمت عددی و گزارش‌های مرکب خروجی غیرجدولی ثابت خود را دارند. DataFrame دریافتی در مالکیت کاربر است؛ worker ذخیره هیچ مرجع mutable به آن نمی‌گیرد. داده برای ذخیره از NormalizedBatch تغییرناپذیر پیش از ساخت DataFrame انتخاب می‌شود. index پیش‌فرض RangeIndex؛ کلید طبیعی در ستون‌هاست؛ ترتیب تاریخچه صعودی بر ins_code/date و ترتیب پایدار sequence برای درون‌روز. ورودی تحلیلی باید کلید یکتا و زمان معتبر داشته باشد؛ مرتب‌سازی با حفظ row_id انجام می‌شود. شناسه string، تعداد صحیح nullable Int64، قیمت تحلیلی nullable Float64، تاریخ روز datetime64[ns] بدون ساعت و timezone، timestamp های واقعی datetime64[ns, UTC]. تبدیل نمایشی به تهران جداست. numeric='exact' قیمت/مقدار اعشاری را Decimal در ستون object نگه می‌دارد؛ analytics در صورت نیاز به float باید تبدیل را صریح و با گزارش دقت انجام دهد. داده خام و decimal دقیق در آرشیو، حتی در numeric='analysis' محفوظ می‌ماند. مقادیر غایب pd.NA/NaT؛ صفر به‌طور عمومی missing نیست. نام field های غلط با errors='ignore' پنهان نمی‌شوند. df.attrs['tse_dara'] شناسنامه کوچک شامل schema_id/version، request_id، snapshot/receipt_id، پوشش و وضعیت اولیه ذخیره دارد. این تنها محل provenance نیست. attrs در Pandas تضمین انتقال همیشگی ندارد [S03]. شناسه ردیف/نسخه و زمان‌های لازم در ستون‌ها، و manifest بادوام در مخزن/فایل جانبی ذخیره می‌شوند. پس از عملیات arbitrary Pandas، فقدان metadata به unknown تبدیل می‌شود؛ کتابخانه از نام ستون یا ظاهر تاریخ، اصالت تاریخی اختراع نمی‌کند. ml.strict_pit داده فاقد شواهد کافی را رد می‌کند.

۷. مسیر هر درخواست عادی

۱) ورودی، بودجه و سیاست بررسی شود. ۲) شناسه با registry حافظه یا داده محلی دارای بودجه خواندن حل شود. ۳) capability و source مشخص شود. ۴) کش بر مبنای نوع داده بررسی شود. ۵) در صورت نیاز درخواست محدود به منبع. ۶) کنترل HTTP/content/business status. ۷) parse با نسخه شِما. ۸) کنترل معنا/واحد/کیفیت. ۹) داده به MemoryCache و صف ذخیره بهترین‌تلاش داده شود؛ DataFrame به کاربر برگردد. منتظر commit SQLite نمی‌مانیم. ۱۰) نویسنده بعداً در همان فرایند کاربر commit می‌کند و receipt/health به‌روز می‌شود. شیء DataFrame بازگردانده‌شده به‌طور پنهان mutate نمی‌شود. این کار یک طراحی نرم‌افزاری برای اجرای خود کاربر است؛ نیازی به سرور یا اجرای پس‌زمینه از طرف دستیار ندارد.

۸. سیاست آنلاین و آفلاین

AccessMode سه حالت auto/online/offline دارد؛ تفاوت آن‌ها دقیقاً در جدول سند ذخیره آمده است. auto برای تاریخچه: کش معتبر -> همان؛ منقضی -> دریافت تدریجی؛ خطای شبکه و مجازبودن stale -> کش قبلی با گزارش. quote در حالت عادی درخواست آخرین گزارش موجود است؛ پیش‌فرض stale fallback ندارد. دریافت آفلاین quote باید با اجازه صریح داده قدیمی و نمایش زمان همراه باشد. online داده قدیمی را به جای شکست شبکه بی‌سروصدا برنمی‌گرداند. offline شبکه ندارد و پوشش ناکافی را گزارش/خطا می‌کند. خطای authentication یا permission مشکل اینترنت محسوب نمی‌شود. مجوز آفلاین داده رسمی باید رعایت شود؛ قابلیت فنی، اجازه قراردادی ایجاد نمی‌کند. as_of فقط با تاریخچه نسخه‌ها و شواهد availability معتبر قابل اجراست. آخرین داده اصلاح‌شده امروز جای نسخه زمان گذشته نمی‌نشیند.

۹. داده مالی و چندبازاری

last_price،closing_price و previous_reference_price جدا هستند. priceYesterday معادل تضمین‌شده پایانی خام ردیف قبل نیست [S01]. شناسه ابزار از شرکت جدا، بازار از نوع ورقه جدا، فعال‌بودن هویتی از مجازبودن معامله جداست. داده بورس/فرابورس به‌طور خودکار با کد Flow سرویس دیگر یکی نمی‌شود. تاریخچه listing و continuous_verified جدا؛ اتصال شناسه‌های قدیمی نیازمند رابطه شاهددار و اعتبار زمانی است. انتخاب فقط نمادهای امروز برای پژوهش تاریخی، universe گذشته را بازسازی نمی‌کند. تعدیل خام/منبع/مشتق در ذخیره جداست. دریافت منبع تعدیل بدون شناسه روش و anchor_date نباید adjusted=True مبهم بسازد. بازده قیمت تعدیل‌شده به‌طور خودکار «بازده کل با سرمایه‌گذاری سود نقدی» نیست. ریزمعاملات، تغییرات تجمعی آمار قیمت و کندل سه مفهوم متفاوت‌اند. بازسازی مظنه به sequence و وضعیت اولیه نیاز دارد؛ پرکردن روی شکاف، حالت کامل ساختگی می‌سازد.

۱۰. شبکه و رابط همگام/ناهمگام

پیشنهاد HTTPX برای هر دو رابط [S05,S06]. Client و AsyncClient session متعلق به خود دارند؛ انتقال parser بین آن‌ها مشترک ولی sharing یک AsyncClient میان حلقه‌های متفاوت ممنوع. ساخت Client/import بدون HTTP، ساخت SQLite، تغییر رمز یا thread. public facade یک کلاینت پیش‌فرض lazy دارد؛ برای کنترل عمر منابع context manager توصیه می‌شود. Sync هیچ asyncio.run پنهان ندارد؛ Async در مسیر انتظار دیسک/شبکه event loop را مسدود نمی‌کند. کار CPU سنگین نیازمند فرایند/اجرای جدا با انتخاب کاربر است. Timeout های اتصال/خواندن و deadline عملیات و سقف concurrency و retry مشخص باشند. retry برای خطاهای موقتی خواندن با backoff محدود؛ 401/403 و schema mismatch retry کور ندارد. اسرار فقط به دامنه مجاز همان provider؛ redirect میان دامنه‌ها با Authorization ممنوع؛ TLS اعتبارسنجی شود؛ مسیر رسمی در مثال HTTP سند بدون TLS استفاده نمی‌شود. payload بزرگ سقف دارد؛ HTTP200+HTML خطاست؛ IsSuccess=false به DataFrame خالی تبدیل نمی‌شود.

۱۱. کیفیت، observability و امنیت

log handler از طرف کاربر؛ بدون telemetry و ارسال داده پیش‌فرض. diagnostic ring در حافظه کران‌دار است و اگر persistence خراب باشد به همان DB وابسته نیست. فقط خطای ذخیره خودکار داخل مرز persistence مهار می‌شود. MemoryError،KeyboardInterrupt،SystemExit و خطای شبکه/اعتبارسنجی در catch-all گم نمی‌شوند. خطاهای public از exceptions پایدار با code،request_id و پیام فارسی/فنی قابل فهم استفاده می‌کنند؛ body حساس در repr وارد نمی‌شود. ذخیره صریح و sync_job برخلاف autosave نیازمند اعلام صریح شکست‌اند. خطر کمبود دیسک نباید به موفقیت دروغین تبدیل شود.

۱۲. انتشار و وابستگی

Pandas/NumPy/HTTPX/platformdirs/tzdata هسته پیشنهادی؛ sqlite3 استاندارد پایتون. پشتیبانی هدف Python 3.12 تا 3.14 تنها پس از ماتریس CI اعلام شود. extra های پیشنهادی: excel=openpyxl؛ parquet=pyarrow؛ jalali=jdatetime؛ ml=scikit-learn؛ polars=polars/pyarrow؛ model-io=skops؛ مدل عمیق/GPU بعداً. نصب data نباید PyTorch یا GPU نصب کند. pip install tse-dara و pip install 'tse-dara[excel,parquet,ml]' شکل آینده انتشارند، نه دستور نصب بسته منتشرشده در این سند. pyproject شامل نسخه،dependencies،optional-dependencies،license و links؛ wheel/sdist در محیط تمیز آزموده شوند [S10]. انتشار PyPI با trusted publishing و approvals جدا پیشنهاد می‌شود [S11]. نام PyPI و مجوز نهایی و حقوق داده باید پیش از انتشار بررسی شوند. دو کتابخانه مرجع کپی یا bundle نمی‌شوند. داده رسمی/عمومی و نرم‌افزار مجوز یکسان ندارند. هر ویرایش کتاب requirements/نسخه و sample fixture ثابت دارد. import های سه ماژول، کلید خروجی و نوع DataFrame و واحدها جزو قرارداد پایدارند. تغییر ناسازگار، major version و راهنمای مهاجرت لازم دارد.

۱۳. اولویت اجرا

نقشه کامل در سند 07 است. P00 تا P05 داده/SQLite/فایل؛ P06 برابری sync/async؛ P07 تحلیل و تعدیل؛ P08–P10 بازار و جزئیات؛ P11 کنترل PIT و ML؛ P12 رسمی/چندبازاری؛ P13 توسعه آینده و انتشار. مدل‌های ML را می‌توان روی نمونه آفلاین موازی آموخت، اما ادعای پژوهش تاریخی معتبر تا تکمیل provenance/PIT ممنوع است. ارائه public API جدید قبل از تعریف schema و آزمون رفتار خطا انجام نمی‌شود. «کامل‌ترین» در این سند یعنی مرز و قرارداد قابل تکمیل، نه قول پوشش همه اطلاعات جهان یا معماری بدون هیچ نقص احتمالی.

قراردادهای مشترک، نوع‌ها و کلاس‌ها

نسخه ۰٫۲؛ همه کلاس‌ها و توابع Dara در این سند پیشنهادی و پیاده‌سازی‌نشده‌اند. نوع‌های دو پروژه موجود در سند 02 مستقل گزارش شده‌اند.

۱. قواعد فراخوانی عمومی

توابع داده هم به‌صورت متد Client و هم facade همگام tse_dara.data عرضه می‌شوند. امضاهای جدول بدون self نوشته شده‌اند. AsyncClient همتای شبکه‌ای آن‌ها را با await و نوع نتیجه یکسان دارد؛ iter_history با async for مصرف می‌شود. capabilities و ساخت نوع‌های تنظیمات I/O ندارند و در AsyncClient هم await نمی‌خواهند.

توابع analytics و ml تابع معمولی هستند؛ هرجا IO لازم است نام عملیات صریح است. آموزش CPU با تزئین async به عملیات موازی تبدیل نمی‌شود.

پیش‌فرض Client از ClientConfig ساخته می‌شود؛ آرگومان‌های غیر None سازنده جایگزین آن‌اند. source=public،mode=auto و storage فعال مقادیر نهایی پیش‌فرض‌اند. منبع رسمی تنها با حساب مجاز.

پارامتر freshness تابع بر FetchPolicy و سپس پیکربندی dataset مقدم است. offline هیچ شبکه‌ای ندارد. cache lookup اختیاری auto/online بودجه کوتاه دارد؛ خواندن ضروری offline/fallback مجاز از offline_read_timeout=30 ثانیه استفاده می‌کند و شکست آن صریح است.

تاریخچه نهایی‌شده کش یک‌روزه پیشنهادی دارد؛ بخش امروز/جلسه‌ای که نهایی‌شدن آن تایید نشده، در درخواست تازه با max_age=0 بازبینی می‌شود. quote به‌طور پیش‌فرض stale نیست. این زمان‌ها سیاست داخلی‌اند و به معنی تضمین سرعت/سلامت منبع نیستند.

همه خروجی‌های جدولی تک‌مجموعه DataFrame هستند؛ BatchFrames/DatasetBundle/ValidationRun فقط ظرف چند جدول مستقل‌اند، نه الزام به to_pandas برای استفاده.

None در پارامتر range یعنی دامنه موجود منبع. ناموجودبودن داده با اختلال/خطا متفاوت است؛ empty معتبر باید ستون‌ها و dtype های صحیح و coverage status داشته باشد.

۲. نوع‌های مشترک

نوع تعریف
PathLike str | pathlib.Path
Source Literal['public','official']
AccessMode Literal['auto','online','offline']
NumericProfile Literal['analysis','exact']
InstrumentLike str | InstrumentRef؛ str فقط نام نماد
DateLike datetime.date | str؛ رشته YYYY-MM-DD و تقویم صریح
Calendar Literal['gregorian','jalali']
Market Enum معنایی مستقل از کدهای Flow منبع: TSE,IFB,BASE,DERIVATIVES,ENERGY,COMMODITY؛ نوع‌های اضافه تنها با نگاشت آزموده
AdjustmentMode Literal['none','source']
SeriesMode Literal['listing','continuous_verified']
PriceField Literal['last','closing','previous_reference']
ErrorPolicy Literal['raise','collect']
CancellationPolicy Literal['as_reported','exclude_verified']
BarInterval Literal['30s','1m','5m','10m','15m','30m','1h']
FileFormat Literal['csv','excel','parquet','sqlite']
FundCategory Enum: STOCK,MIXED,FIXED,MARKET_MAKING,VC,REIT,PROJECT,COMMODITY,PRIVATE,FUND؛ پشتیبانی هرکدام capability منبع
pd pandas
pl polars؛ فقط مبدل اختیاری
BaseEstimator sklearn.base.BaseEstimator یا estimator سازگار با قرارداد ثبت‌شده
Pipeline sklearn.pipeline.Pipeline
QuoteUnit Enum PRICE/PERCENT/INDEX_POINTS/UNKNOWN
QuantityUnit Enum SHARE/CONTRACT/UNIT/MWH/UNKNOWN
DatasetStore درگاه ذخیره تعریف‌شده در سند internal contracts
Mapping typing.Mapping
Sequence typing.Sequence
Iterator typing.Iterator
AsyncIterator typing.AsyncIterator
Literal typing.Literal
datetime datetime.datetime؛ timestamp باید timezone-aware باشد
date datetime.date؛ بدون ساعت
timedelta datetime.timedelta
Decimal decimal.Decimal

۳. شِمای DataFrame

ستون‌های داده روزانه: ins_code،symbol،date،open_price،high_price،low_price،last_price،closing_price،previous_reference_price،volume،turnover،trade_count،source،currency،quote_unit،quantity_unit،adjustment،row_id،observation_id،fetched_at،first_observed_at،available_at،availability_basis و is_stale.

date در جدول روزانه از trade_date مدل داخلی ساخته می‌شود. provider مدل متادیتا به source و retrieved_at به fetched_at نگاشت می‌شوند. این تبدیل‌ها باید در FrameFactory مرکزی باشند، نه در هر Provider با نام دلخواه.

شناسه‌ها string،تعدادها Int64،قیمت‌های پروفایل analysis Float64 nullable،پروفایل exact Decimal object،boolean ها nullable؛ تاریخ روز datetime64[ns] و timestamp ها datetime64[ns,UTC]. خروجی تبدیل به numpy float برای model فقط پس از کنترل دقت و null انجام شود.

کلیدطبیعی به session_id/adjustment_basis نیاز دارد؛ درنبود session معتبر،sentinel صریح unspecified درکلید canonical استفاده شود نه NULL در UNIQUE و نه فرض 'جلسه عادی'.

خروجی‌های گروهی quote یک ردیف به‌ازایهرورودی با request_index,status,error_code,error_message دارند. get_history_many به‌دلیل تعداد ردیف متغیر BatchFrames(data,errors,manifest) می‌دهد. نوع خروجی با on_error تغییر نمی‌کند.

۴. مدل‌های رکوردی و گزارش

InstrumentRecord

هویت ابزار، نه صرفاً نام نماد

فیلد نوع و معنا
ins_code str؛ شناسه داخلی دقیق
symbol str؛ نماد عادی‌شده
raw_symbol str؛ متن دریافتی بدون تغییر
name str | None
instrument_id str | None؛ جدا از company_cisin
company_cisin str | None
market Market | None؛ مقدار معنایی استاندارد
raw_flow str | None؛ کد خام منبع
instrument_type str | None؛ نگاشت تأییدشده یا نامعلوم
is_active bool | None؛ اعتبار/فعالیت مطابق تعریف منبع، نه الزاماً مجازبودن معامله
valid_from date | None
valid_to date | None
first_trade_date date | None
quote_unit QuoteUnit
quantity_unit QuantityUnit
currency str | None
meta RecordMeta

Quote

آخرین وضعیت گزارش‌شده؛ نه تضمین معامله همین ثانیه

فیلد نوع و معنا
instrument InstrumentRecord
trade_date date | None
last_price Decimal | None
closing_price Decimal | None
previous_reference_price Decimal | None
open_price Decimal | None
high_price Decimal | None
low_price Decimal | None
trade_count int | None
volume Decimal | None
turnover Decimal | None
turnover_currency str | None
state str | None؛ وضعیت استاندارد با raw_state محفوظ
source_timestamp datetime آگاه از منطقه زمانی | None
timestamp_kind Literal['trade','snapshot','unknown']
retrieved_at datetime آگاه UTC
meta RecordMeta؛ شامل واحدها، اصالت و کیفیت

DailyBar

یک ردیف قیمت روزانه برای یک شناسه و یک حالت سری

فیلد نوع و معنا
ins_code str
symbol str
trade_date date
open_price Decimal | None
high_price Decimal | None
low_price Decimal | None
last_price Decimal | None
closing_price Decimal | None
previous_reference_price Decimal | None
trade_count int | None
volume Decimal | None
turnover Decimal | None
quote_unit QuoteUnit
quantity_unit QuantityUnit
currency str | None
adjustment AdjustmentMode
adjustment_factor Decimal | None؛ فقط با روش و مبنای ثبت‌شده
is_traded bool | None
meta RecordMeta

ClientTypeRecord

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

فیلد نوع و معنا
ins_code str
trade_date date | None
individual_buy_count int | None
institutional_buy_count int | None
individual_sell_count int | None
institutional_sell_count int | None
individual_buy_volume Decimal | None
institutional_buy_volume Decimal | None
individual_sell_volume Decimal | None
institutional_sell_volume Decimal | None
individual_buy_value Decimal | None
institutional_buy_value Decimal | None
individual_sell_value Decimal | None
institutional_sell_value Decimal | None
meta RecordMeta

Trade

یک معامله یا رکورد وضعیت معامله

فیلد نوع و معنا
ins_code str
trade_date date
trade_id str | None
sequence str | None؛ متن دقیق منبع، ترتیب عددی فقط در صورت مستندبودن
timestamp datetime آگاه | None
price Decimal
quantity Decimal
cancellation_state Literal['valid','cancelled','unknown']
quote_unit QuoteUnit
quantity_unit QuantityUnit
meta RecordMeta

OrderBookLevel

یک ردیف مظنه در یک تصویر

فیلد نوع و معنا
ins_code str
depth int؛ از 1
bid_price Decimal | None
ask_price Decimal | None
bid_volume Decimal | None
ask_volume Decimal | None
bid_order_count int | None
ask_order_count int | None
meta RecordMeta

OrderBookUpdate

رویداد تغییر مظنه؛ نه لزوماً تصویر کامل

فیلد نوع و معنا
ins_code str
trade_date date
timestamp datetime آگاه | None
sequence str | None
reference_id str | None
depth int
operation Literal['upsert','delete','unknown']
bid_price Decimal | None
ask_price Decimal | None
bid_volume Decimal | None
ask_volume Decimal | None
bid_order_count int | None
ask_order_count int | None
field_presence frozenset[str]؛ تمایز فیلد ارسال‌نشده با null و صفر
meta RecordMeta

OrderBookSnapshot

تصویر بازسازی‌شده یا مستقیم مظنه‌ها

فیلد نوع و معنا
ins_code str
trade_date date | None
levels tuple[OrderBookLevel, ...]
sequence str | None
timestamp datetime آگاه | None
is_complete bool
meta RecordMeta

IntradayBar

OHLC ساخته‌شده از معامله؛ نه closing_price رسمی

فیلد نوع و معنا
ins_code str
start_time datetime آگاه
end_time datetime آگاه
interval BarInterval
open Decimal
high Decimal
low Decimal
close Decimal
volume Decimal
trade_count int
meta RecordMeta؛ مرز، timezone، سیاست ابطال و نسخه الگوریتم

PriceAdjustment

رویداد تعدیل با روش و درجه شواهد

فیلد نوع و معنا
ins_code str
effective_date date | None
reported_at datetime | None
price_before Decimal | None
price_after Decimal | None
factor Decimal | None
reason str | None؛ unknown در نبود مدرک
method str
method_version str
evidence_status str
meta RecordMeta

IndexRecord

هویت شاخص

فیلد نوع و معنا
index_code str
name str
market Market | None
index_kind str | None
unit Literal['point']
meta RecordMeta

IndexSnapshot

آخرین وضعیت یک شاخص

فیلد نوع و معنا
index_code str
trade_date date | None
value Decimal | None
high Decimal | None
low Decimal | None
change_percent Decimal | None
timestamp datetime آگاه | None
meta RecordMeta

IndexBar

داده روزانه شاخص

فیلد نوع و معنا
index_code str
trade_date date
value Decimal | None
high Decimal | None
low Decimal | None
open Decimal | None
meta RecordMeta

IndexPoint

یک مشاهده درون‌روز شاخص

فیلد نوع و معنا
index_code str
timestamp datetime آگاه | None
value Decimal | None
meta RecordMeta

IndexMember

عضویت ابزار در شاخص، با تاریخ اعتبار

فیلد نوع و معنا
index_code str
ins_code str
as_of_date date | None
weight Decimal | None؛ scale مستند
share_count Decimal | None
valid_from date | None
valid_to date | None
meta RecordMeta

IndexImpact

اثر ابزار بر شاخص مشخص

فیلد نوع و معنا
ins_code str
index_code str | None
impact_points Decimal | None
trade_date date | None
meta RecordMeta

InstrumentStateRecord

وضعیت ابزار

فیلد نوع و معنا
ins_code str
timestamp datetime آگاه | None
trade_date date | None
state str
raw_state str
reason str | None
meta RecordMeta

ThresholdRecord

حدود مجاز قیمت در یک زمان

فیلد نوع و معنا
ins_code str
trade_date date | None
timestamp datetime آگاه | None
min_price Decimal | None
max_price Decimal | None
quote_unit QuoteUnit
meta RecordMeta

ShareholderPosition

موقعیت سهامدار عمده

فیلد نوع و معنا
ins_code str
shareholder_id str | None
holding_ref str | None
shareholder_name str | None
trade_date date | None
quantity Decimal | None
ownership_percent Decimal | None؛ 0 تا 100
change_quantity Decimal | None
meta RecordMeta

ShareCapitalRecord

تغییر تعداد سهام

فیلد نوع و معنا
ins_code str
effective_date date | None
old_shares Decimal | None
new_shares Decimal | None
reported_at datetime | None
meta RecordMeta

DividendRecord

سود نقدی با تاریخ‌های تفکیک‌شده

فیلد نوع و معنا
ins_code str
fiscal_year_end date | None
meeting_date date | None
publish_date date | None
ex_date date | None
payment_date date | None
cash_dividend_per_share Decimal | None
currency str | None
meta RecordMeta

FundRecord

هویت و مشخصات صندوق

فیلد نوع و معنا
registration_no str
ins_code str | None
name str
category FundCategory | None
inception_date date | None
record_date date | None
meta RecordMeta

FundNavRecord

NAV با نوع مشخص

فیلد نوع و معنا
registration_no str
record_date date | None
timestamp datetime آگاه | None
subscription_nav Decimal | None
redemption_nav Decimal | None
statistical_nav Decimal | None
net_assets Decimal | None
currency str | None
meta RecordMeta

MarketMessage

پیام ناظر

فیلد نوع و معنا
message_id str
title str
text str
market Market | None
ins_code str | None
timestamp datetime آگاه | None
meta RecordMeta

Disclosure

فراده اطلاعیه مرتبط با کدال

فیلد نوع و معنا
tracking_no str
ins_code str | None
symbol str | None
title str
published_at datetime | None
sent_at datetime | None
attachment_flags dict[str,bool|None]
meta RecordMeta

SectorRecord

صنعت

فیلد نوع و معنا
sector_code str
name str
meta RecordMeta

SubsectorRecord

زیرصنعت

فیلد نوع و معنا
sector_code str | None
subsector_code str
name str
meta RecordMeta

BoardRecord

تابلو

فیلد نوع و معنا
board_code str
name str
market Market | None
meta RecordMeta

MarketSession

جلسه معاملاتی تأییدشده

فیلد نوع و معنا
market Market
trade_date date
state Literal['open','closed','unknown']
session_ended bool | None
observed_at datetime آگاه | None
meta RecordMeta

OpeningAuction

اطلاعات نظری گشایش

فیلد نوع و معنا
ins_code str
theoretical_price Decimal | None
theoretical_volume Decimal | None
timestamp datetime آگاه | None
meta RecordMeta

OptionContract

طرح اولیه؛ تثبیت پس از آزمون منبع

فیلد نوع و معنا
ins_code str
underlying_ins_code str | None
contract_size Decimal | None
strike_price Decimal | None
begin_date date | None
end_date date | None
buy_open_interest Decimal | None
sell_open_interest Decimal | None
meta RecordMeta

FutureContract

طرح اولیه؛ تثبیت پس از آزمون منبع

فیلد نوع و معنا
contract_id str
instrument_id str | None
underlying_id str | None
contract_size Decimal | None
begin_date date | None
end_date date | None
initial_margin Decimal | None
maintenance_margin Decimal | None
open_interest Decimal | None
meta RecordMeta

EnergyInstrument

طرح اولیه؛ داده انرژی با تقویم هر فیلد

فیلد نوع و معنا
record_id str
ins_code str
instrument_id str | None
title str
start_date date | None
end_date date | None
expiry_date date | None
load_type str | None
hours Decimal | None
meta RecordMeta

AuctionMessage

پیام حراج انرژی

فیلد نوع و معنا
record_id str
auction_id str | None
message str
message_type str | None
timestamp datetime آگاه | None
meta RecordMeta

QuoteRow

نمای سطری Quote برای جدول

فیلد نوع و معنا
ins_code str
symbol str
trade_date date | None
last_price Decimal | None
closing_price Decimal | None
previous_reference_price Decimal | None
open_price Decimal | None
high_price Decimal | None
low_price Decimal | None
trade_count int | None
volume Decimal | None
turnover Decimal | None
turnover_currency str | None
state str | None؛ وضعیت استاندارد با raw_state محفوظ
source_timestamp datetime آگاه از منطقه زمانی | None
timestamp_kind Literal['trade','snapshot','unknown']
retrieved_at datetime آگاه UTC
meta RecordMeta؛ شامل واحدها، اصالت و کیفیت

MarketOverview

خلاصه بازار

فیلد نوع و معنا
market Market
trade_date date | None
market_value Decimal | None
turnover Decimal | None
volume Decimal | None
trade_count int | None
index_value Decimal | None
state str | None
meta RecordMeta

RecordMeta

اصالت و کیفیت هر رکورد

فیلد نوع و معنا
provider Source
endpoint_id str
retrieved_at datetime آگاه UTC
source_timestamp datetime آگاه | None
schema_version str
parser_version str
quote_unit QuoteUnit | None
quantity_unit QuantityUnit | None
raw_reference str | None؛ hash/شناسه فاقد رمز
quality_flags tuple[str,...]
revision str | None
assumptions tuple[str,...]
row_id str
observation_id str | None
first_observed_at datetime آگاه UTC
source_published_at datetime آگاه UTC | None؛ فقط برای همین نسخه با شاهد
available_at datetime آگاه UTC | None
availability_basis Literal['observed','source_verified','unknown']
committed_at datetime آگاه UTC | None
payload_hash str
request_id str
scope_id str؛ namespace مجوز/کاربر، بدون secret

FrameManifest

شناسنامه DataFrame؛ قابل serialize ولی جای ستون‌های ردیفی نیست

فیلد نوع و معنا
frame_id str
schema_id str
schema_version str
request_ids tuple[str,...]
provider str
scope_id str | None
requested_range tuple[date|None,date|None] | None
data_range tuple[date|None,date|None] | None
coverage_status Literal['complete','partial','unknown']
from_cache bool
is_stale bool
retrieved_at datetime | None
receipt_ids tuple[str,...]
persistence_state Literal['queued','persisted','failed','skipped','disabled','unknown']
snapshot_id str | None
numeric_profile NumericProfile
warnings tuple[str,...]
row_id_hash str | None
lineage tuple[str,...]
next_cursor str | None
availability_basis str
synthetic bool

WriteReceipt

رسید وضعیت ذخیره

فیلد نوع و معنا
receipt_id str
request_id str | None
state Literal['queued','persisted','failed','skipped','disabled']
accepted_at datetime | None
committed_at datetime | None
rows int
payload_bytes int
reason str | None
destination str | None
content_hash str | None

FlushReport

گزارش تخلیه صریح صف

فیلد نوع و معنا
complete bool
queued_at_start int
persisted int
failed int
skipped int
pending int
receipts pd.DataFrame
elapsed_seconds float
last_error str | None

StorageStatus

وضعیت ذخیره بدون نیاز به خواندن DB

فیلد نوع و معنا
enabled bool
health Literal['not_started','ok','degraded','disabled','closed']
path str | None
pending_jobs int
pending_bytes int
persisted_jobs int
failed_jobs int
skipped_jobs int
last_commit_at datetime | None
last_error str | None
cooldown_until datetime | None

BatchFrames

نتیجه گروهی با نوع ثابت

فیلد نوع و معنا
data pd.DataFrame؛ request_index ستون اجباری
errors pd.DataFrame؛ request_index,input,error_code,message
manifest FrameManifest

DownloadPlan

برنامه داده‌برداری قابل ادامه

فیلد نوع و معنا
plan_id str
created_at datetime
chunks pd.DataFrame؛ chunk_id,instrument,start,end,capability,status
source Source
scope_id str
schema_id str
request_budget int
overlap_sessions int
full_recheck bool
config_fingerprint str

SyncReport

خروجی اجرای برنامه دریافت

فیلد نوع و معنا
plan_id str
chunks pd.DataFrame
receipts pd.DataFrame
errors pd.DataFrame
complete bool
downloaded_rows int
committed_rows int
pending_rows int
started_at datetime
finished_at datetime

SnapshotManifest

تعریف یک مجموعه ثابت و بادوام

فیلد نوع و معنا
snapshot_id str
name str
created_at datetime
observation_ids tuple[str,...]
schema_id str
schema_version str
data_hash str
raw_hashes tuple[str,...]
lineage tuple[str,...]
available_cutoff datetime | None
software_version str
durable bool

DatasetManifest

مشخصات مجموعه ML و مبنای PIT

فیلد نوع و معنا
dataset_id str
features tuple[str,...]
target str
source_snapshot_ids tuple[str,...]
data_hash str
feature_spec_hash str
schema_version str
training_cutoff datetime | None
pit_status Literal['verified','partial','unknown','synthetic']
availability_policy str
created_at datetime
durable bool
warnings tuple[str,...]

DatasetBundle

داده آموزشی؛ هیچ مدل fit نشده

فیلد نوع و معنا
X pd.DataFrame
y pd.Series
rows pd.DataFrame؛ row_id,ins_code,decision_at,label_start,label_end,target_available_at
dropped pd.DataFrame
manifest DatasetManifest

SplitBundle

سه بخش زمانی و گزارش حذف‌های لازم

فیلد نوع و معنا
train DatasetBundle
validation DatasetBundle
test DatasetBundle
purged pd.DataFrame
boundaries pd.DataFrame
manifest DatasetManifest

ModelRun

مدل و هویت آزمایش، نه فایل خودکار

فیلد نوع و معنا
run_id str
model BaseEstimator
features tuple[str,...]
dtypes dict[str,str]
training_manifest DatasetManifest
parameters dict[str,object]
seed int
dependency_versions dict[str,str]
fitted_at datetime
metrics pd.DataFrame
artifacts tuple[ModelArtifact,...]

ValidationRun

نتایج ارزیابی زمانی

فیلد نوع و معنا
scores pd.DataFrame
predictions pd.DataFrame
folds pd.DataFrame
purged pd.DataFrame
dataset_manifest DatasetManifest
config dict[str,object]

ModelArtifact

خروجی ذخیره صریح مدل

فیلد نوع و معنا
path str
format str
hash str
manifest_path str
created_at datetime
required_versions dict[str,str]
trusted_types tuple[str,...]

NormalizedBatch

مدل داخلی تغییرناپذیر بین parser،frame و writer

فیلد نوع و معنا
batch_id str
schema_id str
schema_version str
rows tuple[Mapping[str,object],...]؛ mapping ها immutable،نه dict قابل تغییر
raw bytes | None
raw_hash str | None
meta FrameManifest
estimated_bytes int
request_id str

RequestSpec

درخواست شاهددار فاقد اسرار در repr

فیلد نوع و معنا
endpoint_id str
method Literal['GET','POST']
path str
query Mapping[str,object]
body Mapping[str,object] | None
requires_auth bool
safe_retry bool
expected_shape str
max_bytes int
credential_scope str | None

RawResponse

پاسخ پاک‌شده از اسرار

فیلد نوع و معنا
request_id str
endpoint_id str
status_code int
headers Mapping[str,str] با whitelist
body bytes
received_at datetime
source_timestamp datetime | None
scope_id str

QuerySpec

پرس‌وجوی معنایی مستقل از SQL

فیلد نوع و معنا
dataset str
filters Mapping[str,object]
start date | None
end date | None
as_of datetime | None
scope_id str
coverage Literal['raise','report']
columns tuple[str,...] | None

CapabilityInfo

شناسنامه قابلیت؛ نه تضمین زنده

فیلد نوع و معنا
name str
supported bool
evidence Literal['source_reviewed','documented','live_tested','unknown']
auth_required bool
role str | None
coverage str | None
limits Mapping[str,object]
last_verified_at datetime | None

MarketFrames

ترکیب اختیاری چندجدول بازار برای برنامه پیشرفته

فیلد نوع و معنا
quotes pd.DataFrame
order_book pd.DataFrame
client_types pd.DataFrame
manifest FrameManifest

FundamentalSnapshot

داده بنیادی گزارش‌شده با زمان و دوره

فیلد نوع و معنا
ins_code str
eps Decimal | None
eps_basis str | None
sales_per_share Decimal | None
fiscal_period str | None
currency str | None
per_share_basis str | None
meta RecordMeta

InstrumentMetrics

آمار تکمیلی گزارش‌شده

فیلد نوع و معنا
ins_code str
shares_outstanding Decimal | None
base_volume Decimal | None
free_float_percent Decimal | None
month_average_volume Decimal | None
min_week Decimal | None
max_week Decimal | None
min_year Decimal | None
max_year Decimal | None
window_definition str | None
meta RecordMeta

RelatedInstrument

RelatedInstrument

فیلد نوع و معنا
ins_code str
related_ins_code str
relation_kind str
sector_code str | None
meta RecordMeta

KeyStatistic

KeyStatistic

فیلد نوع و معنا
ins_code str
parameter_code str
parameter_name str | None
value Decimal | None
unit str | None
period str | None
meta RecordMeta

MarketMapRow

MarketMapRow

فیلد نوع و معنا
ins_code str
sector_code str | None
market_cap Decimal | None
price_change Decimal | None
meta RecordMeta

FundRanking

FundRanking

فیلد نوع و معنا
ins_code str
rank int
metric str
value Decimal
coverage str
meta RecordMeta

۵. تنظیمات و سازنده‌ها

امضا و مقدار پیش‌فرض هر سازنده در سند03 آمده است. فیلدهای تنظیمات frozen هستند. Client و AsyncClient فقط مالک منابع و سیاست‌اند؛ نباید شبکه یا فایل در سازنده ایجاد کنند.

۶. قواعد عمومی استثناها

DaraError پایه خطاهای کتابخانه است. ValidationError ها می‌توانند از ValueError نیز ارث ببرند تا کاربر پایتون رفتار آشنا داشته باشد. خطای منبع اصلی به‌عنوان cause حفظ واطلاعات محرمانه حذف شود.

نام‌های خطای هر تابع در مرجع آمده‌اند؛ مجموعه خطاهای منبع می‌تواند وسیع باشد،اما در Dara به خانواده پایدار نگاشت می‌شود. این قراردادِ پیشنهادی است،نه ادعای پوشش استثناهای دو کتابخانه مرجع.

در collect تنها شکست اعضای مستقل جمع می‌شود؛ ورودی نامعتبر،لغو کاربر و schema خطرناک یکخطای عمومی را الزاماً قابل ادامه نمی‌کند.

StorageError در autosave به diagnostic تبدیل می‌شود؛ همان خطا در save/load/flush/sync صریح باید اعلام شود. خطاینتیجه/احرازهویت بااینقاعدهپنهان نمی‌شود.

مقایسه قابلیت‌ها و تصمیم انتقال به Dara

این جدول جمع‌بندی کاتالوگ تفصیلی ۱۷۰ مدخل است. علامت نبود/نامشخص فقط محدوده بررسی ثبت‌شده را توصیف می‌کند؛ پوشش همه توابع خصوصی یا نسخه‌های دیگر ادعا نمی‌شود.

حوزه pytse-client tsetmc پیشنهاد Dara مرحله و ملاحظه
فهرست و جست‌وجوی نماد all_symbols; symbols_information; get_ticker_index; get_symbol_info search; Instrument.from_l18/from_search/from_isin; dataset data.search_instruments/get_instruments/get_instrument P03؛ فهرست محلی != کل بازار؛ نتیجه اول بدون کنترل انتخاب نشود.
هویت و اطلاعات پایه Ticker.title/fulltitle/instrument_id/ci_sin/flow Instrument.info/identity; InstrumentOnDate.data data.get_instrument/get_instrument_metrics P03/P10؛ ابزار،شرکت،بازار واعتبار زمانی جدا.
قیمت جاری Ticker.get_ticker_real_time_info_response; last_price/adj_close Instrument.closing_price_info data.get_quote/get_price/get_quotes P03؛ Quote مستقل از history؛ زمان وواحد روشن.
تاریخچه روزانه download; Ticker.history Instrument.daily_closing_price; price_history data.get_history/iter_history/get_history_many P04؛ close/adjClose نام‌های مبهم؛نوع خروجی و ترتیب یکسان شود.
تعدیل download(adjust=True); adjust_price price_adjustments; price_history(adjusted=True) data.get_adjustments; data.get_history(adjustment='source') P07؛ روش،anchor ونسخه؛ نه تضمین بازده کل.
دیده‌بان get_stats market_watch_init/plus; get_market_watch; MarketWatch data.get_market_watch; data.watch_market P08/P09؛ polling کنترل‌شده،نه stream نامحدود.
آمار کلیدی get_stats key_stats; get_inst_value_all_inst_all_param data.get_key_statistics P10؛ کدپارامتر بدون معنا به نام مالی حدسی تبدیل نشود.
مظنه فعلی get_asks_and_bids; RealtimeTickerInfo orders Instrument.best_limits data.get_order_book P09؛ عمق،واحد و timestamp مستقل.
تاریخچه مظنه get_orderbook(diff_orderbook=...) Instrument.on_date(...).best_limits data.get_order_book_updates/reconstruct_order_book P09؛ sequence و initial و gap حفظ شوند.
ریزمعاملات get_trade_details; Ticker.get_trade_details Instrument.trades; InstrumentOnDate.trades data.get_trades P09؛ حالت ابطال وکد رخداد باید تأیید شود.
کندل درون‌روز get_trade_details(timeframe=...) ریزمعاملات آماده ورودی تبدیل محلی analytics.resample_trades P09؛ تبدیل محلی مستقل ازدانلود؛حجم تجمعی باحجم معامله فرق دارد.
حقیقی‌حقوقی download_client_types_records; Ticker.client_types client_type; client_type_history; get_client_type_all data.get_client_types/get_client_type_history/get_market_client_types P08؛ خروجی تاریخی ویک‌روز قراردادثابت؛مقادیر غایب صفرنیست.
شاخص روزانه ودرون‌روز FinancialIndex; download_financial_indexes Index.info/history/last_day_history; indices.last_state data.get_indices/get_index/get_index_history/get_index_intraday P08؛ شاخص،قیمت پولی سهام نیست.
اعضا واثر شاخص FinancialIndex.contributing_symbols Index.companies؛خروجی‌های مرتبط بازار data.get_index_members/get_index_impact P08؛ تاریخچه اعضا بدون شاهد ازاعضای امروز ساخته نشود؛اثر شاخص رسمی درمتنکاربرمشخص است.
سهامداران عمده Ticker.shareholders; get_shareholders_history_async share_holders; share_holder_history; InstrumentOnDate.holders data.get_shareholders/get_shareholder_history/get_shareholder_holdings P10؛ شناسه سهامدار باشناسه ردیف مالکیت اشتباه نشود.
تعدادسهام وشناوری Ticker.total_shares/float_shares; get_total_shares_history_async Instrument.info; InstrumentOnDate.data data.get_share_capital_history/get_instrument_metrics P10؛ رویدادحقوقی افزایشسرمایه وبه‌روزرسانی تعدادسهام مفاهیم جدا.
EPS و P/E و P/S Ticker.eps/p_e_ratio/psr/p_s_ratio Instrument.info؛فیلدهای eps data.get_fundamentals; analytics.fundamental_ratios P10؛ معنای psr منبع و sales-per-share تأییدشود؛قیمت/EPS بازمانهمگام.
سودنقدی درمدخل‌هایبررسی‌شده همتای عمومی مستقل ثبت نشده Instrument.dps_history data.get_dividends P10؛ عدم مشاهده معادل مستقل،اثبات نبود هرراه دریافت نیست.
صندوق و NAV Ticker.nav/nav_date Instrument.etf; funds/fund_details و ETF rankings data.get_funds/get_fund/get_fund_nav_history/get_fund_rankings P10؛ شمارهثبت صندوق از ins_code جدا.
پیام‌هاواطلاعیه درمرجع انتخاب‌شده پوشش مستقیم محدود/نامشخص Instrument.messages/codal/publisher; general.messages/search_messages data.get_messages/get_disclosures P10؛ فراده کدال != خواندن همه صورت‌های مالی.
وضعیت وآستانه Ticker.state/sta_min/sta_max InstrumentOnDate.states/static_thresholds data.get_instrument_states/get_thresholds P09؛ نبود رکورد را بدون قرارداد منبع 'بازبودن' فرض نکنیم.
صنعت وتابلو Ticker.group_name و get_stats general.boards/cs_codes/sectors_summary/related_companies data.get_sectors/get_subsectors/get_boards/get_related_instruments P08/P10؛ هم‌گروهی != رابطه مالکیت.
نقشه بازار خروجی get_stats قابل استفاده درتحلیل general.market_map_data data.get_market_map P10؛ فقط داده؛نه رسم گرافیکی اجباری.
ذخیره CSV write_to_csv/to_csv؛دو export درواقع DataFrame می‌دهند امکان خروجی‌گیری از Polars؛dataset محلی data.save/load + ذخیره خودکار P05؛ نام تابع بااثرش سازگار؛دوام ذخیره مستقل از fetch.
Async بعضی توابع و asyncio.run دربعضی wrapper ها بخش عمده دریافت ناهمگام data.Client و data.AsyncClient P06؛ منطق مشترک؛sync بدون await وبدون run پنهانی.
ذخیره خودکار مقاوم واصلاحات قرارداد کامل مدنظر Dara دراین مرجع احراز نشده dataset محلی و cache بعضی شناسه‌ها؛قرارداد کامل احراز نشده PersistenceCoordinator/DatasetStore/revision ledger P05؛ قابلیت پیشنهادی Dara،نه نسبت‌دادن به دو بسته.
تحلیل وآموزش مدل تعدیل،نسبت‌هاوتجمیع محدود؛نهچارچوبجامع ML ابزار دریافت وتبدیل؛چارچوبجامع ML درمرجعنیست analytics و ml P07/P11؛ قابلیت‌های جدید پیشنهادی؛بدون I/O پنهان.
حساب رسمی و انرژی/مشتقه استفاده مستقیم از API احرازشده جدید درمدخل‌ها احراز نشده همچنین؛نباید مسیر CDN را با API احرازشده یکی گرفت OfficialProvider + قابلیت‌های شرطی P12؛ برپایه متن رسمی ارسالی،نه ادعای همه قابلیت‌های دو کتابخانه.

وابستگی‌ها و استثناهای مرجع

pytse-client در snapshot بررسی‌شده وابستگی‌هایی مانند pandas،requests،jdatetime،beautifulsoup4،tenacity،aiohttp و lxml دارد؛ بعضی مسیرها HTML/متن و بعضی JSON هستند. لازم نیست هر تابع همه این‌ها را در همان لحظه مصرف کند.

tsetmc در snapshot بررسی‌شده عمدتاً بر Polars و HTTP ناهمگام تکیه دارد و مسیرهای JSON و HTML/متنی را کنار هم دارد. LazyFrame خروجی همه متدها نیست؛ بعضی dict/list یا نوع شرطی می‌دهند.

برای هر تابع مرجع امضا وپیش‌فرض ونوع خروجی در02 آمده است. تضمین جامع فهرست exceptions توسط این پروژه‌ها در بررسی حاضر احراز نشده؛ نوع خطای شبکه/parser/وابستگی نیز می‌تواند نشت کند. خطاهای استاندارد تعریف‌شده Dara توصیف این بسته‌ها نیستند.

اصلاح‌های مهم نسبت به برداشت‌های ساده اولیه

Ticker در pytse-client می‌تواند حین ساخت تاریخچه دریافت و روزمعاملاتی را بررسی کند؛ برای Dara این وابستگی حذف می‌شود. adjClose الزاماً به معنی تعدیل شرکتی نیست. get_trade_details(aggregate=True) همچنان dict دارایکلید aggregate برمی‌گرداند. دو تابع export دارای csv درنام خود DataFrame می‌دهند.

Instrument.from_search اولین نتیجه را می‌گیرد؛Dara نتیجه مبهم را رد می‌کند. daily_closing_price(n=0) داده قابل ارائه منبع را درخواست و نزولی مرتب می‌کند؛Dara صعودی و با coverage خواهد بود. client_type_history با وبدونتاریخ نوع متفاوت دارد؛Dara خانواده جدول ثابت پیشنهاد می‌کند. on_date().best_limits() وجود دارد؛ پس تاریخچه مظنه در tsetmc صرفاً حدس نیست.

مرز استفاده از کد

دو پروژه مرجع یادگیری و مقایسه‌اند؛ هیچ‌کدام dependency اجباری Dara نیست. اقتباس کد و استفاده از مجوز آن باید جداگانه بررسی شود. حذف dependency به معنی حذف مسئولیت نگهداری اتصال یا مجوز داده نیست.

مرجع دو کتابخانه موجود — نسخه تثبیت‌شده

این بخش، ۱۷۰ مدخل مرجع نسخه ۰٫۱ را حفظ می‌کند: ۷۹ مدخل از pytse-client و ۹۱ مدخل از tsetmc. مدخل لزوماً یک تابع نیست؛ بعضی ویژگی، گروه ویژگی یا نوع داده‌اند. این عدد ادعای پوشش تمام توابع خصوصی یا تمام نسخه‌های آینده نیست. مبنای مقایسه: pytse-client 0.19.1 در b2ed0b97a7eeaca855935234cf416bcf1f5778b7 و tsetmc 5.1.0 در af5f4578fe4a21030759c8ed1cef3f72a00834ab. در این بازبینی، مسیرهای حساس دریافت تاریخچه، انواع خروجی و تفاوت رابط‌ها مجدداً از منبع خوانده شد؛ ادعای اجرای زنده همه توابع یا ممیزی امنیتی نداریم. امضاها، ورودی‌ها، پیش‌فرض‌ها، نوع خروجی، رفتار مهم و پیوند ثابت منبع در هر مدخل آمده‌اند. وجود تابع، سلامت فعلی سرور را اثبات نمی‌کند. فهرست جامع و تضمین‌شده استثناهای این دو پروژه در منبع اعلام نشده؛ خطاهای شبکه، parser و وابستگی‌ها ممکن است به بیرون منتقل شوند. قرارداد استثناهای «پیشنهادی Dara» در فایل‌های 03 تا 05 مستقل تعریف شده و نباید به این دو پروژه نسبت داده شود. وابستگی اجرایی Dara به این دو بسته وجود ندارد. هرگونه اقتباس از کد باید از حیث مجوز جداگانه بررسی شود.

مرجع بررسی‌شده دو کتابخانه بورسی

تاریخ بررسی: 2026-10-12

دامنه و سطح اعتبار

این فایل 170 مدخل از توابع، متدها، ویژگی‌ها و چند نوع/ساختار مهم را پوشش می‌دهد: 79 مدخل pytse-client و 91 مدخل tsetmc. شمار مدخل‌ها معیار برتری یا شمار کل APIهای هر کتابخانه نیست. توابع کمکی خصوصی parser، همه آزمون‌ها، نمونه‌ها و متدهای استاندارد پایتون در این فهرست نیامده‌اند.

  • pytse-client: نسخه اعلام‌شده 0.19.1، snapshot کد b2ed0b97a7eeaca855935234cf416bcf1f5778b7.
  • tsetmc: commit انتشار 5.1.0، af5f4578fe4a21030759c8ed1cef3f72a00834ab.
  • شاخه توسعه tsetmc در زمان خواندن 5.1.1.dev1 بود؛ مبنای این مرجع آن شاخه نیست.
  • کد منبع بررسی شد؛ همه توابع بر داده زنده اجرا نشده‌اند. موفقیت نصب، صحت تمام داده و پوشش همه سال‌ها اثبات نشده است.
  • امضاها برای خوانایی با حذف self/cls و گاهی تبدیل aliasهای واردشده به نام شناخته‌شده نمایش داده شده‌اند؛ byte-for-byte کپی source نیستند.
  • نوع پس از await نوشته شده است. خود فراخوانی تابع async بدون await یک coroutine می‌دهد.
  • در توابع فاقد annotation، نوع خروجی از مسیر return استنباط شده؛ annotation هم در برخی موارد با نوع واقعی ناسازگار است که توضیح داده شده.
  • TypedDict در زمان اجرا dict است؛ کلاس مدل اعتبارسنجی‌شده نیست.
  • LF = polars.LazyFrame؛ DF = pandas.DataFrame. LazyFrame بودن به معنی معلق بودن درخواست اینترنت نیست: در این توابع درخواست در await انجام شده و پردازش جدولی می‌تواند تنبل باشد.
  • str تاریخ، date و datetime یکسان نیستند. کلید dict و ستون جدول را نیز از یکدیگر جدا می‌کنیم.

یافته‌های تعیین‌کننده برای طراحی Dara

  1. سازنده Ticker تاریخچه/آخرین روز معاملاتی را بررسی می‌کند؛ برای دریافت قیمت جاری وابستگی اضافی ایجاد می‌شود.
  2. نام adjClose در pytse-client به‌تنهایی به معنی قیمت تعدیل‌شده شرکتی نیست.
  3. all_symbols از فایل محلی خوانده می‌شود؛ فهرست زنده و کامل تاریخی نیست.
  4. from_search در tsetmc اولین نتیجه را انتخاب می‌کند؛ برای رفع ابهام نماد کافی نیست.
  5. client_type_history در tsetmc بسته به date، dict یا LazyFrame می‌دهد.
  6. get_trade_details در pytse-client حتی در حالت aggregate دیکشنری با کلید aggregate می‌دهد.
  7. get_orderbook خروجی روزها را با کلید str می‌دهد، ولی get_trade_details معمولی در اجرا از date به عنوان کلید استفاده می‌کند.
  8. برخی پیش‌فرض‌های زمانی datetime.now() هنگام تعریف تابع ارزیابی می‌شوند.
  9. دریافت‌های همگام متکی به asyncio.run می‌توانند در محیط با event loop فعال مشکل‌ساز شوند؛ Dara باید دو رابط بومی داشته باشد.
  10. تاریخچه مظنه در tsetmc صریحاً وجود دارد؛ وضعیت آن در بررسی‌های اولیه نباید «نامعلوم» باقی بماند.
  11. closing_price_all در tsetmc به سابقه مورد استفاده فیلترها مربوط است؛ صرفاً آخرین snapshot همه نمادها نیست.
  12. dataset.update در tsetmc فیلترهایی دارد؛ نباید آن را فهرست بی‌قید همه ابزارهای بورس نامید.
  13. توابع export دارای csv در نام در pytse-client می‌توانند تنها DataFrame برگردانند و خود فایل ننویسند.
  14. از وجود متد نمی‌توان سلامت فعلی endpoint، دامنه تاریخی، مجوز داده و محدودیت نرخ را نتیجه گرفت.

راهنمای خواندن وضعیت

source_reviewed = کد دیده شده؛ deprecated_source_reviewed = در منبع منسوخ اعلام شده؛ experimental_source_reviewed = در منبع آزمایشی؛ internal_exposed_not_stable = دسترسی داخلی/غیرتثبیت‌شده.

مرجع اصلی

P001 — download

کتابخانه: pytse-client — ماژول: pytse_client/download.py

download(symbols: Union[List, str], write_to_csv: bool = False, include_jdate: bool = False, base_path: str = config.DATA_BASE_PATH, adjust: bool = False) -> Dict[str, pd.DataFrame]

کاربرد: دریافت تاریخچه روزانه یک یا چند نماد.

ورودی و پیش‌فرض: symbols: رشته نام نماد یا فهرست رشته‌ها؛ 'all' فهرست محلی کتابخانه را انتخاب می‌کند. write_to_csv: bool برای ذخیره؛ include_jdate: bool برای افزودن تاریخ شمسی؛ base_path: str مسیر نسبی یا مطلق. adjust: bool؛ پیش‌فرض False. مقدار پیش‌فرض base_path برابر 'tickers_data' است.

نوع خروجی: dict[str, pandas.DataFrame]

ساختار خروجی: date, open, high, low, close, adjClose, volume, count, value, yesterday؛ jdate اختیاری. close از و adjClose از می‌آید؛ نام adjClose به‌تنهایی تعدیل شرکتی را ثابت نمی‌کند.

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

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/download.py

P002 — download_financial_indexes

کتابخانه: pytse-client — ماژول: pytse_client/download.py

download_financial_indexes(symbols: Union[List, str], write_to_csv: bool = False, include_jdate: bool = False, base_path: str = config.FINANCIAL_INDEX_BASE_PATH) -> Dict[str, pd.DataFrame]

کاربرد: تاریخچه شاخص‌ها.

ورودی و پیش‌فرض: symbols: رشته نام شاخص یا فهرست رشته‌ها؛ 'all' فهرست محلی کتابخانه را انتخاب می‌کند. write_to_csv: bool برای ذخیره؛ include_jdate: bool برای افزودن تاریخ شمسی؛ base_path: str مسیر نسبی یا مطلق. پیش‌فرض مسیر 'financial_index_data' است.

نوع خروجی: dict[str, pandas.DataFrame]

ساختار خروجی: date, high, low, open, close, volume؛ jdate اختیاری.

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

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/download.py

P003 — download_client_types_records

کتابخانه: pytse-client — ماژول: pytse_client/download.py

download_client_types_records(symbols: Union[List, str], write_to_csv: bool = False, include_jdate: bool = False, base_path: str = config.CLIENT_TYPES_DATA_BASE_PATH)

کاربرد: تاریخچه حقیقی و حقوقی برای یک یا چند نماد.

ورودی و پیش‌فرض: symbols: رشته نام نماد یا فهرست رشته‌ها؛ 'all' فهرست محلی کتابخانه را انتخاب می‌کند. write_to_csv: bool برای ذخیره؛ include_jdate: bool برای افزودن تاریخ شمسی؛ base_path: str مسیر نسبی یا مطلق. پیش‌فرض مسیر 'client_types_data' است.

نوع خروجی: dict[str, pandas.DataFrame]؛ استنباط از return

ساختار خروجی: date؛ individual/corporate × buy/sell × count/vol/value؛ چهار mean_price؛ individual_ownership_change؛ jdate اختیاری.

ملاحظه: نوع بازگشت در امضای منبع نوشته نشده است. بعضی نمادهای ناموفق از دیکشنری حذف می‌شوند؛ گزارش موفقیت جزئی ساختاریافته ندارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/download.py

P004 — adjust_price

کتابخانه: pytse-client — ماژول: pytse_client/download.py

adjust_price(df: pd.DataFrame) -> pd.DataFrame

کاربرد: تعدیل محاسباتی تاریخچه از نسبت‌های قیمت.

ورودی و پیش‌فرض: df: pandas.DataFrame با RangeIndex و ستون‌های مورد نیاز تاریخچه.

نوع خروجی: pandas.DataFrame

ساختار خروجی: همان ستون‌های ورودی؛ open/high/low/close/adjClose/yesterday ممکن است تغییر کنند.

ملاحظه: داده خالی یا فاقد RangeIndex همان‌طور بازگردانده می‌شود. ستون‌های قیمت تغییر می‌کنند و گرد می‌شوند؛ حجم در این تابع تعدیل نمی‌شود. این تابع کمکی ماژول download است، نه نام بازصادرشده ریشه بسته.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/download.py

P005 — all_symbols

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

all_symbols() -> Set

کاربرد: فهرست نام نمادها

ورودی و پیش‌فرض: ورودی صریح ندارد؛ برای متدها شناسه/تنظیمات از شیء گرفته می‌شود.

نوع خروجی: set[str]؛ نوع عضو استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: از فایل symbols_name.json و حافظه داخلی می‌خواند، نه فهرست زنده تضمین‌شده.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P006 — symbols_information

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

symbols_information() -> Dict[str, Dict]

کاربرد: اطلاعات محلی نمادها

ورودی و پیش‌فرض: ورودی صریح ندارد؛ برای متدها شناسه/تنظیمات از شیء گرفته می‌شود.

نوع خروجی: dict[str, dict]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: کلید اصلی نام نماد؛ مقادیر شامل index, code, name, old.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P007 — get_ticker_index

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

get_ticker_index(ticker_symbol: str) -> Optional[str]

کاربرد: کد جاری ذخیره‌شده برای نماد

ورودی و پیش‌فرض: ticker_symbol: str نام نماد

نوع خروجی: str | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: مراجعه به نگاشت محلی.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P008 — get_ticker_old_index

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

get_ticker_old_index(ticker_symbol: str) -> List[str]

کاربرد: کدهای قدیمی نماد

ورودی و پیش‌فرض: ticker_symbol: str

نوع خروجی: list[str]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نبود نگاشت با فهرست خالی پاسخ داده می‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P009 — all_financial_index

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

all_financial_index() -> Set

کاربرد: نام شاخص‌های محلی

ورودی و پیش‌فرض: ورودی صریح ندارد؛ برای متدها شناسه/تنظیمات از شیء گرفته می‌شود.

نوع خروجی: set[str]؛ نوع عضو استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: از indices_name.json.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P010 — financial_indexes_information

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

financial_indexes_information() -> Dict[str, Dict]

کاربرد: مشخصات محلی شاخص‌ها

ورودی و پیش‌فرض: ورودی صریح ندارد؛ برای متدها شناسه/تنظیمات از شیء گرفته می‌شود.

نوع خروجی: dict[str, dict]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P011 — get_financial_index

کتابخانه: pytse-client — ماژول: pytse_client/symbols_data.py

get_financial_index(financial_index_name: str)

کاربرد: یافتن شناسه شاخص

ورودی و پیش‌فرض: financial_index_name: str

نوع خروجی: str | None؛ استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع بازگشت در منبع تصریح نشده.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/symbols_data.py

P012 — get_orderbook

کتابخانه: pytse-client — ماژول: pytse_client/orderbook/order_book.py

get_orderbook(symbol_name: str, start_date: datetime.date, end_date: Optional[datetime.date] = None, to_csv: bool = False, base_path: Optional[str] = None, ignore_date_validation: bool = False, diff_orderbook: bool = False, async_requests: bool = True) -> Dict[str, pd.DataFrame]

کاربرد: تاریخچه مظنه‌های یک نماد.

ورودی و پیش‌فرض: symbol_name: نام نماد. start_date: date میلادی. end_date: date|None، None یعنی همان روز شروع. to_csv: bool. base_path: str|None، مسیر پیش‌فرض orderbook_hist_data. ignore_date_validation: bool؛ از کنترل معامله‌بودن دو سر بازه صرف‌نظر می‌کند. diff_orderbook: bool؛ True تغییرات و False بازسازی جدول پهن. async_requests: bool؛ روش داخلی دریافت.

نوع خروجی: dict[str, pandas.DataFrame]

ساختار خروجی: diff=True: DatetimeIndex و depth,bid,ask,vol_bid,vol_ask,num_bid,num_ask. diff=False: ستون‌های bid_1...num_ask_5، با پرکردن رو به جلو درون خروجی همان روز.

ملاحظه: با وجود async_requests، تابع عمومی همگام است. از Ticker و پردازش چندفرایندی استفاده می‌کند. کلید دیکشنری تاریخ به شکل YYYY-MM-DD است. تابع پردازش، refID را حذف می‌کند؛ در tse-dara حذف شناسه ترتیبی توصیه نمی‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/orderbook/order_book.py

P013 — get_trade_details

کتابخانه: pytse-client — ماژول: pytse_client/historical_intraday/trade_details.py

get_trade_details(symbol_name: str, start_date: datetime.date, end_date: Optional[datetime.date] = None, to_csv: bool = False, base_path: Optional[str] = None, timeframe: Optional[str] = None, aggregate: bool = False) -> Dict[str, pd.DataFrame]

کاربرد: ریزمعاملات تاریخی یا میله‌های تجمیع‌شده درون‌روز.

ورودی و پیش‌فرض: symbol_name: str. start_date/end_date: date میلادی؛ None پایان یعنی شروع. to_csv: bool. base_path: str|None، پیش‌فرض trade_details_history. timeframe: None یا '30s','1m','5m','10m','15m','30m','1h'. aggregate: bool.

نوع خروجی: dict[datetime.date, pandas.DataFrame] یا dict[str, pandas.DataFrame]؛ کلید واقعی از کد، نه annotation

ساختار خروجی: بدون timeframe: DatetimeIndex + price,volume. با timeframe: DatetimeIndex + open,high,low,close,volume.

ملاحظه: aggregate=True خروجی را به {'aggregate': DataFrame} تبدیل می‌کند؛ خود DataFrame برنمی‌گرداند. پیاده‌سازی داخلی asyncio.run دارد. ابهام نقش فلگ انتهای API در معاملات لغوشده باید جداگانه بررسی شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/historical_intraday/trade_details.py

P014 — get_stats

کتابخانه: pytse-client — ماژول: pytse_client/stats.py

get_stats(base_path=None, to_csv=False) -> pd.DataFrame

کاربرد: تجمیع آمار کلیدی، اطلاعات دیده‌بان و حقیقی‌حقوقی.

ورودی و پیش‌فرض: base_path: str|None استنباطی؛ پیش‌فرض stats_data. to_csv: bool استنباطی.

نوع خروجی: pandas.DataFrame

ساختار خروجی: symbol,name,index و مجموعه ستون‌های key stats، client types و market watch؛ ستون‌های ناموجود None و عددی‌سازی با coerce.

ملاحظه: چند پاسخ مختلف با زمان‌های دریافت جدا ادغام می‌شوند؛ لزوماً یک عکس هم‌زمان نیست. جدول کاملِ رسمی همه ابزارهای بازار محسوب نمی‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/stats.py

P015 — get_asks_and_bids

کتابخانه: pytse-client — ماژول: pytse_client/asks_bids.py

get_asks_and_bids(to_csv=False, base_path=None)

کاربرد: مظنه‌های دیده‌بان بازار.

ورودی و پیش‌فرض: to_csv: bool استنباطی. base_path: str|None استنباطی؛ پیش‌فرض asks_bids_data.

نوع خروجی: pandas.DataFrame؛ استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نمادهایی که شناسه‌شان در نگاشت محلی نیست حذف می‌شوند. تبدیل کامل نوع عددی در این تابع انجام نمی‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/asks_bids.py

P016 — Ticker

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker(symbol: str, index: Optional[str] = None, adjust: bool = False)

کاربرد: شیء دسترسی به اطلاعات یک نماد.

ورودی و پیش‌فرض: symbol: نام نماد؛ index: str|None کد داخلی برای نماد قدیمی یا تعیین دستی؛ adjust: bool برای تاریخچه.

نوع خروجی: Ticker

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: سازنده عملیات I/O و دریافت تاریخچه انجام می‌دهد و get_last_trade_day را فراخوانی می‌کند؛ علت وابستگی دریافت قیمت به سرویس تاریخی در تجربه این پروژه.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P017 — Ticker.get_ticker_real_time_info_response

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.get_ticker_real_time_info_response() -> RealtimeTickerInfo

کاربرد: دریافت مجموعه اطلاعات قیمتی، مظنه‌ها و حقیقی‌حقوقی.

ورودی و پیش‌فرض: بدون ورودی افزون بر شیء نماد.

نوع خروجی: RealtimeTickerInfo؛ dataclass

ساختار خروجی: date_time,state,last_price,adj_close,yesterday_price,open_price,high_price,low_price,count,volume,value,last_date,best_demand_vol,best_demand_price,best_supply_vol,best_supply_price,sell_orders,buy_orders,individual_trade_summary,corporate_trade_summary,nav,nav_date,market_cap.

ملاحظه: بسیاری از اعضا Optional هستند؛ عددهای قیمتی با وجود annotation نوع float در مسیر اصلی با int ساخته می‌شوند. last_date زمان اطلاعات برگشتی است؛ نباید بدون تأیید معنایی آخرین معامله قطعی نامیده شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P018 — Ticker.get_trade_details

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.get_trade_details()

کاربرد: ریزمعاملات روز جاری/آخرین خروجی سرویس نماد.

ورودی و پیش‌فرض: بدون پارامتر تاریخ.

نوع خروجی: pandas.DataFrame؛ استنباطی

ساختار خروجی: date از نوع datetime.time؛ volume عدد صحیح؛ price اعشاری.

ملاحظه: این متد با تابع ریشه get_trade_details که بازه تاریخی می‌گیرد یکی نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P019 — Ticker.get_shareholders_history

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.get_shareholders_history(from_when=datetime.timedelta(days=90), to_when=datetime.datetime.now(), only_trade_days=True, session=None) -> pd.DataFrame

کاربرد: تاریخچه سهامداران عمده.

ورودی و پیش‌فرض: from_when: timedelta استنباطی. to_when: datetime استنباطی. only_trade_days: bool استنباطی. session: aiohttp.ClientSession|None استنباطی.

نوع خروجی: pandas.DataFrame پس از await در نسخه async

ساختار خروجی: date,shareholder_id,shareholder_shares,shareholder_percentage,shareholder_instrument_id,shareholder_name,change.

ملاحظه: پیش‌فرض datetime.now() در زمان تعریف تابع ارزیابی می‌شود، نه هر بار فراخوانی. نسخه همگام از asyncio.run استفاده می‌کند؛ برای حلقه رویداد فعال مناسب نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P020 — async Ticker.get_shareholders_history_async

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

async Ticker.get_shareholders_history_async(from_when=datetime.timedelta(days=90), to_when=datetime.datetime.now(), only_trade_days=True, session=None) -> pd.DataFrame

کاربرد: تاریخچه سهامداران عمده.

ورودی و پیش‌فرض: from_when: timedelta استنباطی. to_when: datetime استنباطی. only_trade_days: bool استنباطی. session: aiohttp.ClientSession|None استنباطی.

نوع خروجی: pandas.DataFrame پس از await در نسخه async

ساختار خروجی: date,shareholder_id,shareholder_shares,shareholder_percentage,shareholder_instrument_id,shareholder_name,change.

ملاحظه: پیش‌فرض datetime.now() در زمان تعریف تابع ارزیابی می‌شود، نه هر بار فراخوانی. نسخه همگام از asyncio.run استفاده می‌کند؛ برای حلقه رویداد فعال مناسب نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P021 — async Ticker.get_total_shares_history_async

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

async Ticker.get_total_shares_history_async(from_when=datetime.timedelta(days=60), to_when=datetime.datetime.now(), only_open_days=True, session=None) -> pd.DataFrame

کاربرد: تاریخچه تعداد سهام.

ورودی و پیش‌فرض: from_when: timedelta؛ to_when: datetime؛ only_open_days: bool؛ session: aiohttp.ClientSession|None. این نوع‌ها از کد استنباط شده‌اند.

نوع خروجی: pandas.DataFrame پس از await

ساختار خروجی: date,total_shares.

ملاحظه: نام درست پارامتر only_open_days است، نه only_trade_days. این تفاوت میان README و پیاده‌سازی باید در استفاده لحاظ شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P022 — Ticker.get_last_trade_day

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.get_last_trade_day()

کاربرد: آخرین روز معاملاتی سرویس قدیمی.

ورودی و پیش‌فرض: classmethod، بدون پارامتر عمومی.

نوع خروجی: datetime.date؛ استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: درخواست مستقیم به سرویس تنظیم‌شده؛ خطای شبکه به caller منتقل می‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P023 — Ticker.from_file

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.from_file() -> pd.DataFrame

کاربرد: خواندن تاریخچه از CSV تنظیم‌شده شیء.

ورودی و پیش‌فرض: بدون ورودی عمومی.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ستون date به datetime تبدیل می‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P024 — Ticker.history [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.history  [property]

کاربرد: تاریخچه نگهداری‌شده در شیء

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P025 — Ticker.client_types [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.client_types  [property]

کاربرد: تاریخچه حقیقی‌حقوقی با درخواست در دسترسی

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P026 — Ticker.shareholders [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.shareholders  [property]

کاربرد: سهامداران عمده؛ ستون‌های shareholder,shares,percentage,change

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P027 — Ticker.trade_dates [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.trade_dates  [property]

کاربرد: روزهای موجود در تاریخچه نماد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: list[datetime.date]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P028 — Ticker.url [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.url  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P029 — Ticker.index [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.index  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P030 — Ticker.instrument_id [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.instrument_id  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P031 — Ticker.ci_sin [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.ci_sin  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P032 — Ticker.title [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.title  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P033 — Ticker.fulltitle [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.fulltitle  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P034 — Ticker.group_name [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.group_name  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P035 — Ticker.flow [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.flow  [property]

کاربرد: شناسه یا متن مشخصات؛ بعضی اعضا از HTML استخراج می‌شوند

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P036 — Ticker.fiscal_year [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.fiscal_year  [property]

کاربرد: سال مالی

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P037 — Ticker.p_e_ratio [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.p_e_ratio  [property]

کاربرد: نسبت‌ها و داده بنیادی؛ معنای اقتصادی PSR/SPS را باید جداگانه تأیید کرد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P038 — Ticker.group_p_e_ratio [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.group_p_e_ratio  [property]

کاربرد: نسبت‌ها و داده بنیادی؛ معنای اقتصادی PSR/SPS را باید جداگانه تأیید کرد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P039 — Ticker.eps [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.eps  [property]

کاربرد: نسبت‌ها و داده بنیادی؛ معنای اقتصادی PSR/SPS را باید جداگانه تأیید کرد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P040 — Ticker.p_s_ratio [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.p_s_ratio  [property]

کاربرد: نسبت‌ها و داده بنیادی؛ معنای اقتصادی PSR/SPS را باید جداگانه تأیید کرد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P041 — Ticker.psr [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.psr  [property]

کاربرد: نسبت‌ها و داده بنیادی؛ معنای اقتصادی PSR/SPS را باید جداگانه تأیید کرد

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P042 — Ticker.total_shares [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.total_shares  [property]

کاربرد: تعداد سهام و حجم مبنا با نوع اعشاری منبع

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در منبع

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P043 — Ticker.base_volume [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.base_volume  [property]

کاربرد: تعداد سهام و حجم مبنا با نوع اعشاری منبع

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در منبع

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P044 — Ticker.sta_max [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.sta_max  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P045 — Ticker.sta_min [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.sta_min  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P046 — Ticker.min_week [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.min_week  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P047 — Ticker.max_week [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.max_week  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P048 — Ticker.min_year [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.min_year  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P049 — Ticker.max_year [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.max_year  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P050 — Ticker.float_shares [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.float_shares  [property]

کاربرد: کران‌های قیمت و درصد شناوری گزارش‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: float در annotation؛ decorator ممکن است None برگرداند

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P051 — Ticker.month_average_volume [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.month_average_volume  [property]

کاربرد: میانگین حجم ماه به صورت رشته در منبع

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P052 — Ticker.state [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.state  [property]

کاربرد: وضعیت

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P053 — Ticker.last_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.last_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P054 — Ticker.adj_close [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.adj_close  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P055 — Ticker.yesterday_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.yesterday_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P056 — Ticker.open_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.open_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P057 — Ticker.high_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.high_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P058 — Ticker.low_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.low_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P059 — Ticker.best_demand_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.best_demand_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P060 — Ticker.best_supply_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.best_supply_price  [property]

کاربرد: قیمت‌ها؛ adj_close پایانی است، نه الزاماً قیمت تعدیل‌شده

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در مسیر اصلی؛ DTO: float | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P061 — Ticker.count [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.count  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P062 — Ticker.volume [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.volume  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P063 — Ticker.value [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.value  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P064 — Ticker.best_demand_vol [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.best_demand_vol  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P065 — Ticker.best_supply_vol [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.best_supply_vol  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P066 — Ticker.nav [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.nav  [property]

کاربرد: مقادیر جاری از پاسخ اطلاعات لحظه‌ای

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P067 — Ticker.last_date [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.last_date  [property]

کاربرد: زمان اطلاعات سرویس

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: datetime.datetime | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P068 — Ticker.nav_date [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.nav_date  [property]

کاربرد: زمان NAV خام

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: str | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P069 — Ticker.market_cap [property]

کتابخانه: pytse-client — ماژول: pytse_client/ticker/ticker.py

Ticker.market_cap  [property]

کاربرد: ارزش بازار محاسبه‌شده از پایانی و تعداد سهام

ورودی و پیش‌فرض: بدون آرگومان؛ با property استفاده می‌شود.

نوع خروجی: int | None در DTO؛ در محاسبه ممکن است float

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اگر به پاسخ لحظه‌ای وابسته باشد، خواندن چند property می‌تواند چند درخواست جدا ارسال کند. دریافت snapshot یکجا برای کار جدید ترجیح دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/ticker.py

P070 — FinancialIndex

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex(symbol: str, index: Optional[str] = None, base_path: Optional[str] = config.FINANCIAL_INDEX_BASE_PATH, write_history: Optional[bool] = False)

کاربرد: شیء شاخص مالی.

ورودی و پیش‌فرض: symbol: str نام شاخص. index: str|None شناسه. base_path: str|None پیش‌فرض financial_index_data. write_history: bool|None؛ عموماً bool.

نوع خروجی: FinancialIndex

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: خواندن propertyها ممکن است به HTML و دانلود تاریخچه مراجعه کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P071 — FinancialIndex.history [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.history  [property]

کاربرد: تاریخچه شاخص با include_jdate=True

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P072 — FinancialIndex.intraday_price [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.intraday_price  [property]

کاربرد: time index؛ value,change_percentage,low,high

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: pandas.DataFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P073 — FinancialIndex.contributing_symbols [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.contributing_symbols  [property]

کاربرد: کلیدهای symbol و index

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: list[dict[str,str]]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P074 — FinancialIndex.last_update [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.last_update  [property]

کاربرد: ساعت انتشار به شکل HH:MM

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P075 — FinancialIndex.last_value [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.last_value  [property]

کاربرد: آخرین مقدار

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: float

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P076 — FinancialIndex.high [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.high  [property]

کاربرد: بیشینه روز به صورت متن در این پیاده‌سازی

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P077 — FinancialIndex.low [property]

کتابخانه: pytse-client — ماژول: pytse_client/financial_index/financial_index.py

FinancialIndex.low  [property]

کاربرد: کمینه روز به صورت متن در این پیاده‌سازی

ورودی و پیش‌فرض: بدون پارامتر.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع‌های فاقد annotation از return و تبدیل‌های داخل تابع استنباط شده‌اند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/financial_index/financial_index.py

P078 — ticker_real_time_data_to_csv

کتابخانه: pytse-client — ماژول: pytse_client/ticker/export.py

ticker_real_time_data_to_csv(ticker: Ticker)

کاربرد: جدول یک‌ردیفی اطلاعات جاری و بنیادی

ورودی و پیش‌فرض: ticker: Ticker.

نوع خروجی: pandas.DataFrame؛ استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: با وجود نام csv، فایل نمی‌نویسد؛ caller باید to_csv را فراخوانی کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/export.py

P079 — export_ticker_history_as_csv

کتابخانه: pytse-client — ماژول: pytse_client/ticker/export.py

export_ticker_history_as_csv(ticker: Ticker)

کاربرد: outer join تاریخچه قیمت و حقیقی‌حقوقی بر date

ورودی و پیش‌فرض: ticker: Ticker.

نوع خروجی: pandas.DataFrame؛ استنباطی

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: با وجود نام csv، فایل نمی‌نویسد؛ caller باید to_csv را فراخوانی کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/Glyphack/pytse-client/blob/b2ed0b97a7eeaca855935234cf416bcf1f5778b7/pytse_client/ticker/export.py

T001 — Instrument

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

Instrument(code: str | int, l18: str | None = None, l30: str | None = None)

کاربرد: ساخت نماینده یک ابزار مالی بر اساس شناسه.

ورودی و پیش‌فرض: code: شناسه داخلی؛ l18 و l30: نام کوتاه و بلند اختیاری.

نوع خروجی: Instrument

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: سازنده فقط ویژگی‌ها را مقداردهی می‌کند؛ برخلاف Ticker در کتابخانه دیگر تاریخچه را دریافت نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T002 — await instrument.l18

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

await instrument.l18

کاربرد: نام کوتاه نماد

ورودی و پیش‌فرض: ویژگی ناهمگام؛ ورودی صریح ندارد.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ممکن است از داده محلی، مقدار ذخیره‌شده در شیء یا درخواست اطلاعات نماد استفاده کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T003 — await instrument.l30

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

await instrument.l30

کاربرد: نام بلند

ورودی و پیش‌فرض: ویژگی ناهمگام؛ ورودی صریح ندارد.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ممکن است از داده محلی، مقدار ذخیره‌شده در شیء یا درخواست اطلاعات نماد استفاده کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T004 — await instrument.isin

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

await instrument.isin

کاربرد: شناسه ابزار (instrumentID)

ورودی و پیش‌فرض: ویژگی ناهمگام؛ ورودی صریح ندارد.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ممکن است از داده محلی، مقدار ذخیره‌شده در شیء یا درخواست اطلاعات نماد استفاده کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T005 — await instrument.cisin

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

await instrument.cisin

کاربرد: شناسه cIsin

ورودی و پیش‌فرض: ویژگی ناهمگام؛ ورودی صریح ندارد.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ممکن است از داده محلی، مقدار ذخیره‌شده در شیء یا درخواست اطلاعات نماد استفاده کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T006 — await instrument.cs

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

await instrument.cs

کاربرد: کد صنعت

ورودی و پیش‌فرض: ویژگی ناهمگام؛ ورودی صریح ندارد.

نوع خروجی: str

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ممکن است از داده محلی، مقدار ذخیره‌شده در شیء یا درخواست اطلاعات نماد استفاده کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T007 — async Instrument.from_l18

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.from_l18(l18: str, /) -> Instrument

کاربرد: شناسایی نماد و ساخت شیء.

ورودی و پیش‌فرض: l18: نام کوتاه نماد؛ فقط موضعی.

نوع خروجی: Instrument

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: ابتدا دیتاست محلی؛ سپس from_search. تطبیق یکتای دقیق تضمین نشده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T008 — async Instrument.from_isin

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.from_isin(isin: str, /) -> Instrument

کاربرد: شناسایی نماد و ساخت شیء.

ورودی و پیش‌فرض: isin: شناسه instrumentID؛ فقط موضعی.

نوع خروجی: Instrument

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در این پیاده‌سازی تنها در دیتاست محلی جست‌وجو می‌کند؛ نبود نتیجه KeyError می‌دهد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T009 — async Instrument.from_search

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.from_search(s: str) -> Instrument

کاربرد: شناسایی نماد و ساخت شیء.

ورودی و پیش‌فرض: s: عبارت جست‌وجو.

نوع خروجی: Instrument

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اولین نتیجه search(s) انتخاب می‌شود؛ نبود نتیجه ممکن است IndexError بدهد. برای رفع ابهام قابل اتکا نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T010 — async Instrument.info

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.info() -> InstrumentInfo (TypedDict؛ در اجرا dict)

کاربرد: اطلاعات پایه ابزار.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: InstrumentInfo (TypedDict؛ در اجرا dict)

ساختار خروجی: نام، شناسه‌ها، بازار، صنعت، تعداد سهام، EPS و آستانه‌ها؛ داده‌ها در فیلدهای تودرتو هستند.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T011 — async Instrument.identity

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.identity() -> Identity (TypedDict؛ در اجرا dict)

کاربرد: اطلاعات هویتی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: Identity (TypedDict؛ در اجرا dict)

ساختار خروجی: sector, subSector, insCode, instrumentID, cIsin, lVal18AFC, lVal30, flow و سایر فیلدها.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T012 — async Instrument.closing_price_info

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.closing_price_info() -> ClosingPriceInfo (TypedDict؛ در اجرا dict)

کاربرد: آخرین وضعیت قیمت و معاملات.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: ClosingPriceInfo (TypedDict؛ در اجرا dict)

ساختار خروجی: pDrCotVal, pClosing, priceYesterday, priceFirst, priceMin, priceMax, zTotTran, qTotTran5J, qTotCap, dEven, hEven و وضعیت نماد.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T013 — async Instrument.daily_closing_price

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.daily_closing_price(n=0) -> polars.LazyFrame

کاربرد: تاریخچه روزانه.

ورودی و پیش‌فرض: n: int استنباط‌شده؛ 0 درخواست همه داده قابل ارائه و مقدار مثبت تعداد روز.

نوع خروجی: polars.LazyFrame

ساختار خروجی: فیلدهای قیمت، حجم، ارزش، تعداد و شناسه؛ ستون‌های date/time/datetime ساخته می‌شوند؛ مرتب‌سازی تاریخ نزولی است.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.n=0 تضمین قدمت یا کامل‌بودن تمام تاریخچه بازار نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T014 — async Instrument.price_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.price_history(adjusted: bool = True) -> polars.LazyFrame

کاربرد: تاریخچه قیمت از سرویس نمودار.

ورودی و پیش‌فرض: adjusted: bool؛ پارامتر a سرویس نمودار.

نوع خروجی: polars.LazyFrame

ساختار خروجی: date, pmax, pmin, pf, pl, tvol, pc

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند. از members.tsetmc.com و قالب متنی استفاده می‌کند، نه API جدید JSON.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T015 — async Instrument.price_adjustments

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.price_adjustments() -> polars.LazyFrame

کاربرد: رویدادهای تعدیل قیمت گزارش‌شده.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: محتوای priceAdjust؛ dEven به Date تبدیل می‌شود. فرمول و معنای هر رویداد باید جدا بررسی شود.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T016 — async Instrument.trades

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.trades() -> polars.LazyFrame

کاربرد: معاملات نماد از مسیر GetTrade.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: فیلدهای trade مطابق پاسخ سرور؛ تاریخ صریح در ورودی ندارد.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T017 — async Instrument.best_limits

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.best_limits() -> polars.LazyFrame

کاربرد: مظنه‌های برتر فعلی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: فیلدهای bestLimits مطابق پاسخ سرور.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T018 — async Instrument.client_type

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.client_type() -> ClientType (TypedDict؛ در اجرا dict)

کاربرد: آمار حقیقی و حقوقی فعلی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: ClientType (TypedDict؛ در اجرا dict)

ساختار خروجی: buy_I_Volume, buy_N_Volume, buy_CountI, buy_CountN و همتایان فروش؛ برخی فیلدهای DDD نیز تعریف شده‌اند.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T019 — async Instrument.client_type_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.client_type_history(date: int | str | None = None) -> polars.LazyFrame | ClientTypeOnDate

کاربرد: تاریخچه حقیقی و حقوقی.

ورودی و پیش‌فرض: date: تاریخ میلادی YYYYMMDD به صورت int یا str، یا None.

نوع خروجی: polars.LazyFrame | ClientTypeOnDate

ساختار خروجی: date=None: کل تاریخچه به صورت LazyFrame؛ date معین: dict یک روز. تغییر نوع خروجی به ورودی وابسته است.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T020 — async Instrument.etf

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.etf() -> ETF (TypedDict؛ در اجرا dict)

کاربرد: اطلاعات ETF از جمله NAV.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: ETF (TypedDict؛ در اجرا dict)

ساختار خروجی: insCode, deven, hEven, pRedTran, pSubTran, iClose؛ فقط برای ETF معتبر است.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T021 — async Instrument.related_companies

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.related_companies(cs=None) -> dict[str, polars.LazyFrame]

کاربرد: شرکت‌های مرتبط بر مبنای صنعت.

ورودی و پیش‌فرض: cs: str | None استنباط‌شده؛ None کد صنعت خود ابزار را به کار می‌برد.

نوع خروجی: dict[str, polars.LazyFrame]

ساختار خروجی: کلیدهای relatedCompany و relatedCompanyThirtyDayHistory.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T022 — async Instrument.share_holders

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.share_holders() -> list[ShareHolder]

کاربرد: سهامداران عمده فعلی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: list[ShareHolder]

ساختار خروجی: shareHolderID, shareHolderName, cIsin, dEven, numberOfShares, perOfShares, change, changeAmount, shareHolderShareID.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T023 — async Instrument.share_holder_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.share_holder_history(share_holder_id: int, days: int = 90) -> polars.LazyFrame

کاربرد: تغییرات سهام یک سهامدار در همین نماد.

ورودی و پیش‌فرض: شناسه سهامدار از share_holders؛ days طول بازه در روز.

نوع خروجی: polars.LazyFrame

ساختار خروجی: فیلدهای shareHolder؛ dEven به Date تبدیل می‌شود.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T024 — async Instrument.messages

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.messages() -> list[Message]

کاربرد: پیام‌های ناظر مرتبط با نماد.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: list[Message]

ساختار خروجی: tseMsgIdn, dEven, hEven, tseTitle, tseDesc, flow.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T025 — async Instrument.codal

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.codal(n=9) -> list[Codal]

کاربرد: فراده‌های اطلاعیه‌های کدال مرتبط.

ورودی و پیش‌فرض: n: int استنباط‌شده؛ تعداد درخواست‌شده.

نوع خروجی: list[Codal]

ساختار خروجی: عنوان، ناشر، تاریخ ارسال و انتشار، شماره پیگیری و نشانگر پیوست‌ها؛ معادل تحلیل کامل صورت‌های مالی نیست.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T026 — async Instrument.publisher

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.publisher() -> dict

کاربرد: اطلاعات ناشر در داده‌های مرتبط با کدال.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: dict

ساختار خروجی: codalPublisher مطابق پاسخ سرور.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T027 — async Instrument.dps_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.dps_history() -> polars.LazyFrame

کاربرد: سابقه سود نقدی و اطلاعات مجمع.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: publish_date, meeting_date, fiscal_year, profit_or_loss_after_tax, distributable_profit, accumulated_profit_at_the_end_of_the_period, cash_earnings_per_share.

ملاحظه: ناهمگام؛ نتیجه پس از await به دست می‌آید. TypedDict صرفاً راهنمای نوع است و اعتبارسنجی پاسخ سرور را تضمین نمی‌کند. از مسیر قدیمی DPSData.aspx استفاده می‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T028 — Instrument.on_date

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

Instrument.on_date(date: int | str) -> InstrumentOnDate

کاربرد: ساخت نماینده نماد در یک روز مشخص.

ورودی و پیش‌فرض: date: تاریخ میلادی به صورت YYYYMMDD؛ int یا str.

نوع خروجی: InstrumentOnDate

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: خود این متد همگام است؛ متدهای شیء حاصل ناهمگام‌اند. کد منبع درباره محدودیت فراخوانی هم‌زمان آن‌ها هشدار دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T029 — async InstrumentOnDate.closing_price

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.closing_price() -> ClosingPrice (dict)

کاربرد: قیمت و آمار نهایی/روزانه همان تاریخ.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: ClosingPrice (dict)

ساختار خروجی: pClosing, pDrCotVal, priceFirst, priceMin, priceMax, priceYesterday, zTotTran, qTotTran5J, qTotCap

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T030 — async InstrumentOnDate.closing_price_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.closing_price_history() -> polars.LazyFrame

کاربرد: تغییرات درون‌روزی آمار قیمت.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: closingPriceHistory؛ با ریزمعامله متفاوت است.

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T031 — async InstrumentOnDate.states

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.states() -> polars.LazyFrame

کاربرد: وضعیت‌های درون‌روزی نماد.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: instrumentState

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T032 — async InstrumentOnDate.client_type

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.client_type() -> ClientTypeOnDate (dict)

کاربرد: آمار حقیقی و حقوقی همان روز.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: ClientTypeOnDate (dict)

ساختار خروجی: recDate, buy_I/N_Volume, buy_I/N_Value و تعدادها و مقادیر فروش

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T033 — async InstrumentOnDate.holders

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.holders() -> polars.LazyFrame

کاربرد: سهامداران روز انتخابی و روز قبل بر اساس سرویس.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: shareShareholder

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T034 — async InstrumentOnDate.best_limits

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.best_limits() -> polars.LazyFrame

کاربرد: تاریخچه تغییرات مظنه در روز انتخابی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: bestLimitsHistory؛ لزوماً تصویر کامل در هر ردیف نیست.

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T035 — async InstrumentOnDate.trades

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.trades() -> polars.LazyFrame

کاربرد: ریزمعاملات روز انتخابی.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: tradeHistory

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است. کد در انتهای URL مقدار true دارد و معنای true/false را به شکل TODO باز گذاشته است؛ وضعیت معاملات ابطالی تأیید نشده.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T036 — async InstrumentOnDate.static_thresholds

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.static_thresholds() -> polars.LazyFrame

کاربرد: تاریخچه آستانه‌های قیمت در روز.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: staticThreshold

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T037 — async InstrumentOnDate.data

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.data() -> dict

کاربرد: مشخصات تاریخی ابزار.

ورودی و پیش‌فرض: بدون ورودی صریح؛ تاریخ و شناسه از شیء.

نوع خروجی: dict

ساختار خروجی: instrumentHistory: insCode, lVal30, lVal18AFC, flow, cIsin, zTitad, baseVol, instrumentID و ...

ملاحظه: تاریخ و شناسه در InstrumentOnDate تنظیم شده‌اند؛ محدودیت هم‌زمانی در مستندات تابع ذکر شده است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T038 — async InstrumentOnDate.client_types

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async InstrumentOnDate.client_types() -> ClientTypeOnDate

کاربرد: نام قدیمی client_type.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: dict

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: منسوخ؛ به client_type ارجاع می‌دهد.

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T039 — async search

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async search(s: str, /) -> list[Search]

کاربرد: جست‌وجوی نماد.

ورودی و پیش‌فرض: s عبارت جست‌وجوی موضعی.

نوع خروجی: list[Search]

ساختار خروجی: insCode, insCode2/3/4, lVal18AFC, lVal30, flow, lastDate و ...

ملاحظه: تمام نتایج برمی‌گردند؛ مانند from_search به نتیجه نخست تقلیل نمی‌یابد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T040 — async old_search

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async old_search(skey: str, /) -> polars.LazyFrame

کاربرد: جست‌وجو از سرویس قدیمی.

ورودی و پیش‌فرض: skey نام یا بخشی از نام.

نوع خروجی: polars.LazyFrame

ساختار خروجی: l18, l30, ins_code, retail, compensation, wholesale و _unknown...

ملاحظه: سرویس متنی قدیمی؛ معنای چند فیلد در منبع نامعلوم باقی مانده.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T041 — async price_adjustments

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async price_adjustments(flow: FlowType) -> polars.LazyFrame

کاربرد: فهرست تعدیلات یک بازار.

ورودی و پیش‌فرض: FlowType = int | str | Flow.

نوع خروجی: polars.LazyFrame

ساختار خروجی: l18,l30,date,adj_pc,pc

ملاحظه: این تابع سطح ماژول از HTML استفاده می‌کند؛ با متد هم‌نام Instrument متفاوت است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T042 — async share_holder_companies

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async share_holder_companies(share_holder_share_id: int | str, /) -> list[ShareHolderCompany]

کاربرد: شرکت‌های موجود در پرتفوی سهامدار عمده.

ورودی و پیش‌فرض: شناسه shareHolderShareID از نتیجه سهامداران.

نوع خروجی: list[ShareHolderCompany]

ساختار خروجی: instrument (dict), numberOfShares, perOfShares

ملاحظه: این شناسه را با shareHolderID یکسان فرض نکنید.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T043 — async Instrument.page_data

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.page_data(general=True, trade_history=False, related_companies=False) -> dict

کاربرد: رابط قدیمی با جایگزین مشخص.

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

نوع خروجی: dict

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: info/related_companies/daily_closing_price

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T044 — async Instrument.live_data

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.live_data(general=True, best_limits=False, market_state=False) -> LiveData (dict)

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: پرچم‌های bool؛ قیمت، وضعیت یا مظنه از سرویس متنی قدیمی.

نوع خروجی: LiveData (dict)

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: closing_price_info/best_limits/etf/general.market_overview

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T045 — async Instrument.trade_history

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.trade_history(top: int, all_=False) -> polars.LazyFrame

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: top تعداد روز؛ all_ شامل روزهای بدون معامله.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: daily_closing_price

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T046 — async Instrument.client_type_history_old

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.client_type_history_old() -> polars.LazyFrame

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: بدون ورودی؛ تاریخچه از سرویس قدیمی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: client_type_history

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T047 — async Instrument.holders

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.holders(cisin=None) -> polars.LazyFrame

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: cisin: str|None استنباط‌شده؛ در صورت None از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: share_holders

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T048 — async Instrument.holder

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.holder(id_cisin, history=True, other_holdings=False) -> polars.LazyFrame | tuple[polars.LazyFrame, polars.LazyFrame]

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: متد static؛ id_cisin شناسه قدیمی ترکیبی؛ دو پرچم bool. هر دو True یعنی tuple.

نوع خروجی: polars.LazyFrame | tuple[polars.LazyFrame, polars.LazyFrame]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: share_holder_history / share_holder_companies

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T049 — async Instrument.adjustments

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.adjustments() -> polars.LazyFrame

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: بدون ورودی؛ پارس HTML تعدیلات.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: price_adjustments

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T050 — async Instrument.ombud_messages

کتابخانه: tsetmc — ماژول: tsetmc/instruments.py

async Instrument.ombud_messages() -> polars.LazyFrame

کاربرد: رابط قدیمی با جایگزین مشخص.

ورودی و پیش‌فرض: بدون ورودی؛ پیام‌ها از صفحه قدیمی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: در منبع با deprecated علامت‌گذاری شده است. جایگزین: messages

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/instruments.py

T051 — async last_state

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

async last_state(i=1, /) -> polars.LazyFrame

کاربرد: آخرین آمار مجموعه شاخص‌ها.

ورودی و پیش‌فرض: i: مقدار عددی با پیش‌فرض 1؛ شرح دامنه مجاز این پارامتر در تابع نیامده است.

نوع خروجی: polars.LazyFrame

ساختار خروجی: indexB1

ملاحظه: از نام یا پیش‌فرض پارامتر، پوشش همه بازارها نتیجه نمی‌گیریم.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T052 — Index

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

Index(code: str | int)

کاربرد: ساخت شیء شاخص.

ورودی و پیش‌فرض: code: شناسه شاخص.

نوع خروجی: Index

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T053 — async Index.info

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

async Index.info() -> InstrumentInfo (dict)

کاربرد: اطلاعات پایه شاخص.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: InstrumentInfo (dict)

ساختار خروجی: instrumentInfo

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T054 — async Index.last_day_history

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

async Index.last_day_history() -> polars.LazyFrame

کاربرد: مقادیر شاخص طی آخرین روز.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: datetime و فیلدهای indexB1؛ صعودی

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T055 — async Index.history

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

async Index.history() -> polars.LazyFrame

کاربرد: تاریخچه روزانه شاخص.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: polars.LazyFrame

ساختار خروجی: date و فیلدهای indexB2؛ صعودی

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T056 — async Index.companies

کتابخانه: tsetmc — ماژول: tsetmc/indices.py

async Index.companies() -> dict[str, polars.LazyFrame]

کاربرد: اجزای شاخص و تاریخچه همراه.

ورودی و پیش‌فرض: بدون ورودی صریح؛ شناسه از شیء.

نوع خروجی: dict[str, polars.LazyFrame]

ساختار خروجی: indexCompany, relatedCompanyThirtyDayHistory

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/indices.py

T057 — async market_watch_init

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async market_watch_init(*, market_state=True, prices=True, best_limits=True, join=True) -> MarketWatchInit (dict)

کاربرد: دریافت اولیه دیده‌بان.

ورودی و پیش‌فرض: چهار ورودی bool؛ join تعیین می‌کند مظنه‌ها با قیمت پیوند بخورند.

نوع خروجی: MarketWatchInit (dict)

ساختار خروجی: prices: LF|None; best_limits: LF|None; market_state: dict|None; refid:int

ملاحظه: از سرویس متنی قدیمی استفاده می‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T058 — async market_watch_plus

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async market_watch_plus(heven: int, refid: int, *, messages=True, market_state=True, new_prices=True, price_updates=True, best_limits=True, best_limits_prepare_join=True) -> MarketWatchPlus (dict)

کاربرد: دریافت تغییرات نسبت به وضعیت قبلی.

ورودی و پیش‌فرض: heven زمان HHMMSS؛ refid شناسه مرجع قبلی؛ سایر ورودی‌ها bool.

نوع خروجی: MarketWatchPlus (dict)

ساختار خروجی: new_prices, price_updates, best_limits: LF|None; messages:list[str]|None; market_state; refid

ملاحظه: برای ترکیب درست دلتاها باید وضعیت قبلی حفظ شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T059 — async closing_price_all

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async closing_price_all() -> polars.LazyFrame

کاربرد: سابقه قیمتی مجموعه نمادها برای کاربرد فیلترها.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ins_code,n,pc,pl,tno,tvol,tval,pmin,pmax,py,pf

ملاحظه: نام تابع به معنی فقط قیمت فعلی کل بازار نیست؛ منبع آن را داده متناظر [ih] معرفی می‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T060 — async client_type_all

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async client_type_all() -> polars.LazyFrame

کاربرد: حقیقی و حقوقی بازار از مسیر قدیمی.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ins_code و n/l_buy/sell_count/volume

ملاحظه: n در خروجی انگلیسی natural و l legal است؛ با کدهای I/N سرور متفاوت است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T061 — async key_stats

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async key_stats() -> polars.LazyFrame

کاربرد: آمار کلیدی همه نمادها.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ins_code و is1,is2,...

ملاحظه: معنای شاخص‌های عددی باید با فرهنگ فیلد مرجع بررسی شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T062 — async status_changes

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async status_changes(top: int | str) -> polars.LazyFrame

کاربرد: آخرین تغییرات وضعیت.

ورودی و پیش‌فرض: top تعداد رکورد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: symbol,name,date,time,new_status,datetime

ملاحظه: از HTML استفاده می‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T063 — async get_market_watch

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async get_market_watch(h_even=0, ref_id=0, with_best_limits=True, show_traded=False) -> polars.LazyFrame

کاربرد: دیده‌بان از API جدیدتر.

ورودی و پیش‌فرض: h_even و ref_id: int استنباط‌شده؛ دو پرچم bool.

نوع خروجی: polars.LazyFrame

ساختار خروجی: فیلدهای marketwatch مطابق سرور؛ pe تبدیل عددی می‌شود.

ملاحظه: در docstring نسخه بررسی‌شده experimental است.

وضعیت شواهد: experimental_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T064 — async get_client_type_all

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async get_client_type_all() -> polars.LazyFrame

کاربرد: حقیقی و حقوقی بازار از API جدیدتر.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: clientTypeAllDto

ملاحظه: در منبع experimental است.

وضعیت شواهد: experimental_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T065 — async get_inst_value_all_inst_all_param

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async get_inst_value_all_inst_all_param() -> polars.LazyFrame

کاربرد: پارامترهای آماری همه نمادها از API.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: instValueAllInstAllParam

ملاحظه: در منبع experimental است.

وضعیت شواهد: experimental_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T066 — MarketWatch

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

MarketWatch(*, init_kwargs: dict | None = None, plus_kwargs: dict | None = None, init_callback: Callable[[MarketWatchInit], Any] | None = None, plus_callback: Callable[[MarketWatchPlus], Any] | None = None, interval=1)

کاربرد: مدیریت دیده‌بان با دریافت دوره‌ای.

ورودی و پیش‌فرض: دو dict برای تنظیم فراخوانی‌ها؛ دو callable برای مصرف نتایج؛ interval عدد بر حسب ثانیه.

نوع خروجی: MarketWatch

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: interval=1 پیش‌فرض کتابخانه است، نه مجوز یا تضمین سقف درخواست از طرف بورس.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T067 — async MarketWatch.start

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

async MarketWatch.start()

کاربرد: حلقه دریافت و به‌روزرسانی دیده‌بان.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: None در خاتمه عادی فرضی؛ معمولاً اجرای پیوسته تا لغو

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: WebSocket نیست؛ روی دریافت دوره‌ای init/plus ساخته شده. در کار عادی تا لغو task ادامه دارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T068 — MarketWatch.df / MarketWatch.lf / MarketWatch.update_event

کتابخانه: tsetmc — ماژول: tsetmc/market_watch.py

MarketWatch.df / MarketWatch.lf / MarketWatch.update_event

کاربرد: دسترسی به وضعیت آخر دیده‌بان و اعلان به‌روزرسانی.

ورودی و پیش‌فرض: ویژگی‌ها، نه درخواست مستقل.

نوع خروجی: polars.DataFrame | None / polars.LazyFrame | None / asyncio.Event

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نبود ملاحظه به معنی تضمین سلامت فعلی سرویس نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/market_watch.py

T069 — async boards

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async boards() -> dict[int,str]

کاربرد: فهرست تابلوها.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: dict[int,str]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: HTML؛ کلید عددی و شرح تابلو.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T070 — async cs_codes

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async cs_codes() -> dict[str,str]

کاربرد: فهرست صنایع.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: dict[str,str]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: HTML؛ کد صنعت رشته است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T071 — async sectors_summary

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async sectors_summary() -> polars.LazyFrame

کاربرد: خلاصه صنایع.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: sectorSummeries مطابق پاسخ.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T072 — async industrial_groups_overview

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async industrial_groups_overview() -> polars.LazyFrame

کاربرد: نمای قدیمی صنایع.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: منسوخ؛ جایگزین sectors_summary.

وضعیت شواهد: deprecated_source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T073 — async market_map_data

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async market_map_data(*, market=0, size=9999, sector=0, typeSelected=1, heven=0) -> polars.LazyFrame

کاربرد: داده نقشه بازار.

ورودی و پیش‌فرض: پارامترهای عددی؛ دامنه مجاز بعضی selectorها در تابع توضیح داده نشده.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: نوع نقشه را نباید از نام پارامتر حدس قطعی زد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T074 — async major_holders_activity

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async major_holders_activity() -> polars.LazyFrame | None

کاربرد: فعالیت سهامداران عمده.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame | None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: HTML؛ در نبود جدول None برمی‌گردد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T075 — async top_industry_groups

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async top_industry_groups() -> polars.LazyFrame

کاربرد: رتبه‌بندی صنایع.

ورودی و پیش‌فرض: بدون ورودی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: group,mv,tno,tvol,tval؛ HTML.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T076 — async market_overview

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async market_overview(*, flow: FlowType = Flow.BOURSE) -> MarketOverview (dict)

کاربرد: نمای کلی بازار.

ورودی و پیش‌فرض: flow: int|str|Flow؛ پیش‌فرض بورس.

نوع خروجی: MarketOverview (dict)

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: مقادیر شاخص، ارزش بازار، حجم/ارزش/تعداد و زمان فعالیت؛ datetime ساخته‌شده timezone ندارد.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T077 — async related_companies

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async related_companies(cs: str) -> dict[str,polars.LazyFrame]

کاربرد: نمادهای هم‌صنعت.

ورودی و پیش‌فرض: cs: کد صنعت.

نوع خروجی: dict[str,polars.LazyFrame]

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: relatedCompany, relatedCompanyThirtyDayHistory.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T078 — async messages

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async messages(*, flow: FlowType = Flow.GENERAL, top: int | str = 200) -> polars.LazyFrame

کاربرد: پیام‌های بازار.

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: فیلدهای msg.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T079 — async search_messages

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async search_messages(*, sh_date: str, term: str) -> polars.LazyFrame

کاربرد: جست‌وجوی پیام‌ها.

ورودی و پیش‌فرض: sh_date: تاریخ شمسی YYYY-mm-dd؛ term متن جست‌وجو.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: تقویم این تابع با بسیاری از توابع تاریخی دیگر متفاوت است.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T080 — async trade_top

کتابخانه: tsetmc — ماژول: tsetmc/general.py

async trade_top(*, category: Literal['CommodityFund','ETF','MostTradedETF','MostVisited','PClosingBtmETF','PClosingTopETF'], flow: FlowType = Flow.BOURSE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: دسته‌های منتخب و رتبه‌بندی نمادها.

ورودی و پیش‌فرض: category از شش مقدار نوشته‌شده؛ flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: فیلد instrument تودرتو در صورت وجود باز می‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/general.py

T081 — FundType

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

FundType

کاربرد: کدهای نوع صندوق.

ورودی و پیش‌فرض: ورودی صریح ندارد؛ برای متدها شناسه/تنظیمات از شیء گرفته می‌شود.

نوع خروجی: StrEnum

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: STOCK=6; MIXED=7; FIXED=4; MARKET_MAKING=11; VC=12; REIT=14; PROJECT=13; COMMODITY=5; PRIVATE=16; FUND=17.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T082 — async funds

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async funds(type_: FundType | int | str, /) -> polars.LazyFrame

کاربرد: فهرست صندوق‌ها.

ورودی و پیش‌فرض: type_: نوع صندوق؛ فقط موضعی.

نوع خروجی: polars.LazyFrame

ساختار خروجی: funds

ملاحظه: regNo از پاسخ به Int64 تبدیل می‌شود.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T083 — async fund_details

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async fund_details(reg_no: str | int) -> dict

کاربرد: جزئیات و آمار صندوق.

ورودی و پیش‌فرض: reg_no: شماره ثبت از funds؛ نه ins_code.

نوع خروجی: dict

ساختار خروجی: stats: recordDate,navSub,netAsset,navStat,navRed و مشخصات صندوق

ملاحظه: خروجی مخلوط dict و LazyFrame است؛ stats جدول، recordDate و initiationDate شیء datetime می‌شوند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T084 — async commodity_etfs

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async commodity_etfs(*, flow: FlowType = Flow.MERCANTILE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: ETF کالایی

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: پوششی روی general.trade_top.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T085 — async etfs_with_most_price_decrease

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async etfs_with_most_price_decrease(*, flow: FlowType = Flow.BOURSE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: ETF با بیشترین کاهش قیمت

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: پوششی روی general.trade_top.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T086 — async etfs_with_most_price_increase

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async etfs_with_most_price_increase(*, flow: FlowType = Flow.BOURSE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: ETF با بیشترین افزایش قیمت

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: پوششی روی general.trade_top.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T087 — async most_traded_etfs

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async most_traded_etfs(*, flow: FlowType = Flow.BOURSE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: ETF با بیشترین حجم معاملات

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: پوششی روی general.trade_top.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T088 — async etfs

کتابخانه: tsetmc — ماژول: tsetmc/funds.py

async etfs(*, flow: FlowType = Flow.BOURSE, top: int | str = '9999') -> polars.LazyFrame

کاربرد: فهرست معاملات ETFها

ورودی و پیش‌فرض: flow بازار؛ top تعداد.

نوع خروجی: polars.LazyFrame

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: پوششی روی general.trade_top.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/funds.py

T089 — async update

کتابخانه: tsetmc — ماژول: tsetmc/dataset/__init__.py

async update(df: polars.DataFrame | None = None) -> None

کاربرد: به‌روزرسانی دیتاست محلی شناسایی نمادها.

ورودی و پیش‌فرض: df: داده دیده‌بان، یا None برای دریافت آن.

نوع خروجی: None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: برخی yvalها و نام‌های پایان‌یافته با رقم حذف می‌شوند. فایل بسته بازنویسی می‌شود. این خروجی فهرست کامل تمام ابزارها و تاریخچه هویت نیست.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/dataset/init.py

T090 — async add_instrument

کتابخانه: tsetmc — ماژول: tsetmc/dataset/__init__.py

async add_instrument(inst: Instrument) -> None

کاربرد: افزودن یا اصلاح یک نماد در دیتاست محلی.

ورودی و پیش‌فرض: inst: شیء Instrument.

نوع خروجی: None

ساختار خروجی: ساختار دقیق بر اساس منبع همان مدخل؛ بدون افزودن شِمای حدسی.

ملاحظه: اطلاعات را دریافت و فایل داده بسته را بازنویسی می‌کند.

وضعیت شواهد: source_reviewed؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/dataset/init.py

T091 — lazy_ds.df / lazy_ds.lf / lazy_ds.as_dict

کتابخانه: tsetmc — ماژول: tsetmc/dataset/__init__.py

lazy_ds.df / lazy_ds.lf / lazy_ds.as_dict(key)

کاربرد: ساختار محلی جست‌وجوی نماد.

ورودی و پیش‌فرض: key: Literal['code','l18','l30','cisin','isin'].

نوع خروجی: polars.DataFrame / polars.LazyFrame / dict

ساختار خروجی: code,l18,l30,cisin,isin

ملاحظه: کلاس _LazyDS داخلی است؛ دسترسی عملی به آن به معنی قرارداد عمومی پایدار نیست.

وضعیت شواهد: internal_exposed_not_stable؛ آزمون زنده این بررسی: انجام نشده.

منبع ثابت: https://github.com/5j9/tsetmc/blob/af5f4578fe4a21030759c8ed1cef3f72a00834ab/tsetmc/dataset/init.py

دریافت، پاک‌سازی، ذخیره و مدیریت داده — قرارداد پیشنهادی نسخه ۰٫۲

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

توابعی که وابسته به endpoint هستند، تا اثبات دسترسی/معنا/پوشش در runtime نباید آماده اعلام شوند. نوع نتیجه ثابت است؛ None یا empty نباید خطای شبکه را پنهان کند.

C001 — Client

کلاینت همگام و مالک چرخه عمر اتصال و منابع.

Client(*, config: ClientConfig | None = None, source: Source | None = None, mode: AccessMode | None = None, storage: bool | None = None, data_dir: PathLike | None = None, credentials: Credentials | None = None) -> Client

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: class

پارامتر نوع مقدار پیش‌فرض معنا
config ClientConfig | None None تنظیمات immutable مشترک؛ در Client آرگومان‌های غیر None بر آن مقدم‌اند.
source Source | None None منبع public یا official؛ تعویض پنهان منبع یا حساب مجاز نیست.
mode AccessMode | None None auto،online یاoffline؛ None ارث‌بری از پیکربندی، نه تصمیم بر اساس وجود فایل.
storage bool | None None در Client: فلگ فعال/غیرفعال یا ارث‌بری با None؛ در ClientConfig: تنظیمات StorageConfig. None در ClientConfig یعنی فعال با پیش‌فرض.
data_dir PathLike | None None مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
credentials Credentials | None None اعتبارنامه رسمی متعلق به خود کاربر؛ در حافظه، خارج از repr/log/export.

نوع خروجی: Client

رفتار و محدودیت‌ها: تنظیمات پایه با ClientConfig ساخته می‌شود؛ آرگومان‌های غیر None جایگزین تنظیمات‌اند. مقادیر نهایی پیش‌فرض: source='public'، mode='auto'، ذخیره فعال و بهترین‌تلاش. ساخت و import فاقد درخواست، ساخت فایل و thread است؛ راه‌اندازی ذخیره در اولین عملیات داده به writer واگذار می‌شود.

استثناها: ConfigurationError

وابستگی‌ها: stdlib, pandas, httpx, platformdirs, tzdata

قابلیت حفظ‌شده از سند قبل: Client

C002 — capabilities

فهرست قابلیت‌ها و سطح شواهد.

capabilities() -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
— — — ورودی صریح ندارد.

نوع خروجی: pd.DataFrame

ساختار خروجی: capability_id, provider, support_status, required_role, verified_at, limits, coverage_evidence

رفتار و محدودیت‌ها: وجود قابلیت در کاتالوگ با مجازبودن حساب کاربر یا سلامت فعلی سرور یکسان نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: ConfigurationError, MissingDependencyError

وابستگی‌ها: pandas, httpx, stdlib, provider.capabilities, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: capabilities

C003 — search_instruments

جست‌وجوی نام و مشخصات ابزارها.

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

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
query str الزامی عبارت جست‌وجوی متنی یا QuerySpec مطابق نوع؛ در URL encode و در SQL پارامترگذاری می‌شود.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
include_inactive bool True کنترل دامنه هویت فعال/غیرفعال؛ با وضعیت مجازبودن معامله یکسان نیست.
limit int | None None حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: InstrumentRecord

مدل فیلدها: InstrumentRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: همه گزینه‌های مطابق سیاست برمی‌گردند. حذف خودکار نماد دارای رقم یا حدس اولین نتیجه نداریم؛ limit محلی نیز ممکن است و در meta ثبت می‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.search_instruments, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: search_instruments

C004 — get_instrument

شناسایی یکتای ابزار.

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

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
as_of date | None None cutoff؛ datetime باید آگاه به منطقه زمانی باشد. در get_instrument، as_of تاریخ اعتبار هویت و known_at زمان دانسته‌شدن نسخه است.
known_at datetime | None None cutoff؛ datetime باید آگاه به منطقه زمانی باشد. در get_instrument، as_of تاریخ اعتبار هویت و known_at زمان دانسته‌شدن نسخه است.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: InstrumentRecord

ساختار خروجی: InstrumentRecord

مدل فیلدها: InstrumentRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: نماد مبهم خطا می‌دهد؛ وملت با وبملت یکسان نیست. نگاشت کد قدیم فقط با مدرک و دوره اعتبار. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. as_of تاریخ اعتبار اقتصادی هویت؛ known_at cutoff زمان دانسته‌شدن آن نسخه. این دو متفاوت‌اند.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_instrument, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_instrument

C005 — get_instruments

فهرست ابزارها یا تغییرات هویتی.

get_instruments(*, market: Market | None = None, include_inactive: bool = True, changed_since: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
include_inactive bool True کنترل دامنه هویت فعال/غیرفعال؛ با وضعیت مجازبودن معامله یکسان نیست.
changed_since DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: InstrumentRecord

مدل فیلدها: InstrumentRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: خروجی دیده‌بان به‌تنهایی فهرست کامل تاریخی محسوب نمی‌شود. کامل‌بودن در meta با complete/partial/unknown اعلام می‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_instruments, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_instruments

C006 — get_quote

گزارش آخرین وضعیت قیمت.

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

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
freshness FreshnessPolicy | None None سیاست تازگی همین فراخوانی؛ None سیاست dataset/Client. max_age کش با زمان معامله یکسان نیست.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: Quote

ساختار خروجی: Quote

مدل فیلدها: Quote در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: قیمت و زمان دریافت و زمان منبع جدا؛ مسیر quote نباید برای اجرا مجبور به دانلود تاریخچه شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_quote, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_quote

C007 — get_price

دسترسی ساده به یک قیمت.

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

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
field PriceField 'last' انتخاب last،closing یاprevious_reference؛ قیمت مفقود MissingValueError، نه صفر.
freshness FreshnessPolicy | None None سیاست تازگی همین فراخوانی؛ None سیاست dataset/Client. max_age کش با زمان معامله یکسان نیست.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: Decimal

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

رفتار و محدودیت‌ها: از get_quote استفاده می‌کند؛ برای قیمت ناموجود MissingValueError و برای واحد نامعلوم/غیرپولی UnsupportedQuoteUnitError. در آموزش تحلیلی get_quote ترجیح دارد؛ فقط عدد زمینه زمانی را حذف می‌کند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_price, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_price

C008 — get_quotes

قیمت گروهی.

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

وضعیت: proposed_not_implemented — مرحله: P03 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instruments Sequence[InstrumentLike] الزامی دنباله ابزارها به ترتیب درخواست؛ رشته منفرد به‌جای دنباله پذیرفته نمی‌شود و تکرارها بی‌اجازه حذف نمی‌شوند.
on_error ErrorPolicy 'raise' raise توقف با خطای حاوی گزارش جزئی؛ collect ثبت خطاهای هر مورد. نوع خروجی تابع با این گزینه تغییر نمی‌کند.
freshness FreshnessPolicy | None None سیاست تازگی همین فراخوانی؛ None سیاست dataset/Client. max_age کش با زمان معامله یکسان نیست.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: DataFrame یک ردیف برای هر ورودی: request_index,input_symbol,status,error_code,error_message به‌علاوه ستون‌های Quote و provenance؛ حتی ورودی تکراری حفظ می‌شود.

رفتار و محدودیت‌ها: collect خطا را در همان آیتم ثبت می‌کند؛ raise یک BatchDataError همراه گزارش جزئی می‌دهد. کلیدکردن صرفاً بر نام نماد و حذف ورودی تکراری ممنوع. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. خروجی یک ردیف برای هر ورودی، با request_index و status دارد؛ در collect خطای هر مورد در error_code و error_message و قیمت‌های nullable؛ ترتیب و تکرار ورودی حفظ می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_quotes, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_quotes

C009 — get_history

تاریخچه روزانه.

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

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
adjustment AdjustmentMode 'none' none قیمت خام؛ source روش تعدیل تاییدشده منبع با نسخه وanchor. قیمت خام آرشیو بازنویسی نمی‌شود.
series SeriesMode 'listing' listing فقط همین شناسه؛ continuous_verified زنجیره هویت شاهددار، نه اتصال با تشابه نام.
as_of datetime | None None cutoff؛ datetime باید آگاه به منطقه زمانی باشد. در get_instrument، as_of تاریخ اعتبار هویت و known_at زمان دانسته‌شدن نسخه است.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: DailyBar

مدل فیلدها: DailyBar در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: صعودی؛ listing پیش‌فرض فقط همین شناسه. continuous_verified فقط زنجیره تأییدشده هویت. as_of با پاسخ جاری سرور شبیه‌سازی نمی‌شود؛ نبود نسخه تاریخی خطا. سقف حافظه در config؛ خروجی بزرگ به iter_history هدایت می‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. as_of فقط با نسخه‌های شاهددار؛ استفاده از نسخه اصلاح‌شده امروز برای گذشته ممنوع. adjustment='source' تا تأیید روش، UnsupportedCapabilityError. نبود تاریخ ابتدا/انتها درخواست پوشش موجود است نه تضمین همه تاریخ.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_history

C010 — iter_history

دریافت قطعه‌ای تاریخچه.

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

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
adjustment AdjustmentMode 'none' none قیمت خام؛ source روش تعدیل تاییدشده منبع با نسخه وanchor. قیمت خام آرشیو بازنویسی نمی‌شود.
chunk_days int 366 اندازه قطعه تقویمی مثبت؛ صرفاً برنامه‌ریزی محلی. پشتیبانی fetch-range در منبع باید کنترل شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: Iterator[pd.DataFrame]

ساختار خروجی: قطعات DailyBar با بازه‌های مشخص و meta جدا.

مدل فیلدها: DailyBar در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: درخواست هنگام پیمایش iterator انجام می‌شود. parser مشترک با get_history؛ پایان بازه، پیشرفت و تکرار cursor کنترل می‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.iter_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: iter_history

C011 — get_history_many

تاریخچه چند نماد.

get_history_many(instruments: Sequence[InstrumentLike], *, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', adjustment: AdjustmentMode = 'none', on_error: ErrorPolicy = 'raise', policy: FetchPolicy | None = None) -> BatchFrames

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instruments Sequence[InstrumentLike] الزامی دنباله ابزارها به ترتیب درخواست؛ رشته منفرد به‌جای دنباله پذیرفته نمی‌شود و تکرارها بی‌اجازه حذف نمی‌شوند.
start DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
adjustment AdjustmentMode 'none' none قیمت خام؛ source روش تعدیل تاییدشده منبع با نسخه وanchor. قیمت خام آرشیو بازنویسی نمی‌شود.
on_error ErrorPolicy 'raise' raise توقف با خطای حاوی گزارش جزئی؛ collect ثبت خطاهای هر مورد. نوع خروجی تابع با این گزینه تغییر نمی‌کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: BatchFrames

ساختار خروجی: BatchFrames شامل data:DataFrame با شِمای DailyBar وrequest_index، errors:DataFrame باrequest_index,input,error_code,message وmanifest:FrameManifest.

مدل فیلدها: DailyBar در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: برای کل بازار و بازه بزرگ از برنامه دریافت قطعه‌ای استفاده شود؛ نه ساخت میلیون‌ها task هم‌زمان. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. BatchFrames همیشه دو DataFrame داده و خطا به‌علاوه manifest برمی‌گرداند؛ در raise خطا گزارش جزئی را همراه دارد. هر ردیف داده request_index دارد.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_history_many, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_history_many

C012 — get_daily_market

تصویر روزانه یک بازار.

get_daily_market(day: DateLike, *, market: Market, calendar: Calendar = 'gregorian', include_untraded: bool = True, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
day DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
include_untraded bool True درخواست داده نمادهای بدون معامله نیز؛ اگر منبع پشتیبانی نکند UnsupportedCapabilityError، نه ساخت سطر مصنوعی.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: DailyBar به تفکیک ins_code و trade_date.

مدل فیلدها: DailyBar در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: معنای include_untraded باید به قرارداد واقعی منبع نگاشت شود. TradeOneDayAll و TradeOneDay قابل جایگزینی خاموش نیستند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_daily_market, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_daily_market

C013 — get_adjustments

رویدادهای تعدیل گزارش‌شده.

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

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: PriceAdjustment

مدل فیلدها: PriceAdjustment در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: منبع، ضریب/قیمت قبل و بعد، تاریخ مؤثر و درجه تأیید ثبت می‌شود؛ علت افزایش سرمایه یا سود نقدی بدون مدرک حدس زده نمی‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_adjustments, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_adjustments

C014 — get_market_watch

دیده‌بان بازار.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
include_order_book bool False افزودن مولفه‌های اختیاری با timestamp مستقل؛ ممکن است درخواست اضافه مصرف کند.
include_client_types bool False افزودن مولفه‌های اختیاری با timestamp مستقل؛ ممکن است درخواست اضافه مصرف کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: DataFrame یک ردیف به‌ازای هر ابزار با ستون‌های QuoteRow؛ مظنه اختیاری با ستون‌های bid/ask_*_1..5 وorder_book_timestamp؛ حقیقی‌حقوقی اختیاری باclient_type_timestamp؛ شناسنامه مستقل برای بازه زمانی مولفه‌ها.

رفتار و محدودیت‌ها: ممکن است چند درخواست باشد؛ زمان هر مؤلفه و بازه دریافت حفظ می‌شود؛ atomic یا هم‌زمان واقعی فرض نمی‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. خروجی یک ردیف برای هر ابزار است؛ مظنه اختیاری با ستون‌های bid_price_1 تا ask_count_5 و زمان مظنه؛ حقیقی‌حقوقی با زمان مستقل. از معرفی ترکیب غیرهم‌زمان به‌عنوان یک لحظه اتمی خودداری می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_market_watch, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_market_watch

C015 — get_market_overview

خلاصه وضعیت بازار.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: MarketOverview

مدل فیلدها: MarketOverview در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: مقدار شاخص واحد point دارد؛ ارزش بازار پولی است. این دو در یک نوع قیمت مبهم ادغام نمی‌شوند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_market_overview, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_market_overview

C016 — get_client_types

آخرین آمار حقیقی و حقوقی.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ClientTypeRecord

مدل فیلدها: ClientTypeRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_client_types, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_client_types

C017 — get_client_type_history

تاریخچه حقیقی و حقوقی.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ClientTypeRecord

مدل فیلدها: ClientTypeRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

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

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_client_type_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_client_type_history

C018 — get_market_client_types

آمار حقیقی و حقوقی مجموعه بازار.

get_market_client_types(*, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ClientTypeRecord

مدل فیلدها: ClientTypeRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: پوشش بازار باید در meta مشخص شود؛ نبود market در endpoint رسمی به معنی پوشش همه ابزارها نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_market_client_types, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_market_client_types

C019 — get_indices

فهرست شاخص‌ها.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexRecord

مدل فیلدها: IndexRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: فهرست بر اساس منبع مستند/کشف‌شده؛ از شناسه‌های شرکت‌ها حدس زده نمی‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_indices, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_indices

C020 — get_index

آخرین وضعیت یک شاخص.

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

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
index_code str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexSnapshot

مدل فیلدها: IndexSnapshot در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: واحد point، نه ریال. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_index, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_index

C021 — get_index_history

تاریخچه شاخص.

get_index_history(index_code: str, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
index_code str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexBar

مدل فیلدها: IndexBar در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

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

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_index_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_index_history

C022 — get_index_intraday

مقادیر درون‌روز شاخص.

get_index_intraday(index_code: str, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
index_code str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexPoint

مدل فیلدها: IndexPoint در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: نمونه‌برداری انتشار شاخص است؛ لزوماً هر تیک بازار نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_index_intraday, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_index_intraday

C023 — get_index_members

اجزای شاخص.

get_index_members(index_code: str, *, as_of: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
index_code str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
as_of DateLike | None None cutoff؛ datetime باید آگاه به منطقه زمانی باشد. در get_instrument، as_of تاریخ اعتبار هویت و known_at زمان دانسته‌شدن نسخه است.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexMember

مدل فیلدها: IndexMember در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: اجزای امروز را به گذشته تعمیم نمی‌دهیم؛ نبود ترکیب تاریخی CoverageError. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_index_members, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_index_members

C024 — get_index_impact

تأثیر نمادها بر شاخص.

get_index_impact(*, market: Market, limit: int = 25, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P08 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
limit int 25 حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: IndexImpact

مدل فیلدها: IndexImpact در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: شاخص مبنا و واحد تأثیر باید مشخص باشد. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_index_impact, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_index_impact

C025 — get_order_book

تصویر مظنه فعلی.

get_order_book(instrument: InstrumentLike, *, depth: int = 5, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
depth int 5 عمق مثبت مظنه؛ پیش‌فرض پنج. عمق بیشتر فقط در صورت capability تاییدشده.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: OrderBookLevel

مدل فیلدها: OrderBookSnapshot در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: پنج مظنه به معنی تمام سفارش‌های سامانه نیست. عمق کمتر موجود را اعلام می‌کنیم؛ عمق اضافی نمی‌سازیم. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_order_book, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_order_book

C026 — get_order_book_updates

تغییرات تاریخی مظنه.

get_order_book_updates(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: OrderBookUpdate

مدل فیلدها: OrderBookUpdate در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: شناسه توالی و refID حذف نمی‌شود. دلتا با snapshot یکسان نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_order_book_updates, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_order_book_updates

C027 — get_trades

ریزمعاملات.

get_trades(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', cancellations: CancellationPolicy = 'as_reported', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
cancellations CancellationPolicy 'as_reported' as_reported حفظ وضعیت منبع؛ exclude_verified فقط بعد از تایید معنای ابطال. وضعیت نامعلوم نباید معامله معتبر تلقی شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: Trade

مدل فیلدها: Trade در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: حذف ابطالی فقط با پرچم تأییدشده ممکن است؛ در غیر این صورت UnsupportedCapabilityError. معاملات هم‌زمان با شناسه معامله تفکیک می‌شوند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_trades, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_trades

C028 — get_intraday_quotes

تغییرات آمار تجمعی قیمت در روز.

get_intraday_quotes(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: QuoteRow

مدل فیلدها: QuoteRow در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: با ریزمعاملات یا کندل مشتق‌شده یکی نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_intraday_quotes, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_intraday_quotes

C029 — get_instrument_states

وضعیت تاریخی ابزار.

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

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: InstrumentStateRecord

مدل فیلدها: InstrumentStateRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: نبود داده فقط در قرارداد صریح پاسخ کامل می‌تواند معنی وضعیت مجاز داشته باشد. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_instrument_states, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_instrument_states

C030 — get_thresholds

دامنه قیمت مجاز.

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

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ThresholdRecord

مدل فیلدها: ThresholdRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: نوع خروجی همیشه جدول است تا چند تغییر آستانه در یک روز پوشش داده شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_thresholds, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_thresholds

C031 — get_shareholders

سهامداران عمده.

get_shareholders(instrument: InstrumentLike, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ShareholderPosition

مدل فیلدها: ShareholderPosition در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: فهرست سهامداران عمده لزوماً کل سهامداران نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_shareholders, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_shareholders

C032 — get_shareholder_history

تغییرات مالکیت سهامدار.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
shareholder_id str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
start DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ShareholderPosition

مدل فیلدها: ShareholderPosition در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: شناسه سهامدار با شناسه موقعیت/رابطه او یکسان نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_shareholder_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_shareholder_history

C033 — get_shareholder_holdings

سایر دارایی‌های سهامدار عمده.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
holding_ref str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ShareholderPosition

مدل فیلدها: ShareholderPosition در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: به رمزگشایی یا حدس شناسه از نام نیاز ندارد. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_shareholder_holdings, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_shareholder_holdings

C034 — get_share_capital_history

تاریخچه تعداد سهام.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: ShareCapitalRecord

مدل فیلدها: ShareCapitalRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: تعداد سهام و ارزش سرمایه اسمی دو کمیت جدا هستند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_share_capital_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_share_capital_history

C035 — get_dividends

تاریخچه سود نقدی.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: DividendRecord

مدل فیلدها: DividendRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

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

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_dividends, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_dividends

C036 — get_funds

فهرست صندوق‌ها.

get_funds(*, fund_type: FundCategory | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
fund_type FundCategory | None None نوع صندوق از enum تعریف‌شده؛ None دامنه در دسترس، نه تضمین تمام صندوق‌های کشور.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FundRecord

مدل فیلدها: FundRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

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

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_funds, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_funds

C037 — get_fund

مشخصات صندوق.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
registration_no str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FundRecord

مدل فیلدها: FundRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: NAV و اطلاعات ثبت در قراردادهای جدا. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_fund, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_fund

C038 — get_fund_nav_history

سابقه NAV.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
registration_no str الزامی شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FundNavRecord

مدل فیلدها: FundNavRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: NAV صدور، ابطال و آماری جدا؛ قدمت داده نامعلوم را اعلام می‌کند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_fund_nav_history, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_fund_nav_history

C039 — get_messages

پیام‌های ناظر.

get_messages(*, instrument: InstrumentLike | None = None, market: Market | None = None, day: DateLike | None = None, calendar: Calendar = 'gregorian', query: str | None = None, limit: int = 200, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike | None None نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
query str | None None عبارت جست‌وجوی متنی یا QuerySpec مطابق نوع؛ در URL encode و در SQL پارامترگذاری می‌شود.
limit int 200 حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: MarketMessage

مدل فیلدها: MarketMessage در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: ترکیب فیلترهای غیرقابل پشتیبانی باید صریحاً رد یا اجرای محلی‌اش در meta ثبت شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_messages, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_messages

C040 — get_disclosures

فراده اطلاعیه‌های کدال.

get_disclosures(instrument: InstrumentLike, *, limit: int = 9, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
limit int 9 حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: Disclosure

مدل فیلدها: Disclosure در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

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

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_disclosures, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_disclosures

C041 — get_sectors

فهرست صنایع.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: SectorRecord

مدل فیلدها: SectorRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: کد رشته با صفرهای ابتدایی محفوظ. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_sectors, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_sectors

C042 — get_subsectors

زیرصنایع.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
sector_code str | None None شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: SubsectorRecord

مدل فیلدها: SubsectorRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: فیلتر محلی یا سمت سرور در meta معلوم شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_subsectors, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_subsectors

C043 — get_boards

فهرست تابلوها.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: BoardRecord

مدل فیلدها: BoardRecord در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: کدهای منبع به عنوان رشته حفظ می‌شوند. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_boards, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_boards

C044 — get_market_sessions

تقویم مشاهده‌شده معاملات.

get_market_sessions(*, market: Market, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
start DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: MarketSession

مدل فیلدها: MarketSession در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: NSCStart فقط 20 روز اخیر است؛ برای تقویم کامل باید منبع دیگر یا مجموعه ذخیره‌شده وجود داشته باشد. روز فاقد داده خودکار تعطیل نیست. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_market_sessions, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_market_sessions

C045 — get_options

مشخصات اختیارها.

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

وضعیت: proposed_not_implemented — مرحله: P12 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
underlying InstrumentLike | None None نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: OptionContract

مدل فیلدها: OptionContract در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: مدل ورودی/خروجی نامزد است؛ معنای فیلدهای مبهم قبل از تثبیت نیازمند آزمون. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_options, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_options

C046 — get_futures

مشخصات آتی.

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

وضعیت: proposed_not_implemented — مرحله: P12 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
underlying InstrumentLike | None None نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FutureContract

مدل فیلدها: FutureContract در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: شرح ناسازگار Future در سند رسمی مبنای حدس نوع قرارداد قرار نمی‌گیرد. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_futures, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_futures

C047 — get_opening_auction

قیمت و حجم نظری گشایش.

get_opening_auction(instrument: InstrumentLike, *, market: Market, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P12 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: OpeningAuction

مدل فیلدها: OpeningAuction در سند00؛ نگاشت به ستون Pandas طبق FrameFactory.

رفتار و محدودیت‌ها: قیمت نظری نه پیش‌بینی مدل هوش مصنوعی و نه معامله انجام‌شده. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_opening_auction, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_opening_auction

C048 — get_energy_instruments

ابزارهای بازار انرژی.

get_energy_instruments(*, active_only: bool = True, cursor: str | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P12 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
active_only bool True کنترل دامنه هویت فعال/غیرفعال؛ با وضعیت مجازبودن معامله یکسان نیست.
cursor str | None None مکان ادامه opaque صادرشده توسط منبع یا manifest؛ اولین فراخوانی None. شماره ردیف را حدس نمی‌زنیم.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: EnergyInstrument

رفتار و محدودیت‌ها: نامزد؛ حدود، شمول cursor و ترتیب باید با پاسخ واقعی روشن شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. هر فراخوانی فقط یک صفحه DataFrame؛ cursor بعدی در FrameManifest؛ کاربر با get_frame_manifest(df) آن را می‌خواند. cursor از روی شماره ردیف حدس زده نمی‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_energy_instruments, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_energy_instruments

C049 — get_energy_auctions

پیام‌های حراج انرژی.

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

وضعیت: proposed_not_implemented — مرحله: P12 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
cursor str | None None مکان ادامه opaque صادرشده توسط منبع یا manifest؛ اولین فراخوانی None. شماره ردیف را حدس نمی‌زنیم.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: AuctionMessage

رفتار و محدودیت‌ها: توکن ادامه منبع را نگه می‌داریم؛ کامل‌بودن و پایان صفحه حدس زده نمی‌شود. قرارداد مشترک Data در 00_TYPES_AND_CONVENTIONS اعمال می‌شود. استثنای ذخیره خودکار از این تابع منتشر نمی‌شود؛ وضعیت آن جداگانه گزارش می‌شود. هر فراخوانی فقط یک صفحه DataFrame؛ cursor بعدی در FrameManifest؛ کاربر با get_frame_manifest(df) آن را می‌خواند. cursor از روی شماره ردیف حدس زده نمی‌شود.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: pandas, httpx, stdlib, provider.get_energy_auctions, optional: jdatetime برای تقویم شمسی

قابلیت حفظ‌شده از سند قبل: get_energy_auctions

C050 — to_pandas

تبدیل صریح رکوردهای استاندارد یا اعتبارسنجی یک DataFrame؛ دیگر برای خروجی دریافت ضروری نیست.

to_pandas(records: Sequence[Mapping[str, object]] | pd.DataFrame, *, schema: str, numeric: NumericProfile = 'analysis') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
records Sequence[Mapping[str, object]] | pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
schema str الزامی شناسه شِمای نسخه‌دار ثبت‌شده؛ تبدیل بدون قرارداد معنایی مجاز نیست.
numeric NumericProfile 'analysis' analysis یعنی نوع عددی Pandas مناسب تحلیل؛ exact یعنی Decimal با دقت منبع. شناسه هر دو حالت string است.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: نیازمند شِمای ثبت‌شده؛ فیلد نامعتبر خطاست. DataFrame ورودی را تغییر نمی‌دهد. جایگزین متد TableResult.to_pandas در طرح پیشین.

استثناها: SchemaMismatchError, DataTypeError

وابستگی‌ها: pandas, schema_registry

قابلیت حفظ‌شده از سند قبل: to_pandas

C051 — to_polars

مبدل اختیاری Pandas به Polars.

to_polars(df: pd.DataFrame) -> pl.DataFrame

وضعیت: proposed_not_implemented — مرحله: P13 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.

نوع خروجی: pl.DataFrame

رفتار و محدودیت‌ها: هویت و متادیتای بحرانی در ستون‌ها؛ attrs مسیر تضمین‌شده اصالت نیست. نصب Polars تنها در extra مربوط لازم است.

استثناها: MissingDependencyError, DataTypeError

وابستگی‌ها: pandas, optional:polars, optional:pyarrow

قابلیت حفظ‌شده از سند قبل: to_polars

C053 — reconstruct_order_book

بازسازی وضعیت مظنه از تغییرات؛ پردازش محلی بدون شبکه.

reconstruct_order_book(updates: pd.DataFrame, *, initial: pd.DataFrame | None = None, gap_policy: Literal['raise','mark'] = 'raise') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
updates pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
initial pd.DataFrame | None None مقدار آغازین ثروت یا DataFrame وضعیت اولیه مظنه مطابق نوع تابع.
gap_policy Literal['raise', 'mark'] 'raise' درشکاف مظنه raise یاmark؛ mark هم وضعیت راکامل اعلام نمی‌کند.

نوع خروجی: pd.DataFrame

ساختار خروجی: OrderBookSnapshot long table

رفتار و محدودیت‌ها: اولویت sequence و refID؛ نبود تصویر اولیه یا شکاف به unknown/خطا تبدیل شود. forward-fill فقط در یک جلسه و شناسه، نه از روز قبل. کاهش حجم/پاک‌شدن سطح از داده معتبر اعمال شود.

استثناها: MissingInitialStateError, SequenceGapError, SchemaMismatchError

وابستگی‌ها: pandas, state_reducer

قابلیت حفظ‌شده از سند قبل: reconstruct_order_book

C054 — plan_history_sync

طرح به‌روزرسانی قابل ادامه.

plan_history_sync(client: Client, instruments: Sequence[InstrumentLike], *, start: date, end: date, store: DatasetStore | None = None, overlap_sessions: int = 5, full_recheck: bool = False) -> DownloadPlan

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
client Client الزامی کلاینت ساخته‌شده کاربر با منبع وscope مربوط؛ مالکیت بسته‌شدن در قرارداد تابع مشخص است.
instruments Sequence[InstrumentLike] الزامی دنباله ابزارها به ترتیب درخواست؛ رشته منفرد به‌جای دنباله پذیرفته نمی‌شود و تکرارها بی‌اجازه حذف نمی‌شوند.
start date الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end date الزامی تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
store DatasetStore | None None پیاده‌سازی DatasetStore؛ None مخزن Client. در sync صریح، خاموش/ناموجودبودن ذخیره خطاست.
overlap_sessions int 5 تعداد جلسات گذشته برای بازبینی افزایشی؛ عدد پیشنهادی است و اصلاحات قدیمی‌تر را تضمین نمی‌کند.
full_recheck bool False اگر True باشد کل دامنه برنامه بازبینی می‌شود؛ درخواست‌های بیشتر باید با بودجه و مجوز سازگار باشند.

نوع خروجی: DownloadPlan

رفتار و محدودیت‌ها: طرح شامل دامنه، missing ranges، پنجره بازبینی و capability است. پیش‌فرض ۵ جلسه سیاست پیشنهادی نرم‌افزار است، نه تضمین پوشش اصلاحات بورس. full_recheck بازبینی کل دامنه درخواست‌شده. store=None مخزن تنظیم‌شده Client؛ خاموش بودن مخزن خطای صریح.

استثناها: StorageError, UnsupportedCapabilityError, InvalidArgumentError

وابستگی‌ها: stdlib, pandas, repository, planner

قابلیت حفظ‌شده از سند قبل: plan_history_sync

C055 — run_download_plan

اجرای صریح همگام‌سازی بادوام.

run_download_plan(plan: DownloadPlan, *, client: Client, store: DatasetStore | None = None, resume: bool = True, on_error: ErrorPolicy = 'collect') -> SyncReport

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
plan DownloadPlan الزامی DownloadPlan معتبر با fingerprint منبع،بازه وschema؛ تغییر config ناسازگار برنامه را نامعتبر می‌کند.
client Client الزامی کلاینت ساخته‌شده کاربر با منبع وscope مربوط؛ مالکیت بسته‌شدن در قرارداد تابع مشخص است.
store DatasetStore | None None پیاده‌سازی DatasetStore؛ None مخزن Client. در sync صریح، خاموش/ناموجودبودن ذخیره خطاست.
resume bool True ادامه فقط از checkpointهای commitشده، نه کارهای فقط دریافت‌شده/درصف.
on_error ErrorPolicy 'collect' raise توقف با خطای حاوی گزارش جزئی؛ collect ثبت خطاهای هر مورد. نوع خروجی تابع با این گزینه تغییر نمی‌کند.

نوع خروجی: SyncReport

رفتار و محدودیت‌ها: برخلاف دریافت عادی، هدف این عملیات ذخیره است؛ پیشرفت و checkpoint فقط پس از commit داده و raw و journal. در collect خطای ذخیره در گزارش؛ failed chunks برای resume باقی می‌مانند. فایل/دیتابیس خطادار موفق گزارش نمی‌شود.

استثناها: StorageError, SyncPlanError, NetworkError, BatchDataError

وابستگی‌ها: repository, httpx, pandas

قابلیت حفظ‌شده از سند قبل: run_download_plan

C056 — load_sample

داده آموزشی آفلاین نسخه‌دار.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
name str 'daily_prices_v1' نام نمونه،snapshot یاfeature مطابق تابع؛ نام فایل/مدل arbitrary code اجرا نمی‌کند.

نوع خروجی: pd.DataFrame

ساختار خروجی: DailyBar schema

رفتار و محدودیت‌ها: نمونه ساختگی یا بازتوزیع‌مجاز با برچسب صریح؛ اینترنت/دیتابیس لازم نیست؛ PIT تاریخی از داده ساختگی استنباط نشود.

استثناها: UnknownSampleError, IntegrityError

وابستگی‌ها: pandas, stdlib

قابلیت حفظ‌شده از سند قبل: load_sample

C057 — AsyncClient

کلاینت ناهمگام هم‌ارز Client.

AsyncClient(*, config: ClientConfig | None = None, source: Source | None = None, mode: AccessMode | None = None, storage: bool | None = None, data_dir: PathLike | None = None, credentials: Credentials | None = None) -> AsyncClient

وضعیت: proposed_not_implemented — مرحله: P06 — نوع مدخل: class

پارامتر نوع مقدار پیش‌فرض معنا
config ClientConfig | None None تنظیمات immutable مشترک؛ در Client آرگومان‌های غیر None بر آن مقدم‌اند.
source Source | None None منبع public یا official؛ تعویض پنهان منبع یا حساب مجاز نیست.
mode AccessMode | None None auto،online یاoffline؛ None ارث‌بری از پیکربندی، نه تصمیم بر اساس وجود فایل.
storage bool | None None در Client: فلگ فعال/غیرفعال یا ارث‌بری با None؛ در ClientConfig: تنظیمات StorageConfig. None در ClientConfig یعنی فعال با پیش‌فرض.
data_dir PathLike | None None مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
credentials Credentials | None None اعتبارنامه رسمی متعلق به خود کاربر؛ در حافظه، خارج از repr/log/export.

نوع خروجی: AsyncClient

رفتار و محدودیت‌ها: فقط هماهنگی I/O ناهمگام متفاوت است؛ parser، شِما، validator، planner و منطق خطا مشترک. config همان معنا؛ async with و aclose. I/O SQLite در thread محدود؛ CPU سنگین analytics یا ML با async سریع‌تر نمی‌شود.

استثناها: ConfigurationError

وابستگی‌ها: pandas, httpx, stdlib

قابلیت حفظ‌شده از سند قبل: AsyncClient

C058 — watch_market

دیده‌بان با polling کنترل‌شده.

watch_market(*, client: AsyncClient, market: Market, interval: float, stop_after: int | None = None) -> AsyncIterator[pd.DataFrame]

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: async_iterator

پارامتر نوع مقدار پیش‌فرض معنا
client AsyncClient الزامی کلاینت ساخته‌شده کاربر با منبع وscope مربوط؛ مالکیت بسته‌شدن در قرارداد تابع مشخص است.
market Market الزامی بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
interval float الزامی interval فاصله polling یا بازه کندل مطابق نوع؛ stop_after تعداد خروجی‌های دیده‌بان، None تا لغو صریح.
stop_after int | None None interval فاصله polling یا بازه کندل مطابق نوع؛ stop_after تعداد خروجی‌های دیده‌بان، None تا لغو صریح.

نوع خروجی: AsyncIterator[pd.DataFrame]

رفتار و محدودیت‌ها: interval الزامی و مثبت؛ با محدودیت منبع محدود می‌شود. WebSocket یا دسترسی نامحدود نیست. cancellation پاک‌سازی اتصال؛ ذخیره به صف محدود سپرده می‌شود؛ هر yield timestamp و freshness دارد.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError, PointInTimeUnavailableError, MissingValueError, UnsupportedQuoteUnitError, BatchDataError, CoverageError

وابستگی‌ها: httpx, pandas, asyncio

قابلیت حفظ‌شده از سند قبل: watch_market

C059 — configure

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

configure(config: ClientConfig) -> None

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
config ClientConfig الزامی تنظیمات immutable مشترک؛ در Client آرگومان‌های غیر None بر آن مقدم‌اند.

نوع خروجی: None

رفتار و محدودیت‌ها: تغییر config پس از ایجاد default client رد می‌شود؛ برای تنظیمات مختلف Client مستقل بسازید.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C060 — get_frame_manifest

خواندن شناسنامه نتیجه.

get_frame_manifest(df: pd.DataFrame) -> FrameManifest

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.

نوع خروجی: FrameManifest

رفتار و محدودیت‌ها: شناسنامه کوچک attrs + شناسه‌های ردیفی اعتبارسنجی می‌شود؛ attrs مفقود به unknown تبدیل، نه منبع/زمان حدسی. این تابع وعده بازیابی shِمای اصلی پس از عملیات arbitrary Pandas ندارد.

استثناها: MissingMetadataError, IntegrityError

وابستگی‌ها: pandas

C061 — get_request_report

گزارش موفقیت، شکست، پوشش و صف یک درخواست.

get_request_report(request_id: str) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
request_id str الزامی شناسه درخواست برای تشخیص/رسید؛ بدون secret. ممکن است گزارش RAM پس از پایان retention موجود نباشد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: از ring buffer کران‌دار حافظه؛ در صورت expire صریح unknown. گزارش بادوام فقط با ذخیره موفق قابل بازیابی از مخزن است.

استثناها: UnknownRequestError

وابستگی‌ها: pandas, diagnostics

C062 — storage_status

وضعیت حافظه‌ای ذخیره و صف.

storage_status() -> StorageStatus

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
— — — ورودی صریح ندارد.

نوع خروجی: StorageStatus

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

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C063 — flush

انتظار صریح تا تعیین تکلیف نوشتن‌های پذیرفته‌شده پیش از فراخوانی.

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

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
timeout float 5.0 مهلت انتظار صریح بر حسب ثانیه؛ deadline سیستم‌عامل را به‌صورت سخت تضمین نمی‌کند؛ بعد از آن نتیجه ناقص آشکار است.
raise_on_error bool True در صورت False گزارش شکست بازمی‌گردد؛ هیچ حالت failed به complete/persisted تبدیل نمی‌شود.

نوع خروجی: FlushReport

رفتار و محدودیت‌ها: این عملیات عمداً ممکن است منتظر دیسک بماند. timeout مثبت؛ queued به persisted تبدیل تلقی نمی‌شود. raise_on_error=False گزارش incomplete/failed برمی‌گرداند. داده ردشده هنگام پرشدن صف، با flush بازیابی نمی‌شود.

استثناها: StorageError, StorageFlushTimeout

وابستگی‌ها: stdlib, repository

C064 — close

بستن کلاینت همگام و تلاش محدود برای تخلیه.

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

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
flush_timeout float 1.0 مهلت انتظار صریح بر حسب ثانیه؛ deadline سیستم‌عامل را به‌صورت سخت تضمین نمی‌کند؛ بعد از آن نتیجه ناقص آشکار است.

نوع خروجی: FlushReport

رفتار و محدودیت‌ها: context manager نیز همین رفتار دارد؛ خطای اصلی بلوک با خطای cleanup پوشانده نمی‌شود. پس از close فراخوانی داده ClosedClientError؛ با پایان مهلت ممکن است داده‌های pending از دست برود.

استثناها: InvalidArgumentError, ClosedClientError

وابستگی‌ها: stdlib, httpx

C065 — aflush

تخلیه صریح بدون مسدودکردن event loop.

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

وضعیت: proposed_not_implemented — مرحله: P06 — نوع مدخل: async_function

پارامتر نوع مقدار پیش‌فرض معنا
timeout float 5.0 مهلت انتظار صریح بر حسب ثانیه؛ deadline سیستم‌عامل را به‌صورت سخت تضمین نمی‌کند؛ بعد از آن نتیجه ناقص آشکار است.
raise_on_error bool True در صورت False گزارش شکست بازمی‌گردد؛ هیچ حالت failed به complete/persisted تبدیل نمی‌شود.

نوع خروجی: FlushReport

رفتار و محدودیت‌ها: همان قرارداد flush؛ await لازم است، نه asyncio.run داخل notebook.

استثناها: StorageError, StorageFlushTimeout

وابستگی‌ها: asyncio, repository

C066 — aclose

بستن کلاینت ناهمگام.

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

وضعیت: proposed_not_implemented — مرحله: P06 — نوع مدخل: async_function

پارامتر نوع مقدار پیش‌فرض معنا
flush_timeout float 1.0 مهلت انتظار صریح بر حسب ثانیه؛ deadline سیستم‌عامل را به‌صورت سخت تضمین نمی‌کند؛ بعد از آن نتیجه ناقص آشکار است.

نوع خروجی: FlushReport

رفتار و محدودیت‌ها: await لازم است؛ لغو شبکه و cleanup زمان‌دار؛ خطای اصلی حفظ شود.

استثناها: InvalidArgumentError

وابستگی‌ها: asyncio, httpx

C067 — save

ذخیره صریح CSV/Excel/Parquet/SQLite.

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

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
path PathLike الزامی مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
format FileFormat | None None قالب مجاز فایل/مدل مطابق Literal؛ None فقط برای فایل از پسوند معتبر استنتاج می‌شود.
dataset str 'user_data' نام dataset/جدول مجاز یا DatasetBundle مطابق نوع پارامتر؛ به SQL بدون اعتبارسنجی چسبانده نمی‌شود.
metadata bool True همراهی manifest وشِما با ذخیره؛ خاموش‌کردن آن تضمین بازیابی نوع وPIT را کاهش می‌دهد.
overwrite bool False اجازه جایگزینی مقصد؛ False پیش‌فرض و وجود مقصد FileExistsError.
safe_text bool True خنثی‌سازی رشته‌های قابل تفسیر به فرمول هنگام export و ثبت تبدیل؛ مقادیر عددی اصلی بی‌دلیل متن نمی‌شوند.

نوع خروجی: WriteReceipt

رفتار و محدودیت‌ها: format=None فقط از پسوند معتبر؛ SQLite destination یک جدول مجاز زیر namespace user_data است نه جدول داخلی observations. metadata=True فایل شِما/manifest یا sheet metadata/table manifests. امن‌سازی متن خروجی جداول برای جلوگیری از تفسیر فرمول، تغییر قابل ردگیری. خطای ذخیره هرگز موفق اعلام نمی‌شود.

استثناها: StorageError, FileExistsError, MissingDependencyError, DataTypeError

وابستگی‌ها: pandas, sqlite3, optional:openpyxl, optional:pyarrow

C068 — load

بازیابی صریح از چهار قالب.

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

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
path PathLike الزامی مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
format FileFormat | None None قالب مجاز فایل/مدل مطابق Literal؛ None فقط برای فایل از پسوند معتبر استنتاج می‌شود.
dataset str 'user_data' نام dataset/جدول مجاز یا DatasetBundle مطابق نوع پارامتر؛ به SQL بدون اعتبارسنجی چسبانده نمی‌شود.
schema str | None None شناسه شِمای نسخه‌دار ثبت‌شده؛ تبدیل بدون قرارداد معنایی مجاز نیست.
verify bool True کنترل hash،schema وmetadata؛ hash به‌تنهایی اعتماد به ناشر را اثبات نمی‌کند.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: CSV بدون manifest تضمین dtype/PIT ندارد؛ schema کاربر یا metadata بررسی شود. dtype شناسه همیشه string و زمان منطقه‌دار بازسازی می‌شود. فایل ناامن pickle پذیرفته نیست.

استثناها: StorageError, IntegrityError, MissingDependencyError, SchemaMismatchError

وابستگی‌ها: pandas, sqlite3, optional:openpyxl, optional:pyarrow

C069 — load_stored

خواندن صریح آرشیو محلی بدون اینترنت.

load_stored(dataset: str, *, instruments: Sequence[InstrumentLike] | None = None, start: DateLike | None = None, end: DateLike | None = None, as_of: datetime | None = None, calendar: Calendar = 'gregorian', strict: bool = True) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
dataset str الزامی نام dataset/جدول مجاز یا DatasetBundle مطابق نوع پارامتر؛ به SQL بدون اعتبارسنجی چسبانده نمی‌شود.
instruments Sequence[InstrumentLike] | None None دنباله ابزارها به ترتیب درخواست؛ رشته منفرد به‌جای دنباله پذیرفته نمی‌شود و تکرارها بی‌اجازه حذف نمی‌شوند.
start DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
end DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
as_of datetime | None None cutoff؛ datetime باید آگاه به منطقه زمانی باشد. در get_instrument، as_of تاریخ اعتبار هویت و known_at زمان دانسته‌شدن نسخه است.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
strict bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: strict=True فقدان دامنه/نسخه لازم خطاست؛ این API برخلاف کش اختیاری به دیسک وابسته است. بدون as_of نمای latest؛ با as_of فقط نسخه شناخته‌شده در زمان مشخص.

استثناها: StorageError, OfflineDataUnavailableError, PointInTimeUnavailableError

وابستگی‌ها: pandas, repository

C070 — make_snapshot

ثبت صریح مجموعه ثابت برای بازتولید آزمایش.

make_snapshot(df: pd.DataFrame, *, name: str, include_raw: bool = True) -> SnapshotManifest

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
name str الزامی نام نمونه،snapshot یاfeature مطابق تابع؛ نام فایل/مدل arbitrary code اجرا نمی‌کند.
include_raw bool True حفظ پاسخ خام فاقد اسرار؛ include_raw در snapshot نیازمند وجود واقعی raw است.

نوع خروجی: SnapshotManifest

رفتار و محدودیت‌ها: نسخه‌های داده، schema، code، query و hash ثبت شوند؛ raw ناموجود/ذخیره‌نشده با include_raw=True خطا، نه تضمین ساختگی.

استثناها: StorageError, MissingProvenanceError

وابستگی‌ها: repository, hashlib, pandas

C071 — validate

گزارش کنترل شِما و کیفیت.

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

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
schema str الزامی شناسه شِمای نسخه‌دار ثبت‌شده؛ تبدیل بدون قرارداد معنایی مجاز نیست.
strict bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: خروجی ستون‌های row_id, rule, severity, message دارد. strict=True روی خطای مانع ادامه DataQualityError حاوی همین گزارش؛ DataFrame ورودی دست‌نخورده.

استثناها: SchemaMismatchError, DataQualityError

وابستگی‌ها: pandas, schema_registry

C072 — normalize

عادی‌سازی صریح داده واردشده با نگاشت ثبت‌شده.

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

وضعیت: proposed_not_implemented — مرحله: P04 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
schema str الزامی شناسه شِمای نسخه‌دار ثبت‌شده؛ تبدیل بدون قرارداد معنایی مجاز نیست.
source str الزامی منبع public یا official؛ تعویض پنهان منبع یا حساب مجاز نیست.
strict bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: فقط نگاشت source/schema تأییدشده؛ تغییر نویسه‌ها در کل payload ممنوع. missing≠0، واحد از روی حدس تعیین نمی‌شود؛ raw در آرشیو یا ورودی کاربر محفوظ بماند.

استثناها: SchemaMismatchError, DataQualityError

وابستگی‌ها: pandas, schema_registry

C104 — StorageConfig

تنظیمات ذخیره خودکار بهترین‌تلاش.

StorageConfig(*, enabled: bool = True, backend: Literal['sqlite'] = 'sqlite', path: PathLike | 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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
enabled bool True فعال‌بودن ذخیره وBackend پشتیبانی‌شده؛ در نسخه اولیه فقط sqlite.
backend Literal['sqlite'] 'sqlite' فعال‌بودن ذخیره وBackend پشتیبانی‌شده؛ در نسخه اولیه فقط sqlite.
path PathLike | None None مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
queue_max_jobs int 128 کران صف و سیاست overflow؛ bytes فقط payload صف،نه کلRAM؛ drop_new اجازه انتظار دیسک نمی‌دهد.
queue_max_bytes int 67108864 کران صف و سیاست overflow؛ bytes فقط payload صف،نه کلRAM؛ drop_new اجازه انتظار دیسک نمی‌دهد.
queue_overflow Literal['drop_new'] 'drop_new' کران صف و سیاست overflow؛ bytes فقط payload صف،نه کلRAM؛ drop_new اجازه انتظار دیسک نمی‌دهد.
read_timeout float 0.05 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
offline_read_timeout float 30.0 بودجه ثانیه‌ای خواندن ضروری مخزن در حالت آفلاین یا fallback پذیرفته‌شده؛ با بودجه کوتاه cache lookup عادی متفاوت است.
busy_timeout float 0.1 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
failure_cooldown float 60.0 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
raw_capture bool True حفظ پاسخ خام فاقد اسرار؛ include_raw در snapshot نیازمند وجود واقعی raw است.

نوع خروجی: StorageConfig

رفتار و محدودیت‌ها: path=None مسیر user_data_dir('tse-dara')/dara.sqlite3. سقف ۶۴MiB بودجه payload صف است نه کل RAM. queue_full/drop_new ثبت failure و برگرداندن داده؛ نه انتظار دیسک. مقادیر timeout و سقف‌ها انتخاب قابل تنظیم پروژه‌اند و تضمین سیستم‌عامل یا نرخ مجاز بورس نیستند.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C105 — 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) -> NetworkConfig

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
connect_timeout float 5.0 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
read_timeout float 20.0 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
operation_timeout float 60.0 بودجه‌های ثانیه‌ای طبق کلاس میزبان: read_timeout شبکه/کش متفاوت است؛ failure_cooldown فاصله تلاش دوباره ذخیره degraded.
max_concurrency int 4 حدمحلی concurrency/retry/تعداددرخواست/نرخ؛ محدودیت واقعی منبع مقدم ونامعلوم به نامحدود تبدیل نمی‌شود.
max_retries int 2 حدمحلی concurrency/retry/تعداددرخواست/نرخ؛ محدودیت واقعی منبع مقدم ونامعلوم به نامحدود تبدیل نمی‌شود.
requests_per_second float 0.5 حدمحلی concurrency/retry/تعداددرخواست/نرخ؛ محدودیت واقعی منبع مقدم ونامعلوم به نامحدود تبدیل نمی‌شود.
request_budget int 100 حدمحلی concurrency/retry/تعداددرخواست/نرخ؛ محدودیت واقعی منبع مقدم ونامعلوم به نامحدود تبدیل نمی‌شود.

نوع خروجی: NetworkConfig

رفتار و محدودیت‌ها: مقادیر مثبت و retries>=0؛ operation deadline کل تلاش‌ها را پوشش می‌دهد. نرخ ۰٫۵ سقف محتاطانه پیشنهادی محلی است، نه سقف رسمی سرویس؛ مجوز/Retry-After و محدودیت شناخته‌شده هر endpoint مقدم‌اند. retry روی POST احراز‌شده فقط پس از ثبت safe_read و اثر اعتبار؛ پیش‌فرض برای آن صفر.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C106 — FreshnessPolicy

تازگی و اجازه استفاده از داده قدیمی.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
max_age timedelta | None None حدسن کش/حدقدمت قابل استفاده و اجازه stale. None طبق توضیح FreshnessPolicy؛ زمان دریافت بازمان معامله یکسان نیست.
allow_stale bool False حدسن کش/حدقدمت قابل استفاده و اجازه stale. None طبق توضیح FreshnessPolicy؛ زمان دریافت بازمان معامله یکسان نیست.
max_stale timedelta | None None حدسن کش/حدقدمت قابل استفاده و اجازه stale. None طبق توضیح FreshnessPolicy؛ زمان دریافت بازمان معامله یکسان نیست.

نوع خروجی: FreshnessPolicy

رفتار و محدودیت‌ها: max_age زمان اعتبار از fetched_at برای سیاست کش است نه اثبات معامله جدید؛ source_timestamp جدا کنترل می‌شود. max_stale=None همراه allow_stale=False نادیده؛ با True بدون سقف زمانی صریح ولی هشدار واضح. زمان منبع نامعلوم به fresh تبدیل نمی‌شود.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C107 — FetchPolicy

سیاست خواندن هر درخواست.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
mode AccessMode | None None auto،online یاoffline؛ None ارث‌بری از پیکربندی، نه تصمیم بر اساس وجود فایل.
freshness FreshnessPolicy | None None سیاست تازگی همین فراخوانی؛ None سیاست dataset/Client. max_age کش با زمان معامله یکسان نیست.
coverage Literal['raise', 'report'] 'report' raise پوشش ناکافی را رد؛ report وضعیت partial/unknown را همراه نتیجه حفظ می‌کند.
allow_official_offline bool False اجازه نرم‌افزاری خواندن ذخیره رسمی؛ به‌تنهایی جایگزین اجازه قراردادی نیست.

نوع خروجی: FetchPolicy

رفتار و محدودیت‌ها: None به config و سپس سیاست نوع داده ارجاع دارد. offline هرگز شبکه نمی‌زند؛ online از داده تازه یا شبکه استفاده و در خطا stale خودکار ندارد؛ auto بر اساس freshness. 401/403 یا انقضای مجوز بهانه fallback پنهان نیست. استفاده آفلاین داده رسمی علاوه بر فلگ نیازمند مجوز مربوط است.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C108 — ClientConfig

پیکربندی پایه هر Client.

ClientConfig(*, source: Source = 'public', mode: AccessMode = 'auto', storage: StorageConfig | None = None, network: NetworkConfig | None = None, numeric: NumericProfile = 'analysis', timezone: str = 'Asia/Tehran', strict_schema: bool = True) -> ClientConfig

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
source Source 'public' منبع public یا official؛ تعویض پنهان منبع یا حساب مجاز نیست.
mode AccessMode 'auto' auto،online یاoffline؛ None ارث‌بری از پیکربندی، نه تصمیم بر اساس وجود فایل.
storage StorageConfig | None None در Client: فلگ فعال/غیرفعال یا ارث‌بری با None؛ در ClientConfig: تنظیمات StorageConfig. None در ClientConfig یعنی فعال با پیش‌فرض.
network NetworkConfig | None None تنظیمات شبکه؛ None معادل NetworkConfig پیش‌فرض.
numeric NumericProfile 'analysis' analysis یعنی نوع عددی Pandas مناسب تحلیل؛ exact یعنی Decimal با دقت منبع. شناسه هر دو حالت string است.
timezone str 'Asia/Tehran' شناسه منطقه زمانی معتبر مانند Asia/Tehran؛ نه اختلاف ثابتUTC.
strict_schema bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: ClientConfig

رفتار و محدودیت‌ها: storage=None در این dataclass یعنی StorageConfig() فعال؛ غیرفعال‌سازی با StorageConfig(enabled=False) یا Client(storage=False). network=None=>NetworkConfig(). داده تاریخی auto اجازه stale با گزارش؛ quote None-freshness معادل max_age=0 وallow_stale=False. پیکربندی immutable و بعد از ساخت کلاینت قابل تغییر نیست.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C109 — Credentials

اعتبارنامه حساب رسمی.

Credentials(*, username: str, password: str) -> Credentials

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
username str الزامی اعتبارنامه خصوصی کاربر؛ عدم ثبت درlog/repr/zip؛ ارسال فقطباTLS بهدامنه رسمی مجاز.
password str الزامی اعتبارنامه خصوصی کاربر؛ عدم ثبت درlog/repr/zip؛ ارسال فقطباTLS بهدامنه رسمی مجاز.

نوع خروجی: Credentials

رفتار و محدودیت‌ها: repr و log باید redact شوند؛ secret از محیط/ورودی امن؛ serialization عمومی ممنوع. توکن داخل AuthSession فقط حافظه‌ای است. وجود نوع Credentials به معنی حساب یا مجوز همراه بسته نیست.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C110 — InstrumentRef

شناسه صریح ابزار.

InstrumentRef(*, kind: Literal['symbol','ins_code','isin'], value: str, market: Market | None = None) -> InstrumentRef

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
kind Literal['symbol', 'ins_code', 'isin'] الزامی نوع شناسه صریح: symbol/ins_code/isin.
value str الزامی نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.

نوع خروجی: InstrumentRef

رفتار و محدودیت‌ها: value غیرخالی؛ عدد طولانی یا نماد شبیه عدد از روی رشته تنها حدس زده نمی‌شود؛ constructor هیچ شبکه‌ای ندارد. by_ins_code/ by_isin/ by_symbol سازنده‌های راحتی همان قراردادند.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

C112 — InstrumentRef.by_ins_code

سازنده شناسه نوع ins_code.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: staticmethod

پارامتر نوع مقدار پیش‌فرض معنا
value str الزامی نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.

نوع خروجی: InstrumentRef

رفتار و محدودیت‌ها: برابر InstrumentRef(kind='ins_code',value=value,market=market)؛ بدون I/O.

استثناها: InvalidArgumentError

وابستگی‌ها: stdlib

C113 — InstrumentRef.by_isin

سازنده شناسه نوع isin.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: staticmethod

پارامتر نوع مقدار پیش‌فرض معنا
value str الزامی نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.

نوع خروجی: InstrumentRef

رفتار و محدودیت‌ها: برابر InstrumentRef(kind='isin',value=value,market=market)؛ بدون I/O.

استثناها: InvalidArgumentError

وابستگی‌ها: stdlib

C114 — InstrumentRef.by_symbol

سازنده شناسه نوع symbol.

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

وضعیت: proposed_not_implemented — مرحله: P01 — نوع مدخل: staticmethod

پارامتر نوع مقدار پیش‌فرض معنا
value str الزامی نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.

نوع خروجی: InstrumentRef

رفتار و محدودیت‌ها: برابر InstrumentRef(kind='symbol',value=value,market=market)؛ بدون I/O.

استثناها: InvalidArgumentError

وابستگی‌ها: stdlib

C119 — get_fundamentals

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

get_fundamentals(instrument: InstrumentLike, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
day DateLike | None None تاریخ یا رشته با تقویم اعلام‌شده؛ start/end شامل‌اند. None در بازه تاریخچه یعنی حد پوشش موجود منبع، نه تضمین تمام تاریخ.
calendar Calendar 'gregorian' تقویم رشته‌های DateLike: gregorian یاjalali. date پایتون میلادی است؛ تقویم از عدد حدس زده نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FundamentalSnapshot

رفتار و محدودیت‌ها: eps،sales_per_share در صورت وجود،eps_basis/fiscal_period،published_at/observed_at وquote_basis. None برایday یعنی snapshot جاری؛ تاریخچه فقط باcapabilityمنبع. اعداد EPS/P/S ناشناخته با حدس برچسب TTM نمی‌گیرند. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_fundamentals

C120 — get_instrument_metrics

مشخصات و آمار تکمیلی نماد.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: InstrumentMetrics

رفتار و محدودیت‌ها: source-reported: تعدادسهام،حجم‌مبنا،درصدشناوری،میانگین‌حجم‌ماه وکمینه/بیشینه‌هفته/سال درصورتوجود؛window/time/unit/sourceهرآمارثبت. داده غایب ازقیمت تاریخچه به‌طور پنهانی محاسبه نشود. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_instrument_metrics

C121 — get_related_instruments

نمادهای مرتبط/هم‌گروه بر اساس قرارداد منبع.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
instrument InstrumentLike الزامی نام نماد یا InstrumentRef صریح؛ رشته عددی به‌طور خودکار شناسه فرض نمی‌شود؛ underlying دارایی پایه را مشخص می‌کند.
sector_code str | None None شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: RelatedInstrument

رفتار و محدودیت‌ها: ارتباط گروه صنعتی به معنی مالکیت یا رابطه شرکت مادر/فرعی نیست. quote و تاریخچه جانبی پاسخ اگر استفاده شوند با زمان مستقل ثبت شوند. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_related_instruments

C122 — get_key_statistics

آمار کلیدی نمادها با فرهنگ پارامتر نسخه‌دار.

get_key_statistics(*, market: Market | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: KeyStatistic

رفتار و محدودیت‌ها: خروجی long: ins_code,parameter_code,parameter_name,value,unit,period,observed_at؛پارامتر بی‌شرحunknownمی‌ماند. صفر یا متن '-' خودکار عدد معتبر نمی‌شود. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_key_statistics

C123 — get_market_map

داده نقشه بازار، بدون رسم نمودار.

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

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
sector_code str | None None شناسه نوع مربوطه به شکل رشته دقیق؛ این شناسه‌ها با ins_code هم‌معنی نیستند.
limit int | None None حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: MarketMapRow

رفتار و محدودیت‌ها: فقط داده استاندارد ابزار/گروه/ارزش/تغییرقیمت؛پارامترهای اختصاصیAPIمانندtypeSelected تا اثبات معنابهقراردادعمومی‌نشت نکنند. coverage دامنه واقعی پاسخ. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_market_map

C124 — get_fund_rankings

رتبه‌بندی ETFها طبق منبع یا محاسبه صریح رویsnapshotکامل.

get_fund_rankings(*, ranking: Literal['volume','price_increase','price_decrease'], market: Market | None = None, limit: int = 20, policy: FetchPolicy | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: client_method_and_module_facade

پارامتر نوع مقدار پیش‌فرض معنا
ranking Literal['volume', 'price_increase', 'price_decrease'] الزامی معیار صریح انتخاب طبق Literal وشرح رفتار تابع.
market Market | None None بازار معنایی استاندارد؛ None یعنی محدودنکردن جست‌وجو یا استفاده از دامنه پشتیبانی‌شده تابع، نه نگاشت حدسی Flow=0.
limit int 20 حد تعداد ردیف؛ عدد مثبت یا None برای دامنه موجود. نرخ مجاز یا تعداد کل داده از آن نتیجه نمی‌شود.
policy FetchPolicy | None None سیاست همین فراخوانی؛ None یعنی سیاست پیش‌فرض dataset و Client. freshness صریح تابع از این policy مقدم است.

نوع خروجی: pd.DataFrame

ساختار خروجی: FundRanking

رفتار و محدودیت‌ها: ranking معنای روشن؛رتبه‌بندی برگرفته‌از subset ناقص به‌عنوان کل بازار معرفی نشود. method/source_timestamp/datacoverage اعلام. ذخیره خودکار بهترین‌تلاش؛ schema وواحدغایب خطا/unknown مطابقسیاست،نهحدس.

استثناها: InvalidArgumentError, UnknownInstrumentError, AmbiguousInstrumentError, NetworkError, ApiError, PermissionDeniedError, RateLimitError, CreditExhaustedError, SchemaMismatchError, DataQualityError, StaleDataError, OfflineDataUnavailableError, UnsupportedCapabilityError, RequestBudgetExceededError, MissingDependencyError, ClosedClientError

وابستگی‌ها: pandas, httpx, provider.get_fund_rankings

C125 — get_write_receipt

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

get_write_receipt(receipt_id: str) -> WriteReceipt

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
receipt_id str الزامی شناسه رسید ذخیره؛ هیچ token کاربری نیست.

نوع خروجی: WriteReceipt

رفتار و محدودیت‌ها: ابتدا حافظه؛ در حالت عادی منتظر DB نمی‌ماند. رسید خارج از retention حافظه باید با خواندن صریح journal مخزن بازیابی شود؛ UnknownReceiptError به معنی persisted نیست.

استثناها: UnknownReceiptError

وابستگی‌ها: stdlib

C126 — load_snapshot

بازیابی همان مجموعه ثابت ثبت‌شده.

load_snapshot(snapshot_id: str) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
snapshot_id str الزامی شناسه اسنپ‌شات بادوام.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: فقط اعضای immutable snapshot؛ hash/وجود همه observationها کنترل شود. snapshot ناقص یا داده حذف‌شده IntegrityError؛ network برای پرکردن با نسخه امروز مجاز نیست.

استثناها: StorageError, IntegrityError, UnknownSnapshotError

وابستگی‌ها: pandas, repository

C127 — migrate_storage

برنامه یا اجرای صریح مهاجرت مخزن.

migrate_storage(*, target_version: int, dry_run: bool = True) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P05 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
target_version int الزامی نسخه هدف مهاجرت ثبت‌شده؛ عدد دلخواهِ بدون مسیر مهاجرت پذیرفته نیست.
dry_run bool True True فقط برنامه را گزارش می‌کند؛ False اجازه اجرای صریح.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: پیش‌فرض صرف طرح؛ شروع migration بعد از توقف نویسنده و تعیین تکلیف صف؛ دسترسی به داده اصلی بدون حذف/جایگزینی خودکار. اگر flush کامل نشد اجرای migration متوقف شود. دریافت عادی بدون انتظار این عملیات از شبکه ممکن است؛ همان مخزن تا اتمام درحالتdegraded/read-only است.

استثناها: StorageError, SchemaVersionError, StorageFlushTimeout

وابستگی‌ها: repository, pandas

همتاهای AsyncClient

در سطرهای عادی زیر نوع بعد از await نوشته شده است؛ iter_history تولیدکننده ناهمگام و مصرف آن async for است. پیاده‌سازی‌ها از parser/validator/planner یکسان استفاده می‌کنند.

متد امضای کامل قرارداد مشترک
search_instruments async search_instruments(query: str, *, market: Market | None = None, include_inactive: bool = True, limit: int | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C003
get_instrument async get_instrument(instrument: InstrumentLike, *, market: Market | None = None, as_of: date | None = None, known_at: datetime | None = None, policy: FetchPolicy | None = None) -> InstrumentRecord C004
get_instruments async get_instruments(*, market: Market | None = None, include_inactive: bool = True, changed_since: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C005
get_quote async get_quote(instrument: InstrumentLike, *, freshness: FreshnessPolicy | None = None, policy: FetchPolicy | None = None) -> Quote C006
get_price async get_price(instrument: InstrumentLike, *, field: PriceField = 'last', freshness: FreshnessPolicy | None = None, policy: FetchPolicy | None = None) -> Decimal C007
get_quotes async get_quotes(instruments: Sequence[InstrumentLike], *, on_error: ErrorPolicy = 'raise', freshness: FreshnessPolicy | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C008
get_history async get_history(instrument: InstrumentLike, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', adjustment: AdjustmentMode = 'none', series: SeriesMode = 'listing', as_of: datetime | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C009
iter_history async iter_history(instrument: InstrumentLike, *, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', adjustment: AdjustmentMode = 'none', chunk_days: int = 366, policy: FetchPolicy | None = None) -> AsyncIterator[pd.DataFrame] C010
get_history_many async get_history_many(instruments: Sequence[InstrumentLike], *, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', adjustment: AdjustmentMode = 'none', on_error: ErrorPolicy = 'raise', policy: FetchPolicy | None = None) -> BatchFrames C011
get_daily_market async get_daily_market(day: DateLike, *, market: Market, calendar: Calendar = 'gregorian', include_untraded: bool = True, policy: FetchPolicy | None = None) -> pd.DataFrame C012
get_adjustments async get_adjustments(instrument: InstrumentLike, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C013
get_market_watch async get_market_watch(*, market: Market | None = None, include_order_book: bool = False, include_client_types: bool = False, policy: FetchPolicy | None = None) -> pd.DataFrame C014
get_market_overview async get_market_overview(*, market: Market, policy: FetchPolicy | None = None) -> pd.DataFrame C015
get_client_types async get_client_types(instrument: InstrumentLike, *, policy: FetchPolicy | None = None) -> pd.DataFrame C016
get_client_type_history async get_client_type_history(instrument: InstrumentLike, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C017
get_market_client_types async get_market_client_types(*, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C018
get_indices async get_indices(*, market: Market | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C019
get_index async get_index(index_code: str, *, policy: FetchPolicy | None = None) -> pd.DataFrame C020
get_index_history async get_index_history(index_code: str, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C021
get_index_intraday async get_index_intraday(index_code: str, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C022
get_index_members async get_index_members(index_code: str, *, as_of: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C023
get_index_impact async get_index_impact(*, market: Market, limit: int = 25, policy: FetchPolicy | None = None) -> pd.DataFrame C024
get_order_book async get_order_book(instrument: InstrumentLike, *, depth: int = 5, policy: FetchPolicy | None = None) -> pd.DataFrame C025
get_order_book_updates async get_order_book_updates(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C026
get_trades async get_trades(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', cancellations: CancellationPolicy = 'as_reported', policy: FetchPolicy | None = None) -> pd.DataFrame C027
get_intraday_quotes async get_intraday_quotes(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C028
get_instrument_states async get_instrument_states(instrument: InstrumentLike, day: DateLike, *, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C029
get_thresholds async get_thresholds(instrument: InstrumentLike, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C030
get_shareholders async get_shareholders(instrument: InstrumentLike, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C031
get_shareholder_history async get_shareholder_history(instrument: InstrumentLike, shareholder_id: str, *, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C032
get_shareholder_holdings async get_shareholder_holdings(holding_ref: str, *, policy: FetchPolicy | None = None) -> pd.DataFrame C033
get_share_capital_history async get_share_capital_history(instrument: InstrumentLike, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C034
get_dividends async get_dividends(instrument: InstrumentLike, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C035
get_funds async get_funds(*, fund_type: FundCategory | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C036
get_fund async get_fund(registration_no: str, *, policy: FetchPolicy | None = None) -> pd.DataFrame C037
get_fund_nav_history async get_fund_nav_history(registration_no: str, *, start: DateLike | None = None, end: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C038
get_messages async get_messages(*, instrument: InstrumentLike | None = None, market: Market | None = None, day: DateLike | None = None, calendar: Calendar = 'gregorian', query: str | None = None, limit: int = 200, policy: FetchPolicy | None = None) -> pd.DataFrame C039
get_disclosures async get_disclosures(instrument: InstrumentLike, *, limit: int = 9, policy: FetchPolicy | None = None) -> pd.DataFrame C040
get_sectors async get_sectors(*, policy: FetchPolicy | None = None) -> pd.DataFrame C041
get_subsectors async get_subsectors(*, sector_code: str | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C042
get_boards async get_boards(*, policy: FetchPolicy | None = None) -> pd.DataFrame C043
get_market_sessions async get_market_sessions(*, market: Market, start: DateLike, end: DateLike, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C044
get_options async get_options(*, underlying: InstrumentLike | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C045
get_futures async get_futures(*, underlying: InstrumentLike | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C046
get_opening_auction async get_opening_auction(instrument: InstrumentLike, *, market: Market, policy: FetchPolicy | None = None) -> pd.DataFrame C047
get_energy_instruments async get_energy_instruments(*, active_only: bool = True, cursor: str | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C048
get_energy_auctions async get_energy_auctions(*, cursor: str | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C049
get_fundamentals async get_fundamentals(instrument: InstrumentLike, *, day: DateLike | None = None, calendar: Calendar = 'gregorian', policy: FetchPolicy | None = None) -> pd.DataFrame C119
get_instrument_metrics async get_instrument_metrics(instrument: InstrumentLike, *, policy: FetchPolicy | None = None) -> pd.DataFrame C120
get_related_instruments async get_related_instruments(instrument: InstrumentLike, *, sector_code: str | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C121
get_key_statistics async get_key_statistics(*, market: Market | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C122
get_market_map async get_market_map(*, market: Market | None = None, sector_code: str | None = None, limit: int | None = None, policy: FetchPolicy | None = None) -> pd.DataFrame C123
get_fund_rankings async get_fund_rankings(*, ranking: Literal['volume','price_increase','price_decrease'], market: Market | None = None, limit: int = 20, policy: FetchPolicy | None = None) -> pd.DataFrame C124

watch_market نیز AsyncIterator است؛ flush/close همتای صریح aflush/aclose دارند. قابلیت‌های خالص مانند ساخت تنظیمات و capabilities نیاز به await ندارند.

رابط facade سطح ماژول برای استفاده کوتاه است؛ مدیریت دقیق lifecycle با Client/AsyncClient و context manager انجام می‌شود. پس از پایان استفاده، flush صریح تنها راه انتظار آگاهانه برای دوام کارهای صف‌شده است.

تحلیل مالی، آماری و تکنیکال — قرارداد پیشنهادی نسخه ۰٫۲

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

توابعی که وابسته به endpoint هستند، تا اثبات دسترسی/معنا/پوشش در runtime نباید آماده اعلام شوند. نوع نتیجه ثابت است؛ None یا empty نباید خطای شبکه را پنهان کند.

C052 — resample_trades

ساخت OHLCV از ریزمعاملات معتبر.

resample_trades(trades: pd.DataFrame, *, interval: BarInterval, timezone: str = 'Asia/Tehran', closed: Literal['left','right'] = 'left', label: Literal['left','right'] = 'left', cancellations: CancellationPolicy = 'exclude_verified', sessions: pd.DataFrame | None = None) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P09 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
trades pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
interval BarInterval الزامی interval فاصله polling یا بازه کندل مطابق نوع؛ stop_after تعداد خروجی‌های دیده‌بان، None تا لغو صریح.
timezone str 'Asia/Tehran' شناسه منطقه زمانی معتبر مانند Asia/Tehran؛ نه اختلاف ثابتUTC.
closed Literal['left', 'right'] 'left' سمت باز/بسته بودن مرز بازه زمانی و برچسب کندل؛ مستقل ازقیمت closing.
label Literal['left', 'right'] 'left' سمت باز/بسته بودن مرز بازه زمانی و برچسب کندل؛ مستقل ازقیمت closing.
cancellations CancellationPolicy 'exclude_verified' as_reported حفظ وضعیت منبع؛ exclude_verified فقط بعد از تایید معنای ابطال. وضعیت نامعلوم نباید معامله معتبر تلقی شود.
sessions pd.DataFrame | None None جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.

نوع خروجی: pd.DataFrame

ساختار خروجی: IntradayBar + feature lineage

رفتار و محدودیت‌ها: گروه‌بندی مستقل هر ins_code و جلسه؛ حفظ ترتیب sequence در یک ثانیه؛ دوره خالی کندل ساختگی ندارد. cumulative volume را جمع نمی‌زند. ابتدا بررسی ابطال؛ وضعیت نامعلوم با exclude_verified خطاست. sessions=None فقط مرز روز محلی، نه ادعای بازسازی وقفه‌های بازار.

استثناها: SchemaMismatchError, UnknownCancellationError, DataQualityError

وابستگی‌ها: pandas, numpy

قابلیت حفظ‌شده از سند قبل: resample_trades

C073 — returns

محاسبه بازده قیمت هر ابزار.

returns(df: pd.DataFrame, *, price: str = 'closing_price', periods: int = 1, method: Literal['simple','log'] = 'simple', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
price str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
periods int 1 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
method Literal['simple', 'log'] 'simple' روش محاسبه محدود به Literal همین تابع؛ تعریف فرمول وseed در بخش رفتار ثبت شده است.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. بدون پرکردن خودکار داده؛ ساده P_t/P_(t-k)-1 و لگاریتمی log(P_t/P_(t-k)). مخرج صفر/قیمت نامعتبر خطاست؛ warm-up و قیمت گمشده NA. period تعداد ردیف مرتب هر گروه است نه روز تقویمی. خروجی کپی ورودی + return و return_basis؛ این بازده الزاماً بازده کل با سرمایه‌گذاری سود نقدی نیست.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C074 — cumulative_returns

ساخت مسیر ثروت و بازده انباشته.

cumulative_returns(df: pd.DataFrame, *, returns_col: str = 'return', initial: float = 1.0, missing: Literal['raise','propagate'] = 'raise', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
returns_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
initial float 1.0 مقدار آغازین ثروت یا DataFrame وضعیت اولیه مظنه مطابق نوع تابع.
missing Literal['raise', 'propagate'] 'raise' raise ردِ داده مفقود؛ propagate انتشار NA؛ drop_report حذف همراه گزارش فقط در تابعی که این گزینه را دارد.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. wealth=initial*product(1+r)؛ ورودی باید بازده ساده باشد؛ return<-1 رد، -1 ثروت را صفر می‌کند. missing='propagate' پس از اولین NA نتیجه گروه NA باقی می‌ماند؛ skip پنهانی ممنوع.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C075 — sma

میانگین متحرک ساده.

sma(df: pd.DataFrame, *, column: str = 'closing_price', window: int = 20, min_periods: int | None = None, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
column str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 20 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
min_periods int | None None حداقل مشاهدات معتبر؛ None برابر window/span همان تابع. warm-up با NA حفظ می‌شود.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. min_periods=None برابر window؛ rolling گذشته و امروز، center=False؛ خروجی sma_{window}. مقدار امروز تنها پس از در دسترس بودن آن قابل استفاده است.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C076 — ema

میانگین متحرک نمایی.

ema(df: pd.DataFrame, *, column: str = 'closing_price', span: int = 20, adjust: bool = False, min_periods: int | None = None, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
column str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
span int 20 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
adjust bool False گزینه وزن‌دهی ewm در EMA؛ با تعدیل شرکتی قیمت متفاوت است.
min_periods int | None None حداقل مشاهدات معتبر؛ None برابر window/span همان تابع. warm-up با NA حفظ می‌شود.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. قرارداد ewm با alpha=2/(span+1)؛ adjust=False بازگشتی با seed نخستین مقدار؛ min_periods=None برابر span. در هر قطعه داده پیوسته معتبر محاسبه؛ شکاف reset و warm-up مجدد دارد، نه پرکردن از آینده.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C077 — rsi

شاخص قدرت نسبی با تعریف مشخص.

rsi(df: pd.DataFrame, *, column: str = 'closing_price', window: int = 14, method: Literal['wilder'] = 'wilder', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
column str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 14 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
method Literal['wilder'] 'wilder' روش محاسبه محدود به Literal همین تابع؛ تعریف فرمول وseed در بخش رفتار ثبت شده است.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. seed میانگین ساده نخستین window تغییر معتبر؛ سپس میانگین بازگشتی alpha=1/window. 100-100/(1+avg_gain/avg_loss). هر دو صفر =>50؛ فقط زیان صفر=>100؛ فقط سود صفر=>0. شکاف reset؛ خروجی rsi_{window}. ادعای برابری با هر نرم‌افزار تکنیکال بدون تطبیق seed ندارد.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C078 — macd

محاسبه MACD، خط سیگنال و هیستوگرام.

macd(df: pd.DataFrame, *, column: str = 'closing_price', fast: int = 12, slow: int = 26, signal: int = 9, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
column str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
fast int 12 دوره EMA در MACD؛ slow>fast>0 وsignal>0.
slow int 26 دوره EMA در MACD؛ slow>fast>0 وsignal>0.
signal int 9 دوره EMA در MACD؛ slow>fast>0 وsignal>0.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. EMA قرارداد تابع ema؛ slow>fast>0؛ signal>0. macd=EMA_fast-EMA_slow؛ signal EMA روی macdهای معتبر؛ histogram اختلاف آن‌ها. warm-up منتشرشده و NA حذف نمی‌شود.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C079 — bollinger_bands

باندهای میانگین و انحراف معیار.

bollinger_bands(df: pd.DataFrame, *, column: str = 'closing_price', window: int = 20, deviations: float = 2.0, ddof: int = 0, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
column str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 20 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
deviations float 2.0 ضریب مثبت انحراف معیار باندهای بولینگر.
ddof int 0 درجه آزادی محاسبه انحراف معیار؛ صحیح نامنفی و کمتر از اندازه پنجره. در std شاخص‌ها به قرارداد همان تابع مراجعه شود.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. middle=SMA؛ upper/lower=middle±deviations*rolling_std؛ ddof به‌طور صریح صفر پیش‌فرض؛ window کامل، gap نتیجه NA. خروجی bb_middle,bb_upper,bb_lower.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C080 — atr

میانگین محدوده واقعی با هموارسازی Wilder.

atr(df: pd.DataFrame, *, high: str = 'high_price', low: str = 'low_price', close: str = 'closing_price', window: int = 14, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
high str 'high_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
low str 'low_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
close str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 14 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. TR=max(high-low,abs(high-prev_close),abs(low-prev_close))؛ نخستین ردیف هر قطعه high-low. seed میانگین اولین window TR، سپس alpha=1/window. همه قیمت‌ها باید از یک مبنای تعدیل و واحد باشند. ATRهای نسخه‌های دیگر با close=آخرین معامله ممکن است تفاوت داشته باشند.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C081 — rolling_volatility

نوسان سالانه‌شده بر اساس قرارداد کاربر.

rolling_volatility(df: pd.DataFrame, *, returns_col: str = 'return', window: int = 20, periods_per_year: int, ddof: int = 1, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
returns_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 20 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
periods_per_year int الزامی تعداد دوره‌های فرضی سال برای سالانه‌سازی؛ الزامی، مثبت و متناسب با داده، نه عدد ثابت 252.
ddof int 1 درجه آزادی محاسبه انحراف معیار؛ صحیح نامنفی و کمتر از اندازه پنجره. در std شاخص‌ها به قرارداد همان تابع مراجعه شود.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. std بازده ساده در window کامل ضرب sqrt(periods_per_year). عدد سالانه‌سازی الزاماً 252 نیست و باید متناسب با تعریف مشاهده داده انتخاب شود. nullها window را ناقص می‌کنند؛ ddof<window.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C082 — drawdown

افت از قله مسیر ارزش.

drawdown(df: pd.DataFrame, *, value: str = 'wealth', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
value str 'wealth' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. drawdown=value/cummax(value)-1؛ مسیر nonnegative و قله مثبت؛ خروجی drawdown منفی یا صفر. ورودی به ارزش جریان نقدی اضافه‌شده حساس است، نه جایگزین محاسبه بازده پول‌وزن.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C083 — max_drawdown

گزارش بزرگ‌ترین افت هر گروه.

max_drawdown(df: pd.DataFrame, *, value: str = 'wealth', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
value str 'wealth' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. یک ردیف برای هر گروه: max_drawdown(منفی)، peak_at,trough_at,recovered_at nullable. در تساوی انتخاب اولین رخداد مستند؛ ادعای بازسازی دادوستد ندارد.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C084 — risk_summary

آمار توصیفی بازده و ریسک.

risk_summary(df: pd.DataFrame, *, returns_col: str = 'return', periods_per_year: int, risk_free_per_period: float = 0.0, ddof: int = 1, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
returns_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
periods_per_year int الزامی تعداد دوره‌های فرضی سال برای سالانه‌سازی؛ الزامی، مثبت و متناسب با داده، نه عدد ثابت 252.
risk_free_per_period float 0.0 نرخ بدون ریسک ساده در همان دوره بازده ورودی؛ نرخ سالانه به‌طور پنهان تبدیل نمی‌شود.
ddof int 1 درجه آزادی محاسبه انحراف معیار؛ صحیح نامنفی و کمتر از اندازه پنجره. در std شاخص‌ها به قرارداد همان تابع مراجعه شود.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. ستون‌های n,mean_return,std_return,annualized_volatility,sharpe,max_drawdown؛ Sharpe=mean(r-rf)/std(r-rf)*sqrt(ppy). rf هم‌دوره ورودی نه سالانه؛ std=0=>NA و diagnostic. بدون NA پنهان؛ ابتدا warm-up را کاربر با گزارش حذف کند. فرض سالانه‌سازی باید در metadata ثبت شود.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C085 — correlation

همبستگی زوجی ابزارها.

correlation(df: pd.DataFrame, *, value: str = 'return', method: Literal['pearson','spearman'] = 'pearson', min_observations: int = 30, group_col: str = 'ins_code', time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
value str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
method Literal['pearson', 'spearman'] 'pearson' روش محاسبه محدود به Literal همین تابع؛ تعریف فرمول وseed در بخش رفتار ثبت شده است.
min_observations int 30 حداقل مشاهدات مشترک برای آمار قابل ارائه؛ کمبود، مقدار NA/گزارش و نه برآورد بی‌سند.
group_col str 'ins_code' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. قالب long: ins_code_a,ins_code_b,correlation,n_common؛ join روی زمان مشترک و اعلام تعداد. صفرکردن بازده‌های غایب ممنوع؛ این مقدار علّیت نیست.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C086 — rolling_beta

بتای غلتان نسبت به شاخص معرفی‌شده.

rolling_beta(df: pd.DataFrame, benchmark: pd.DataFrame, *, returns_col: str = 'return', benchmark_col: str = 'return', window: int = 60, group_col: str = 'ins_code', time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
benchmark pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
returns_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
benchmark_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 60 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
group_col str 'ins_code' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. join یک‌به‌یک زمان benchmark و هر ابزار؛ cov/var با ddof=1 یکسان؛ var=0=>NA. فقط window کامل مشاهدات هم‌تراز؛ عدم هم‌ترازی زمان‌های انتشار هشدار/مانع استفاده PIT.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C087 — portfolio_returns

محاسبه بازده پرتفوی وزن‌دار با قرارداد اجرا.

portfolio_returns(returns: pd.DataFrame, weights: pd.DataFrame, *, time_col: str = 'date', asset_col: str = 'ins_code', return_col: str = 'return', weight_col: str = 'weight', execution_lag: int = 1, costs_bps: float = 0.0, allow_leverage: bool = False) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
returns pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
weights pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
asset_col str 'ins_code' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
return_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
weight_col str 'weight' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
execution_lag int 1 تأخیر صحیح نامنفی در اعمال وزن/ویژگی؛ استفاده بدون تأخیر باید با زمان واقعی دسترسی داده سازگار باشد.
costs_bps float 0.0 هزینه یک‌طرفه بر حسب basis point؛ تقسیم بر10000. صفر فقط فرض آزمایش است، نه نبود هزینه بازار.
allow_leverage bool False اجازه صریح وزن منفی یا اهرم؛ پیش‌فرض False. نقدشوندگی وامکان سفارش واقعی را تضمین نمی‌کند.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. weights هر جلسه باید بردار کامل باشد؛ وزن t-execution_lag روی بازده t اعمال می‌شود. هزینه یک‌طرفه costs_bps/10000*sum(abs(delta_weight))؛ باقیمانده وجه نقد بازده صفر. پیش‌فرض بدون فروش استقراضی/اهرم. این مدل وزن ثابتِ ازپیش‌تعریف‌شده در هر دوره است، نه شبیه‌ساز صف و نقدشوندگی؛ عرضه وزن یک نماد غایب خطاست.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C088 — fundamental_ratios

نسبت‌های ساده از داده دارای واحد و دوره روشن.

fundamental_ratios(df: pd.DataFrame, *, price: str = 'closing_price', eps: str = 'eps', sales_per_share: str = 'sales_per_share', require_same_currency: bool = True) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P10 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
price str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
eps str 'eps' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
sales_per_share str 'sales_per_share' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
require_same_currency bool True کنترل تطابق ارز/واحد قیمت و مبنای هر سهم در نسبت‌های مالی.

نوع خروجی: pd.DataFrame

ساختار خروجی: ستون‌های هویتی و زمانی ورودی حفظ؛ ستون‌های نتیجه در توضیح قرارداد.

رفتار و محدودیت‌ها: بدون شبکه و دیسک و ذخیره خودکار؛ ورودی تغییر نمی‌کند؛ شِمای لازم کنترل و گروه‌ها مستقل‌اند. P/E=price/EPS؛ P/S=price/SPS؛ مخرج صفر NA با flag، منفی حذف نمی‌شود. تاریخ انتشار، مبنای سهم و دوره EPS باید همراه داده باشد. نبودن TTM یا سالانه در منبع به حدس تبدیل نمی‌شود. نمونه ورودی از TSETMC صورت مالی حسابرسی‌شده فرض نمی‌شود.

استثناها: InvalidArgumentError, SchemaMismatchError, DataTypeError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C115 — historical_var

ارزش در معرض ریسک و میانگین زیان دُم با روش تاریخی.

historical_var(df: pd.DataFrame, *, returns_col: str = 'return', confidence: float = 0.95, horizon: int = 1, interpolation: Literal['linear','lower','higher'] = 'linear', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
returns_col str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
confidence float 0.95 سطح اطمینان بین صفر ویک برای quantile تاریخی زیان؛ VaR تضمین حد ضرر نیست.
horizon int 1 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
interpolation Literal['linear', 'lower', 'higher'] 'linear' روش محاسبه صدک نمونه مطابق Literal؛ نتایج روش‌های متفاوت ممکن است متفاوت باشند.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: بازده horizon مشاهده با ترکیب (1+r) و سپس loss=-return؛ quantile(confidence) بدون clamp مصنوعی به صفر. expected_shortfall میانگین loss>=quantile با قرارداد شفاف tie؛ تعداد نمونه‌ها وoverlap گزارش شوند. ضرب sqrt(horizon) خودکار ندارد؛ VaR سقف قطعی زیان نیست. ورودی تغییر نمی‌کند؛ بدون شبکه/ذخیره خودکار.

استثناها: InvalidArgumentError, SchemaMismatchError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C116 — cagr

نرخ رشد مرکب بر مبنای زمان سپری‌شده.

cagr(df: pd.DataFrame, *, value: str = 'wealth', year_days: float = 365.2425, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
value str 'wealth' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
year_days float 365.2425 قرارداد طول سال برای CAGR زمانی؛ مقدارپیش‌فرض قراردادی،نه تعداد جلسات معامله.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: (last/first)**(year_days/elapsed_days)-1؛ آغاز مثبت،پایان نامنفی،فاصله مثبت؛ first==0 خطا. جریان وجوه ورودی/خروجی نباید با بازده یک دارایی اشتباه شود؛ مسیر wealth تعریف‌شده لازم است. ورودی تغییر نمی‌کند؛ بدون شبکه/ذخیره خودکار.

استثناها: InvalidArgumentError, SchemaMismatchError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C117 — vwap

میانگین قیمت وزن‌دار با حجم معاملات معتبر.

vwap(trades: pd.DataFrame, *, price: str = 'price', volume: str = 'volume', group_by: tuple[str, ...] = ('ins_code','date'), cancellations: CancellationPolicy = 'exclude_verified') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
trades pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
price str 'price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
volume str 'volume' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
group_by tuple[str, ...] ('ins_code', 'date') ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
cancellations CancellationPolicy 'exclude_verified' as_reported حفظ وضعیت منبع؛ exclude_verified فقط بعد از تایید معنای ابطال. وضعیت نامعلوم نباید معامله معتبر تلقی شود.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: sum(price*volume)/sum(volume) برای هرگروه؛ volume منفی رد؛ حجم مجموع صفر=>NA؛ واحدها یکسان؛ قیمت پایانی رسمی بورس را با این محاسبه یکی فرض نمی‌کنیم. ورودی تغییر نمی‌کند؛ بدون شبکه/ذخیره خودکار.

استثناها: InvalidArgumentError, SchemaMismatchError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

C118 — rolling_correlation

همبستگی غلتان با سری مرجع.

rolling_correlation(df: pd.DataFrame, benchmark: pd.DataFrame, *, value: str = 'return', benchmark_value: str = 'return', window: int = 60, group_col: str = 'ins_code', time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P07 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
benchmark pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
value str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
benchmark_value str 'return' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
window int 60 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
group_col str 'ins_code' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

رفتار و محدودیت‌ها: هم‌ترازی یک‌به‌یک وwindow کامل؛ نه forward-fill مرجع از آینده. خروجی rolling_correlation وn_common؛ واریانس صفر=>NA. ورودی تغییر نمی‌کند؛ بدون شبکه/ذخیره خودکار.

استثناها: InvalidArgumentError, SchemaMismatchError, DataQualityError, UnitMismatchError

وابستگی‌ها: pandas, numpy

یادگیری ماشین و کنترل نشت اطلاعات — قرارداد پیشنهادی نسخه ۰٫۲

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

توابعی که وابسته به endpoint هستند، تا اثبات دسترسی/معنا/پوشش در runtime نباید آماده اعلام شوند. نوع نتیجه ثابت است؛ None یا empty نباید خطای شبکه را پنهان کند.

C089 — point_in_time_join

اتصال اطلاعات قابل دسترس هنگام تصمیم.

point_in_time_join(left: pd.DataFrame, right: pd.DataFrame, *, left_time: str = 'decision_at', right_time: str = 'available_at', by: tuple[str, ...] = ('ins_code',), tolerance: timedelta | None = None, allow_exact_matches: bool = True) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
left pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
right pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
left_time str 'decision_at' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
right_time str 'available_at' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
tolerance timedelta | None None حداکثر فاصله زمانی مجاز اتصال backward؛ None بدون حد فاصله اما بدون اجازه اتصال آینده.
allow_exact_matches bool True اجازه استفاده از داده با زمان availability دقیقاً مساوی decision؛ زمان انتشار باید واقعاً معتبر باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ فقط backward در زمان availability و effective_at<=decision_at. right باید revision-resolved باشد: برای هر کلید طبیعی در هر cutoff آخرین نسخه شاهددار انتخاب شود؛ event تاریخ یکسان به جمع ناسازگار تبدیل نشود. تساوی/نسخه مبهم خطاست؛ right_time نامعلوم مجوز استفاده از trade_date نیست.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C090 — add_lags

ساخت ویژگی‌های تأخیری.

add_lags(df: pd.DataFrame, *, columns: Sequence[str], lags: tuple[int, ...] = (1, 5, 20), group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
columns Sequence[str] الزامی فهرست صریح نام ستون‌ها؛ ترتیب حفظ می‌شود. features نباید شامل target یا داده در دسترس پس از تصمیم باشد.
lags tuple[int, ...] (1, 5, 20) tuple اعداد صحیح مثبت؛ هر عضو مستقل. lags/windows از آینده یا گروه دیگر داده نمی‌گیرد.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ lags مثبت؛ shift جداگانه هر ابزار در ترتیب زمان. warm-up NA؛ lag تعداد مشاهده است و با تعطیلی/توقف تقویمی یکسان نیست. زمان دسترسی خروجی حداقل زمان دسترسی ورودی استفاده‌شده.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C091 — rolling_features

ویژگی‌های پنجره‌ای گذشته‌نگر.

rolling_features(df: pd.DataFrame, *, columns: Sequence[str], windows: tuple[int, ...] = (5, 20), statistics: tuple[str, ...] = ('mean','std'), lag: int = 1, group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
columns Sequence[str] الزامی فهرست صریح نام ستون‌ها؛ ترتیب حفظ می‌شود. features نباید شامل target یا داده در دسترس پس از تصمیم باشد.
windows tuple[int, ...] (5, 20) tuple اعداد صحیح مثبت؛ هر عضو مستقل. lags/windows از آینده یا گروه دیگر داده نمی‌گیرد.
statistics tuple[str, ...] ('mean', 'std') نام آمارهای whitelist برای rolling؛ callable arbitrary به‌طور پیش‌فرض پذیرفته نیست.
lag int 1 تأخیر صحیح نامنفی در اعمال وزن/ویژگی؛ استفاده بدون تأخیر باید با زمان واقعی دسترسی داده سازگار باشد.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ اول shift(lag)، سپس rolling با window کامل و center=False؛ lag>=0، برای تصمیم پیش از بسته‌شدن بازار lag=0 بدون شاهد زمان دسترسی مجاز نیست. std با ddof=1؛ میانه/میانگین/کمینه/بیشینه از فهرست whitelist؛ callable arbitrary پیش‌فرض ندارد.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C092 — make_forward_target

ساخت برچسب آینده برای آموزش، نه ویژگی.

make_forward_target(df: pd.DataFrame, *, price: str = 'closing_price', horizon: int = 5, method: Literal['return','direction'] = 'return', group_by: tuple[str, ...] = ('ins_code',), time_col: str = 'date') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
price str 'closing_price' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
horizon int 5 تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
method Literal['return', 'direction'] 'return' روش محاسبه محدود به Literal همین تابع؛ تعریف فرمول وseed در بخش رفتار ثبت شده است.
group_by tuple[str, ...] ('ins_code',) ستون‌های گروه‌بندی/اتصال؛ اطلاعات یک نماد به نماد یا جلسه دیگر منتقل نمی‌شود.
time_col str 'date' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ target=P_(t+h)/P_t-1؛ direction علامت آن. output target,label_start,label_end,target_available_at؛ h آخر هر ابزار NA باقی می‌ماند. این ستون‌ها حق ورود به X ندارند؛ یک ردیف هدف فقط وقتی وارد train می‌شود که پایان برچسب و زمان دسترسی آن قبل از cutoff آموزش باشد.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C093 — audit_leakage

گزارش موارد قابل کشف نشت و نبود شواهد.

audit_leakage(df: pd.DataFrame, *, features: Sequence[str], decision_col: str = 'decision_at', strict: bool = True) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
features Sequence[str] الزامی فهرست صریح نام ستون‌ها؛ ترتیب حفظ می‌شود. features نباید شامل target یا داده در دسترس پس از تصمیم باشد.
decision_col str 'decision_at' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
strict bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ گزارش rule,severity,row_id,message؛ زمان ویژگی>decision خطا، unknown provenance حالت unknown و در strict مانع است. ابزار اثبات ریاضی نبود همه انواع نشت نیست؛ تنظیمات fit/preprocess، survivorship و universe مستقل بررسی شوند.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C094 — make_dataset

جداسازی X، y، ردیف‌ها و منشأ داده.

make_dataset(df: pd.DataFrame, *, features: Sequence[str], target: str = 'target', decision_col: str = 'decision_at', target_end_col: str = 'label_end', missing: Literal['raise','drop_report'] = 'raise', strict_pit: bool = True) -> DatasetBundle

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
df pd.DataFrame الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.
features Sequence[str] الزامی فهرست صریح نام ستون‌ها؛ ترتیب حفظ می‌شود. features نباید شامل target یا داده در دسترس پس از تصمیم باشد.
target str 'target' نام ستون هدف؛ جدا ازX وfeature؛ زمان دسترسی هدف برای آموزش کنترل می‌شود.
decision_col str 'decision_at' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
target_end_col str 'label_end' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.
missing Literal['raise', 'drop_report'] 'raise' raise ردِ داده مفقود؛ propagate انتشار NA؛ drop_report حذف همراه گزارش فقط در تابعی که این گزینه را دارد.
strict_pit bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: DatasetBundle

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ X:DataFrame،y:Series،rows:DataFrame،dropped:DataFrame،manifest:DatasetManifest. حذف با گزارش؛ داده دارای revision ambiguity یا provenance نامعلوم در strict_pit رد. snapshot_id ذخیره‌نشده با ادعای بازتولید بادوام صادر نشود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C095 — temporal_split

تقسیم زمانی بدون shuffle.

temporal_split(dataset: DatasetBundle, *, train_end: datetime, validation_end: datetime, test_end: datetime | None = None, gap_sessions: int = 0) -> SplitBundle

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
dataset DatasetBundle الزامی نام dataset/جدول مجاز یا DatasetBundle مطابق نوع پارامتر؛ به SQL بدون اعتبارسنجی چسبانده نمی‌شود.
train_end datetime الزامی مرز زمانی آگاه بهtimezone؛ train/validation/test به‌ترتیب‌اند. test_end=None تا انتهای دامنه موجود.
validation_end datetime الزامی مرز زمانی آگاه بهtimezone؛ train/validation/test به‌ترتیب‌اند. test_end=None تا انتهای دامنه موجود.
test_end datetime | None None مرز زمانی آگاه بهtimezone؛ train/validation/test به‌ترتیب‌اند. test_end=None تا انتهای دامنه موجود.
gap_sessions int 0 تعداد زمان‌های تصمیم/جلسات جهانی در پنل، نه تعداد ردیف دارایی‌ها؛ step None=test_sessions.

نوع خروجی: SplitBundle

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ همه دارایی‌های دارای decision_at یکسان در یک بخش؛ train<=train_end،validation تاvalidation_end،test تاtest_end. label_end و target_available_at قطعات train نباید وارد validation/test شوند؛ purge واقعی بازه برچسب نه صرفاً حذف چند ردیف.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C096 — make_pipeline

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

make_pipeline(estimator: BaseEstimator, *, impute: Literal['none','median'] = 'none', scale: Literal['none','standard','robust'] = 'none') -> Pipeline

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
estimator BaseEstimator الزامی مدل سازگار با قرارداد estimator؛ تابع سازنده آن را fit نمی‌کند و آموزش داخل بخش train است.
impute Literal['none', 'median'] 'none' روش مجاز پیش‌پردازش؛ none بدون تبدیل. پارامترها فقط داخل fit بخش train آموخته می‌شوند.
scale Literal['none', 'standard', 'robust'] 'none' روش مجاز پیش‌پردازش؛ none بدون تبدیل. پارامترها فقط داخل fit بخش train آموخته می‌شوند.

نوع خروجی: Pipeline

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ هیچ fit در این تابع انجام نمی‌شود؛ imputer/scaler تنها داخل fit هر fold یاد می‌گیرند. get_feature_names_out و ستون‌های ورودی ثبت؛ ترتیب ستون‌ها هنگام پیش‌بینی تأیید شود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy, optional:scikit-learn

C097 — make_baseline

مدل مبنا برای سنجش ارزش مدل پیچیده.

make_baseline(*, task: Literal['regression','classification'], strategy: str = 'dummy', random_state: int = 42) -> BaseEstimator

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
task Literal['regression', 'classification'] الزامی نوع مسئله/راهبرد مدل مبنا؛ ترکیب‌های نامعتبر رد می‌شوند.
strategy str 'dummy' نوع مسئله/راهبرد مدل مبنا؛ ترکیب‌های نامعتبر رد می‌شوند.
random_state int 42 کنترل تصادفی‌بودن و ثبت برای بازتولید؛ سازگاری همه نسخه‌ها/سخت‌افزارها را تضمین نمی‌کند.

نوع خروجی: BaseEstimator

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ strategy مجاز بسته به task؛ dummy reg=mean،classification=prior؛ linear برای regression=Ridge وclassification=LogisticRegression با پارامترهای ثبت‌شده. ساخت مدل نه fit؛ اعداد seed تضمین بازتولید همه محیط‌ها نیستند.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy, optional:scikit-learn

C098 — fit

آموزش صریح روی بخش train.

fit(model: BaseEstimator, train: DatasetBundle, *, seed: int = 42, strict_pit: bool = True) -> ModelRun

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
model BaseEstimator الزامی مدل سازگار با قرارداد estimator؛ تابع سازنده آن را fit نمی‌کند و آموزش داخل بخش train است.
train DatasetBundle الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
seed int 42 کنترل تصادفی‌بودن و ثبت برای بازتولید؛ سازگاری همه نسخه‌ها/سخت‌افزارها را تضمین نمی‌کند.
strict_pit bool True در حالت سخت، نبود داده/شِما/شواهد لازم خطاست؛ حالت نرم باید unknown/diagnostic را حفظ کند، نه قطعیت بسازد.

نوع خروجی: ModelRun

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ مدل clone شود تا ورودی mutate نشود؛ X فقط ویژگی‌های اعلام‌شده؛ target باید تا training_cutoff از manifest در دسترس باشد. نسخه‌ها، seed، schema و hash ویژگی‌ها ثبت؛ ذخیره فایل یا ارسال شبکه به‌طور پیش‌فرض انجام نمی‌شود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy, optional:scikit-learn

C099 — predict

پیش‌بینی با مدل آموزش‌دیده.

predict(run: ModelRun, data: DatasetBundle) -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
run ModelRun الزامی ModelRun یاخروجی آموزش معتبر، شامل schema ویژگی و نسخه‌های وابستگی.
data DatasetBundle الزامی داده ورودی؛ نوع دقیق در ستون نوع آمده است. تابع آن را درجا تغییر نمی‌دهد مگر خلاف آن صریحاً در قرارداد آمده باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ کلید ردیف و decision_at و prediction؛ بدون fit مجدد. mismatch ترتیب، نوع یا نام ویژگی‌ها خطا؛ عدد prediction توصیه معامله محسوب نمی‌شود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy, optional:scikit-learn

C100 — evaluate

سنجش خطا با هم‌ترازی صریح.

evaluate(predictions: pd.DataFrame, actual: pd.DataFrame, *, task: Literal['regression','classification'], key: str = 'row_id') -> pd.DataFrame

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
predictions pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
actual pd.DataFrame الزامی جدول یاDatasetBundle طرف مربوط مطابق نوع؛ کلید،زمان،گروه وschema آن کنترل می‌شود. sessions=None ادعای تقویم کامل بازار نمی‌سازد.
task Literal['regression', 'classification'] الزامی نوع مسئله/راهبرد مدل مبنا؛ ترکیب‌های نامعتبر رد می‌شوند.
key str 'row_id' نام ستون ورودی یا مقدار مطابق نوع؛ الزامی‌بودن آن در شِما،واحد و معنایش پیش از محاسبه کنترل می‌شود. برای price/close مبنای تعدیل باید یکسان باشد.

نوع خروجی: pd.DataFrame

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ join یک‌به‌یک روی key؛ regression: MAE/RMSE/n؛classification: accuracy/balanced_accuracy/n؛ احتمال فقط با قرارداد probability پذیرفته شود. ردیف غایب یا برچسب آینده در ارزیابی زمان‌دار آشکار گزارش شود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy

C101 — walk_forward_validate

ارزیابی چندبخشی زمانی.

walk_forward_validate(model: BaseEstimator, dataset: DatasetBundle, *, train_sessions: int, test_sessions: int, step_sessions: int | None = None, expanding: bool = True, gap_sessions: int = 0, purge_labels: bool = True, seed: int = 42) -> ValidationRun

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
model BaseEstimator الزامی مدل سازگار با قرارداد estimator؛ تابع سازنده آن را fit نمی‌کند و آموزش داخل بخش train است.
dataset DatasetBundle الزامی نام dataset/جدول مجاز یا DatasetBundle مطابق نوع پارامتر؛ به SQL بدون اعتبارسنجی چسبانده نمی‌شود.
train_sessions int الزامی تعداد زمان‌های تصمیم/جلسات جهانی در پنل، نه تعداد ردیف دارایی‌ها؛ step None=test_sessions.
test_sessions int الزامی تعداد زمان‌های تصمیم/جلسات جهانی در پنل، نه تعداد ردیف دارایی‌ها؛ step None=test_sessions.
step_sessions int | None None تعداد زمان‌های تصمیم/جلسات جهانی در پنل، نه تعداد ردیف دارایی‌ها؛ step None=test_sessions.
expanding bool True پنجره آموزش تجمعی یا لغزان؛ True تجمعی.
gap_sessions int 0 تعداد زمان‌های تصمیم/جلسات جهانی در پنل، نه تعداد ردیف دارایی‌ها؛ step None=test_sessions.
purge_labels bool True حذف ردیف آموزش با بازه برچسب یا زمان دسترسی هدف واردشده به آزمون؛ gap جایگزین آن نیست.
seed int 42 کنترل تصادفی‌بودن و ثبت برای بازتولید؛ سازگاری همه نسخه‌ها/سخت‌افزارها را تضمین نمی‌کند.

نوع خروجی: ValidationRun

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ session به مجموعه زمان‌های تصمیم جهانی مربوط است، نه تعداد ردیف همه دارایی‌ها. step None=test_sessions؛ تمام fitها داخل fold؛ purge با label_end,target_available_at. آخرین holdout برای انتخاب مدل مصرف نشود. خروجی scores وpredictions وfolds DataFrame وmanifest.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError

وابستگی‌ها: pandas, numpy, optional:scikit-learn

C102 — save_model

انتشار صریح مدل با شناسنامه.

save_model(run: ModelRun, path: PathLike, *, format: Literal['skops','onnx'] = 'skops', overwrite: bool = False) -> ModelArtifact

وضعیت: proposed_not_implemented — مرحله: P13 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
run ModelRun الزامی ModelRun یاخروجی آموزش معتبر، شامل schema ویژگی و نسخه‌های وابستگی.
path PathLike الزامی مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
format Literal['skops', 'onnx'] 'skops' قالب مجاز فایل/مدل مطابق Literal؛ None فقط برای فایل از پسوند معتبر استنتاج می‌شود.
overwrite bool False اجازه جایگزینی مقصد؛ False پیش‌فرض و وجود مقصد FileExistsError.

نوع خروجی: ModelArtifact

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ ذخیره اختیاری جدا از داده خودکار. قالب و نسخه وابستگی و snapshot/feature order ثبت شود. ONNX فقط مدل‌های قابل تبدیل؛ اصل model در metadata به pickle خودکار تبدیل نشود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError, StorageError, UntrustedArtifactError, VersionMismatchError

وابستگی‌ها: pandas, numpy, optional:skops, optional:onnx/onnxruntime برای قالب ONNX

C103 — load_model

بارگذاری مدل با کنترل منشأ و نوع.

load_model(path: PathLike, *, trusted_types: tuple[str, ...] = (), verify: bool = True) -> ModelRun

وضعیت: proposed_not_implemented — مرحله: P13 — نوع مدخل: function

پارامتر نوع مقدار پیش‌فرض معنا
path PathLike الزامی مسیر فایل/پوشه محلی؛ None فقط در پارامترهای اختیاری یعنی مسیر داده استاندارد کاربر، نه site-packages.
trusted_types tuple[str, ...] () نوع‌های بررسی و مجازشده برای بارگذاری مدل؛ tuple خالی اجازه خودکار همه انواع نمی‌دهد.
verify bool True کنترل hash،schema وmetadata؛ hash به‌تنهایی اعتماد به ناشر را اثبات نمی‌کند.

نوع خروجی: ModelRun

ساختار خروجی: نوع مرکب در مرجع کلاس‌ها تعریف شده؛ بخش‌های جدولی DataFrame هستند.

رفتار و محدودیت‌ها: بدون دریافت شبکه و ذخیره خودکار؛ از بارگذاری pickle/joblib ناشناس پرهیز؛ hash تغییرناپذیری را بررسی می‌کند نه هویت ناشر. skops types باید بررسی/اجازه صریح؛ ناسازگاری نسخه یا مدل تبدیل‌نشده خطای روشن. اجرا sandbox تضمین نمی‌شود.

استثناها: InvalidArgumentError, SchemaMismatchError, LeakageError, MissingProvenanceError, NotFittedError, MissingDependencyError, StorageError, UntrustedArtifactError, VersionMismatchError

وابستگی‌ها: pandas, numpy, optional:skops, optional:onnx/onnxruntime برای قالب ONNX

C111 — FeatureSpec

تعریف ویژگی قابل ردگیری.

FeatureSpec(*, name: str, inputs: tuple[str, ...], window: int | None = None, lag: int = 1, availability_rule: Literal['max_input'] = 'max_input', version: str = '1') -> FeatureSpec

وضعیت: proposed_not_implemented — مرحله: P11 — نوع مدخل: configuration_class

پارامتر نوع مقدار پیش‌فرض معنا
name str الزامی نام نمونه،snapshot یاfeature مطابق تابع؛ نام فایل/مدل arbitrary code اجرا نمی‌کند.
inputs tuple[str, ...] الزامی فهرست صریح نام ستون‌ها؛ ترتیب حفظ می‌شود. features نباید شامل target یا داده در دسترس پس از تصمیم باشد.
window int | None None تعداد صحیح مثبت مشاهدات مرتب هر گروه؛ horizon افق برچسب است. این عدد روز تقویمی نیست.
lag int 1 تأخیر صحیح نامنفی در اعمال وزن/ویژگی؛ استفاده بدون تأخیر باید با زمان واقعی دسترسی داده سازگار باشد.
availability_rule Literal['max_input'] 'max_input' قاعده انتشار feature ونسخه فرمول؛ نسخه متن‌باز بسته با نسخه روش داده متفاوت است.
version str '1' قاعده انتشار feature ونسخه فرمول؛ نسخه متن‌باز بسته با نسخه روش داده متفاوت است.

نوع خروجی: FeatureSpec

رفتار و محدودیت‌ها: فقط schema/contract؛ فرمول اجرایی باید به نام whitelist در registry متصل و آزموده باشد. available_at ویژگی حداکثر داده‌های مؤثر و زمان تصمیم لازم؛ lag منفی ممنوع.

استثناها: ConfigurationError

وابستگی‌ها: stdlib

ذخیره خودکار، اینترنت ناپایدار و تاریخچه نسخه‌ها

۱. قرارداد اصلی: ذخیره خودکار مانع دریافت عادی نیست

ذخیره خودکار فعال، بهترین‌تلاش و جدا از نتیجه دریافت است. «اطلاعات معتبر را گرفتم» و «اطلاعات را بادوام ذخیره کردم» دو نتیجه جدا هستند. این سه خواسته هم‌زمان در همه شرایط قابل تضمین نیستند: برگشت فوری، ذخیره قطعی روی دیسک، و ادامه بی‌خطا هنگام خرابی دیسک. انتخاب پیش‌فرض Dara: ادامه کار عادی، صف محدود و گزارش صریح دوام. هزینه CPU برای ساخت batch/hash/frame و سربار حافظه صفر نیست؛ منظور از non-blocking، منتظر نماندن برای نوشتن/قفل/flush دیسک در مسیر عادی است، نه زمان اجرای صفر یا تضمین hard real-time.

۲. راه‌اندازی و مسیر

ساخت/import Client فقط تنظیمات است. اولین دریافت موفق، PersistenceCoordinator را به‌صورت lazy راه می‌اندازد. worker پوشه user_data_dir('tse-dara') و dara.sqlite3 را می‌سازد؛ path قابل تغییر است. در ویندوز مسیر از platformdirs خوانده می‌شود، نه پوشه پروژه یا site-packages. ممکن است %LOCALAPPDATA% مبنا باشد؛ مسیر دقیق از API گزارش می‌شود، نه hard-code. Client(storage=False) مانع ساخت پوشه، DB، raw archive و writer است؛ حافظه کش جداگانه می‌تواند فعال بماند. analytics و ml حتی با تنظیم پیش‌فرض هیچ مخزنی باز نمی‌کنند. تغییر مسیر، مهاجرت خودکار داده قدیمی نیست؛ کاربر باید صریحاً export/import یا migration را اجرا کند. نمونه load_sample مستقل از دیسک کاربر و شبکه است؛ فقط داده کوچک داخل بسته را می‌خواند.

۳. طراحی صف و مالکیت داده

NormalizedBatch شامل رکوردهای تغییرناپذیر و raw bytes فاقد اسرار، قبل از ساخت DataFrame تولید می‌شود. writer مرجعی به DataFrame mutable کاربر ندارد. در هر process/path یک coordinator با شمارنده reference وجود دارد؛ چند Client همان صف محدود را به اشتراک می‌گذارند. process های دیگر اتصال مستقل دارند و قفل SQLite هنوز ممکن است. پیش‌فرض صف ۱۲۸ کار و ۶۴MiB payload است. هر دو حد اعمال می‌شوند؛ اندازه تخمینی محافظه‌کارانه batch محاسبه می‌شود. این سقف شامل کل pandas/RAM نیست. enqueue به‌صورت put_nowait انجام می‌شود. وقتی صف پر یا batch بزرگ‌تر از سقف است، سیاست پیش‌فرض drop_new است: داده به کاربر برمی‌گردد، not_saved با علت queue_full/payload_too_large گزارش می‌شود. نه انتظار نامحدود، نه صف نامحدود، نه موفقیت دروغین. batch بزرگ برای autosave باید قطعه‌بندی شود یا از sync صریح استفاده شود. قطعه‌بندی، جلوگیری از بارگذاری بی‌حد کل دیتاست را جایگزین نمی‌کند. حذف کار autosave معادل حذف داده از نتیجه کاربر نیست. کاربر با save صریح همچنان می‌تواند نتیجه را ذخیره کند.

۴. وضعیت و رسید

WriteReceipt شامل receipt_id،request_id،state،accepted_at،rows،bytes،reason است. state یکی از queued/persisted/failed/skipped/disabled است. وضعیت درج‌شده در DataFrame.attrs یک snapshot زمان برگشت است و worker حق تغییر آن را ندارد. وضعیت نهایی از storage_status یا receipt/report گرفته می‌شود. ثبت queued یعنی پذیرفته‌شدن در RAM، نه fsync یا commit. kill/kernel restart/خاموشی می‌تواند pending را از بین ببرد. flush(timeout=5,raise_on_error=True) صریحاً منتظر commit کارهای پذیرفته‌شده پیش از شروع flush می‌ماند. اگر کار failed/skipped مرتبط باشد، گزارش باید آن را نشان دهد؛ flush داده rejected را دوباره نمی‌سازد. close(flush_timeout=1) و خروج context manager تلاش محدود می‌کنند و گزارش incomplete ممکن است. تضمین بی‌اتلافی تنها از یک receipt persisted و سیاست durability مشخص به دست می‌آید، نه صرف خروج تابع get_history. worker daemon پس از بسته‌شدن برنامه بی‌نهایت جلوی خروج را نمی‌گیرد. برای آرشیو پژوهشی کاربر باید save/sync/flush صریح موفق انجام دهد.

۵. خطای ذخیره و قطع‌کننده

disk full،PermissionError،read-only،SQLITE_BUSY و schema ناسازگار مخزن در مرز autosave به diagnostic تبدیل می‌شوند؛ fetch معتبر ادامه دارد. چند شکست باعث حالت degraded و cooldown قابل تنظیم می‌شود؛ تلاش نوشتن در هر دریافت دوباره تکرار نمی‌شود. مخزن خراب هرگز بی‌اجازه حذف/جایگزین/repair خودکار تخریبی نمی‌شود. رویداد خطا به ring حافظه و logger بدون secret می‌رود؛ گزارش خطای DB نباید خودش نیازمند نوشتن در همان DB باشد. fail-open فقط برای ذخیره کمکی است. خطای داده، شبکه، اعتبارنامه یا محاسبه پنهان نمی‌شود. در save/load/load_stored/run_download_plan ذخیره/خواندن هدف اصلی است؛ شکست StorageError یا failure صریح گزارش می‌شود. «نمی‌خواهم ذخیره مانع باشد» اجازه اعلام موفقیت false به save نیست.

۶. خواندن از کش و آفلاین

خواندن مستقیم دیسک نیز می‌تواند کند شود. در auto/online خواندن کش فقط با بودجه کوتاه و thread pool کران‌دار (مثلاً دو read هم‌زمان) انجام می‌شود؛ timeout => cache miss/diagnostic و مسیر شبکه ادامه دارد. timeout روی Future عملیات گیرکرده سیستم‌عامل را لزوماً متوقف نمی‌کند؛ بنابراین تعداد کارهای in-flight و صف read نیز محدودند و thread جدید بی‌پایان ساخته نمی‌شود. offline به خواندن مخزن وابسته است؛ خرابی/نبود رکورد/عدم پوشش، خطای روشن است و با «اینترنت قطع است» اشتباه نمی‌شود.

mode کش تازه کش قدیمی شکست شبکه ذخیره
auto استفاده طبق freshness ابتدا revalidate؛ سپس فقط با allow_stale داده قدیمی با پرچم در صورت مجازبودن بهترین‌تلاش
online طبق max_age؛ quote default تازه‌خوانی منبع تازه لازم خطا، نه fallback خاموش بهترین‌تلاش
offline خواندن محلی فقط طبق freshness صریح/نوع داده اصلاً شبکه ندارد دریافت جدید ندارد
پیش‌فرض تاریخچه در auto: revalidate_after یک روز، stale مجاز با log و flags؛ این SLA بورس نیست.
پیش‌فرض quote: max_age=0،allow_stale=False. کاربر برای آخرین قیمت ذخیره‌شده آفلاین باید allow_stale=True بدهد و زمان واقعی را ببیند.
from_cache،is_stale و source_timestamp و fetched_at اطلاعات جدا هستند. fresh از نظر عمر کش، تضمین انجام معامله در همان لحظه نیست.
مجوزهای رسمی،namespace cache مبتنی بر credential_scope و محدودیت استفاده آفلاین باید مستقل رعایت شوند؛ داده یک حساب به‌طور خودکار برای حساب دیگر خوانده نشود.

۷. ساختار SQLite

پیشنهاد schema نسخه‌دار:

جدول کلید/وظیفه
schema_migrations version یکتا،checksum،applied_at
datasets dataset_id،schema_id،schema_version،source،scope
fetch_runs run_id،query،started_at،received_at،committed_at،status،بدون اسرار
raw_responses raw_id،run_id،hash،content_type،compressed_body؛ در نسخه اول BLOB تراکنشی
observations observation_id،dataset_id،natural_key،payload_hash،observed_at،available_at،availability_basis،source_revision
observation_sightings دریافت دوباره همان نسخه و زمان last_seen؛ payload اقتصادی تکراری ساخته نشود
instrument_revisions هویت،اعتبار اقتصادی و نسخه دانسته‌شده در هر زمان
daily_bars observation_id،ins_code،date،listing،prices_exact و fields استاندارد
quotes observation_id،ins_code،source_timestamp،قیمت و واحد
dataset_payloads داده رکورد سایر خانواده‌ها با schema ثبت‌شده، نه JSON بی‌قرارداد
lineage_edges parent_observation/derived_snapshot/method_version
sync_chunks chunk_id،plan_id،range،commit_id،status
sync_checkpoints plan_id،cursor/range،آخرین commit موفق
snapshots snapshot_id،نام،hash،نسخه schema و query
snapshot_members snapshot_id،observation_id؛ مجموعه ثابت
write_journal receipt_id،run_id،committed status/diagnostics مجاز
کلید طبیعی روزانه حداقل source+scope+ins_code+trade_date+session/listing+basis است. source های متفاوت بدون ثبت lineage جای هم نمی‌نشینند.
برای ریزمعاملات، timestamp به تنهایی یکتا نیست؛ trade/sequence ID معتبر و شناسه روز لازم است. برای مظنه depth،refID/sequence و روز لازم است.
قیمت دقیق می‌تواند متن اعشاری canonical در SQLite و NUMERIC در PostgreSQL آینده باشد؛ query و serialization باید قرارداد مشترک، نه dtype تصادفی ORM، داشته باشند.

۸. atomicity، اصلاحات و duplicate

در نسخه اول raw،observations،جداول typed و checkpoint در یک تراکنش SQLite commit شوند. checkpoint با enqueue،موفقیت شبکه یا شروع write جلو نمی‌رود. commit داده+checkpoint شکست بخورد => آن chunk incomplete و قابل دریافت مجدد. upsert معنایی idempotent، نه حذف کور ردیف‌های تکراری. hash فقط فیلدهای اقتصادی/شناسه/واحد/نسخه روش را در canonical serialization شامل می‌شود؛ timestamp دریافت hash را عوض نمی‌کند. داده یکسان => sighting جدید؛ مقدار اقتصادی متفاوت => revision جدید. نسخه قبلی پاک نمی‌شود. استفاده از latest یک projection است. داده پاسخ دیررس نباید بدون سیاست ترتیب، current را عقب ببرد. request sequence،source_revision/time در صورت معتبر بودن و observed_at ثبت؛ conflict نامطمئن flag/قرنطینه می‌شود. soft delete یا لغو تنها با سند منبع ثبت شود؛ نبودن ردیف در یک پاسخ ناقص دلیل حذف دارایی نیست. پنجره overlap=5 جلسه و full_recheck انتخاب‌های پیشنهادی‌اند. هیچ پنجره محدود، اصلاح ده سال قبل را تضمین نمی‌کند؛ sweep دوره‌ای و change log در صورت وجود لازم است. اصلاح raw باید derived series/features مبتنی بر آن را invalid کند؛ lineage DAG و method_version امکان بازسازی می‌دهند.

۹. WAL و چند فرایند

WAL پیشنهاد برای دیسک محلی، نه پوشه شبکه‌ای/همگام‌شده نامطمئن. SQLite در WAL نیز فقط یک نویسنده دارد و SQLITE_BUSY ممکن است [S04]. worker اتصال متعلق به thread خود را باز می‌کند؛ اتصال sqlite میان thread ها بدون قرارداد ایمنی ردوبدل نمی‌شود. transaction کوتاه و network بیرون transaction است. busy_timeout کوتاه برای autosave؛ retry محدود؛ گلوگاه writer با ساخت چند writer رفع نمی‌شود. synchronous=FULL برای commit دارای ادعای دوام پیشنهاد اولیه است؛ هزینه آن در writer قرار می‌گیرد. تضمین به فایل‌سیستم/سخت‌افزار وابسته است؛ داده queued هنوز بادوام نیست. خواندن‌های طولانی/رشد WAL،checkpoint و GC در مسیر پاسخ عادی اجرا نشوند. vacuum/prune عملیات صریح با تایید هدف‌اند. مهاجرت سنگین schema در اولین fetch مسدودکننده انجام نشود. writer به حالت unavailable برود و دستور migrate صریح پیشنهاد شود؛ fetch عمومی همچنان کار کند.

۱۰. فایل‌های خروجی

CSV/Excel/Parquet/SQLite با save/load پشتیبانی می‌شوند [S09]. CSV نوع داده را کامل حفظ نمی‌کند؛ manifest.json شامل schema،dtype،units،timezone و hash ذخیره شود. UTF-8 با BOM برای تعامل Excel یک انتخاب exporter است. کاربر بدون manifest داده را با سطح provenance=unknown بازخوانی می‌کند. Excel شناسه طولانی را متن بنویسد؛ زمان دارای منطقه به ISO8601+metadata، نه datetime بی‌منطقه تبدیل شود. فرمول‌های رشته‌ای نامطمئن به متن امن تبدیل و در manifest ثبت شوند. این قالب آرشیو کامل میلیاردها رکورد نیست؛ حد ظرفیت باید پیش از export بررسی شود. Parquet با pyarrow اختیاری؛ metadata schema و exact decimal طبق precision قابل پشتیبانی؛ اگر decimal از ظرفیت نوع انتخابی بزرگ‌تر است باید fail یا encoding متن ثبت‌شده به کار رود، نه float بی‌هشدار. SQLite export در جدول namespace داده کاربر نوشته می‌شود؛ نه overwrite جدول داخلی schema_migrations. فایل و manifest با temp+rename و commit marker ذخیره شوند. چند فایل لزوماً اتمی مشترک نیستند؛ manifest آخر نوشته می‌شود و reader فقط hash/commit معتبر را می‌پذیرد. Parquet خارجی آینده: ابتدا object جدید،سپس manifest در DB؛ crash ممکن است orphan ایجاد کند اما manifest به object ناقص اشاره نمی‌کند. حذف orphan فقط ابزار نگهداری.

۱۱. PostgreSQL آینده

DatasetStore قرارداد query/read_revision/commit_batch/snapshot/checkpoint/migrate دارد. پیاده‌سازی SQLite و Postgres زیر یک قرارداد آزموده خواهند بود. اضافه‌کردن PostgreSQL فقط تغییر connection string نیست: locking،upsert،timezone،decimal،migration،transaction isolation و pool باید جدا پیاده‌سازی/آزمون شود. هیچ SQL خصوصی SQLite به services/analytics/ml نشت نکند. schemas business مستقل از DDL هستند. SQL injection با نام جدول whitelist وپارامترگذاری جلوگیری شود. SQLAlchemy/psycopg در extra آینده، نه dependency اجباری دریافت ساده.

۱۲. زمان در دسترس شدن و PIT

برای هر نسخه:

  • effective_at/date: رخداد اقتصادی یا جلسه معامله.
  • source_timestamp: زمان اعلام‌شده در پاسخ، با معنا و timezone مشخص.
  • source_published_at: زمان انتشار همان نسخه، فقط در صورت شاهد واقعی؛ ممکن است null باشد.
  • first_observed_at: اولین مشاهده این نسخه توسط برنامه؛ از زمان دریافت شبکه.
  • committed_at: زمان ثبت بادوام؛ ممکن است پس از first_observed_at باشد.
  • available_at و availability_basis: زمان قابل دفاع برای استفاده پژوهشی و مبنای آن. پیش‌فرض محافظه‌کارانه available_at=first_observed_at است. استفاده از source_published_at فقط وقتی مربوط به همین revision و تاییدشده است؛ تاریخ قدیمی رکورد یا ناشر، شاهد انتشار revision فعلی نیست. در استفاده بازپخش «دانسته‌های سیستم خودمان»، cutoff بر first_observed_at هم اعمال می‌شود؛ در پژوهش انتشار عمومی تاریخی فقط سند نسخه‌دار معتبر می‌تواند مبنای زودتر بدهد. داده سال ۱۳۹۵ که امروز دریافت شد، به‌خودی‌خود PIT سال ۱۳۹۵ نیست. صف ذخیره،این واقعیت را تغییر نمی‌دهد. اسنپ‌شات as_of(t) آخرین نسخه هر کلید با available_at<=t و effective_at<=t و scope مجاز را انتخاب می‌کند؛ فاقد شاهد => PointInTimeUnavailableError یا نتیجه unknown با اجازه صریح، نه موفقیت کامل. محاسبات تعدیل باید anchor_date و known_at داشته باشند. ضریب افزایش سرمایه آینده برای feature گذشته در strict mode ممنوع است. نسخه‌های adjusted/processed از raw مستقل وبا lineage هستند. دانش درباره نمادهای حذف‌شده و اعضای شاخص نیز زمان‌مند است؛ universe امروز را به گذشته تعمیم نمی‌دهیم.

۱۳. ML و ارزیابی تاریخی

feature و target کاملاً جدا؛ target می‌تواند آینده را مصرف کند اما feature حق چنین استفاده‌ای ندارد. label_start/label_end/target_available_at همراه هر ردیف نگه‌داری شود. تمام دارایی‌های یک زمان تصمیم در یک split قرار گیرند؛ split تصادفی ردیف‌ها برای panel مالی پیش‌فرض نیست. fit imputer/scaler/feature selection فقط روی train همان fold؛ سپس transform validation/test. Pipeline کمک می‌کند ولی نوع داده تاریخی نامعتبر را معتبر نمی‌کند [S07]. gap سشن‌ها و purge بازه برچسب دو چیز متفاوت‌اند [S08]. حذف آموزش‌هایی که label_end یا target_available_at آن‌ها وارد ناحیه آزمون شده ضروری است. asof join تنها backward و با revision معتبر؛ توان تشخیص leakage محدود به metadata و قراردادهای ارائه‌شده است، نه ممیزی همه کد arbitrary کاربر. بارگذاری مدل pickle/joblib ناشناس پیشنهاد نمی‌شود؛ hash فقط سلامت فایل،نه اعتماد به ناشر. قالب کنترل‌شده نیز تضمین امنیت مطلق نیست [S12].

۱۴. سناریوهای پذیرش ذخیره

A01: PermissionError هنگام ساخت پوشه => قیمت معتبر برگردد،storage_status degraded. A02: دیسک پر وسط تراکنش => rollback،checkpoint ثابت،receipt failed،fetch معتبر دست‌نخورده. A03: writer قفل => API عادی منتظر busy_timeout های تکراری نماند. A04: صف پر => حافظه کران‌دار،drop_new صریح،نه داده ناقص پنهان. A05: کاربر DataFrame را mutate کند => داده صف تغییر نکند. A06: worker ازبین‌رفته => API عادی ادامه دهد،diagnostic مستقل از DB. A07: حالت disabled => صفر ساخت فایل و صفر worker. A08: offline روی cache کافی => بدون درخواست شبکه؛ cache ناکافی=>خطای روشن. A09: interruption بعد از network قبل commit=> دریافت مجدد امن،بدون checkpoint زودرس. A10: اصلاح رکورد=>نسخه قبلی حفظ و as_of درست. A11: plain pandas concat metadata را حذف کند=>ML عدم شواهد را ببیند. A12: async deadline=>event loop زنده؛ SQLite در thread کران‌دار. A13: close محدود=>پردازش بی‌نهایت برای pending متوقف نشود؛flush صریح شکست را بگوید. A14: CSV/Excel/Parquet/SQLite round-trip=>شناسه طولانی،NA،Decimal،timezone و manifest آزموده شود. A15: زمان مشاهده قدیمی‌تر از commit=>داده ذخیره‌نشده در snapshot بادوام عضویت نگیرد. A16: حافظه read/write queue و logs در قطع طولانی اینترنت/خرابی‌دیسک رشد بی‌حد نداشته باشد.

نقشه راه اجرایی نسخه ۰٫۲

۱۴ مرحله و ۹۰ واحد کار؛ این تعداد واحد برنامه‌ریزی است، نه برآورد زمان یا وعده ساخت در یک نوبت.

همه مراحل بر آزمون و سند شِما متکی‌اند. کارهای رسمی و آینده شرط دسترسی/منبع دارند. رابط Async جزء نیاز نهایی است و پیش از اعلام پشتیبانی نسخه پایه باید آزمون شود.

P00 — قراردادها، شواهد و دامنه

پیش‌نیاز: ندارد

شناسه کار کار قابل تحویل
P00.1 ثبت سه زیرماژول و تصمیم خروجی مستقیم DataFrame در دفتر تصمیم‌های معماری.
P00.2 حفظ کاتالوگ توابع مرجع و مسیرهای رسمی، همراه با سطح شواهد.
P00.3 ثبت ابهام‌های دسترسی، تعرفه، مجوز داده و نام انتشار؛ بدون حدس عددی.
P00.4 تثبیت قرارداد هویت، واحد، شِما، تازگی و خطاها.
P00.5 تهیه نمونه پاسخ موفق، خالی، HTML با وضعیت ۲۰۰ و خطای رسمی، بدون اطلاعات محرمانه.
P00.6 انتخاب نمونه‌های متنوع برای آزمون زنده محدود؛ تعیین بودجه درخواست.

معیار پذیرش: ابهام‌ها و شواهد ثبت شده باشند؛ هیچ مسیر یا سقف حدسی به‌عنوان قطعی معرفی نشود.

P01 — بسته نصب‌شدنی و قراردادهای مشترک

پیش‌نیاز: P00

شناسه کار کار قابل تحویل
P01.1 ساخت ساختار src، فایل pyproject و تفکیک وابستگی‌های پایه از امکانات اختیاری.
P01.2 تعریف نوع‌ها، تنظیمات تغییرناپذیر، خطاها و مدل‌های پایه.
P01.3 ساخت فهرست شِماهای نسخه‌دار و آزمون شناسه بلند، تقویم و مقدار ناموجود.
P01.4 آزمون ورود سه زیرماژول بدون شبکه، فایل، نویسنده ذخیره یا بارگذاری ML سنگین.
P01.5 ساخت داده نمونه آفلاین و دفترچه آموزشی با سلول‌های جداگانه.
P01.6 آزمون wheel و sdist در محیط تمیز و ثبت ماتریس سازگاری واقعی.

معیار پذیرش: ورود بسته سبک و نمونه آفلاین مستقل از سرویس بورس اجرا شود.

P02 — شبکه و دریافت‌کننده اولیه

پیش‌نیاز: P01

شناسه کار کار قابل تحویل
P02.1 ساخت انتقال HTTP همگام با مهلت انتظار، بودجه کل و مدیریت عمر اتصال.
P02.2 ثبت قرارداد درخواست و پاسخ و حذف اسرار از گزارش‌ها.
P02.3 پیاده‌سازی تلاش مجدد محدود برای درخواست‌های امن و محدودکننده نرخ.
P02.4 آزمون پاسخ HTML، JSON نامعتبر، خطای تجاری، ۴۲۹، احراز هویت و اعتبار.
P02.5 ساخت دریافت‌کننده عمومی جست‌وجو و قیمت با مسیرهای دارای شاهد.
P02.6 آزمون با MockTransport و سپس آزمون زنده کم‌حجم.

معیار پذیرش: خطای منبع با جدول خالی پوشانده نشود و انتظار نامحدود وجود نداشته باشد.

P03 — هویت و قیمت

پیش‌نیاز: P02

شناسه کار کار قابل تحویل
P03.1 حل شناسه دقیق و تشخیص ابهام؛ جداسازی نمادهای مشابه و قدیمی.
P03.2 دریافت Quote و قیمت بدون نیاز به دانلود تاریخچه.
P03.3 ساخت کش حافظه‌ای محدود و جداسازی منبع و حساب.
P03.4 ثبت زمان منبع، زمان دریافت، واحد و فقدان قیمت؛ آزمون سیاست سخت تازگی.
P03.5 ساخت رابط ساده و Client با مدیریت عمر منابع.
P03.6 دریافت گروهی قیمت با حفظ ترتیب و تکرار ورودی‌ها.

معیار پذیرش: نماد اشتباه انتخاب نشود و قیمت قدیمی بدون برچسب تازه معرفی نشود.

P04 — تاریخچه و Pandas

پیش‌نیاز: P03

شناسه کار کار قابل تحویل
P04.1 دریافت تاریخچه و قطعات آن با بازه شامل و ترتیب صعودی.
P04.2 ساخت DataFrame دارای نوع ثابت حتی هنگام خالی‌بودن نتیجه.
P04.3 ثبت متادیتای ردیفی و شناسنامه کوچک همراه جدول.
P04.4 ساخت batch خام و استاندارد در حافظه با مصرف کنترل‌شده.
P04.5 تفکیک تاریخچه یک شناسه از زنجیره هویت تأییدشده و اعلام پوشش نامعلوم.
P04.6 ساخت BatchFrames برای تاریخچه گروهی و گزارش شکست هر ورودی.

معیار پذیرش: خروجی مستقیم DataFrame با واحد، ترتیب، شِما و پوشش روشن باشد.

P05 — ذخیره خودکار، آفلاین و فایل‌ها

پیش‌نیاز: P04

شناسه کار کار قابل تحویل
P05.1 راه‌اندازی تنبل ذخیره خودکار، صف محدود و یک نویسنده برای هر مسیر در فرایند.
P05.2 ساخت SQLite با WAL محلی، مهاجرت نسخه‌دار و تراکنش اتمی داده و checkpoint.
P05.3 پیاده‌سازی وضعیت ذخیره، رسید، flush و close با تشخیص مستقل از دیتابیس.
P05.4 آزمون پوشه فقط‌خواندنی، دیسک پر، قفل، صف پر، خرابی نویسنده و تغییر DataFrame کاربر.
P05.5 پیاده‌سازی سه حالت آنلاین، خودکار و آفلاین با بودجه خواندن کش.
P05.6 ذخیره و بازیابی چهار قالب با شِما و آزمون رفت‌وبرگشت.
P05.7 ساخت برنامه دریافت تدریجی، ادامه عملیات، حذف تکرار معنایی و حفظ اصلاحات.
P05.8 آزمون قطع برنامه پیش و پس از commit؛ جلوگیری از پیشرفت زودهنگام checkpoint.

معیار پذیرش: سناریوهای A01 تا A16 سند ذخیره عبور کنند؛ fetch با خرابی autosave ادامه یابد ولی save صریح شکست را اعلام کند.

P06 — رابط Async هم‌ارز

پیش‌نیاز: P05

شناسه کار کار قابل تحویل
P06.1 ساخت انتقال واقعی ناهمگام با HTTPX؛ بدون asyncio.run پنهان در رابط عادی.
P06.2 اشتراک منطق برنامه‌ریزی، تبدیل، اعتبارسنجی و خطا بین دو اجراکننده.
P06.3 پشتیبانی AsyncClient از همه قابلیت‌های پایه همان نسخه.
P06.4 اجرای انتظار SQLite در thread محدود و خارج از حلقه رویداد.
P06.5 آزمون لغو، مهلت انتظار، پاک‌سازی وظایف و مالکیت session.
P06.6 آزمون برابری شِما، مقدار، خطا، تازگی و شکست ذخیره در هر دو رابط.

معیار پذیرش: داده و خطاهای دو رابط معنای یکسان داشته باشند و event loop هنگام I/O دیسک زنده بماند.

P07 — تعدیل و تحلیل مالی

پیش‌نیاز: P04, P05

شناسه کار کار قابل تحویل
P07.1 ثبت روش تعدیل، تاریخ مبنا و نسخه الگوریتم بدون بازنویسی داده خام.
P07.2 پیاده‌سازی بازده، بازده انباشته، رشد مرکب و افت سرمایه با مثال عددی.
P07.3 پیاده‌سازی میانگین‌ها، RSI، MACD، باندها و ATR با تعریف seed و warm-up.
P07.4 پیاده‌سازی ریسک، صدک زیان، همبستگی و بتا با سالانه‌سازی صریح.
P07.5 محاسبه پرتفوی وزن‌دار با تأخیر اجرا، وجه نقد و هزینه اعلام‌شده.
P07.6 آزمون گروه‌بندی، مرز دارایی، واحد، عدم تغییر ورودی و نبود I/O.

معیار پذیرش: فرمول‌ها و مفروضات قابل بازتولید باشند و تعدیل با بازده کل اشتباه نشود.

P08 — بازار، شاخص و حقیقی‌حقوقی

پیش‌نیاز: P06

شناسه کار کار قابل تحویل
P08.1 دریافت دیده‌بان و نمای بازار با جدول استاندارد.
P08.2 دریافت حقیقی و حقوقی با تفکیک تعداد، حجم، ارزش و فیلد ناموجود.
P08.3 دریافت شاخص روزانه، درون‌روزی، اجزا و اثرگذاری با هویت دقیق.
P08.4 ثبت زمان جداگانه مولفه‌های ترکیبی بازار.
P08.5 دریافت روزانه کل بازار فقط با قابلیت تأییدشده و تفکیک نماد معامله‌شده و همه نمادها.
P08.6 افزودن صنایع، تابلوها و جلسات بازار با پوشش اعلام‌شده.

معیار پذیرش: مصرف درخواست کنترل و داده ناقص یا بازار فاقد پشتیبانی اعلام شود.

P09 — ریزمعاملات، مظنه و دیده‌بان

پیش‌نیاز: P08

شناسه کار کار قابل تحویل
P09.1 دریافت ریزمعاملات با ترتیب رخداد و وضعیت ابطال تأییدشده.
P09.2 دریافت تغییرات مظنه با حفظ عمق، refID و توالی.
P09.3 بازسازی مظنه با وضعیت اولیه و تشخیص شکاف؛ بدون پرکردن بین جلسات.
P09.4 ساخت کندل از معاملات معتبر با مرز جلسه مشخص.
P09.5 دریافت آمار قیمت درون‌روز، وضعیت و آستانه‌ها با معنای مستقل.
P09.6 ساخت دیده‌بان دوره‌ای ناهمگام با لغوپذیری و صف محدود.

معیار پذیرش: رخدادهای هم‌ثانیه حذف نشوند و شکاف به تصویر کامل تبدیل نشود.

P10 — مالکیت، صندوق و اطلاعیه

پیش‌نیاز: P08

شناسه کار کار قابل تحویل
P10.1 دریافت سهامداران، سابقه مالکیت و سایر دارایی‌های مالک با شناسه درست.
P10.2 دریافت تغییر سرمایه و سود نقدی همراه زمان دسترسی.
P10.3 دریافت صندوق و NAV با تمایز شماره ثبت و شناسه ابزار.
P10.4 دریافت پیام و فراده اطلاعیه؛ بدون ادعای استخراج کامل صورت‌های مالی.
P10.5 محاسبه نسبت‌های بنیادی با دوره، واحد و انتشار روشن.
P10.6 ثبت نمونه خام، شِما و محدودیت هر خانواده پیش از انتشار.

معیار پذیرش: پوشش، هویت و معنای هر قابلیت پیش از انتشار روشن باشد.

P11 — داده نقطه‌درزمان و ML

پیش‌نیاز: P05, P07

شناسه کار کار قابل تحویل
P11.1 انتخاب نسخه هر مشاهده در زمان مشخص بر اساس شواهد انتشار یا اولین مشاهده.
P11.2 اتصال نقطه‌درزمان و مدیریت مجموعه تاریخی ابزارها.
P11.3 ساخت تأخیرها، پنجره‌ها و برچسب آینده با زمان شروع و پایان برچسب.
P11.4 ساخت DatasetBundle و اسنپ‌شات؛ رد شواهد نامعلوم در حالت سخت.
P11.5 تقسیم زمانی و ارزیابی گام‌به‌گام با حذف هم‌پوشانی بازه برچسب‌ها.
P11.6 ساخت Pipeline و آموزش فقط روی train؛ مقایسه با مدل مبنا.
P11.7 پیش‌بینی و ارزیابی با هم‌ترازی شناسه ردیف.
P11.8 آزمون نشت عمدی آینده، اصلاح گذشته، متادیتای گم‌شده و اختلاط دارایی‌ها.

معیار پذیرش: داده دریافت‌شده امروز، بدون شاهد نسخه، PIT گذشته محسوب نشود و ارزیابی با مدل مبنا انجام شود.

P12 — حساب رسمی و چندبازاری

پیش‌نیاز: P06

شناسه کار کار قابل تحویل
P12.1 روشن‌کردن شرایط حساب و مجوز؛ بدون کلید مشترک برای کاربران کتابخانه.
P12.2 آزمون ورود، انقضا، نقش، اعتبار، تغییر رمز اولیه و اختلاف نام فیلدها.
P12.3 آزمون سرویس‌های تاریخی رسمی با پاسخ واقعی حساب مجاز.
P12.4 تعریف مستقل نوع ابزار، ارز و واحد در مشتقه و انرژی.
P12.5 حفظ عملکرد مسیر عمومی در نبود حساب رسمی.
P12.6 جداسازی کش حساب‌ها و رعایت حقوق استفاده آفلاین و بازنشر.

معیار پذیرش: بدون حساب واقعی، وضعیت قابلیت رسمی documented باقی بماند؛ تعرفه و مجوز حدسی اعلام نشود.

P13 — انتشار پایدار و توسعه آینده

پیش‌نیاز: P06, P07

شناسه کار کار قابل تحویل
P13.1 تکمیل راهنمای نصب، مرجع API، مثال‌ها و سازگاری هر ویرایش کتاب.
P13.2 تثبیت نسخه‌گذاری، نسخه شِما، منسوخ‌سازی و راهنمای مهاجرت.
P13.3 آزمون نسخه‌های پشتیبانی‌شده در ویندوز و لینوکس و روی بسته ساخته‌شده.
P13.4 انتشار آزمایشی و سپس PyPI با احراز هویت انتشار و تأیید مناسب.
P13.5 افزودن PostgreSQL اختیاری با آزمون قرارداد و برنامه مهاجرت مستقل.
P13.6 افزودن ذخیره مدل و مبدل اختیاری؛ بررسی مدل عمیق، NLP و AutoML در آینده.
P13.7 حفظ رابط پایه هنگام افزودن امکانات و اعلام بودجه مصرف اختیاری.
P13.8 عبور از چک‌لیست کیفیت، خطا و اجرای مثال‌های کتاب پیش از هر انتشار.

معیار پذیرش: قابلیت ناتمام آماده معرفی نشود؛ هر نسخه فقط دامنه واقعاً آزموده خود را متعهد شود.

قاعده اتمام هر قابلیت

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

تقسیم کار

گروه زیرساخت: P01/P02/P05/P06؛ گروه داده: P03/P04/P08/P09/P10؛ گروه تحلیل: P07؛ گروه ML: P11؛ حساب رسمی: P12؛ انتشار و کیفیت: P00/P13. کار موازی فقط پس از تثبیت شِما و درگاه مشترک آغاز شود.

نقاط انتشار پیشنهادی

نسخه آزمایشی آموزشی بعد از P04؛ نسخه پایه شامل ذخیره و هر دو رابط بعد از P05/P06؛ تحلیل‌ها و قابلیت‌های تکمیلی در نسخه‌های افزایشی. نسخه 1.0 الزاماً به معنی تکمیل همه امکانات آینده نیست، بلکه تعهد به قراردادهای واقعاً پیاده‌سازی و آزموده است.

تغییرات و ردیابی نیازمندی‌ها

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

کد نیاز محل پاسخ طراحی
R01 سه زیرماژول عمومی 01،03،04،05 analytics و ml ازخارج‌دامنه‌بودن طرح قبلی بهزیرماژول همینبسته تبدیل شدند.
R02 Pandas قالب اصلی جدول 00،03–05 TableResult عمومی اجباری حذف و DataFrame مستقیم جایگزین؛مدل‌های داخلی محفوظ.
R03 دو رابط ساده و Async 01،03،10 Client و AsyncClient با53 همتای شبکه‌ای و parser/validator مشترک.
R04 CSV/Excel/Parquet/SQLite و PostgreSQL آینده 03،06،07 save/load،manifest ومخزن مستقل؛PostgreSQL مشروط.
R05 ذخیره محلی خودکار پیش‌فرض 03،06 فعال دراولینعملیات‌داده؛مسیرقابلتغییر؛storage=False.
R06 اینترنت ناپایدار وبه‌روزرسانی 01،06 mode سهبخشی،cache،overlap/revision،resume و checkpoint اتمی.
R07 raw/adjusted/processed و PIT 00،05،06 نسخه‌داده،first_observed/available/committed،lineage و strictleakage.
R08 PyPI ومستندات ومشارکت 01،07 extras،CI،trustedpublishing،نسخه‌بندی وراهنمایمهاجرت.
R09 مرجع کامل قراردادهای قابلیت‌ها 02–05،10 127 قراردادعمومیباپارامتر،پیش‌فرض،نوع،خطا،وابستگی ومرحله؛18 درگاه داخلی.
R10 ذخیره مانع فعالیت عادی نشود 06 صف کران‌دار و fail-open؛save/flush صریح صداقت شکست راحفظ می‌کنند.

ردیابی ۵۸ مدخل طرح قبلی

هر قابلیت قبلی مقصد مشخص دارد. جابه‌جایی یا تغییر نوع دراین مرحله تغییر طراحی پیش‌ازانتشار است، نه وعده سازگاری API منتشرشده.

نام در۰٫۱ مقصد در۰٫۲ شناسه قرارداد تغییر اصلی
Client tse_dara.data.Client C001 ذخیره فعال به‌صورت lazy وبهترین‌تلاش؛ سازنده همچنان بدون I/O.
capabilities tse_dara.data.capabilities C002 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
search_instruments tse_dara.data.search_instruments C003 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_instrument tse_dara.data.get_instrument C004 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_instruments tse_dara.data.get_instruments C005 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_quote tse_dara.data.get_quote C006 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_price tse_dara.data.get_price C007 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_quotes tse_dara.data.get_quotes C008 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_history tse_dara.data.get_history C009 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
iter_history tse_dara.data.iter_history C010 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_history_many tse_dara.data.get_history_many C011 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_daily_market tse_dara.data.get_daily_market C012 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_adjustments tse_dara.data.get_adjustments C013 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_market_watch tse_dara.data.get_market_watch C014 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_market_overview tse_dara.data.get_market_overview C015 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_client_types tse_dara.data.get_client_types C016 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_client_type_history tse_dara.data.get_client_type_history C017 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_market_client_types tse_dara.data.get_market_client_types C018 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_indices tse_dara.data.get_indices C019 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_index tse_dara.data.get_index C020 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_index_history tse_dara.data.get_index_history C021 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_index_intraday tse_dara.data.get_index_intraday C022 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_index_members tse_dara.data.get_index_members C023 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_index_impact tse_dara.data.get_index_impact C024 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_order_book tse_dara.data.get_order_book C025 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_order_book_updates tse_dara.data.get_order_book_updates C026 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_trades tse_dara.data.get_trades C027 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_intraday_quotes tse_dara.data.get_intraday_quotes C028 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_instrument_states tse_dara.data.get_instrument_states C029 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_thresholds tse_dara.data.get_thresholds C030 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_shareholders tse_dara.data.get_shareholders C031 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_shareholder_history tse_dara.data.get_shareholder_history C032 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_shareholder_holdings tse_dara.data.get_shareholder_holdings C033 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_share_capital_history tse_dara.data.get_share_capital_history C034 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_dividends tse_dara.data.get_dividends C035 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_funds tse_dara.data.get_funds C036 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_fund tse_dara.data.get_fund C037 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_fund_nav_history tse_dara.data.get_fund_nav_history C038 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_messages tse_dara.data.get_messages C039 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_disclosures tse_dara.data.get_disclosures C040 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_sectors tse_dara.data.get_sectors C041 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_subsectors tse_dara.data.get_subsectors C042 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_boards tse_dara.data.get_boards C043 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_market_sessions tse_dara.data.get_market_sessions C044 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_options tse_dara.data.get_options C045 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_futures tse_dara.data.get_futures C046 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_opening_auction tse_dara.data.get_opening_auction C047 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_energy_instruments tse_dara.data.get_energy_instruments C048 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
get_energy_auctions tse_dara.data.get_energy_auctions C049 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
to_pandas tse_dara.data.to_pandas C050 تبدیل کمکی؛ دیگر لازمه استفاده از get_history نیست.
to_polars tse_dara.data.to_polars C051 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
resample_trades tse_dara.analytics.resample_trades C052 انتقال به analytics؛ DataFrame ورودی/خروجی.
reconstruct_order_book tse_dara.data.reconstruct_order_book C053 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
plan_history_sync tse_dara.data.plan_history_sync C054 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
run_download_plan tse_dara.data.run_download_plan C055 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
load_sample tse_dara.data.load_sample C056 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
AsyncClient tse_dara.data.AsyncClient C057 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.
watch_market tse_dara.data.watch_market C058 حفظ قابلیت؛ مراجعه به قرارداد جدید برای نوع خروجی/ذخیره/سیاست.

ردیابی واحدهای اجرایی قبلی

هر ۶۶ واحد کار قدیمی در legacy_task_map.json با متن اصلی ومقصد مرحله جدید حفظ شده است. نقشه اجرایی فعال۱۴مرحله و۹۰واحدکار دارد.

وضعیت صداقت اجرا

این بسته سند است. هیچ تابع Dara دراین نوبت پیاده‌سازی یا رویبورس اجرا نشده؛ تست‌های پذیرش،برنامه آزمون‌اند. بررسی خروجی‌ها و امضاها صرفاً QA ساختاری سنداست. داده‌های دوکتابخانه مرجع از snapshot ثابت وازبررسی قبلی حفظ شده‌اند؛چندمسیرحساس دوبارهخوانده شدند.

قرارداد کلاس‌های داخلی

این‌ها درگاه‌های پیشنهادی‌اند؛ هیچ‌یک در این بسته پیاده‌سازی نشده‌اند. Provider های کوچک بر اساس قابلیت تقسیم می‌شوند، نه یک کلاس عظیم با همه متدها.

ProviderAdapter — build_request

build_request(query: QuerySpec) -> RequestSpec

تبدیل query معنایی به درخواست همان منبع.

بدون I/O؛ فقط endpoint ثبت‌شده و capability آزموده. نام/نوع Flow در این مرز نگاشت می‌شود.

وابستگی: endpoint_registry

استثنا: UnsupportedCapabilityError, InvalidArgumentError

مرحله: P02

ProviderAdapter — parse_response

parse_response(response: RawResponse) -> NormalizedBatch

parse و نگاشت منبع.

HTTP/business validation قبل از ساخت batch؛ خطا HTML200 رد؛ aliases حروف فقط موارد آزموده.

وابستگی: schema_registry

استثنا: SchemaMismatchError, ApiError

مرحله: P02

ProviderAdapter — capabilities

capabilities() -> tuple[CapabilityInfo, ...]

قابلیت‌های adapter.

خود گزارش به معنی live probe نیست؛ unsupported/pending جدا.

وابستگی: capability_registry

استثنا: خطای ذخیره کمکی منتشر نمی‌شود؛ خطای برنامه‌نویسی پنهان نمی‌شود.

مرحله: P01

SyncTransport — send

send(request: RequestSpec) -> RawResponse

اجرای HTTP همگام.

Session عمرمدار؛ بودجه،redaction،deadline و retry محدود؛ auth در repr/log نیست.

وابستگی: httpx, NetworkConfig

استثنا: NetworkError, RateLimitError, RequestBudgetExceededError

مرحله: P02

AsyncTransport — async send

async send(request: RequestSpec) -> RawResponse

اجرای HTTP ناهمگام.

مدل‌های ورودی/خروجی یکسان sync؛ cancellation پس از پاکسازی حفظ شود.

وابستگی: httpx, asyncio, NetworkConfig

استثنا: NetworkError, RateLimitError, RequestBudgetExceededError

مرحله: P06

FrameFactory — build

build(batch: NormalizedBatch, *, numeric: NumericProfile = 'analysis', receipt: WriteReceipt | None = None) -> pd.DataFrame

ساخت DataFrame مستقل ازصف.

typed empty،ستون هویت/provenance،attrs کوچک؛ هیچ mutable ref از frame به writer. رسید در metadata جدید frame کپی می‌شود؛ batch صف‌شده تغییر نمی‌کند.

وابستگی: pandas

استثنا: SchemaMismatchError, DataTypeError

مرحله: P04

DatasetStore — read

read(query: QuerySpec) -> NormalizedBatch

خواندن نسخه معتبر.

خروجی مستقل از SQLite/Postgres؛ snapshot transaction؛ unknown coverage اعلام شود.

وابستگی: repository_backend

استثنا: StorageError, OfflineDataUnavailableError

مرحله: P05

DatasetStore — commit_batch

commit_batch(batch: NormalizedBatch, *, checkpoint: Mapping[str, object] | None = None) -> WriteReceipt

ثبت اتمی داده و checkpoint.

raw+observations+projection+checkpoint یک commit؛ idempotence و revision؛ receipt پس از commit.

وابستگی: repository_backend

استثنا: StorageError, SchemaVersionError

مرحله: P05

DatasetStore — snapshot

snapshot(query: QuerySpec, *, name: str) -> SnapshotManifest

ساخت snapshot پایدار.

فقط observation commit شده؛ immutable membership و hash؛ مجوز scope لحاظ.

وابستگی: repository_backend, hashlib

استثنا: StorageError, PointInTimeUnavailableError

مرحله: P11

DatasetStore — migrate

migrate(*, target_version: int, dry_run: bool = True) -> pd.DataFrame

مهاجرت صریح ساختار مخزن.

دریافت عادی منتظر migration سنگین نیست؛ تراکنش/قفل وطرح بازگشت مشخص،حذف DB خودکار ممنوع.

وابستگی: repository_backend

استثنا: StorageError, SchemaVersionError

مرحله: P05

PersistenceCoordinator — enqueue

enqueue(batch: NormalizedBatch) -> WriteReceipt

پذیرش non-waiting درصف.

بدون دیسک؛ صف کران‌دار؛ fail/skipped به receipt و ring. دریافت معتبر ازاین خطا شکست نمی‌خورد.

وابستگی: stdlib, bounded_queue

استثنا: خطای ذخیره کمکی منتشر نمی‌شود؛ خطای برنامه‌نویسی پنهان نمی‌شود.

مرحله: P05

PersistenceCoordinator — flush

flush(*, timeout: float = 5.0) -> FlushReport

تعیین تکلیف صریح صف.

کار پذیرفته‌شده تا fence seq؛ timeout واقعی بدون forcekill thread؛complete فقط پس از commit.

وابستگی: stdlib, DatasetStore

استثنا: StorageFlushTimeout

مرحله: P05

PersistenceCoordinator — status

status() -> StorageStatus

وضعیت مستقل از DB.

snapshot thread-safe؛نه بازکردن DB برایگزارش خطای DB.

وابستگی: stdlib

استثنا: خطای ذخیره کمکی منتشر نمی‌شود؛ خطای برنامه‌نویسی پنهان نمی‌شود.

مرحله: P05

MemoryCache — get

get(key: str) -> NormalizedBatch | None

کش RAM.

key شامل source/scope/schema/identity/range/basis؛ immutable؛ محدودحجم/LRU.

وابستگی: stdlib

استثنا: خطای ذخیره کمکی منتشر نمی‌شود؛ خطای برنامه‌نویسی پنهان نمی‌شود.

مرحله: P03

MemoryCache — put

put(key: str, batch: NormalizedBatch, *, ttl: timedelta) -> None

کش RAM زمان‌دار.

انقضای TTL مجوزحذفآرشیو revision نیست؛ حافظه محدود.

وابستگی: stdlib

استثنا: InvalidArgumentError

مرحله: P03

AuthSession — login

login(credentials: Credentials) -> None

ورود رسمی کنترل‌شده.

توکن فقطحافظه؛رمز باید preflight در host مجاز ارسالشود؛-107 خطای needs-password-change وبدونتغییرپنهانی.

وابستگی: httpx

استثنا: AuthenticationError, PasswordChangeRequiredError

مرحله: P12

AuthSession — authorization_header

authorization_header() -> Mapping[str, str]

هدرمحرمانهبرای request مجاز.

انقضا UTC،قفل refreshsingle-flight؛انتقالبه publichost ممنوع؛reprredacted.

وابستگی: stdlib

استثنا: AuthenticationError

مرحله: P12

RevisionResolver — select

select(rows: pd.DataFrame, *, as_of: datetime, key: tuple[str, ...]) -> pd.DataFrame

انتخاب revision درزمان.

version-specificavailability،scope واعتباراقتصادی؛سطرهای unknown بهگذشتهتعبیرنشوند.

وابستگی: pandas

استثنا: PointInTimeUnavailableError, DataConflictError

مرحله: P11

طبقه‌بندی خطاهای پیشنهادی

نام و کد خطا بخشی از قرارداد عمومی خواهد بود. نگاشت دقیق به زیرکلاس‌ها پیش از انتشار تثبیت می‌شود؛ علت اصلی در cause محفوظ و اسرار حذف می‌شوند.

خطا خانواده و اقدام
AmbiguousInstrumentError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
ApiError منبع/شبکه؛ retry تنها با سیاست امن، سقف تلاش و بودجه مجاز.
AuthenticationError مجوز و حساب؛ خطای اینترنت نیست و با تعویض پنهانی حساب/منبع دور زده نمی‌شود.
BatchDataError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
ClosedClientError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
ConfigurationError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
CreditExhaustedError مجوز و حساب؛ خطای اینترنت نیست و با تعویض پنهانی حساب/منبع دور زده نمی‌شود.
DataConflictError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
DataQualityError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
DataTypeError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
FileExistsError خطای استاندارد پایتون؛ فایل مقصد وجود دارد و overwrite مجاز نشده است.
IntegrityError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
InvalidArgumentError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
LeakageError اعتبار پژوهشی؛ در حالت سخت ادامه مجاز نیست؛ با حدس زمان یا حذف بی‌گزارش درمان نمی‌شود.
MissingDependencyError قابلیت یا وابستگی؛ پیام روشن درباره قابلیت پشتیبانی‌نشده یا extra لازم.
MissingInitialStateError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
MissingMetadataError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
MissingProvenanceError اعتبار پژوهشی؛ در حالت سخت ادامه مجاز نیست؛ با حدس زمان یا حذف بی‌گزارش درمان نمی‌شود.
NetworkError منبع/شبکه؛ retry تنها با سیاست امن، سقف تلاش و بودجه مجاز.
NotFittedError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
OfflineDataUnavailableError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
PasswordChangeRequiredError مجوز و حساب؛ خطای اینترنت نیست و با تعویض پنهانی حساب/منبع دور زده نمی‌شود.
PermissionDeniedError مجوز و حساب؛ خطای اینترنت نیست و با تعویض پنهانی حساب/منبع دور زده نمی‌شود.
PointInTimeUnavailableError اعتبار پژوهشی؛ در حالت سخت ادامه مجاز نیست؛ با حدس زمان یا حذف بی‌گزارش درمان نمی‌شود.
RateLimitError منبع/شبکه؛ retry تنها با سیاست امن، سقف تلاش و بودجه مجاز.
RequestBudgetExceededError منبع/شبکه؛ retry تنها با سیاست امن، سقف تلاش و بودجه مجاز.
SchemaMismatchError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
SchemaVersionError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
SequenceGapError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
StaleDataError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
StorageError ذخیره/دوام؛ autosave آن را گزارش می‌کند، عملیات صریح save/flush/load آن را اعلام می‌کند.
StorageFlushTimeout ذخیره/دوام؛ autosave آن را گزارش می‌کند، عملیات صریح save/flush/load آن را اعلام می‌کند.
SyncPlanError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
UnitMismatchError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
UnknownCancellationError ساختار یا صحت داده؛ گزارش مشخص و اصلاح مبتنی بر شاهد؛ errors='ignore' عمومی ممنوع.
UnknownInstrumentError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
UnknownReceiptError ذخیره/دوام؛ autosave آن را گزارش می‌کند، عملیات صریح save/flush/load آن را اعلام می‌کند.
UnknownRequestError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
UnknownSampleError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
UnknownSnapshotError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
UnsupportedCapabilityError قابلیت یا وابستگی؛ پیام روشن درباره قابلیت پشتیبانی‌نشده یا extra لازم.
UntrustedArtifactError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.
VersionMismatchError قرارداد ورودی، وضعیت شیء یا شناسه نتیجه؛ علت و روش اصلاح روشن گزارش می‌شود.

خطاهای معنایی تکمیلی

CoverageError: خطای معنایی صریح مطابق قرارداد تابع؛ قیمت یا وضعیت ناموجود نباید با صفر یا موفقیت ساختگی جایگزین شود.

MissingValueError: خطای معنایی صریح مطابق قرارداد تابع؛ قیمت یا وضعیت ناموجود نباید با صفر یا موفقیت ساختگی جایگزین شود.

UnsupportedQuoteUnitError: خطای معنایی صریح مطابق قرارداد تابع؛ قیمت یا وضعیت ناموجود نباید با صفر یا موفقیت ساختگی جایگزین شود.

نمونه‌های رابط هدف

این مثال‌ها برای توضیح قراردادند؛ بسته tse-dara در این تحویل پیاده‌سازی یا منتشر نشده است. اجرای آن‌ها اکنون بدون ساخت کتابخانه الزاماً ممکن نیست.

سلول ۱ — وارد کردن ابزارها

from tse_dara import data, analytics
from tse_dara.data import Client, AsyncClient, FetchPolicy, FreshnessPolicy

سلول ۲ — تنظیمات پروژه

DATA_DIR = r"G:\My progect\Python\TSE\dara-data"
SYMBOL = "فولاد"

سلول ۳ — دریافت معمولی

with Client(data_dir=DATA_DIR) as client:
    df = client.get_history(SYMBOL, start="2024-01-01")
    quote = client.get_quote(SYMBOL)
    print(quote.last_price, quote.source_timestamp)
    print(client.storage_status())
    # This explicit call asks for persistence, unlike best-effort autosave.
    report = client.flush(timeout=5.0, raise_on_error=False)

اگر داده معتبر دریافت شود ولی SQLite خطا داشته باشد، df و quote همچنان برمی‌گردند. report می‌تواند شکست یا pending را نشان دهد؛ این وضعیت را موفقیت ذخیره تلقی نمی‌کنیم.

سلول ۴ — تحلیل بدون اینترنت و بدون ذخیره پنهانی

df_returns = analytics.returns(df, price="closing_price")
df_sma = analytics.sma(df, window=20)

منطق تحلیل مستقل است؛ جایگزینی DataFrame با داده فایل یا نمونه آموزشی به Client نیاز ندارد.

سلول ۵ — آفلاین با اجازه صریح داده قدیمی

offline_policy = FetchPolicy(
    mode="offline",
    freshness=FreshnessPolicy(allow_stale=True),
)
with Client(data_dir=DATA_DIR) as client:
    cached = client.get_history(SYMBOL, policy=offline_policy)

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

سلول ۶ — بدون ذخیره خودکار

with Client(storage=False) as client:
    df = client.get_history(SYMBOL)

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

سلول ۷ — دریافت ناهمگام در Jupyter

async with AsyncClient(data_dir=DATA_DIR) as client:
    df_async = await client.get_history(SYMBOL)
    await client.aflush(timeout=5.0, raise_on_error=False)

هیچ asyncio.run پنهان در رابط عادی نداریم. منطق ساخت ستون‌ها و کنترل کیفیت همان رابط همگام است.

سلول ۸ — ذخیره صریح چهار قالب

data.save(df, "foolad.csv")
data.save(df, "foolad.xlsx")
data.save(df, "foolad.parquet")
data.save(df, "research.sqlite3", dataset="foolad_daily")

loaded = data.load("foolad.parquet")

نصب موتورهای Excel و Parquet از extra مربوط لازم است. save صریح باید خطای ذخیره را اعلام کند؛ انتظار ادامه بی‌خطای آن هنگام خرابی مقصد منطقی نیست. داده صرفاً ذخیره‌شده امروز، شاهد در دسترس بودن همان نسخه در گذشته نمی‌شود.

منابع و حدود اعتبار

تاریخ بازبینی سند: ۱۲ اکتبر ۲۰۲۶. پیوندها منابع بررسی‌اند؛ وجود پیوند تضمین دسترس‌پذیری آینده نیست.

S01 — pytse-client snapshot

https://github.com/Glyphack/pytse-client/tree/b2ed0b97a7eeaca855935234cf416bcf1f5778b7

نسخه ثابت مرجع؛ نه ادعای تازه‌ترین انتشار

S02 — tsetmc snapshot 5.1.0

https://github.com/5j9/tsetmc/tree/af5f4578fe4a21030759c8ed1cef3f72a00834ab

نسخه ثابت مرجع

S03 — pandas DataFrame.attrs

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.attrs.html

attrs آزمایشی؛ در concat/merge انتقال آن مشروط است

S04 — SQLite WAL

https://www.sqlite.org/wal.html

یک نویسنده؛ امکان SQLITE_BUSY؛ نامناسب برای network filesystem

S05 — HTTPX async

https://www.python-httpx.org/async/

Client همگام و AsyncClient؛ عمر اتصال و بستن منابع

S06 — HTTPX transports

https://www.python-httpx.org/advanced/transports/

آزمون transport؛ retry داخلی همه خطاها را پوشش نمی‌دهد

S07 — scikit-learn pitfalls

https://scikit-learn.org/stable/common_pitfalls.html

fit فقط روی train؛ Pipeline به‌تنهایی تضمین PIT نیست

S08 — TimeSeriesSplit

https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.TimeSeriesSplit.html

تقسیم ترتیبی و gap؛ purging بازه برچسب موضوع جداگانه است

S09 — pandas IO

https://pandas.pydata.org/docs/user_guide/io.html

CSV، Excel، Parquet، SQL؛ تبدیل نوع باید کنترل شود

S10 — pyproject.toml

https://packaging.python.org/en/latest/guides/writing-pyproject-toml/

وابستگی‌ها و extras و metadata توزیع

S11 — PyPI trusted publishing

https://docs.pypi.org/trusted-publishers/

انتشار هویت‌محور CI

S12 — model persistence

https://scikit-learn.org/stable/model_persistence.html

خطر بارگذاری مدل نامطمئن و ناسازگاری نسخه

S13 — Python queue

https://docs.python.org/3/library/queue.html

صف کران‌دار و put_nowait؛ صف حافظه‌ای بادوام نیست

S14 — TSETMC official supplied docs

Pasted text(4).txt

احراز هویت، نقش، CheckCredit؛ تعرفه و سقف‌ها نامعلوم

تفکیک شواهد و طراحی

کاتالوگ دو کتابخانه، اطلاعات منبع کد در snapshot های ثابت را گزارش می‌کند. قراردادهای data/analytics/ml وپیش‌فرض‌های ذخیره،پیشنهاد مهندسی این سند هستند. نمونه‌های سند رسمی منبع،پاسخ اجرای زنده نیستند.

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