sahiapi 0.1.0__py3-none-any.whl

sahiapi/sahi/instruments.py

@@ -0,0 +1,315 @@
+"""Scrip master: the daily instrument file and lookups over it.
+
+The scrip master is a CSV of every tradable and quotable instrument, rebuilt once
+per trading day around 06:00 IST. Its ``id`` column is the ``instrument_id`` every
+market-data call takes, and its ``symbol`` and ``segment`` columns are what the
+order endpoints take: ``segment`` is the ``exchange_segment`` of an order, while
+``exchange`` is the listing exchange and is *not* that field — every NSE option
+carries ``exchange=NSE`` and ``segment=NFO``. Download the file once at start of
+day and look instruments up locally.
+
+The file is parsed by its header row rather than a fixed column list, so the SDK
+tracks whatever columns the file carries. Each row is returned as a ``dict`` of
+strings, except a small set of always-integer columns (``id``, ``lot_size``,
+``freeze_quantity``, ``token``, ``price_precision``) which are cast to ``int``
+when present. Money, tick sizes and ``price_multiplier`` are left as the strings
+the file holds — some are rupees, some paise, and a commodity multiplier is
+fractional — so the SDK never guesses a unit; see the API reference's Scrip master
+page for which column is which.
+
+One parsed copy is shared by every client in the process, keyed by URL: the file
+is around 10 MB and costs well over a hundred megabytes once parsed, and it is
+the same file for every account.
+
+The download URL is not part of the public API reference; it is provided when
+your API access is set up. Pass it as ``scrip_master_url`` to :class:`SahiAPI`, or
+set ``SAHI_SCRIP_MASTER_URL``. Until one is given, these methods raise
+:class:`SahiConfigurationException`.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import threading
+import time
+from dataclasses import dataclass, field
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+from .base import EndpointGroup
+from .exceptions import (
+    SahiAPIException,
+    SahiConfigurationException,
+    SahiConnectionException,
+    SahiTimeoutException,
+)
+
+__all__ = ["_Instruments"]
+
+# Columns that are always integers where present. Everything else stays a string,
+# because the file mixes rupee and paise money columns and the SDK never guesses.
+# price_multiplier is deliberately not here: it is integral for most rows but
+# fractional on MCX commodities (0.125 on an 8-gram GOLDGUINEA contract), and a
+# column that is an int for most rows and a str for the rest is worse than either.
+_INT_COLUMNS = ("id", "lot_size", "freeze_quantity", "token", "price_precision")
+
+# Seconds in the 06:00 IST offset: IST is UTC+5:30, and the file rebuilds at
+# 06:00 IST, so the trading day rolls at 00:30 UTC.
+_IST_OFFSET_SECONDS = 5 * 3600 + 30 * 60
+_DAY_ROLL_SECONDS = 6 * 3600  # 06:00
+
+# The rebuild lands a little after 06:00 IST, and by a margin that moves from day
+# to day, so a copy whose Last-Modified predates today's roll is yesterday's file
+# and is re-checked rather than trusted. The check is conditional (a 304 is a few
+# hundred bytes), and this is how often it may run in that window.
+_RECHECK_INTERVAL_SECONDS = 60.0
+
+
+@dataclass
+class _Master:
+    """One parsed scrip master, shared by every client using the same URL."""
+
+    rows: list[dict[str, Any]]
+    by_id: dict[int, dict[str, Any]] = field(default_factory=dict)
+    by_symbol: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+    by_isin: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+    #: ``Last-Modified`` as epoch seconds, and verbatim for a conditional request.
+    last_modified: float | None = None
+    last_modified_raw: str | None = None
+    etag: str | None = None
+    #: When this copy was last known to be the server's current one.
+    checked_at: float = 0.0
+    #: Trading day of that check, for a server that sends no validators at all.
+    day: int = 0
+
+
+# One parsed file per URL for the whole process. The lock is held across the
+# download so that N clients starting together fetch once rather than N times.
+_CACHE: dict[str, _Master] = {}
+_CACHE_LOCK = threading.Lock()
+
+
+class _Instruments(EndpointGroup):
+    """Scrip-master download and lookup methods mixed into :class:`SahiAPI`.
+
+    ``SahiAPI`` provides ``_scrip_master_url`` (from its constructor or the
+    environment); the parsed file itself lives in this module, shared by URL.
+    """
+
+    # Provided/managed by SahiAPI; declared here so the mixin is self-describing.
+    _scrip_master_url: str | None
+
+    def get_instruments(
+        self, *, refresh: bool = False, timeout: float | None = None
+    ) -> list[dict[str, Any]]:
+        """Return every instrument in today's scrip master.
+
+        Downloads and parses the file on first use, then serves it from memory —
+        one copy per URL, shared by every client in the process. Freshness follows
+        the file rather than the clock: a copy built at or after today's 06:00 IST
+        rebuild serves the rest of the day, and a copy older than that is
+        re-checked (conditionally, at most once a minute) until the new file
+        appears. A re-check that cannot reach the server leaves the copy in place
+        and is retried after the interval, so a blip does not cost a file already
+        loaded — and a host that stays down leaves the last copy serving, rather
+        than failing lookups. ``refresh=True`` downloads again regardless, and
+        raises if it cannot.
+
+        Args:
+            refresh: Force a re-download even if a cached copy is current.
+            timeout: Download timeout in seconds (default 30).
+
+        Returns:
+            One ``dict`` per row, keyed by the file's header. Values are strings
+            except the always-integer columns. The list is a fresh copy each call,
+            but the row dicts are shared with the lookup indexes, with the cache
+            and with every other client on this URL, so treat them as read-only —
+            mutating a row changes what later lookups return.
+
+        Raises:
+            SahiConfigurationException: If no scrip-master URL is configured.
+            SahiConnectionException: If the download could not be started.
+            SahiTimeoutException: If the download times out.
+            SahiAPIException: If the download fails (``status`` set for a non-2xx).
+        """
+        return list(self._master(refresh=refresh, timeout=timeout).rows)
+
+    def get_instrument_by_id(
+        self, instrument_id: int, *, timeout: float | None = None
+    ) -> dict[str, Any] | None:
+        """Return the instrument with this ``id``, or ``None`` if there is none."""
+        return self._master(refresh=False, timeout=timeout).by_id.get(instrument_id)
+
+    def get_instruments_by_symbol(
+        self, symbol: str, exchange_segment: str | None = None, *, timeout: float | None = None
+    ) -> list[dict[str, Any]]:
+        """Return instruments with this ``symbol``.
+
+        A symbol can appear in more than one segment — an ETF listed on both
+        exchanges, say — so this returns a list.
+
+        Args:
+            symbol: The file's ``symbol`` column, which is also the ``symbol`` an
+                order takes.
+            exchange_segment: Narrow to one segment, matched against the file's
+                ``segment`` column: the same ``NSE`` / ``NFO`` / ``BSE`` / ``BFO``
+                value an order takes. A symbol is unique within a segment, so this
+                selects at most one row. Note this is *not* the ``exchange``
+                column, which holds the listing exchange (``NSE`` for an NFO
+                option).
+            timeout: Download timeout for the first load.
+        """
+        master = self._master(refresh=False, timeout=timeout)
+        matches = master.by_symbol.get(symbol, [])
+        if exchange_segment is None:
+            return list(matches)
+        return [row for row in matches if row.get("segment") == exchange_segment]
+
+    def get_instruments_by_isin(
+        self, isin: str, *, timeout: float | None = None
+    ) -> list[dict[str, Any]]:
+        """Return instruments with this ``isin`` (a stock can list on both exchanges)."""
+        return list(self._master(refresh=False, timeout=timeout).by_isin.get(isin, []))
+
+    # -- internals ------------------------------------------------------------
+
+    def _master(self, *, refresh: bool, timeout: float | None) -> _Master:
+        url = self._scrip_master_url
+        if not url:
+            raise SahiConfigurationException(
+                "no scrip-master URL is configured. Pass scrip_master_url=... to "
+                "SahiAPI() or set SAHI_SCRIP_MASTER_URL. The URL is provided when "
+                "your API access is set up."
+            )
+        with _CACHE_LOCK:
+            cached = _CACHE.get(url)
+            if not refresh and cached is not None and _is_current(cached):
+                return cached
+            try:
+                # On a refresh the cached copy is not offered for validation: the
+                # caller asked for the file, not confirmation that it is the same.
+                master = _download(url, timeout, cached=None if refresh else cached)
+            except SahiAPIException:
+                # A revalidation that could not reach the server is no reason to
+                # lose a file already in hand: keep serving it and try again after
+                # the interval. A first load has nothing to serve, and a refresh
+                # was asked for explicitly, so both still raise.
+                if refresh or cached is None:
+                    raise
+                cached.checked_at = time.time()
+                return cached
+            _CACHE[url] = master
+            return master
+
+
+def _is_current(master: _Master) -> bool:
+    """Whether this copy can be served without asking the server again."""
+    if master.last_modified is not None and master.last_modified >= _day_roll_epoch():
+        return True  # built at or after today's rebuild; immutable for the day
+    if master.last_modified is None and master.etag is None:
+        # No validators at all: nothing to re-check against, so fall back to the
+        # trading-day key.
+        if master.day == _trading_day():
+            return True
+    # Older than today's rebuild, or carrying only an ETag: re-check, but no more
+    # often than this. The same interval paces the retry after a failed check.
+    return (time.time() - master.checked_at) < _RECHECK_INTERVAL_SECONDS
+
+
+def _download(url: str, timeout: float | None, cached: _Master | None) -> _Master:
+    """Fetch the file, conditionally when there is a copy worth revalidating."""
+    headers: dict[str, str] = {}
+    if cached is not None:
+        if cached.etag:
+            headers["If-None-Match"] = cached.etag
+        elif cached.last_modified_raw:
+            headers["If-Modified-Since"] = cached.last_modified_raw
+    # The scrip host is a static file server, not an API host: no error envelope,
+    # no request id. Map failures onto the SDK's own exceptions — the same ones
+    # the API host raises — so callers can catch one set for everything.
+    try:
+        response = httpx.get(url, headers=headers, timeout=timeout if timeout is not None else 30.0)
+    except (httpx.ConnectError, httpx.ConnectTimeout) as e:  # DNS, refused, TLS
+        raise SahiConnectionException(
+            f"could not download the scrip master from {url}: {e}. "
+            "Check network access and the URL."
+        ) from e
+    except httpx.TimeoutException as e:
+        raise SahiTimeoutException("scrip-master download timed out") from e
+    except httpx.HTTPError as e:  # protocol errors after the connection opened
+        raise SahiAPIException(f"scrip-master download failed: {e}") from e
+
+    if cached is not None and response.status_code == 304:
+        cached.checked_at = time.time()
+        cached.day = _trading_day()
+        return cached
+    if not response.is_success:
+        raise SahiAPIException("scrip-master download failed", status=response.status_code)
+
+    master = _Master(rows=_parse(response.text))
+    _build_indexes(master)
+    master.last_modified_raw = response.headers.get("Last-Modified")
+    master.last_modified = _http_date_epoch(master.last_modified_raw)
+    master.etag = response.headers.get("ETag")
+    master.checked_at = time.time()
+    master.day = _trading_day()
+    return master
+
+
+def _parse(text: str) -> list[dict[str, Any]]:
+    reader = csv.DictReader(io.StringIO(text))
+    rows: list[dict[str, Any]] = []
+    for raw in reader:
+        row: dict[str, Any] = dict(raw)
+        for column in _INT_COLUMNS:
+            value = row.get(column)
+            if value is not None and value != "":
+                try:
+                    row[column] = int(value)
+                except ValueError:
+                    pass  # leave a non-integer value as its original string
+        rows.append(row)
+    return rows
+
+
+def _build_indexes(master: _Master) -> None:
+    by_id: dict[int, dict[str, Any]] = {}
+    by_symbol: dict[str, list[dict[str, Any]]] = {}
+    by_isin: dict[str, list[dict[str, Any]]] = {}
+    for row in master.rows:
+        rid = row.get("id")
+        if isinstance(rid, int):
+            by_id[rid] = row
+        symbol = row.get("symbol")
+        if symbol:
+            by_symbol.setdefault(symbol, []).append(row)
+        isin = row.get("isin")
+        if isin:
+            by_isin.setdefault(isin, []).append(row)
+    master.by_id = by_id
+    master.by_symbol = by_symbol
+    master.by_isin = by_isin
+
+
+def _http_date_epoch(value: str | None) -> float | None:
+    """Epoch seconds for an HTTP date header, or ``None`` if it is absent or odd."""
+    if not value:
+        return None
+    try:
+        return parsedate_to_datetime(value).timestamp()
+    except (TypeError, ValueError):
+        return None
+
+
+def _trading_day() -> int:
+    """The current trading day as a day number, rolling at 06:00 IST."""
+    ist_now = time.time() + _IST_OFFSET_SECONDS
+    return int((ist_now - _DAY_ROLL_SECONDS) // 86400)
+
+
+def _day_roll_epoch() -> float:
+    """Epoch seconds of the most recent 06:00 IST boundary."""
+    return _trading_day() * 86400.0 + _DAY_ROLL_SECONDS - _IST_OFFSET_SECONDS

sahiapi/sahi/marketdata.py

@@ -0,0 +1,268 @@
+"""Market-data REST endpoints: LTP, quotes, candles and the option chain.
+
+Mirrors the Market data page of the API reference. Everything here needs the
+``marketdata.read`` scope and addresses instruments by ``instrument_id`` — the
+integer ``id`` from the scrip master. Prices are integer paise and timestamps are
+epoch milliseconds, returned unchanged.
+
+The one method beyond the raw endpoints is :meth:`get_candle_history`, which pages
+a long history for you. ``GET /v1/marketdata/candles`` returns at most 2500 candles
+per response, clipped at the start of the window, so a wide range needs several
+calls; ``get_candle_history`` follows ``has_more`` backward and returns the rows in
+ascending time order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from . import constants
+from .base import EndpointGroup
+
+__all__ = ["_MarketData"]
+
+_MAX_INSTRUMENTS_PER_REQUEST = 500
+_CANDLE_SIZES = (
+    constants.CANDLE_1M,
+    constants.CANDLE_3M,
+    constants.CANDLE_5M,
+    constants.CANDLE_15M,
+    constants.CANDLE_30M,
+    constants.CANDLE_1H,
+    constants.CANDLE_1D,
+)
+
+
+class _MarketData(EndpointGroup):
+    """Market-data methods mixed into :class:`SahiAPI`."""
+
+    def get_ltp(
+        self, instrument_ids: int | Sequence[int], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Last traded price for one or many instruments (``GET /v1/marketdata/ltp``).
+
+        Args:
+            instrument_ids: One ``instrument_id``, or up to 500 of them. The
+                endpoint is single or bulk, so a lone id needs no list around it;
+                the response is keyed by id either way.
+
+        Returns:
+            ``{"data": {"<id>": {"last_trade_price": ..., "last_trade_time": ...}}}``.
+            A non-existent instrument's value is ``null``; the call still returns
+            ``200``.
+
+        Raises:
+            ValueError: If no ids are given, or more than 500 are.
+        """
+        ids = self._as_instrument_ids(instrument_ids)
+        return self._request(  # type: ignore[no-any-return]
+            "GET",
+            "/v1/marketdata/ltp",
+            params={"i": ids},
+            timeout=timeout,
+            retry_on_rate_limit=True,
+        )
+
+    def get_quotes(
+        self, instrument_ids: int | Sequence[int], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Full quote with market depth (``GET /v1/marketdata/quotes``).
+
+        Args:
+            instrument_ids: One ``instrument_id``, or up to 500 of them, as on
+                :meth:`get_ltp`.
+
+        Returns:
+            ``{"data": {"<id>": {...}}}`` — the REST equivalent of the tick
+            stream's depth tick: price, volume, DPR band, open interest and depth.
+
+        Raises:
+            ValueError: If no ids are given, or more than 500 are.
+        """
+        ids = self._as_instrument_ids(instrument_ids)
+        return self._request(  # type: ignore[no-any-return]
+            "GET",
+            "/v1/marketdata/quotes",
+            params={"i": ids},
+            timeout=timeout,
+            retry_on_rate_limit=True,
+        )
+
+    def get_candles(
+        self,
+        instrument_id: int,
+        size: str,
+        from_ms: int,
+        to_ms: int,
+        *,
+        include_partial: bool = False,
+        oi: bool = False,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Historical candles (``GET /v1/marketdata/candles``).
+
+        Args:
+            instrument_id: The instrument to fetch.
+            size: One of ``1m``, ``3m``, ``5m``, ``15m``, ``30m``, ``1h``, ``1d``.
+                Case-sensitive.
+            from_ms: Window start, epoch milliseconds, inclusive.
+            to_ms: Window end, epoch milliseconds, inclusive. Must be ``>= from_ms``.
+            include_partial: When true and the market is open, append the
+                in-progress candle as the last entry.
+            oi: When true, append open interest as a 7th element to each candle.
+            timeout: Per-call timeout override.
+
+        Returns:
+            ``{"instrument_id", "size", "candles": [[ts,o,h,l,c,v(,oi)]], "has_more"}``.
+            Each candle is a fixed-length array; the width is 6, or 7 with ``oi``.
+            At most 2500 candles per response, clipped at the start of the window.
+
+        Raises:
+            ValueError: If ``size`` is not one of the supported sizes, or
+                ``to_ms`` is before ``from_ms``.
+        """
+        self._check_candle_size(size)
+        if to_ms < from_ms:
+            raise ValueError(f"to_ms ({to_ms}) must not be before from_ms ({from_ms})")
+        return self._request(  # type: ignore[no-any-return]
+            "GET",
+            "/v1/marketdata/candles",
+            params={
+                "instrument_id": instrument_id,
+                "size": size,
+                "from": from_ms,
+                "to": to_ms,
+                "include_partial": include_partial,
+                "oi": oi,
+            },
+            timeout=timeout,
+            retry_on_rate_limit=True,
+        )
+
+    def get_candle_history(
+        self,
+        instrument_id: int,
+        size: str,
+        from_ms: int,
+        to_ms: int,
+        *,
+        oi: bool = False,
+        timeout: float | None = None,
+    ) -> list[list[Any]]:
+        """Every candle in a range, ascending, paging past the 2500 cap.
+
+        A single :meth:`get_candles` call returns at most 2500 candles, clipped at
+        the start of the window, and the endpoint pages backward only: each call
+        ends at ``first_timestamp - 1`` of the one before. This walks that chain
+        to the start of the range and returns the rows oldest-first — the same raw
+        arrays :meth:`get_candles` returns, unchanged.
+
+        The whole range is fetched before anything is returned, so a wide window
+        is many requests (candles are budgeted at 2 per second and 250 per
+        minute) held in memory at once, and a failure part-way loses the walk.
+        Call :meth:`get_candles` yourself to page a long history under your own
+        control, following ``has_more`` as above.
+
+        ``include_partial`` is not offered here: a multi-call history is a
+        completed series, and a partial candle only makes sense on a single live
+        call.
+
+        Returns:
+            Every candle in ``[from_ms, to_ms]``, in ascending timestamp order.
+            Empty when the instrument has no candles in the range.
+        """
+        pages: list[list[list[Any]]] = []
+        current_to = to_ms
+        while current_to >= from_ms:
+            response = self.get_candles(
+                instrument_id, size, from_ms, current_to, oi=oi, timeout=timeout
+            )
+            candles = response.get("candles") or []
+            if not candles:
+                break
+            pages.append(candles)
+            if not response.get("has_more"):
+                break
+            earliest_ts = candles[0][0]
+            current_to = int(earliest_ts) - 1
+        rows: list[list[Any]] = []
+        for page in reversed(pages):
+            rows.extend(page)
+        return rows
+
+    def get_option_expiries(
+        self, underlying_id: int, *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Available expiries for an underlying (``GET /v1/marketdata/optionchain/expiries``).
+
+        Args:
+            underlying_id: The underlying's ``instrument_id`` — the index or
+                stock, not a derivative.
+
+        Returns:
+            ``{"expiries": ["YYYY-MM-DD", ...]}``.
+        """
+        return self._request(  # type: ignore[no-any-return]
+            "GET",
+            "/v1/marketdata/optionchain/expiries",
+            params={"underlying_id": underlying_id},
+            timeout=timeout,
+            retry_on_rate_limit=True,
+        )
+
+    def get_option_chain(
+        self,
+        underlying_id: int,
+        expiry: str | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Option chain for an underlying and expiry (``GET /v1/marketdata/optionchain``).
+
+        Args:
+            underlying_id: The underlying's ``instrument_id``.
+            expiry: ``YYYY-MM-DD``, one of the expiries endpoint's values. Omit to
+                use the nearest unexpired expiry.
+
+        Returns:
+            The chain dict: ``underlying_id``, the resolved ``expiry``,
+            ``last_price`` and ``strikes`` (one row per strike, with ``ce`` / ``pe``
+            legs).
+        """
+        params: dict[str, Any] = {"underlying_id": underlying_id}
+        if expiry is not None:
+            params["expiry"] = expiry
+        return self._request(  # type: ignore[no-any-return]
+            "GET",
+            "/v1/marketdata/optionchain",
+            params=params,
+            timeout=timeout,
+            retry_on_rate_limit=True,
+        )
+
+    @staticmethod
+    def _as_instrument_ids(instrument_ids: int | Sequence[int]) -> list[int]:
+        # The endpoint is single or bulk, so a lone id is wrapped rather than
+        # refused. Both limits are the API's own rules; failing here saves a round
+        # trip that would come back 400 and gives a message that names the fix.
+        ids = [instrument_ids] if isinstance(instrument_ids, int) else list(instrument_ids)
+        if not ids:
+            raise ValueError("instrument_ids must contain at least one instrument_id")
+        if len(ids) > _MAX_INSTRUMENTS_PER_REQUEST:
+            raise ValueError(
+                f"at most {_MAX_INSTRUMENTS_PER_REQUEST} instrument_ids per request, got "
+                f"{len(ids)}; split the list into batches of "
+                f"{_MAX_INSTRUMENTS_PER_REQUEST}"
+            )
+        return ids
+
+    @staticmethod
+    def _check_candle_size(size: str) -> None:
+        # Sizes are case-sensitive on the server ("1M" is rejected as not one
+        # minute), which is the kind of typo a clear local error prevents.
+        if size not in _CANDLE_SIZES:
+            raise ValueError(
+                f"unknown candle size {size!r}; use one of {', '.join(_CANDLE_SIZES)} "
+                "(case-sensitive; the SahiAPI.CANDLE_* constants are the safe spelling)"
+            )