Khanna, Videh Rakesh Rakesh commited on
Commit
d809f52
·
1 Parent(s): ae185d5

Fix exact-contract F&O watchlist snapshots

Browse files
README.md CHANGED
@@ -39,6 +39,47 @@ the F&O popup with the selected contract. They do not run equity AI/ML forecasts
39
  prices, or enter equity cache-warming and prediction-refresh jobs. Other stock-prediction
40
  search inputs remain equity-only.
41
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
42
  ## Provider-Independent F&O Paper Trading
43
 
44
  Stock cards and Portfolio include an **F&O** action that opens the existing trade popup
@@ -64,6 +105,7 @@ their original semantics; the legacy `shares` column stores derivative quantity
64
  | Variable | Default | Purpose |
65
  | --- | --- | --- |
66
  | `FO_PROVIDER` | `manual` | Optional registered live adapter; built-in choices are `manual` and `dhan` |
 
67
  | `FO_AUTO_REFERENCE` | `1` | Discover NSE stock/index futures and options from the public Dhan master; `0` disables discovery |
68
  | `FO_REFERENCE_CSV` | Unset | Override discovery with a server-managed, validated neutral CSV; use `/data/fo_contracts.csv` on HF Spaces |
69
  | `FO_AUTO_MONITOR` | `1` | With a live provider, check up to five derivative positions per 15-second pass; `0` disables background checks |
@@ -97,6 +139,7 @@ Live market paper entries buy at ask/sell at bid only when fresh quote data and
97
  displayed quantity exist. Automatic exits use the opposing executable side. Quotes require
98
  both recent receipt and trade timestamps. Limits, stops and targets are sampled checks, not
99
  guaranteed tick-level fills. Missing/stale data blocks automation rather than inventing prices.
 
100
 
101
  **F&O learning trades ignore all fees and taxes.** P&L is the contract price change times
102
  quantity, with the sign reversed for SHORT positions. No fee configuration is needed;
 
39
  prices, or enter equity cache-warming and prediction-refresh jobs. Other stock-prediction
40
  search inputs remain equity-only.
41
 
42
+ Without an available live F&O provider, watchlist prices try Jugaad's NSE option chain or
43
+ derivative endpoint, then direct NSE snapshots. Matching requires the exact underlying,
44
+ instrument, expiry, strike and Call/Put. Snapshot source and NSE update time are displayed;
45
+ quotes older than two minutes are labeled stale, and data older than seven days is rejected.
46
+ Yahoo and Google index/stock quotes are not valid substitutes for an NSE option premium;
47
+ no verified exact-contract endpoint from either is used. Public NSE access can be blocked
48
+ from HF Spaces/datacenter IPs; failures remain explicit, never synthetic prices. Requests
49
+ have bounded timeouts; successful and failed snapshot lookups are cached for 30 seconds.
50
+ Use public NSE data only with the necessary data-use permission.
51
+
52
+ The same lookup covers every **listed NSE index and stock option/future** in the reference
53
+ catalog, not just one Nifty strike. For example, Nifty 22800/22850/22900 CE and PE each
54
+ retain their own price and identity. Available strikes, expiries and lot sizes come from
55
+ the catalog, never assumed strike increments. Option-chain downloads are shared across
56
+ strikes and CE/PE for each underlying/expiry; futures downloads cover all expiries for
57
+ one underlying. Downloads are capped at four concurrent requests, and a slow underlying
58
+ does not lock other watchlist cards. Different symbols, index/stock types and option
59
+ expiries never share prices. BSE derivatives are not supported.
60
+
61
+ ### Hugging Face F&O Quotes
62
+
63
+ Deploy the code, including `fo_quotes.py`, to the Docker Space and restart it. Existing
64
+ dependencies are installed by the Dockerfile; no local daemon or browser cookies are
65
+ required. `FO_AUTO_REFERENCE=1` and `FO_NSE_SNAPSHOTS=1` are enabled by default. The
66
+ catalog persists in the existing SQLite database; quote caches are short-lived in-memory
67
+ data and may safely disappear on a restart.
68
+
69
+ **Jugaad and direct NSE both depend on NSE website access.** A local success is not proof
70
+ of HF connectivity, and neither is a guaranteed live feed. For dependable hosted quotes,
71
+ configure an entitled server-side feed. The existing Dhan adapter uses `FO_PROVIDER=dhan`,
72
+ `DHAN_ENABLED=1`, `DHAN_ALLOW_BROWSER_DATA=1` and the server authentication described below.
73
+ Restrict dashboard access and confirm data-use permission before enabling browser data;
74
+ these settings are never enabled automatically. No paid subscription is purchased.
75
+
76
+ After deployment, `/api/fo/status` confirms catalog/provider configuration. For each
77
+ selected contract, `/api/watchlist-pick/<contract_id>` must return a positive `pick.price`,
78
+ the exact `pick.contract.contract_id`, source and provider timestamp in `pick.quote`, and
79
+ no `pick.quote_error`. Provider capabilities describe the live adapter, not public
80
+ snapshot availability. An untraded contract or a blocked/unavailable source is reported
81
+ explicitly; an index value or another strike's premium is never substituted.
82
+
83
  ## Provider-Independent F&O Paper Trading
84
 
85
  Stock cards and Portfolio include an **F&O** action that opens the existing trade popup
 
105
  | Variable | Default | Purpose |
106
  | --- | --- | --- |
107
  | `FO_PROVIDER` | `manual` | Optional registered live adapter; built-in choices are `manual` and `dhan` |
108
+ | `FO_NSE_SNAPSHOTS` | `1` | Display-only Jugaad/NSE derivative watchlist snapshots; `0` disables both snapshot paths. Does not enable broker access, equity Jugaad quotes or automatic fills |
109
  | `FO_AUTO_REFERENCE` | `1` | Discover NSE stock/index futures and options from the public Dhan master; `0` disables discovery |
110
  | `FO_REFERENCE_CSV` | Unset | Override discovery with a server-managed, validated neutral CSV; use `/data/fo_contracts.csv` on HF Spaces |
111
  | `FO_AUTO_MONITOR` | `1` | With a live provider, check up to five derivative positions per 15-second pass; `0` disables background checks |
 
139
  displayed quantity exist. Automatic exits use the opposing executable side. Quotes require
140
  both recent receipt and trade timestamps. Limits, stops and targets are sampled checks, not
141
  guaranteed tick-level fills. Missing/stale data blocks automation rather than inventing prices.
142
+ Public watchlist snapshots are never used for executable prices, fills, stops or exits.
143
 
144
  **F&O learning trades ignore all fees and taxes.** P&L is the contract price change times
145
  quantity, with the sign reversed for SHORT positions. No fee configuration is needed;
app.py CHANGED
@@ -434,7 +434,7 @@ def _watchlist_contract_pick(item: dict, *, fetch_quote: bool = False) -> dict:
434
  pick["contract"] = contract
435
  pick["company"] = fo.contract_label(contract)
436
  if fetch_quote:
437
- pick["quote"] = service.quote(contract)
438
  pick["price"] = pick["quote"].get("price")
439
  except fo.FoUnavailable as exc:
440
  pick["quote_error"] = str(exc)
 
434
  pick["contract"] = contract
435
  pick["company"] = fo.contract_label(contract)
436
  if fetch_quote:
437
+ pick["quote"] = service.watchlist_quote(contract)
438
  pick["price"] = pick["quote"].get("price")
439
  except fo.FoUnavailable as exc:
440
  pick["quote_error"] = str(exc)
fo.py CHANGED
@@ -23,6 +23,11 @@ _REFERENCE_TTL = 86400
23
  _REFERENCE_MAX_AGE = 2 * _REFERENCE_TTL
24
 
25
 
 
 
 
 
 
26
  def number(value, name, *, allow_zero=False):
27
  try:
28
  result = Decimal(str(value))
@@ -287,6 +292,8 @@ class FoService:
287
  self._reference_retry_at = 0.0
288
  self._quotes = {}
289
  self._chains = {}
 
 
290
 
291
  def _refresh_public_reference(self):
292
  try:
@@ -428,6 +435,35 @@ class FoService:
428
  finally:
429
  self._lock.release()
430
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
431
  def chain(self, underlying, expiry):
432
  if not self.provider or not self.provider.capabilities().get("option_chain"):
433
  raise FoUnavailable("Live option chain is unavailable; manual contract selection is available")
 
23
  _REFERENCE_MAX_AGE = 2 * _REFERENCE_TTL
24
 
25
 
26
+ def fetch_contract_snapshot(contract):
27
+ from fo_quotes import fetch_contract_snapshot as fetch
28
+ return fetch(contract)
29
+
30
+
31
  def number(value, name, *, allow_zero=False):
32
  try:
33
  result = Decimal(str(value))
 
292
  self._reference_retry_at = 0.0
293
  self._quotes = {}
294
  self._chains = {}
295
+ self._snapshots = {}
296
+ self._snapshot_lock = threading.Lock()
297
 
298
  def _refresh_public_reference(self):
299
  try:
 
435
  finally:
436
  self._lock.release()
437
 
438
+ def watchlist_quote(self, contract):
439
+ try:
440
+ return self.quote(contract)
441
+ except FoUnavailable:
442
+ pass
443
+ identity = contract.get("contract_id")
444
+ with self._snapshot_lock:
445
+ cached = self._snapshots.get(identity)
446
+ if cached and time.monotonic() - cached[0] < 30:
447
+ if isinstance(cached[1], str):
448
+ raise FoUnavailable(cached[1])
449
+ quote = dict(cached[1])
450
+ if quote.get("quote_time") is not None:
451
+ quote["stale"] = time.time() - quote["quote_time"] > 120
452
+ return quote
453
+ try:
454
+ quote = fetch_contract_snapshot(contract)
455
+ except FoUnavailable as exc:
456
+ with self._snapshot_lock:
457
+ if len(self._snapshots) >= 500:
458
+ self._snapshots.clear()
459
+ self._snapshots[identity] = (time.monotonic(), str(exc))
460
+ raise
461
+ with self._snapshot_lock:
462
+ if len(self._snapshots) >= 500:
463
+ self._snapshots.clear()
464
+ self._snapshots[identity] = (time.monotonic(), quote)
465
+ return quote
466
+
467
  def chain(self, underlying, expiry):
468
  if not self.provider or not self.provider.capabilities().get("option_chain"):
469
  raise FoUnavailable("Live option chain is unavailable; manual contract selection is available")
fo_quotes.py ADDED
@@ -0,0 +1,167 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Display-only NSE contract snapshots, separate from executable broker quotes."""
2
+
3
+ from concurrent.futures import Future, TimeoutError
4
+ from datetime import datetime
5
+ import os
6
+ import threading
7
+ import time
8
+
9
+ import requests
10
+
11
+ from fo import FoUnavailable, IST, number
12
+
13
+
14
+ _BASE_URL = "https://www.nseindia.com"
15
+ _HEADERS = {"User-Agent": "Mozilla/5.0", "Accept": "application/json",
16
+ "Referer": _BASE_URL + "/option-chain"}
17
+ _payloads = {}
18
+ _payload_lock = threading.Lock()
19
+ _request_slots = threading.BoundedSemaphore(4)
20
+
21
+
22
+ class _SnapshotSession(requests.Session):
23
+ def request(self, method, url, **kwargs):
24
+ kwargs["timeout"] = (2, 3)
25
+ response = super().request(method, url, **kwargs)
26
+ response.raise_for_status()
27
+ return response
28
+
29
+
30
+ def _expiry(value):
31
+ if not isinstance(value, str):
32
+ raise ValueError("Missing contract expiry")
33
+ for pattern in ("%d-%b-%Y", "%d-%m-%Y", "%Y-%m-%d"):
34
+ try:
35
+ return datetime.strptime(value, pattern).date().isoformat()
36
+ except ValueError:
37
+ continue
38
+ raise ValueError("Invalid contract expiry")
39
+
40
+
41
+ def _snapshot_records(payload):
42
+ if not isinstance(payload, dict):
43
+ raise ValueError("Invalid derivative snapshot")
44
+ records = payload.get("records", payload)
45
+ if not isinstance(records, dict) or not isinstance(records.get("data"), list):
46
+ raise ValueError("Missing derivative contracts")
47
+ timestamp = datetime.strptime(records.get("timestamp", ""), "%d-%b-%Y %H:%M:%S").replace(tzinfo=IST).timestamp()
48
+ if not -5 <= time.time() - timestamp <= 7 * 86400:
49
+ raise ValueError("Derivative snapshot timestamp is unavailable or too old")
50
+ if not records["data"]:
51
+ raise ValueError("Missing derivative contracts")
52
+ return records, timestamp
53
+
54
+
55
+ def _parse_snapshot(payload, contract, source):
56
+ records, timestamp = _snapshot_records(payload)
57
+ now = time.time()
58
+ kind = contract["instrument_type"]
59
+ for row in records["data"]:
60
+ if not isinstance(row, dict):
61
+ continue
62
+ nested = kind == "OPTION" and ("CE" in row or "PE" in row)
63
+ raw = row.get(contract["option_type"]) if nested else row
64
+ if not isinstance(raw, dict):
65
+ continue
66
+ try:
67
+ if raw.get("underlying") != contract["underlying"] or _expiry(raw.get("expiryDate")) != contract["expiry"]:
68
+ continue
69
+ instrument = ("OPT" if kind == "OPTION" else "FUT") + ("IDX" if contract["underlying_type"] == "INDEX" else "STK")
70
+ if kind == "OPTION":
71
+ if number(raw.get("strikePrice"), "strike") != number(contract["strike"], "strike"):
72
+ continue
73
+ if raw is row and raw.get("optionType") != contract["option_type"]:
74
+ continue
75
+ if raw.get("instrumentType", instrument) != instrument:
76
+ continue
77
+ identifier = raw.get("identifier", "")
78
+ if not identifier.startswith(instrument + contract["underlying"]):
79
+ continue
80
+ if kind == "OPTION":
81
+ expiry = datetime.strptime(contract["expiry"], "%Y-%m-%d").strftime("%d-%m-%Y")
82
+ prefix = instrument + contract["underlying"] + expiry + contract["option_type"]
83
+ if not identifier.startswith(prefix) or number(identifier[len(prefix):], "strike") != number(contract["strike"], "strike"):
84
+ continue
85
+ price = float(number(raw.get("lastPrice"), "contract price"))
86
+ except (ValueError, TypeError):
87
+ continue
88
+ return {"contract_id": contract["contract_id"], "price": price, "source": source,
89
+ "upstream": "nse", "quote_time": timestamp, "observed_at": now,
90
+ "as_of": datetime.fromtimestamp(timestamp, IST).isoformat(),
91
+ "timestamp_basis": "provider_quote_update", "trade_time": None,
92
+ "is_live": False, "executable": False, "stale": now - timestamp > 120}
93
+ raise ValueError("Exact derivative contract has no traded price")
94
+
95
+
96
+ def _fetch_payload(contract, source):
97
+ expiry = datetime.strptime(contract["expiry"], "%Y-%m-%d").strftime("%d-%b-%Y")
98
+ kind = contract["instrument_type"]
99
+ with _SnapshotSession() as session:
100
+ session.headers.update(_HEADERS)
101
+ if source == "jugaad":
102
+ from jugaad_data.nse import NSELive
103
+ session.get(_BASE_URL + "/option-chain")
104
+ client = NSELive.__new__(NSELive)
105
+ client.s = session
106
+ if kind == "OPTION":
107
+ method = client.index_option_chain if contract["underlying_type"] == "INDEX" else client.equities_option_chain
108
+ payload = method(contract["underlying"], expiry=expiry)
109
+ else:
110
+ payload = client.stock_quote_fno(contract["underlying"])
111
+ else:
112
+ if kind == "OPTION":
113
+ response = session.get(_BASE_URL + "/api/option-chain-v3", params={
114
+ "type": "Indices" if contract["underlying_type"] == "INDEX" else "Equity",
115
+ "symbol": contract["underlying"], "expiry": expiry})
116
+ else:
117
+ response = session.get(_BASE_URL + "/api/NextApi/apiClient/GetQuoteApi", params={
118
+ "functionName": "getSymbolDerivativesData", "symbol": contract["underlying"]})
119
+ payload = response.json()
120
+ _snapshot_records(payload)
121
+ return payload
122
+
123
+
124
+ def _cached_payload(contract, source):
125
+ key = (source, contract["underlying_type"], contract["underlying"], contract["instrument_type"],
126
+ contract["expiry"] if contract["instrument_type"] == "OPTION" else "")
127
+ with _payload_lock:
128
+ cached = _payloads.get(key)
129
+ owner = not cached or (cached[1].done() and time.monotonic() - cached[0] >= 30)
130
+ if owner:
131
+ if len(_payloads) >= 128:
132
+ for existing in list(_payloads):
133
+ if _payloads[existing][1].done():
134
+ del _payloads[existing]
135
+ break
136
+ else:
137
+ raise FoUnavailable("Contract snapshot requests are busy; retry shortly")
138
+ future = Future()
139
+ _payloads[key] = (time.monotonic(), future)
140
+ else:
141
+ future = cached[1]
142
+ if owner:
143
+ acquired = _request_slots.acquire(timeout=5)
144
+ try:
145
+ if not acquired:
146
+ raise FoUnavailable("Contract snapshot requests are busy; retry shortly")
147
+ future.set_result(_fetch_payload(contract, source))
148
+ except (ImportError, OSError, AttributeError, LookupError, TypeError, ValueError, OverflowError):
149
+ future.set_exception(FoUnavailable("Contract snapshot source is unavailable"))
150
+ finally:
151
+ if acquired:
152
+ _request_slots.release()
153
+ try:
154
+ return future.result(timeout=20)
155
+ except TimeoutError:
156
+ raise FoUnavailable("Contract snapshot request timed out; retry shortly") from None
157
+
158
+
159
+ def fetch_contract_snapshot(contract):
160
+ if os.getenv("FO_NSE_SNAPSHOTS", "1") != "1":
161
+ raise FoUnavailable("Contract snapshots are disabled; enable FO_NSE_SNAPSHOTS or configure a live F&O provider")
162
+ for source in ("jugaad", "nse_snapshot"):
163
+ try:
164
+ return _parse_snapshot(_cached_payload(contract, source), contract, source)
165
+ except (FoUnavailable, TypeError, ValueError, OverflowError):
166
+ continue
167
+ raise FoUnavailable("Exact contract snapshot unavailable from Jugaad/NSE; retry shortly or record a manual price")
static/app.js CHANGED
@@ -2065,7 +2065,9 @@ function renderWatchlistContractCard(pick) {
2065
  const contract = pick.contract;
2066
  const quote = pick.quote;
2067
  const price = pick.price != null ? `INR ${num(pick.price)}` : 'Unavailable';
2068
- const source = quote ? `${quote.source || 'Unknown'}${quote.stale ? ' (stale)' : ''}` : '';
 
 
2069
  const actionTicker = _foEscape(JSON.stringify(pick.ticker));
2070
  return `<div class="pick-card watchlist-contract-card" id="${cardId}" data-contract-id="${ticker}">
2071
  <div class="pick-header">
@@ -2081,6 +2083,7 @@ function renderWatchlistContractCard(pick) {
2081
  <div class="pick-body"><div class="pick-signals">
2082
  <div class="pick-price">${price}</div>
2083
  <div class="pick-symbol-row">${_foEscape(source)}${contract ? ` | Lot ${contract.lot_size} | ${_foEscape(contract.expiry)}` : ''}</div>
 
2084
  ${pick.quote_error ? `<div class="error-card">${_foEscape(pick.quote_error)}</div>` : ''}
2085
  </div></div>
2086
  </div>`;
 
2065
  const contract = pick.contract;
2066
  const quote = pick.quote;
2067
  const price = pick.price != null ? `INR ${num(pick.price)}` : 'Unavailable';
2068
+ const provider = { jugaad: 'Jugaad / NSE', nse_snapshot: 'NSE' }[quote?.source] || quote?.source || 'Unknown';
2069
+ const source = quote ? `${provider}${quote.is_live === false ? ' snapshot' : ''}${quote.stale ? ' (stale)' : ''}` : '';
2070
+ const asOf = quote?.as_of ? new Date(quote.as_of).toLocaleString('en-IN', { timeZone: 'Asia/Kolkata', hour12: false }) : '';
2071
  const actionTicker = _foEscape(JSON.stringify(pick.ticker));
2072
  return `<div class="pick-card watchlist-contract-card" id="${cardId}" data-contract-id="${ticker}">
2073
  <div class="pick-header">
 
2083
  <div class="pick-body"><div class="pick-signals">
2084
  <div class="pick-price">${price}</div>
2085
  <div class="pick-symbol-row">${_foEscape(source)}${contract ? ` | Lot ${contract.lot_size} | ${_foEscape(contract.expiry)}` : ''}</div>
2086
+ ${asOf ? `<div class="pick-symbol-row">As of ${_foEscape(asOf)} IST</div>` : ''}
2087
  ${pick.quote_error ? `<div class="error-card">${_foEscape(pick.quote_error)}</div>` : ''}
2088
  </div></div>
2089
  </div>`;
templates/index.html CHANGED
@@ -541,6 +541,6 @@
541
  </a>
542
  </nav>
543
 
544
- <script src="/static/app.js?v=20261015watch3"></script>
545
  </body>
546
  </html>
 
541
  </a>
542
  </nav>
543
 
544
+ <script src="/static/app.js?v=20261016foquotes"></script>
545
  </body>
546
  </html>
tests/test_api_contract.py CHANGED
@@ -557,7 +557,7 @@ class ApiContractTests(unittest.TestCase):
557
  ticker = contract["contract_id"]
558
  watchlist.return_value = [{"ticker": ticker, "name": "Reliance call"}]
559
  service.return_value.resolve.return_value = contract
560
- service.return_value.quote.return_value = {"price": 100, "source": "fake", "stale": False}
561
  response = self.client.get("/api/watchlist-pick/" + ticker)
562
  self.assertEqual(response.status_code, 200, response.get_json())
563
  pick = response.get_json()["pick"]
@@ -579,15 +579,46 @@ class ApiContractTests(unittest.TestCase):
579
  ticker = contract["contract_id"]
580
  watchlist.return_value = [{"ticker": ticker, "name": "Reliance call"}]
581
  service.return_value.resolve.return_value = contract
582
- service.return_value.quote.side_effect = _app_module.fo.FoUnavailable("Manual prices only")
583
  pick = self.client.get("/api/watchlist-pick/" + ticker).get_json()["pick"]
584
  self.assertIsNone(pick["price"])
585
  self.assertEqual(pick["quote_error"], "Manual prices only")
586
- service.return_value.quote.side_effect = None
587
- service.return_value.quote.return_value = {"price": 100, "source": "fake", "stale": True}
588
  pick = self.client.get("/api/watchlist-pick/" + ticker).get_json()["pick"]
589
  self.assertTrue(pick["quote"]["stale"])
590
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
591
  def test_watchlist_database_preserves_instrument_identifiers(self):
592
  with tempfile.TemporaryDirectory() as directory, patch.object(db, "DB_PATH", os.path.join(directory, "book.db")):
593
  db.init_db()
 
557
  ticker = contract["contract_id"]
558
  watchlist.return_value = [{"ticker": ticker, "name": "Reliance call"}]
559
  service.return_value.resolve.return_value = contract
560
+ service.return_value.watchlist_quote.return_value = {"price": 100, "source": "fake", "stale": False}
561
  response = self.client.get("/api/watchlist-pick/" + ticker)
562
  self.assertEqual(response.status_code, 200, response.get_json())
563
  pick = response.get_json()["pick"]
 
579
  ticker = contract["contract_id"]
580
  watchlist.return_value = [{"ticker": ticker, "name": "Reliance call"}]
581
  service.return_value.resolve.return_value = contract
582
+ service.return_value.watchlist_quote.side_effect = _app_module.fo.FoUnavailable("Manual prices only")
583
  pick = self.client.get("/api/watchlist-pick/" + ticker).get_json()["pick"]
584
  self.assertIsNone(pick["price"])
585
  self.assertEqual(pick["quote_error"], "Manual prices only")
586
+ service.return_value.watchlist_quote.side_effect = None
587
+ service.return_value.watchlist_quote.return_value = {"price": 100, "source": "fake", "stale": True}
588
  pick = self.client.get("/api/watchlist-pick/" + ticker).get_json()["pick"]
589
  self.assertTrue(pick["quote"]["stale"])
590
 
591
+ @patch("app.db.get_watchlist")
592
+ @patch("fo.fetch_contract_snapshot")
593
+ @patch("fo.get_service")
594
+ def test_manual_only_watchlist_displays_exact_derivative_snapshots(self, service, snapshot, watchlist):
595
+ manual = _app_module.fo.FoService()
596
+ manual.resolve = Mock()
597
+ service.return_value = manual
598
+ cases = [("NIFTY", "INDEX", "OPTION", strike, "PE") for strike in (22800, 22850, 22900)]
599
+ cases += [("BANKNIFTY", "INDEX", "OPTION", 55000, "CE"),
600
+ ("RELIANCE", "STOCK", "OPTION", 1200, "PE"),
601
+ ("SBIN", "STOCK", "OPTION", 950, "CE"),
602
+ ("NIFTY", "INDEX", "FUTURE", None, None),
603
+ ("RELIANCE", "STOCK", "FUTURE", None, None)]
604
+ for index, (symbol, underlying_type, kind, strike, side) in enumerate(cases):
605
+ reference = _app_module.fo.validate_contract({**self._watchlist_reference(),
606
+ "underlying": symbol, "underlying_type": underlying_type, "expiry": "2099-10-19",
607
+ "strike": strike, "option_type": side}, kind)
608
+ manual.resolve.return_value = reference
609
+ snapshot.return_value = {"price": 100 + index, "source": "nse_snapshot", "is_live": False,
610
+ "executable": False, "stale": False}
611
+ watchlist.return_value = [{"ticker": reference["contract_id"], "name": "Contract"}]
612
+ with self.subTest(contract_id=reference["contract_id"]):
613
+ response = self.client.get("/api/watchlist-pick/" + reference["contract_id"])
614
+ self.assertEqual(response.status_code, 200)
615
+ pick = response.get_json()["pick"]
616
+ self.assertEqual(pick["price"], 100 + index)
617
+ self.assertEqual(pick["contract"]["contract_id"], reference["contract_id"])
618
+ self.assertEqual(pick["quote"]["source"], "nse_snapshot")
619
+ self.assertIsNone(pick["quote_error"])
620
+ self.assertFalse(pick["quote"]["executable"])
621
+
622
  def test_watchlist_database_preserves_instrument_identifiers(self):
623
  with tempfile.TemporaryDirectory() as directory, patch.object(db, "DB_PATH", os.path.join(directory, "book.db")):
624
  db.init_db()
tests/test_fo.py CHANGED
@@ -1,9 +1,19 @@
1
  import json
 
2
  from datetime import date, datetime
 
3
  from unittest.mock import Mock, patch, mock_open
4
 
5
  import pytest
6
  import fo
 
 
 
 
 
 
 
 
7
 
8
 
9
  def contract(**updates):
@@ -70,6 +80,260 @@ def test_manual_service_remains_available_without_any_provider():
70
  service.quote(contract())
71
 
72
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
73
  def test_reference_csv_is_provider_independent_and_filters_bad_rows():
74
  text = "underlying,underlying_type,instrument_type,expiry,strike,option_type,lot_size,tick_size\n"
75
  text += "NIFTY,INDEX,OPTION,2099-10-29,25000,CE,25,0.05\n"
 
1
  import json
2
+ from concurrent.futures import ThreadPoolExecutor
3
  from datetime import date, datetime
4
+ from threading import Event
5
  from unittest.mock import Mock, patch, mock_open
6
 
7
  import pytest
8
  import fo
9
+ import fo_quotes
10
+
11
+
12
+ @pytest.fixture(autouse=True)
13
+ def isolate_snapshot_downloads():
14
+ fo_quotes._payloads.clear()
15
+ yield
16
+ fo_quotes._payloads.clear()
17
 
18
 
19
  def contract(**updates):
 
80
  service.quote(contract())
81
 
82
 
83
+ def test_watchlist_quote_uses_contract_snapshot_without_enabling_execution():
84
+ service = fo.FoService()
85
+ reference = fo.validate_contract(contract(strike=22900, expiry="2099-10-19"), "OPTION")
86
+ snapshot = {"price": 123.5, "source": "nse_snapshot", "is_live": False}
87
+ with patch("fo.fetch_contract_snapshot", return_value=snapshot, create=True) as fetch:
88
+ assert service.watchlist_quote(reference) == snapshot
89
+ fetch.assert_called_once_with(reference)
90
+ with pytest.raises(fo.FoUnavailable):
91
+ service.quote(reference)
92
+
93
+
94
+ def test_watchlist_quote_prefers_configured_live_provider():
95
+ service = fo.FoService()
96
+ quote = {"price": 123.5, "source": "dhan", "is_live": True}
97
+ with patch.object(service, "quote", return_value=quote), patch("fo.fetch_contract_snapshot", create=True) as fetch:
98
+ assert service.watchlist_quote(contract()) == quote
99
+ fetch.assert_not_called()
100
+
101
+
102
+ def test_watchlist_snapshots_do_not_block_other_contracts():
103
+ service = fo.FoService()
104
+ first = fo.validate_contract(contract(strike=22800), "OPTION")
105
+ second = fo.validate_contract(contract(strike=22850), "OPTION")
106
+ started, release = Event(), Event()
107
+
108
+ def fetch(reference):
109
+ if reference["contract_id"] == first["contract_id"]:
110
+ started.set()
111
+ assert release.wait(2)
112
+ return {"contract_id": reference["contract_id"], "price": reference["strike"] / 100}
113
+
114
+ with patch("fo.fetch_contract_snapshot", side_effect=fetch), ThreadPoolExecutor(max_workers=2) as workers:
115
+ pending = workers.submit(service.watchlist_quote, first)
116
+ try:
117
+ assert started.wait(2)
118
+ assert service.watchlist_quote(second)["contract_id"] == second["contract_id"]
119
+ finally:
120
+ release.set()
121
+ assert pending.result(timeout=2)["contract_id"] == first["contract_id"]
122
+
123
+
124
+ @pytest.fixture
125
+ def option_snapshot():
126
+ return {"records": {"timestamp": "16-Oct-2026 09:30:00", "data": [{"PE": {
127
+ "underlying": "NIFTY", "expiryDate": "29-10-2099", "strikePrice": 25000,
128
+ "identifier": "OPTIDXNIFTY29-10-2099PE25000.00", "lastPrice": 108.2,
129
+ }}]}}
130
+
131
+
132
+ def test_contract_snapshot_is_timestamped_display_only(option_snapshot):
133
+ reference = fo.validate_contract(contract(), "OPTION")
134
+ now = datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()
135
+ with patch("fo_quotes.time.time", return_value=now):
136
+ result = fo_quotes._parse_snapshot(option_snapshot, reference, "nse_snapshot")
137
+ assert result["price"] == 108.2
138
+ assert result["contract_id"] == reference["contract_id"]
139
+ assert result["source"] == "nse_snapshot"
140
+ assert result["quote_time"] == now - 60
141
+ assert result["as_of"] == "2026-10-16T09:30:00+05:30"
142
+ assert not result["is_live"] and not result["executable"] and not result["stale"]
143
+ assert result["trade_time"] is None
144
+
145
+
146
+ @pytest.mark.parametrize("underlying,underlying_type", [
147
+ ("NIFTY", "INDEX"), ("BANKNIFTY", "INDEX"), ("FINNIFTY", "INDEX"),
148
+ ("MIDCPNIFTY", "INDEX"), ("NIFTYNXT50", "INDEX"),
149
+ ("RELIANCE", "STOCK"), ("SBIN", "STOCK"),
150
+ ])
151
+ @pytest.mark.parametrize("kind,side", [("OPTION", "CE"), ("OPTION", "PE"), ("FUTURE", "")])
152
+ @pytest.mark.parametrize("strike", [22800, 22850, 22900])
153
+ def test_snapshots_match_each_index_stock_strike_and_instrument(underlying, underlying_type, kind, side, strike):
154
+ reference = fo.validate_contract(contract(underlying=underlying, underlying_type=underlying_type,
155
+ strike=strike, option_type=side), kind)
156
+ instrument = ("OPT" if kind == "OPTION" else "FUT") + ("IDX" if underlying_type == "INDEX" else "STK")
157
+ suffix = f"{side}{strike}.00" if kind == "OPTION" else "XX0.00"
158
+ row = {"underlying": underlying, "expiryDate": "29-Oct-2099", "strikePrice": strike,
159
+ "optionType": side, "instrumentType": instrument,
160
+ "identifier": f"{instrument}{underlying}29-10-2099{suffix}", "lastPrice": 108.2}
161
+ data = {"timestamp": "16-Oct-2026 09:30:00", "data": [row]}
162
+ with patch("fo_quotes.time.time", return_value=datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()):
163
+ quote = fo_quotes._parse_snapshot(data, reference, "nse_snapshot")
164
+ assert quote["contract_id"] == reference["contract_id"]
165
+ assert quote["price"] == 108.2
166
+ assert not quote["is_live"] and not quote["executable"]
167
+
168
+
169
+ def test_snapshot_download_is_shared_across_strikes_and_option_sides(option_snapshot, monkeypatch):
170
+ monkeypatch.setenv("FO_NSE_SNAPSHOTS", "1")
171
+ rows = option_snapshot["records"]["data"]
172
+ rows.clear()
173
+ for strike, side, price in [(22800, "PE", 80), (22850, "PE", 90), (22900, "CE", 120)]:
174
+ rows.append({side: {"underlying": "NIFTY", "expiryDate": "29-10-2099", "strikePrice": strike,
175
+ "identifier": f"OPTIDXNIFTY29-10-2099{side}{strike}.00", "lastPrice": price}})
176
+ with patch("fo_quotes._SnapshotSession"), patch("jugaad_data.nse.NSELive.index_option_chain", return_value=option_snapshot) as fetch:
177
+ with patch("fo_quotes.time.time", return_value=datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()):
178
+ for strike, side, price in [(22800, "PE", 80), (22850, "PE", 90), (22900, "CE", 120)]:
179
+ reference = fo.validate_contract(contract(strike=strike, option_type=side), "OPTION")
180
+ assert fo_quotes.fetch_contract_snapshot(reference)["price"] == price
181
+ fetch.assert_called_once()
182
+
183
+
184
+ @pytest.mark.parametrize("updates,source", [
185
+ ({"underlying": "BANKNIFTY"}, "jugaad"),
186
+ ({"underlying": "RELIANCE", "underlying_type": "STOCK"}, "jugaad"),
187
+ ({"expiry": "2099-11-26"}, "jugaad"),
188
+ ({"instrument_type": "FUTURE"}, "jugaad"),
189
+ ({}, "nse_snapshot"),
190
+ ])
191
+ def test_snapshot_download_cache_separates_feeds(updates, source):
192
+ reference = fo.validate_contract(contract(), "OPTION")
193
+ other = {**reference, **updates}
194
+ with patch("fo_quotes._fetch_payload", side_effect=[{"feed": 1}, {"feed": 2}]) as fetch:
195
+ assert fo_quotes._cached_payload(reference, "jugaad") == {"feed": 1}
196
+ assert fo_quotes._cached_payload(other, source) == {"feed": 2}
197
+ assert fo_quotes._cached_payload(reference, "jugaad") == {"feed": 1}
198
+ assert fetch.call_count == 2
199
+
200
+
201
+ def test_snapshot_download_reuses_pending_work():
202
+ reference = fo.validate_contract(contract(), "OPTION")
203
+ started, release, second_started = Event(), Event(), Event()
204
+
205
+ def fetch(*args):
206
+ started.set()
207
+ assert release.wait(2)
208
+ return {"data": []}
209
+
210
+ def second():
211
+ second_started.set()
212
+ return fo_quotes._cached_payload(reference, "jugaad")
213
+
214
+ with patch("fo_quotes._fetch_payload", side_effect=fetch) as download, ThreadPoolExecutor(max_workers=2) as workers:
215
+ first = workers.submit(fo_quotes._cached_payload, reference, "jugaad")
216
+ try:
217
+ assert started.wait(2)
218
+ pending = workers.submit(second)
219
+ assert second_started.wait(2)
220
+ finally:
221
+ release.set()
222
+ assert first.result(timeout=2) == pending.result(timeout=2) == {"data": []}
223
+ download.assert_called_once()
224
+
225
+
226
+ def test_snapshot_download_caches_failures_and_retries_after_ttl():
227
+ reference = fo.validate_contract(contract(), "OPTION")
228
+ with patch("fo_quotes.time.monotonic", return_value=1) as clock, patch("fo_quotes._fetch_payload", side_effect=fo_quotes.requests.Timeout()) as download:
229
+ for attempt in range(2):
230
+ with pytest.raises(fo.FoUnavailable):
231
+ fo_quotes._cached_payload(reference, "jugaad")
232
+ download.assert_called_once()
233
+ clock.return_value = 32
234
+ download.side_effect = None
235
+ download.return_value = {"retry": True}
236
+ assert fo_quotes._cached_payload(reference, "jugaad") == {"retry": True}
237
+ assert download.call_count == 2
238
+
239
+
240
+ def test_snapshot_download_limits_workers_without_leaving_pending_work():
241
+ reference = fo.validate_contract(contract(), "OPTION")
242
+ with patch("fo_quotes._request_slots") as slots, patch("fo_quotes._fetch_payload") as download:
243
+ slots.acquire.return_value = False
244
+ for attempt in range(2):
245
+ with pytest.raises(fo.FoUnavailable):
246
+ fo_quotes._cached_payload(reference, "jugaad")
247
+ slots.acquire.assert_called_once_with(timeout=5)
248
+ slots.release.assert_not_called()
249
+ download.assert_not_called()
250
+ assert next(iter(fo_quotes._payloads.values()))[1].done()
251
+
252
+
253
+ @pytest.mark.parametrize("updates", [
254
+ {"underlying": "BANKNIFTY"}, {"expiryDate": "28-10-2099"}, {"expiryDate": None},
255
+ {"strikePrice": 24900}, {"identifier": "OPTIDXNIFTY29-10-2099CE25000.00"},
256
+ {"identifier": "OPTSTKNIFTY29-10-2099PE25000.00"}, {"lastPrice": 0},
257
+ {"lastPrice": True}, {"lastPrice": "nan"}, {"instrumentType": "FUTIDX"},
258
+ ])
259
+ def test_contract_snapshot_rejects_wrong_contract_and_invalid_prices(option_snapshot, updates):
260
+ option_snapshot["records"]["data"][0]["PE"].update(updates)
261
+ with patch("fo_quotes.time.time", return_value=datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()):
262
+ with pytest.raises(ValueError):
263
+ fo_quotes._parse_snapshot(option_snapshot, fo.validate_contract(contract(), "OPTION"), "nse_snapshot")
264
+
265
+
266
+ @pytest.mark.parametrize("payload", [None, {}, {"records": []}, {"records": {"data": [], "timestamp": "invalid"}},
267
+ {"records": {"data": [], "timestamp": "01-Oct-2026 09:30:00"}},
268
+ {"records": {"data": [], "timestamp": "17-Oct-2026 09:30:00"}}])
269
+ def test_contract_snapshot_rejects_malformed_and_unbounded_timestamps(payload):
270
+ with patch("fo_quotes.time.time", return_value=datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()):
271
+ with pytest.raises((ValueError, TypeError)):
272
+ fo_quotes._parse_snapshot(payload, fo.validate_contract(contract(), "OPTION"), "nse_snapshot")
273
+
274
+
275
+ def test_contract_snapshot_preserves_stale_last_session_quote(option_snapshot):
276
+ with patch("fo_quotes.time.time", return_value=datetime(2026, 10, 16, 16, 0, tzinfo=fo.IST).timestamp()):
277
+ quote = fo_quotes._parse_snapshot(option_snapshot, fo.validate_contract(contract(), "OPTION"), "nse_snapshot")
278
+ assert quote["price"] == 108.2 and quote["stale"]
279
+
280
+
281
+ @pytest.mark.parametrize("underlying_type,kind,method", [
282
+ ("INDEX", "OPTION", "index_option_chain"), ("STOCK", "OPTION", "equities_option_chain"),
283
+ ("INDEX", "FUTURE", "stock_quote_fno"), ("STOCK", "FUTURE", "stock_quote_fno"),
284
+ ])
285
+ def test_snapshot_tries_jugaad_then_direct_nse(option_snapshot, underlying_type, kind, method, monkeypatch):
286
+ monkeypatch.setenv("FO_NSE_SNAPSHOTS", "1")
287
+ reference = fo.validate_contract(contract(underlying_type=underlying_type), kind)
288
+ if kind == "FUTURE":
289
+ raw = option_snapshot["records"]["data"][0]["PE"]
290
+ option_snapshot = {"timestamp": "16-Oct-2026 09:30:00", "data": [{**raw,
291
+ "instrumentType": "FUTIDX" if underlying_type == "INDEX" else "FUTSTK",
292
+ "identifier": ("FUTIDX" if underlying_type == "INDEX" else "FUTSTK") + "NIFTY29-10-2099"}]}
293
+ elif underlying_type == "STOCK":
294
+ option_snapshot["records"]["data"][0]["PE"]["identifier"] = "OPTSTKNIFTY29-10-2099PE25000.00"
295
+ with patch("fo_quotes._SnapshotSession") as sessions, patch("jugaad_data.nse.NSELive." + method) as jugaad:
296
+ sessions.return_value.__enter__.return_value.get.return_value.json.return_value = option_snapshot
297
+ now = datetime(2026, 10, 16, 9, 31, tzinfo=fo.IST).timestamp()
298
+ with patch("fo_quotes.time.time", return_value=now):
299
+ jugaad.return_value = option_snapshot
300
+ assert fo_quotes.fetch_contract_snapshot(reference)["source"] == "jugaad"
301
+ fo_quotes._payloads.clear()
302
+ jugaad.side_effect = fo_quotes.requests.Timeout()
303
+ assert fo_quotes.fetch_contract_snapshot(reference)["source"] == "nse_snapshot"
304
+ fo_quotes._payloads.clear()
305
+ sessions.return_value.__enter__.return_value.get.return_value.json.return_value = {}
306
+ with pytest.raises(fo.FoUnavailable, match="Exact contract"):
307
+ fo_quotes.fetch_contract_snapshot(reference)
308
+
309
+
310
+ def test_snapshot_opt_out_and_http_timeout(monkeypatch):
311
+ monkeypatch.setenv("FO_NSE_SNAPSHOTS", "0")
312
+ with patch("fo_quotes._SnapshotSession") as sessions:
313
+ with pytest.raises(fo.FoUnavailable, match="disabled"):
314
+ fo_quotes.fetch_contract_snapshot(fo.validate_contract(contract(), "OPTION"))
315
+ sessions.assert_not_called()
316
+ with patch("requests.Session.request") as request:
317
+ with fo_quotes._SnapshotSession() as session:
318
+ session.get("https://www.nseindia.com/api/option-chain-v3", timeout=999)
319
+ assert request.call_args.kwargs["timeout"] == (2, 3)
320
+ request.return_value.raise_for_status.assert_called_once()
321
+
322
+
323
+ def test_watchlist_snapshot_cache_throttles_failures_and_rechecks_staleness():
324
+ service = fo.FoService()
325
+ reference = fo.validate_contract(contract(), "OPTION")
326
+ with patch("fo.fetch_contract_snapshot", return_value={"price": 100, "quote_time": 1000}), patch("fo.time.monotonic", return_value=1), patch("fo.time.time", return_value=1200):
327
+ service.watchlist_quote(reference)
328
+ assert service.watchlist_quote(reference)["stale"]
329
+ service._snapshots.clear()
330
+ with patch("fo.fetch_contract_snapshot", side_effect=fo.FoUnavailable("Unavailable")) as fetch:
331
+ for attempt in range(2):
332
+ with pytest.raises(fo.FoUnavailable):
333
+ service.watchlist_quote(reference)
334
+ assert fetch.call_count == 1
335
+
336
+
337
  def test_reference_csv_is_provider_independent_and_filters_bad_rows():
338
  text = "underlying,underlying_type,instrument_type,expiry,strike,option_type,lot_size,tick_size\n"
339
  text += "NIFTY,INDEX,OPTION,2099-10-29,25000,CE,25,0.05\n"
tests/test_watchlist_frontend.cjs CHANGED
@@ -437,6 +437,14 @@ test('derivative watchlist cards show contract quotes without equity controls',
437
  pick.price = null;
438
  pick.quote_error = 'Manual prices only';
439
  assert.match(context.renderWatchlistContractCard(pick), /Manual prices only/);
 
 
 
 
 
 
 
 
440
  });
441
 
442
  test('clearing search invalidates an already pending response', async () => {
 
437
  pick.price = null;
438
  pick.quote_error = 'Manual prices only';
439
  assert.match(context.renderWatchlistContractCard(pick), /Manual prices only/);
440
+ pick.price = 108.2;
441
+ pick.quote_error = null;
442
+ pick.quote = { source: 'nse_snapshot', is_live: false, stale: true, as_of: '2026-10-16T09:30:00+05:30' };
443
+ const snapshotCard = context.renderWatchlistContractCard(pick);
444
+ assert.match(snapshotCard, /108.20/);
445
+ assert.match(snapshotCard, /NSE snapshot \(stale\)/);
446
+ assert.match(snapshotCard, /As of .*16.*10.*2026.*09:30:00 IST/);
447
+ assert.doesNotMatch(snapshotCard, /error-card/);
448
  });
449
 
450
  test('clearing search invalidates an already pending response', async () => {