settfex 0.2.0__tar.gz → 0.3.0__tar.gz

settfex-0.3.0/.editorconfig

@@ -0,0 +1,23 @@
+# EditorConfig — https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 100
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

settfex-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Report a bug to help us improve settfex
+labels: bug
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to reproduce
+
+```python
+# Minimal async snippet that triggers the bug
+```
+
+1.
+2.
+3.
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened — include the full error message / traceback or logs.
+
+## Service / endpoint
+
+Which settfex service is involved (e.g. `get_highlight_data`, `Stock`,
+`get_stock_list`, TFEX series list) and the symbol used, if relevant.
+
+## Environment
+
+- OS: [e.g. macOS 15, Ubuntu 24.04]
+- Python version: [e.g. 3.11.9]
+- settfex version: [from `pip show settfex` or `uv pip show settfex`]
+- uv version: [from `uv --version`, if applicable]
+
+## Additional context
+
+Add any other context (network/proxy setup, intermittent vs reproducible, etc.).

settfex-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new service, data field, or improvement for settfex
+labels: enhancement
+---
+
+## Problem
+
+Describe the problem this feature would solve (e.g. "settfex has no service for
+X data that the SET/TFEX website exposes").
+
+## Proposed solution
+
+Describe what you'd like to happen. If it's a new data service, include the
+endpoint URL / API shape if you know it.
+
+## Alternatives considered
+
+Describe any alternative solutions or workarounds you've tried.
+
+## Additional context
+
+Add any other context, links to SET/TFEX pages, or sample responses.

settfex-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+<!-- Briefly describe what this PR does. -->
+
+## Changes
+
+<!-- List the key changes with file paths. -->
+
+- ...
+
+## Test plan
+
+<!-- Check the boxes after verifying each step locally. -->
+
+- [ ] `uv run ruff check .` passes
+- [ ] `uv run ruff format --check .` passes
+- [ ] `uv run mypy settfex/` passes
+- [ ] `uv run pytest` passes (coverage gate met)
+- [ ] New/changed behavior is covered by tests (external API calls mocked)
+- [ ] Docs / docstrings / `CHANGELOG.md` updated if user-facing
+
+## Related
+
+<!-- Link to issues or discussions. -->
+
+Closes #

settfex-0.3.0/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  # Python dependencies (uv.lock / pyproject.toml).
+  # If your Dependabot version rejects the "uv" ecosystem, change it to "pip".
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+    labels:
+      - "dependencies"
+
+  # GitHub Actions used in workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(ci)"
+    labels:
+      - "dependencies"
+      - "github-actions"

{settfex-0.2.0 → settfex-0.3.0}/.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
     paths:
       - "**/*.py"
       - "pyproject.toml"
+      - "uv.lock"
       - "tests/**"
       - ".github/workflows/ci.yml"
   push:
@@ -18,12 +19,13 @@ on:
     paths:
       - "**/*.py"
       - "pyproject.toml"
+      - "uv.lock"
       - "tests/**"
       - ".github/workflows/ci.yml"
 
 jobs:
-  ruff:
-    name: Ruff
+  lint:
+    name: Lint & Type
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -32,18 +34,23 @@ jobs:
         with:
           version: "latest"
           enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
+          cache-dependency-glob: "uv.lock"
 
       - run: uv python install 3.11
-      - run: uv sync --group dev
+      - run: uv sync --group dev --frozen
 
       - run: uv run ruff check .
       - run: uv run ruff format --check .
+      - run: uv run mypy settfex/
 
-  quality:
-    name: Type & Tests
+  test:
+    name: Test (py${{ matrix.python-version }})
     runs-on: ubuntu-latest
-    needs: ruff
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -51,15 +58,15 @@ jobs:
         with:
           version: "latest"
           enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
+          cache-dependency-glob: "uv.lock"
 
-      - run: uv python install 3.11
-      - run: uv sync --group dev
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev --frozen
 
-      - run: uv run mypy settfex/
       - run: uv run pytest --cov=settfex --cov-branch --cov-report=xml --cov-report=term-missing -v
 
       - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.12'
         uses: codecov/codecov-action@v4
         with:
           files: coverage.xml

{settfex-0.2.0 → settfex-0.3.0}/.github/workflows/release.yml

@@ -66,10 +66,10 @@ jobs:
         with:
           version: "latest"
           enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
+          cache-dependency-glob: "uv.lock"
 
       - run: uv python install 3.11
-      - run: uv sync --group dev
+      - run: uv sync --group dev --frozen
 
       - run: uv run ruff check .
       - run: uv run ruff format --check .
@@ -89,7 +89,7 @@ jobs:
         with:
           version: "latest"
           enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
+          cache-dependency-glob: "uv.lock"
 
       - run: uv python install 3.11
       - run: uv run python -m build
@@ -141,7 +141,6 @@ jobs:
           path: dist/
 
       - name: Extract changelog section
-        id: changelog
         run: |
           VERSION="${{ needs.validate.outputs.version }}"
           python3 - "$VERSION" <<'PYEOF'
@@ -152,19 +151,14 @@ jobs:
           match = re.search(pattern, content, re.DOTALL)
           notes = match.group(1).strip() if match else f"Release v{version}"
           with open("release_notes.txt", "w") as f:
-              f.write(notes)
+              f.write(notes + "\n")
           PYEOF
-          {
-            echo 'notes<<CHANGELOG_EOF'
-            cat release_notes.txt
-            echo 'CHANGELOG_EOF'
-          } >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           name: "settfex v${{ needs.validate.outputs.version }}"
-          body: ${{ steps.changelog.outputs.notes }}
+          body_path: release_notes.txt
           prerelease: ${{ needs.validate.outputs.is_prerelease }}
           files: dist/*
           make_latest: ${{ needs.validate.outputs.is_prerelease == 'false' }}

settfex-0.3.0/.github/workflows/security.yml

@@ -0,0 +1,62 @@
+name: Security
+
+on:
+  schedule:
+    - cron: "23 3 * * 3" # Wednesdays at 03:23 UTC
+  push:
+    branches: [main]
+    paths:
+      - "**/*.py"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/security.yml"
+  workflow_dispatch:
+
+jobs:
+  bandit:
+    name: Bandit (static analysis)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - run: uv python install 3.12
+      - run: uv sync --group dev --frozen
+
+      # `|| true` so a finding uploads the report instead of failing the job;
+      # review findings in the artifact.
+      - run: uv run bandit -c pyproject.toml -r settfex -f json -o bandit-results.json || true
+
+      - name: Upload Bandit results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bandit-results
+          path: bandit-results.json
+          retention-days: 7
+
+  pip-audit:
+    name: pip-audit (dependency CVEs)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - run: uv python install 3.12
+      - run: uv sync --group dev --frozen
+
+      # Non-blocking: surfaces dependency CVEs for triage without blocking PRs.
+      # Some advisories are transitive or not-yet-fixed upstream (e.g. no fix
+      # released), so review results and bump deps in a dedicated PR.
+      - run: uv run pip-audit --desc
+        continue-on-error: true

settfex-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,36 @@
+# Pre-commit hooks mirroring the CI quality gate.
+#   Install once:   uv run pre-commit install
+#   Run manually:   uv run pre-commit run --all-files
+#   Update revs:    uv run pre-commit autoupdate
+repos:
+  # Ruff: lint (with autofix) + format — matches CI `ruff check` / `ruff format`.
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Standard hygiene hooks.
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: detect-private-key
+
+  # mypy runs as a local hook via `uv run` so it uses the project environment
+  # and the strict config in pyproject.toml — identical to CI (`mypy settfex/`).
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (settfex)
+        entry: uv run mypy settfex/
+        language: system
+        types: [python]
+        pass_filenames: false
+        files: ^settfex/

{settfex-0.2.0 → settfex-0.3.0}/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-17
+
+### Added
+
+- **TFEX underlying-price service** (`get_underlying_price`, `TFEXUnderlyingPriceService`,
+  `UnderlyingPrice`): fetches the underlying instrument price for a TFEX series via
+  `GET /api/set/tfex/series/{symbol}/underlying-price`. For SET50 index options/futures the underlying
+  is the **SET50 index spot** — exposes last/prior/high/low, change, total volume/value, and P/E + P/BV.
+  Mirrors the existing TFEX service pattern (SessionManager/Incapsula bypass, NaN-rejecting hardened
+  parsing, `get_*` convenience function + `*_raw` variant); 100% module test coverage. Adds the
+  `verify_underlying_price.py` script and the `examples/tfex/03_underlying_price.ipynb` notebook.
+
+## [0.2.1] - 2026-06-17
+
+Robustness and concurrency hardening release. No public API changes — function
+signatures, return types, Pydantic model fields, and `en`/`th` + symbol normalization
+are all preserved. See `COMPREHENSIVE_AUDIT.md` for full details and benchmarks.
+
+### Fixed
+
+- **Silent financial-data corruption:** `NaN`/`Infinity` values from the SET/TFEX APIs were
+  silently accepted into numeric model fields (prices, P/E, margins). They are now rejected at
+  decode time with a clear error that includes the originating symbol and endpoint.
+- Parse and validation failures now raise with **symbol + endpoint context** (and per-item
+  index for lists) instead of a bare, context-free `ValidationError`/`JSONDecodeError`.
+- Replaced unsafe `assert isinstance(data, dict)` in the TFEX trading-statistics and
+  series-list raw paths — `assert` is stripped under `python -O` — with explicit, contextful
+  errors.
+- **Session warm-up stampede:** concurrent cold-start callers each fired their own warm-up
+  round-trip (which can trip bot detection); warm-up is now serialized to run at most once.
+- Offloaded blocking cache initialization (directory creation + opening the on-disk cache) off
+  the asyncio event loop.
+
+### Changed
+
+- Centralized JSON decode + Pydantic validation across all SET/TFEX services into a shared
+  internal helper (`settfex/utils/parsing.py`), removing ~111 lines of duplicated boilerplate.
+- Hoisted static request headers in `AsyncDataFetcher.fetch()` to a module-level constant.
+- Added regression tests for malformed/NaN/partial responses and TFEX coverage
+  (test suite 116 → 149; coverage 49% → 61%).
+
 ## [0.2.0] - 2026-06-09
 
 ### Added

settfex-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,83 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at b@candythink.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

settfex-0.3.0/COMPREHENSIVE_AUDIT.md

@@ -0,0 +1,139 @@
+# settfex Hardening Pass — Comprehensive Audit
+
+**Branch:** `claude-settfex-overhaul` (off `chore/adopt-python-template-tooling`)
+**Scope:** robustness / financial-correctness + performance / concurrency hardening of the
+SET/TFEX async client, with the public API contract preserved exactly.
+
+---
+
+## 1. Executive summary
+
+| Metric | Before | After |
+|---|---|---|
+| Tests passing | 116 | **149** (+33) |
+| Test runtime | 3.77 s | 2.81 s |
+| Coverage (gate = 45%) | 49.26% | **61.25%** (+11.99 pts) |
+| `ruff check` / `ruff format` / `mypy --strict` | clean | clean |
+
+- **5 classes of defect fixed** — the headline one being **silent NaN/Infinity acceptance**
+  into financial models (prices, P/E, margins), plus context-free parse failures, an
+  `assert`-based type check stripped under `python -O`, a cold-start **warmup stampede**, and
+  blocking disk I/O on the event loop.
+- **~15 service parse sites** routed through one hardened helper, **removing ~111 net lines**
+  of duplicated decode/validation boilerplate while *adding* guarantees.
+- **+33 regression tests**; two previously-0%-covered TFEX services now tested.
+- **Performance:** measured every candidate; applied only the wins that benchmarks justified
+  (header hoist; warmup stampede 25→1). Notably, **blanket lazy-logging was measured to be a
+  regression here and deliberately NOT applied** (see §3).
+- **Public API:** unchanged — verified by signature/return-type/field smoke test (§6).
+
+---
+
+## 2. Bugs & robustness
+
+The shared fix is a new internal module **`settfex/utils/parsing.py`**
+(`decode_json`, `validate_or_raise`, `validate_list_or_raise`, `ResponseParseError`), routed
+into every service. Untrusted payloads still go through **full** Pydantic validation
+(`model_validate`) — no `model_construct` bypass.
+
+| # | Location (pre-change) | Trigger (malformed input) | Root cause | Fix | Regression test |
+|---|---|---|---|---|---|
+| 1 | All numeric models, via every service decode + `data_fetcher.fetch_json` | API returns `{"pe": NaN}` / `Infinity` / `-Infinity` | `json.loads` accepts non-finite literals by default and Pydantic `float` defaults to `allow_inf_nan=True`, so a non-finite **price/P-E/margin enters the model silently** | `decode_json` parses with `parse_constant=` a hook that **rejects** NaN/Infinity, raising `ResponseParseError` with symbol+endpoint context | `test_parsing.py::TestDecodeJson::test_nonfinite_rejected`; end-to-end `test_shareholder.py::...rejects_nan`, `test_financial.py::...rejects_nan_in_financial_amount`, `test_data_fetcher.py::...rejects_nonfinite` |
+| 2 | Every `Model(**data)` / `[Model(**x) for x in data]` across ~15 services | Any missing key / wrong type / partial record | Bare `pydantic.ValidationError` surfaced with **no symbol/endpoint**, so logs/tracebacks weren't actionable | `validate_or_raise` / `validate_list_or_raise` log `symbol (endpoint)` (+ item index for lists) and re-raise; decode failures wrapped in `ResponseParseError` carrying context | `test_parsing.py` (unit); `test_board_of_director/corporate_action/shareholder ...json_decode_error` now assert the symbol appears |
+| 3 | `tfex/trading_statistics.py:210`, `tfex/list.py:276` | Raw endpoint returns a JSON array (or `null`) instead of an object | `assert isinstance(data, dict)` is **stripped under `python -O`** and yields a context-free `AssertionError` | Explicit `if not isinstance(data, dict): raise ResponseParseError(... symbol/endpoint ...)` | `test_trading_statistics.py::...raw_rejects_non_dict_response`, `test_list.py::...raw_rejects_non_dict_response` |
+| 4 | `session_manager.py::ensure_initialized` | N concurrent fetches on a cold cache (first use) | Method was unguarded: every coroutine passed the `not _initialized` check before any finished warming up → **N duplicate warmup round-trips** (wasteful; can trip Incapsula bot detection) | Per-instance `asyncio.Lock` serializes init; double-checked so the rest reuse the warmed session. **Measured 25 → 1** | `test_session_manager.py::...concurrent_cold_start_warms_once` |
+| 5 | `session_cache.py::get_global_cache` | First cache use (cold) | `SessionCache.__init__` does blocking `mkdir` + opens the diskcache SQLite DB **directly on the event loop** | Construction offloaded via `asyncio.to_thread` | covered by session-manager init path; existing cache tests still green |
+
+Also hardened in passing: the existing list-shape guards (`Expected list response …`) were
+**kept** for defense-in-depth and backward-compatible non-list behavior; `validate_list_or_raise`
+adds the same guard centrally with per-item index context.
+
+---
+
+## 3. Performance & memory
+
+Method: throwaway `timeit`/`tracemalloc` micro-benchmarks (200k iterations, loguru at ERROR so
+`debug()` is disabled — the production default), deleted before finishing. Numbers are µs/call.
+
+| Hot path | Change | Before | After | Verdict |
+|---|---|---|---|---|
+| Cold-start warmup under concurrency | per-instance init lock | **25** round-trips (25 callers) | **1** round-trip | **Real correctness + latency + politeness win** (avoids bot-detection risk) |
+| `fetch()` request headers | hoist 11-entry literal → module constant, copy per call | 0.378 / 0.385 | **0.146** | Real ~2.6× micro-win (≈0.2µs/call; negligible vs network, zero-risk, de-duplicates) |
+| JSON decode NaN guard | `json.loads(parse_constant=…)` on finite payload | 53.7 | ~50–52 | **Free** — within run-to-run noise; the hook fires only on NaN/Inf tokens |
+| Pydantic build | `Model(**d)` → `model_validate(d)` | 2.11 | ~2.09 | Equivalent within noise (~0.3µs); no regression from the switch |
+| Decode/validate de-duplication | ~15 inline `import json` + try/except blocks → 1 helper | — | — | **−111 net LOC**; fewer per-call closures/objects, single maintained path |
+| Debug logging (`text[:500]`, `list(keys())`) | **considered `logger.opt(lazy=True)`; rejected** | eager 0.755 | lazy **1.841** | **Lazy is WORSE here** — `.opt()` overhead exceeds the bounded/cheap interpolation it would defer; kept eager (see note) |
+
+**Lazy-logging note (evidence over assumption).** The brief suggested converting eager debug
+logs to loguru lazy form. Benchmarks show that for this codebase's debug statements — all cheap,
+bounded interpolations (`text[:500]`, `list(data.keys())` over ~15–40 keys) — `logger.opt(lazy=True)`
+*adds* ~1µs/call of its own overhead and is a net regression when the level is disabled. There are
+no debug logs inside hot loops or over unbounded data. So lazy conversion was **measured and
+declined** rather than applied blindly; the logging win instead came from **removing ~15 duplicated
+decode-error log lines** into the single helper. (At request scale all of these are <2µs vs ~50µs
+JSON parse + network I/O, i.e. noise either way — reported honestly, not inflated.)
+
+---
+
+## 4. Test summary
+
+| | Before | After |
+|---|---|---|
+| Passing | 116 | 149 |
+| Runtime | 3.77 s | 2.81 s |
+| Coverage | 49.26% | 61.25% |
+
+New tests (+33): `tests/utils/test_parsing.py` (18), `tests/utils/test_session_manager.py` (3),
+`tests/services/tfex/test_trading_statistics.py` (5), `tests/services/tfex/test_list.py` (4),
+plus end-to-end NaN/decode cases in `test_data_fetcher.py`, `test_shareholder.py`,
+`test_financial.py`. Three existing JSON-decode tests were updated from the over-specific
+`json.JSONDecodeError` to the new context-rich `ResponseParseError` (now also asserting the symbol).
+
+Coverage movers: `utils/parsing.py` 100%; `tfex/list.py` 0% → ~80%;
+`tfex/trading_statistics.py` 0% → covered; `session_manager.py` 14% → 45%.
+
+**Slowest-tests delta:** unchanged in shape — the four `test_data_fetcher` retry/rate-limit tests
+(~0.30 s each) still dominate because they exercise real `retry_delay`/`rate_limit_delay`
+`asyncio.sleep`s. The new concurrency and NaN tests run in ~0.01 s; no new slow tests introduced.
+
+---
+
+## 5. Risks / deferred (intentionally not changed)
+
+- **NaN rejection is coarse.** A single non-finite field fails the whole record (with context),
+  chosen deliberately for financial correctness over silently dropping data. `parse_constant`
+  catches the realistic case (a backend serializing the `NaN`/`Infinity` literal). It does **not**
+  catch numeric *overflow* to `inf` (e.g. `1e999`, which `json` parses to `float('inf')` without a
+  constant token). **Recommendation:** add `model_config = ConfigDict(allow_inf_nan=False)` to the
+  numeric-heavy models as a belt-and-suspenders follow-up; deferred here to avoid touching every
+  model's config in this pass.
+- **Module/class-scope `asyncio.Lock`** (`session_manager._lock`, `session_cache._cache_lock`):
+  reviewed and left as-is. On Python 3.11 (the project floor) `asyncio.Lock()` binds to the running
+  loop lazily on first `await` (since 3.10), so construction at import/class scope is safe for the
+  normal single-event-loop process. Caveat: code that drives the singletons from *multiple* event
+  loops in one process could hit "bound to a different loop"; this pre-exists and the constraint to
+  not introduce new global state / respect the singleton argued against changing it now.
+- **Monetary/price fields use `float`, not `Decimal`.** This is the existing **public** Pydantic
+  contract; switching would break field types, so per the brief it is **documented, not changed**.
+  Worth a future decision if exact decimal precision becomes a requirement.
+- **No comma/locale-formatted numeric coercion was added.** An early hypothesis was that the API
+  might return `"1,234.56"` strings (which would fail `float()`); the test fixtures and observed
+  payloads use **native JSON numbers**, and adding silent comma-stripping coercion risks masking
+  malformed data. Left out by design; flagged as a watch item if such a payload is ever observed.
+
+---
+
+## 6. Public API compatibility
+
+Confirmed unchanged (smoke-tested via `inspect.signature` + attribute checks):
+
+- `fetch_*()` (models), `fetch_*_raw()` (dicts), and `get_*()` convenience functions keep identical
+  signatures and return types (`symbol`, `lang="en"`, `config=None`); the unified
+  `Stock` class and all its accessor methods are present; `en`/`th` + symbol normalization
+  (`Stock("cpall").symbol == "CPALL"`) is intact.
+- Pydantic model class names, field names, and field types are untouched.
+- The new `settfex/utils/parsing.py` is **internal** (not exported from `settfex.utils.__all__`).
+- Exception types: the documented `Raises: ValueError` contract is preserved —
+  `ResponseParseError` subclasses `ValueError`, and original exceptions are chained (`from e`) or
+  re-raised unchanged (`ValidationError`), so existing `except ValueError`/`Exception` handlers and
+  `pytest.raises` continue to work.