tse-dara 0.3.1a1__tar.gz

tse_dara-0.3.1a1/BUNDLE.json

@@ -0,0 +1,20 @@
+{
+  "bundle": "unified-data-usability-review",
+  "bundle_revision": 3,
+  "package_version": "0.3.1a1",
+  "wheel": "dist/tse_dara-0.3.1a1-py3-none-any.whl",
+  "wheel_sha256": "ed9225ce531b58bd2f9e360454f466e1d10d416e3aeea0356914e056f7253295",
+  "extras": [
+    "files",
+    "notebook"
+  ],
+  "minimum_python": [
+    3,
+    12
+  ],
+  "runtime_code_changed": true,
+  "runtime_files_matched": 31,
+  "source_archive": "TSE_Dara_Unified_v0.3.0a2_Windows_fix.zip",
+  "source_archive_sha256": "b6448adf0da23e7c3fdbeb44314a259d208736a744e094fca1f8048d4b888cd4",
+  "scope": "data only; no analytics or ML implementation added"
+}

tse_dara-0.3.1a1/CHANGELOG.md

@@ -0,0 +1,43 @@
+# 0.3.1a1 — Data interface/Pandas review
+
+- Preserve the unified 0.3.0a2 runtime, cache schema and Windows fsync fix.
+- Add single-row DataFrame getters, safe ordered Pandas batch inputs and explicit freshness helpers.
+- Add local schema, validation, canonical normalization, column selection, metadata and synthetic-data tools.
+- Add lazy module configuration, real signature documentation and per-blueprint-contract status mapping.
+- Preserve strict identity, stale-data warnings and independent best-effort autosave.
+- Stabilize timestamp units and archive string storage; improve input validation.
+- Add offline usage notebooks and regression tests. Analytics/ML and unverified market endpoints are not added.
+
+## 0.3.0a2 - Windows file export hotfix
+
+- Fix Windows `OSError: [Errno 9] Bad file descriptor` during CSV/Excel/Parquet export by opening temporary files with a writable handle before `os.fsync`.
+- No SQLite data migration; previously persisted data is untouched.
+
+# Changelog
+
+## Unified bundle revision 1 (runtime remains 0.3.0a1)
+
+- Combined Parts 1-3 in one root folder and retained only the current wheel.
+- Added a single environment-aware installer for files/notebook extras.
+- Added wheel checksum verification and post-install import/API checks.
+- Fixed stale 0.2.0a1 assertions in notebooks 03 and 04; cleared saved outputs.
+- Included the full v0.2 architecture/comparison reference, labelled planning-only.
+- Preserved runtime bytes and prior raw-cache/database behavior unchanged.
+- Separated current verification from historical reports.
+
+## 0.3.0a1 - Data Part 3
+
+- Added explicit save/load for self-describing CSV, Excel, Parquet and SQLite snapshots.
+- Added safe typed DataFrame codec, checksums, literal spreadsheet text and overwrite protection.
+- Added versioned per-day SQLite index using the existing bounded background writer.
+- Preserved old raw-cache schema/path. Added explicit, resumable offline reindexing.
+- Added stored-history reads, revision/status reports and locally observed as-of snapshots.
+- Added explicit sync_history: initial full, subsequent tail with overlap, full fallback and periodic full audits.
+- Sync and Async share normalizers, storage code and sync planning.
+- Existing quote/history functions remain compatible; normal get_history does not wait for persistence.
+- Excel and Parquet engines are optional and lazy. No computed adjustments, analytics, ML or PostgreSQL added.
+
+## Previous releases
+
+Parts 1 and 2 source behavior is retained and exercised by the original 189 tests.
+See the previous-part docs for their original release scope. Current limits are in PART3_API.md.

tse_dara-0.3.1a1/INSTALL_WINDOWS.bat

@@ -0,0 +1,10 @@
+@echo off
+setlocal
+if not defined CONDA_PREFIX if not defined VIRTUAL_ENV (
+ echo Activate your project environment in Anaconda Prompt first.
+ echo Then run: python install.py
+ exit /b 2
+)
+python "%~dp0install.py" %*
+set "RESULT=%ERRORLEVEL%"
+endlocal & exit /b %RESULT%

tse_dara-0.3.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tse-dara contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tse_dara-0.3.1a1/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE README.md README_FA.md CHANGELOG.md SECURITY.md
+recursive-include docs *.md *.json
+recursive-include tests *.py
+recursive-include examples *.ipynb *.py
+recursive-include tools *.py
+recursive-include src *.json py.typed
+exclude *.sqlite3
+
+include THIRD_PARTY_NOTICES.md
+recursive-include docs *.md *.json
+recursive-include tools *.py
+
+include START_HERE_FA.html PATCH_NOTES_FA.md
+
+include INSTALL_WINDOWS.bat
+
+recursive-include docs *.html
+include install.py BUNDLE.json

tse_dara-0.3.1a1/PATCH_NOTES_FA.md

@@ -0,0 +1,26 @@
+# یادداشت نسخه 0.3.1a1
+
+این نسخه ادامه بسته یکپارچه 0.3.0a2 و متمرکز بر بخش data است؛ نه اعلام تکمیل همه توابع نقشه راه.
+
+## تغییرات واقعی
+
+- پذیرش Series، Index و آرایه یک‌بعدی در دریافت گروهی؛ حفظ ترتیب و تکرار و رد داده نامعتبر پیش از شبکه.
+- get_quote_frame و get_instrument_frame برای DataFrame مستقیم.
+- FetchPolicy.offline/fresh و پذیرش رشته‌های صریح auto/online/offline؛ اجازه stale همچنان مستقل و صریح است.
+- configure/get_config بدون ساخت پایگاه یا شبکه؛ تغییر تنظیمات کلاینت فعال نیاز به close صریح دارد.
+- schema_info، validate_data، normalize_data، validate، normalize، select_columns، frame_metadata و load_sample.
+- Timestamp روزانه پانداس، تنها بدون ساعت و timezone؛ انواع timestamp خروجی ثابت ns/UTC.
+- مرجع امضاهای اجرایی و قرارداد ستون‌ها؛ شرح مدل‌های واقعی و گزارش شکاف نقشه راه.
+- حفظ اطلاعات backend رشته در codec آرشیو و اعتبارسنجی واضح‌تر پارامترهای فایل و تنظیمات.
+
+## سازگاری
+
+کدهای قدیمی get_price/get_quote/get_history/save/load حفظ شده‌اند. اصلاح fsync ویندوز و مقدار صفر insCode در پاسخ قیمت باقی مانده‌اند. پایگاه داده حذف یا جابه‌جا نمی‌شود. پس از نصب، Kernel را Restart کنید.
+
+## دامنه
+
+normalize با source='canonical' فقط نام‌های استاندارد فعلی را پشتیبانی می‌کند؛ نگاشت raw API جدید اختراع نشده است. ابزارهای validation ساختار را می‌سنجند، نه صحت اقتصادی یا نشت اطلاعات آینده را. get_instruments/دیده‌بان/شاخص/حقیقی‌حقوقی/تعدیل/رسمی هنوز مرحله بعدند. analytics و ml پیاده‌سازی نشده‌اند.
+
+## آزمون
+
+نتیجه واقعی آزمون‌های این نسخه در reports/review_031/VERIFICATION.json قرار دارد. محیط آزمون Linux/Python 3.13.5/Pandas 2.2.3 است. Windows/Pandas 3 و اتصال زنده این تحویل جداگانه تأیید نشده‌اند. آزمون Parquet بدون pyarrow اجرا نمی‌شود.

tse_dara-0.3.1a1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: tse-dara
+Version: 0.3.1a1
+Summary: Direct TSETMC data access: quotes, history, typed exports and resilient versioned local storage
+Author: tse-dara contributors
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: excel
+Requires-Dist: openpyxl<4,>=3.1.5; extra == "excel"
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=19; extra == "parquet"
+Provides-Extra: files
+Requires-Dist: openpyxl<4,>=3.1.5; extra == "files"
+Requires-Dist: pyarrow>=19; extra == "files"
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8; extra == "test"
+Provides-Extra: notebook
+Requires-Dist: ipykernel>=6; extra == "notebook"
+Requires-Dist: nbformat>=5; extra == "notebook"
+Requires-Dist: nbclient>=0.10; extra == "notebook"
+Dynamic: license-file
+
+# tse-dara
+
+Release **0.3.1a1**, a unified alpha distribution of Parts 1–3 plus a data-interface and Pandas contract review. Direct public TSETMC requests; no runtime dependency on pytse-client or tsetmc.
+
+## Scope
+
+Existing quotes, raw daily history, sync/async clients, versioned SQLite history and file archives are preserved. This release adds simple one-row DataFrame getters, ordered Pandas batch input, explicit freshness helpers, local schema/normalization/validation tools, synthetic samples and a reference generated from actual signatures.
+
+It does **not** implement analytics, ML, market watch, indices, client-type endpoints, corporate-action adjustment, historical identity chains, official JWT access, or PostgreSQL. The architecture HTML is a plan, not a declaration of supported features. See docs/BLUEPRINT_DATA_COVERAGE.md.
+
+## Install from PyPI
+
+Requires Python 3.12 or newer. This is an alpha release; install it explicitly:
+
+```console
+python -m pip install tse-dara==0.3.1a1
+```
+
+Optional Excel/Parquet exports and notebook support:
+
+```console
+python -m pip install "tse-dara[files,notebook]==0.3.1a1"
+```
+
+Import the installed package as `tse_dara`. Restart an existing notebook kernel after installation or upgrade.
+
+## Install from a local release bundle
+
+```console
+python install.py
+```
+
+The installer reads the single local wheel from BUNDLE.json and invokes pip with files/notebook extras. Missing dependencies need internet. Use `python install.py --core-only` explicitly when Excel/Parquet/notebooks are not required. Never delete your Conda environment or cache database to upgrade. Restart the notebook kernel afterwards.
+
+The local bundle is not a self-contained offline wheelhouse.
+
+## Examples
+
+```python
+from tse_dara import data
+
+# Synthetic teaching data, no external HTTP or database
+df = data.load_sample()
+report = data.validate_data(df)
+compact = data.select_columns(df)
+
+# Real data: makes a network request or uses an eligible cache entry
+quote_df = data.get_quote_frame("فولاد")
+history = data.get_history("فولاد", start="1403-01-01",
+                           end="1403-12-30", calendar="jalali")
+
+# Documentation without a network request
+reference = data.api_reference("get_history")
+columns = data.schema_info("daily_bars")
+```
+
+Offline quote use is explicit: `policy=data.FetchPolicy.offline(allow_stale=True)`. The shortcut `policy="offline"` does not permit stale data. Use `FetchPolicy.fresh()` for a network read with max_age=0; online mode alone may use fresh cache.
+
+`get_quotes` and `get_history_many` accept a list/tuple, Series, Index or 1D NumPy array. Input order and duplicates are preserved. Null entries are rejected before fetching. Raw numeric strings are not inferred as instrument IDs; use `InstrumentRef.by_ins_code`.
+
+## Persistence
+
+Best-effort autosave failures do not invalidate successfully fetched data. A queued receipt is not durable storage. Explicit `save`, `load`, `flush` and `sync_history(wait=True)` report failures. Existing 0.3.0a2 SQLite schemas and cache paths are retained; no destructive migration is introduced.
+
+`save/load` use typed Dara archives. Preserve the JSON sidecar with CSV. They are not a generic parser for arbitrary external files. Use Pandas readers with explicit identifier dtypes, then normalize_data with an explicit column mapping for external data. Never treat a floating identifier as recoverable original text.
+
+## References and examples
+
+- START_HERE_FA.html: Persian getting-started guide.
+- docs/DATA_REVIEW_REPORT_FA.html: complete current review and actual API/model documentation.
+- docs/API_REFERENCE_FA.md and API_REFERENCE.md: real signatures, defaults, outputs, main exceptions and dependencies.
+- docs/MODELS_REFERENCE_FA.md: actual runtime dataclasses and enums.
+- docs/ROADMAP_REVIEW_FA.md: next data-only stages.
+- docs/design_v0_2/USER_SUPPLIED_REPORT.html: original uploaded architecture, unchanged.
+- examples/10_data_usability_offline.ipynb and 11_pandas_validation.ipynb: new offline notebooks.
+- examples/12_data_review_live.ipynb: optional real-network test, disabled by default.
+- tools/check_data_usability.py: offline check; `--live` explicitly opts into external requests.
+
+## Verification
+
+The PyPI preparation checks also run on Windows/Python 3.13.1/Pandas 3.0.6 with Excel and Parquet dependencies installed. See reports/pypi-tests.xml for the local test report and reports/review_031/VERIFICATION.json for historical Linux/Python 3.13.5/Pandas 2.2.3 checks and limitations. Python 3.14 is not verified by this local run. Parquet tests require pyarrow; skipped tests are not successes. The GitHub matrix is supplied configuration. Historical reports are preserved in separate directories.
+
+Structural validation does not establish source accuracy, historical coverage, official publication time or absence of all forms of future-data leakage. No live-price number is bundled as a current quote.
+
+## Development
+
+```console
+python -m pip install -e ".[test,notebook]"
+python tools/generate_api_reference.py
+python tools/build.py
+python tools/update_bundle.py
+python -m pytest -q
+```
+
+Generating the optional HTML documentation requires mistune, a documentation-only dependency, not a runtime dependency. Retain exactly one current wheel under dist/.
+
+License: MIT; third-party notices are in THIRD_PARTY_NOTICES.md. Data-access and redistribution rights are separate from the code license.

tse_dara-0.3.1a1/README.md

@@ -0,0 +1,97 @@
+# tse-dara
+
+Release **0.3.1a1**, a unified alpha distribution of Parts 1–3 plus a data-interface and Pandas contract review. Direct public TSETMC requests; no runtime dependency on pytse-client or tsetmc.
+
+## Scope
+
+Existing quotes, raw daily history, sync/async clients, versioned SQLite history and file archives are preserved. This release adds simple one-row DataFrame getters, ordered Pandas batch input, explicit freshness helpers, local schema/normalization/validation tools, synthetic samples and a reference generated from actual signatures.
+
+It does **not** implement analytics, ML, market watch, indices, client-type endpoints, corporate-action adjustment, historical identity chains, official JWT access, or PostgreSQL. The architecture HTML is a plan, not a declaration of supported features. See docs/BLUEPRINT_DATA_COVERAGE.md.
+
+## Install from PyPI
+
+Requires Python 3.12 or newer. This is an alpha release; install it explicitly:
+
+```console
+python -m pip install tse-dara==0.3.1a1
+```
+
+Optional Excel/Parquet exports and notebook support:
+
+```console
+python -m pip install "tse-dara[files,notebook]==0.3.1a1"
+```
+
+Import the installed package as `tse_dara`. Restart an existing notebook kernel after installation or upgrade.
+
+## Install from a local release bundle
+
+```console
+python install.py
+```
+
+The installer reads the single local wheel from BUNDLE.json and invokes pip with files/notebook extras. Missing dependencies need internet. Use `python install.py --core-only` explicitly when Excel/Parquet/notebooks are not required. Never delete your Conda environment or cache database to upgrade. Restart the notebook kernel afterwards.
+
+The local bundle is not a self-contained offline wheelhouse.
+
+## Examples
+
+```python
+from tse_dara import data
+
+# Synthetic teaching data, no external HTTP or database
+df = data.load_sample()
+report = data.validate_data(df)
+compact = data.select_columns(df)
+
+# Real data: makes a network request or uses an eligible cache entry
+quote_df = data.get_quote_frame("فولاد")
+history = data.get_history("فولاد", start="1403-01-01",
+                           end="1403-12-30", calendar="jalali")
+
+# Documentation without a network request
+reference = data.api_reference("get_history")
+columns = data.schema_info("daily_bars")
+```
+
+Offline quote use is explicit: `policy=data.FetchPolicy.offline(allow_stale=True)`. The shortcut `policy="offline"` does not permit stale data. Use `FetchPolicy.fresh()` for a network read with max_age=0; online mode alone may use fresh cache.
+
+`get_quotes` and `get_history_many` accept a list/tuple, Series, Index or 1D NumPy array. Input order and duplicates are preserved. Null entries are rejected before fetching. Raw numeric strings are not inferred as instrument IDs; use `InstrumentRef.by_ins_code`.
+
+## Persistence
+
+Best-effort autosave failures do not invalidate successfully fetched data. A queued receipt is not durable storage. Explicit `save`, `load`, `flush` and `sync_history(wait=True)` report failures. Existing 0.3.0a2 SQLite schemas and cache paths are retained; no destructive migration is introduced.
+
+`save/load` use typed Dara archives. Preserve the JSON sidecar with CSV. They are not a generic parser for arbitrary external files. Use Pandas readers with explicit identifier dtypes, then normalize_data with an explicit column mapping for external data. Never treat a floating identifier as recoverable original text.
+
+## References and examples
+
+- START_HERE_FA.html: Persian getting-started guide.
+- docs/DATA_REVIEW_REPORT_FA.html: complete current review and actual API/model documentation.
+- docs/API_REFERENCE_FA.md and API_REFERENCE.md: real signatures, defaults, outputs, main exceptions and dependencies.
+- docs/MODELS_REFERENCE_FA.md: actual runtime dataclasses and enums.
+- docs/ROADMAP_REVIEW_FA.md: next data-only stages.
+- docs/design_v0_2/USER_SUPPLIED_REPORT.html: original uploaded architecture, unchanged.
+- examples/10_data_usability_offline.ipynb and 11_pandas_validation.ipynb: new offline notebooks.
+- examples/12_data_review_live.ipynb: optional real-network test, disabled by default.
+- tools/check_data_usability.py: offline check; `--live` explicitly opts into external requests.
+
+## Verification
+
+The PyPI preparation checks also run on Windows/Python 3.13.1/Pandas 3.0.6 with Excel and Parquet dependencies installed. See reports/pypi-tests.xml for the local test report and reports/review_031/VERIFICATION.json for historical Linux/Python 3.13.5/Pandas 2.2.3 checks and limitations. Python 3.14 is not verified by this local run. Parquet tests require pyarrow; skipped tests are not successes. The GitHub matrix is supplied configuration. Historical reports are preserved in separate directories.
+
+Structural validation does not establish source accuracy, historical coverage, official publication time or absence of all forms of future-data leakage. No live-price number is bundled as a current quote.
+
+## Development
+
+```console
+python -m pip install -e ".[test,notebook]"
+python tools/generate_api_reference.py
+python tools/build.py
+python tools/update_bundle.py
+python -m pytest -q
+```
+
+Generating the optional HTML documentation requires mistune, a documentation-only dependency, not a runtime dependency. Retain exactly one current wheel under dist/.
+
+License: MIT; third-party notices are in THIRD_PARTY_NOTICES.md. Data-access and redistribution rights are separate from the code license.

tse_dara-0.3.1a1/README_FA.md

@@ -0,0 +1,177 @@
+# tse-dara — نسخه یکپارچه 0.3.1a1
+
+## دامنه این تحویل
+
+این نسخه برای **تثبیت و ساده‌سازی بخش داده موجود** است، نه تکمیل همه سرویس‌های نقشه راه. هیچ الگوریتم تحلیل، اندیکاتور یا یادگیری ماشین اضافه نشده است. قابلیت‌های قیمت، تاریخچه خام، دریافت گروهی، ذخیره خودکار، بازیابی آفلاین، اصلاحات تاریخچه و خروجی فایل‌های قسمت‌های اول تا سوم حفظ شده‌اند. اصلاح Windows برای fsync نیز محفوظ است.
+
+سند اصلی ارسالی در `docs/design_v0_2/USER_SUPPLIED_REPORT.html` بدون تغییر نگهداری شده است. `docs/ROADMAP_REVIEW_FA.md` طرح را با پیاده‌سازی واقعی مقایسه می‌کند. سند طراحی پیشین، به‌تنهایی مدرک پیاده‌سازی نیست.
+
+## نصب یک‌باره یا ارتقا
+
+برای نصب نسخهٔ آزمایشی از PyPI با Python 3.12 یا جدیدتر:
+
+```console
+python -m pip install tse-dara==0.3.1a1
+```
+
+برای امکانات Excel، Parquet و Notebook:
+
+```console
+python -m pip install "tse-dara[files,notebook]==0.3.1a1"
+```
+
+نام کتابخانه هنگام import برابر `tse_dara` است. پس از نصب یا ارتقا، Kernel ژوپیتر را Restart کن.
+
+### نصب از بستهٔ محلی
+
+پوشه `tse-dara` این ZIP را در محل دلخواه استخراج کن؛ برای جلوگیری از باقی‌ماندن فایل نصب قدیمی، از پوشه تمیزِ استخراج‌شده استفاده کن. محیط پایتون و پایگاه داده قبلی را حذف نکن.
+
+```bat
+python install.py
+```
+
+نصاب فقط Wheel همین بسته را نصب می‌کند. برای قابلیت‌های Excel و Parquet و Notebook، وابستگی‌های اختیاری را در همان مرحله درخواست می‌کند. نصب کاملاً آفلاین نیست؛ اگر وابستگی‌ای موجود نباشد، اینترنت لازم است. برای نصب فقط هسته: `python install.py --core-only`.
+
+پس از نصب Kernel ژوپیتر را Restart کن و سپس بررسی کن:
+
+```python
+import sys
+import tse_dara
+print(sys.executable)
+print(tse_dara.__version__)
+print(tse_dara.__file__)
+```
+
+نسخه باید `0.3.1a1` باشد. تغییر نسخه به حذف یا مهاجرت پایگاه SQLite قبلی نیاز ندارد.
+
+## تغییرهای اصلی
+
+* `get_quotes()` و `get_history_many()` علاوه بر list و tuple، ورودی `pandas.Series`، `pandas.Index` و آرایه یک‌بعدی NumPy می‌پذیرند. ترتیب و تکرار ورودی حفظ می‌شود. null، جدول دوبعدی، مجموعه بی‌ترتیب و شناسه عددیِ مبهم پیش از درخواست شبکه رد می‌شوند.
+* `get_quote_frame()` و `get_instrument_frame()` مستقیماً DataFrame می‌دهند. `get_quote()` همچنان مدل Quote و `get_price()` همچنان Decimal می‌دهد؛ رفتار قدیمی عوض نشده است.
+* `Client(numeric="exact")` میان‌بری برای تنظیم پروفایل عددی است. در حالت معمول جدول‌ها Float64/Int64 nullable دارند و شناسه‌ها رشته باقی می‌مانند.
+* `FetchPolicy.offline(allow_stale=True)` استفاده صریح از کش قدیمی را ساده می‌کند. `policy="offline"` نیز اکنون پذیرفته می‌شود، اما اجازه استفاده از داده منقضی را خودکار صادر نمی‌کند.
+* `FetchPolicy.fresh()` کش را برای درخواست تازه کنار می‌گذارد. این با `policy="online"` متفاوت است؛ حالت online ممکن است کش تازه را استفاده کند.
+* تاریخ‌های `pd.Timestamp` فقط اگر نیمه‌شب و بدون منطقه زمانی باشند در ورودی تاریخ روزانه پذیرفته می‌شوند. تقویم این شیء همیشه میلادی است؛ رشته شمسی نیازمند `calendar="jalali"` است.
+* زمان‌های ستون‌های مرکزی به `datetime64[ns, UTC]` یکدست شده‌اند. این تغییر، اختلاف پیش‌فرض دقت زمانی میان نسخه‌های Pandas را کم می‌کند؛ به معنی آزمون عملی همه نسخه‌ها نیست.
+* حفظ نوع رشته هنگام ذخیره و بازیابی دقیق‌تر شده و ورودی غلط مسیر یا قالب، خطای عمومی قابل فهم کتابخانه می‌دهد.
+* مرجع امضای واقعی توابع داخل بسته و از طریق `data.api_reference()` در دسترس است.
+
+## نمونه ساده و بدون تغییر به کد قدیمی
+
+```python
+from tse_dara import data
+
+price = data.get_price("فولاد")
+quote_df = data.get_quote_frame("فولاد")
+history = data.get_history("فولاد", include_jdate=True)
+```
+
+برای نمایش خلوت‌تر بدون تغییر جدول اصلی:
+
+```python
+display(data.select_columns(history, "compact"))
+```
+
+نمای compact بعضی ستون‌های شناسنامه را حذف می‌کند و در متادیتا این موضوع را اعلام می‌کند. برای آرشیو کامل، جدول اصلی را ذخیره کن؛ نمای خلوت جای مدرک منشأ داده نیست.
+
+## تنظیمات ساده پیش از اولین دریافت
+
+```python
+from tse_dara import data
+
+data.configure(
+    data_dir=r"G:\My progect\Python\TSE\dara-data",
+    numeric="analysis",
+    storage=True,
+)
+```
+
+`configure` فایل یا شبکه ایجاد نمی‌کند. اگر قبلاً از توابع مستقیم data استفاده کرده‌ای، ابتدا `report = data.close()` را اجرا و تکمیل ذخیره را بررسی کن؛ سپس تنظیمات جدید را اعمال کن. مسیر جدید، اطلاعات مسیر قدیمی را خودکار جابه‌جا نمی‌کند. تغییر تنظیمات Client مستقل، کلاینت‌های دیگر را عوض نمی‌کند.
+
+## دریافت گروهی با Pandas
+
+```python
+import pandas as pd
+from tse_dara import data
+
+symbols = pd.Series(["فولاد", "شستا", "فولاد"], dtype="string")
+quotes = data.get_quotes(symbols, on_error="collect")
+batch = data.get_history_many(symbols, on_error="collect")
+display(quotes)
+display(batch.requests)
+display(batch.errors)
+```
+
+ورودی تکراری، سطر/گزارش مستقل دارد. برای تاریخچه گروهی، `batch.data` جدول داده و `batch.errors` جدول خطاهاست. `on_error="collect"` اجازه انتخاب تصادفی نماد مبهم را نمی‌دهد.
+
+## آفلاین و داده قدیمی
+
+```python
+from tse_dara.data import Client, FetchPolicy
+
+with Client() as client:
+    quote = client.get_quote(
+        "فولاد",
+        policy=FetchPolicy.offline(allow_stale=True),
+    )
+    print(quote.last_price, quote.trade_date)
+    print(quote.meta.quality_flags)
+```
+
+این دستور اینترنت ندارد، اما باید قبلاً پاسخ لازم در همین مسیر و همین فضای کش ذخیره شده باشد. `stale_cached_response` و StaleDataWarning خطای برنامه نیستند؛ می‌گویند داده قدیمی است. تاریخ منبع با زمان دریافت داده تفاوت دارد. قیمت آفلاین به قیمت لحظه‌ای تبدیل نمی‌شود.
+
+## کار با جدول و کنترل کیفیت
+
+```python
+schema = data.schema_info("daily_bars")
+issues = data.validate_data(history)
+metadata = data.frame_metadata(history)
+
+display(schema)
+display(issues)
+```
+
+گزارش خالی یعنی قواعد ساختاری اجراشده ایرادی پیدا نکرده‌اند، نه اینکه داده بورس از نظر اقتصادی یا تاریخی قطعاً کامل است. این ابزار آزمون نشت اطلاعات آینده یا تحلیل سرمایه‌گذاری نیست.
+
+برای تبدیل جدول خارجی، نام‌ها را خودت صریح تعیین کن:
+
+```python
+normalized = data.normalize_data(
+    external_df,
+    columns={"نماد": "symbol", "تاریخ": "date", "پایانی": "closing_price"},
+    calendar="jalali",
+)
+```
+
+ستون‌های ناشناخته و رکوردها حفظ می‌شوند. مقدار گمشده پر نمی‌شود؛ شناسه float به‌دروغ بازیابی نمی‌شود؛ سطر تکراری حذف و قیمت منفی بریده نمی‌شود. وجود نقص را با `validate_data()` بررسی کن. برای timestamp بدون timezone، پارامتر `timezone` لازم است.
+
+## ذخیره
+
+```python
+data.save(history, "folad.csv", overwrite=True)
+restored = data.load("folad.csv")
+```
+
+CSV به فایل همراه `.csv.dara.json` نیاز دارد. Excel و Parquet و SQLite خروجی نیز شناسنامه دارند. `data.load()` خواننده آرشیو Dara است، نه مفسر خودکار فایل دلخواه؛ فایل خارجی را با Pandas بخوان و سپس با نگاشت صریح عادی‌سازی کن.
+
+شکست ذخیره خودکار، نتیجه معتبر دریافت را متوقف نمی‌کند. اما save/load/flush عملیات صریح هستند و شکست را اعلام می‌کنند. صف حافظه، دوام روی دیسک نیست.
+
+## از کدام دفترچه شروع کنیم؟
+
+`10_data_usability_offline.ipynb`: مثال کامل امکانات ساده‌شده با داده مصنوعی.
+
+`11_pandas_validation.ipynb`: نمونه کنترل نوع، نگاشت ستون، خطاها و حفظ ورودی.
+
+`12_data_review_live.ipynb`: آزمون اختیاری روی سرور واقعی؛ پیش‌فرض دریافت زنده خاموش است.
+
+هر ۹ دفترچه قبلی حفظ شده‌اند. دفترچه‌های نمونه قیمت واقعی بازار نشان نمی‌دهند و کش نمونه از کش واقعی جداست.
+
+## هنوز آماده نیست
+
+فهرست کامل و تاریخی تمام ابزارها، اتصال شناسه‌های قدیمی، دریافت بر اساس ISIN، تعدیل تأییدشده، API رسمی دارای حساب، دیده‌بان، شاخص‌ها، حقیقی‌حقوقی، مظنه، ریزمعاملات، صندوق‌ها و اطلاعیه‌ها هنوز به عنوان قابلیت‌های کامل در این نسخه عرضه نشده‌اند. مرحله بعد پیشنهادی، خانواده داده‌های بازار P08 پس از تثبیت آزمون‌های همین نسخه است.
+
+توابع تحلیل و هوش مصنوعی بنا به درخواست فعلی اضافه نشده‌اند. پرونده اصلی طراحی آن‌ها به‌عنوان سابقه باقی مانده، اما وابستگی ML نصب نمی‌شود.
+
+## آزمون و حدود تأیید
+
+آمار دقیق و محیط آزمون نهایی در `reports/review_031/VERIFICATION.json` ثبت می‌شود. آزمون‌های خودکار شبکه واقعی را مسدود می‌کنند. نبود خطا در نمونه‌های ساختگی، سلامت همیشگی API بورس را ثابت نمی‌کند. اگر آزمون Pandas 3، Windows یا Parquet اجرا نشده باشد، در گزارش صریحاً اجرا‌نشده درج می‌شود.

tse_dara-0.3.1a1/SECURITY.md

@@ -0,0 +1,33 @@
+# Security and operational notes
+
+No API credentials are needed or accepted in this release. No telemetry, trading,
+account access, proxy rotation, TLS bypass, or package auto-update is performed.
+Requests target a fixed HTTPS base URL; redirects are not followed. Response
+bytes are capped; malformed JSON and duplicate keys are rejected. Only validated
+responses enter the cache. Never send credentials or tokens in issue reports.
+
+Do not treat a fresh retrieval timestamp as proof of fresh exchange data.
+Unit normalization is deliberately narrow and unverified instruments carry
+unknown units. The fixture suite is not an independent security audit.
+
+No background network polling is started. The optional background writer only
+persists data already obtained by an explicit user operation. Stop/close clients
+when finished, and explicitly flush when durability is required.
+
+The supplied license covers code, not permission to redistribute exchange data.
+A public endpoint does not imply unlimited access or a service-level guarantee.
+
+Daily-history cache versions are response observations, not certified publication history.
+Do not use raw or retroactively adjusted daily data as point-in-time ML evidence.
+
+Part 3 adds inert tagged serialization, not pickle or eval. Structural dtype
+parsing uses an allowlist. Hashes detect accidental corruption, not malicious
+rewriting of data and hashes together. XLSX formulas are not executed;
+metadata is not encrypted. CSV+sidecar are two files, not an atomic pair.
+Readers are eager and file-size limits are not a universal sandbox against
+all compressed-format resource-exhaustion attacks. Only open trusted archives.
+
+Normalized history stores observation versions. `committed_at` is the writer's
+transaction timestamp, not a metrologically precise post-fsync timestamp.
+Local as_of is based on recorded timestamps and does not certify an exchange
+publication time or a sub-second, crash-consistent replay of database visibility.