sahiapi 0.1.0__py3-none-any.whl

sahiapi/sahi/ws_client.py

@@ -0,0 +1,355 @@
+"""One WebSocket connection, with reconnect and close-code handling.
+
+Both Sahi streams share the same connection rules: the access token goes on the
+upgrade as a Bearer header, the server pings every 30 seconds and expects a pong
+within 15, and some close codes are fatal while others just mean reconnect. This
+class implements those rules once; :class:`~sahiapi.sahi.feed.SahiFeed` owns one
+instance per stream.
+
+The connection runs a receive loop on a daemon thread and hands each frame to an
+``on_message`` callback. On a transient drop it reconnects with exponential
+backoff and calls ``on_open`` again so the owner can re-send its subscriptions
+(stream state does not survive a reconnect). That covers a missed heartbeat
+(4408) and a slow-consumer drop (4409) as well as network drops — the API
+reference asks clients to reconnect and re-sync on both. A fatal close — an
+expired token (4401), a forbidden scope (4403) or too many connections (4429) —
+stops the loop and records the error for the owner to surface. A handshake the
+server refuses with HTTP 401 or 403 is fatal too: retrying an already-expired
+token would loop forever.
+
+The loop is deliberately hard to kill by accident. A frame the owner cannot
+handle is dropped and logged rather than ending the stream, and a failure in
+``on_open`` is treated as a transient drop and reconnected.
+
+The transport is injectable so the reconnect and close-code logic can be tested
+without a real socket; by default it is ``websocket-client``. Frames are read
+with ``recv_data`` so a close frame arrives as itself, with the server's status
+code in its payload: the plain ``recv`` turns a close into an empty string and
+keeps the code nowhere, so a fatal 4401 or 4429 would look like a clean drop.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import struct
+import threading
+from typing import Any, Callable, Protocol
+
+from . import constants, exceptions
+
+__all__ = ["Transport", "WebSocketConnection"]
+
+logger = logging.getLogger(__name__)
+
+
+class Transport(Protocol):
+    """The minimal socket surface this class needs.
+
+    ``websocket.WebSocket`` from ``websocket-client`` satisfies it; tests provide
+    a fake.
+    """
+
+    def recv_data(self) -> tuple[int, Any]: ...
+    def send_binary(self, data: bytes) -> Any: ...
+    def send(self, data: str) -> Any: ...
+    def close(self) -> Any: ...
+
+
+ConnectFn = Callable[[str, list[str]], Transport]
+
+# RFC 6455 opcodes, as websocket-client's ``recv_data`` reports them.
+_OPCODE_TEXT = 0x1
+_OPCODE_BINARY = 0x2
+_OPCODE_CLOSE = 0x8
+
+_BACKOFF_START = 1.0
+_BACKOFF_CAP = 30.0
+# Each backoff sleep is scaled by a factor drawn from this range.
+_BACKOFF_JITTER = (0.5, 1.5)
+
+
+# Twice the server's 30 s ping interval: a healthy socket delivers bytes at
+# least that often, so a read that waits longer is a half-open link.
+_READ_TIMEOUT_SECONDS = 60.0
+
+
+def _default_connect(url: str, header: list[str]) -> Transport:
+    import websocket
+
+    # Without a timeout a link that died silently (a NAT drop, a Wi-Fi switch)
+    # blocks recv forever and the stream goes quiet with nothing to notice. The
+    # timeout turns that silence into an exception, and the loop reconnects.
+    return websocket.create_connection(
+        url, header=header, enable_multithread=True, timeout=_READ_TIMEOUT_SECONDS
+    )
+
+
+def _close_code_of(payload: Any) -> int | None:
+    """The status code a close frame carries (RFC 6455 §5.5.1), or None if it has none."""
+    if isinstance(payload, (bytes, bytearray)) and len(payload) >= 2:
+        return int(struct.unpack("!H", bytes(payload[:2]))[0])
+    return None
+
+
+def _fatal_error_for(close_code: int | None) -> exceptions.SahiFeedException | None:
+    if close_code == constants.WS_CLOSE_AUTH_EXPIRED:
+        return exceptions.SahiFeedAuthExpiredException(
+            "the server closed the stream because the token expired or was revoked (4401). "
+            "Mint a new token, build a new SahiFeed and re-subscribe.",
+            close_code=close_code,
+        )
+    if close_code == constants.WS_CLOSE_FORBIDDEN:
+        return exceptions.SahiFeedForbiddenException(
+            "the token lacks the scope this stream needs (4403): orders.read for order "
+            "updates, marketdata.read for ticks. Mint a token that carries it.",
+            close_code=close_code,
+        )
+    if close_code == constants.WS_CLOSE_TOO_MANY:
+        return exceptions.SahiFeedConnectionException(
+            "too many concurrent connections (4429): each stream allows 5 at once, per token "
+            "for the tick stream and per account for order updates. Close an existing "
+            "connection before opening another.",
+            close_code=close_code,
+        )
+    # 4408 (heartbeat) and 4409 (slow consumer) fall through: reconnect and re-sync.
+    return None
+
+
+def _fatal_error_for_handshake(exc: BaseException) -> exceptions.SahiFeedException | None:
+    """Map an upgrade refused by the server to a fatal error, or None to retry.
+
+    Before the socket exists the server can only refuse with an HTTP status, so
+    an expired token shows up here as 401, not as a 4401 close. websocket-client
+    exposes the status as ``status_code`` on its handshake exception.
+    """
+    status = getattr(exc, "status_code", None)
+    if status == 401:
+        return exceptions.SahiFeedAuthExpiredException(
+            "the server rejected the token at the WebSocket handshake (401): it has expired "
+            "or been revoked. Mint a new token, build a new SahiFeed and re-subscribe."
+        )
+    if status == 403:
+        return exceptions.SahiFeedForbiddenException(
+            "the server refused the WebSocket handshake (403): the token lacks the scope "
+            "this stream needs. Mint a token that carries it."
+        )
+    return None
+
+
+class WebSocketConnection:
+    """A self-reconnecting WebSocket connection for one stream.
+
+    Args:
+        url: The ``wss://`` URL to connect to.
+        access_token: Bearer token for the upgrade request.
+        binary: True for the protobuf tick stream, False for the JSON order
+            stream. Decides whether outgoing sends and the frames handed to
+            ``on_message`` are bytes or text.
+        on_message: Called with each received frame (bytes if ``binary`` else str),
+            on the connection's own thread.
+        on_open: Called after every successful (re)connect, before reading, so the
+            owner can re-send subscriptions. Optional.
+        on_fatal: Called once, on the connection's thread, with the error that
+            ended the loop for good. Must not call :meth:`stop` — that would join
+            the calling thread. Optional.
+        name: A short label used for the daemon thread name.
+        connect_fn: Transport factory, for testing. Defaults to websocket-client.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        access_token: str,
+        binary: bool,
+        on_message: Callable[[Any], None],
+        on_open: Callable[[], None] | None = None,
+        on_fatal: Callable[[exceptions.SahiFeedException], None] | None = None,
+        name: str = "sahi-ws",
+        connect_fn: ConnectFn | None = None,
+    ) -> None:
+        self._url = url
+        self._header = [f"Authorization: Bearer {access_token}"]
+        self._binary = binary
+        self._on_message = on_message
+        self._on_open = on_open
+        self._on_fatal = on_fatal
+        self._name = name
+        self._connect = connect_fn or _default_connect
+
+        self._thread: threading.Thread | None = None
+        self._stopped = threading.Event()
+        self._send_lock = threading.Lock()
+        self._transport: Transport | None = None
+        self._epoch = 0  # bumped each time a new transport is installed
+        self._fatal_error: exceptions.SahiFeedException | None = None
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the background connect/receive loop, if not already running."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stopped.clear()
+        self._fatal_error = None
+        self._thread = threading.Thread(target=self._run, name=self._name, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the loop and close the socket."""
+        self._stopped.set()
+        with self._send_lock:
+            transport, self._transport = self._transport, None
+        if transport is not None:
+            self._close_quietly(transport)
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+
+    @property
+    def fatal_error(self) -> exceptions.SahiFeedException | None:
+        """The fatal close error that stopped the loop, if any."""
+        return self._fatal_error
+
+    def is_running(self) -> bool:
+        """Whether the background loop is alive."""
+        return self._thread is not None and self._thread.is_alive()
+
+    @property
+    def epoch(self) -> int | None:
+        """A number that changes on every (re)connect, or None while not connected.
+
+        A sender that must not repeat a frame across a reconnect records the
+        epoch it sent under and passes it back to :meth:`send`; the reconnect
+        replay carries anything that missed the old socket.
+        """
+        with self._send_lock:
+            return self._epoch if self._transport is not None else None
+
+    # -- sending --------------------------------------------------------------
+
+    def send(self, data: bytes | str, *, epoch: int | None = None) -> None:
+        """Send a frame on the current connection.
+
+        Args:
+            data: The frame.
+            epoch: If given, the :attr:`epoch` the frame was prepared under. A
+                frame prepared for an older connection is refused rather than
+                sent on the new one, which the replay has already brought up.
+
+        Raises:
+            SahiFeedConnectionException: If the connection is not currently open,
+                or ``epoch`` no longer matches it.
+        """
+        with self._send_lock:
+            transport = self._transport
+            if transport is None:
+                raise exceptions.SahiFeedConnectionException(
+                    "the stream is not connected yet; subscriptions are queued and sent "
+                    "automatically once it is"
+                )
+            if epoch is not None and epoch != self._epoch:
+                raise exceptions.SahiFeedConnectionException(
+                    "the stream reconnected since this frame was prepared; the reconnect "
+                    "replay has already re-sent the subscription table"
+                )
+            if self._binary:
+                transport.send_binary(data if isinstance(data, bytes) else data.encode())
+            else:
+                transport.send(data if isinstance(data, str) else data.decode())
+
+    # -- loop -----------------------------------------------------------------
+
+    def _run(self) -> None:
+        backoff = _BACKOFF_START
+        while not self._stopped.is_set():
+            try:
+                transport = self._connect(self._url, self._header)
+            except Exception as e:
+                fatal = _fatal_error_for_handshake(e)
+                if fatal is not None:
+                    self._finish_fatal(fatal)
+                    return
+                if self._sleep_or_stop(backoff):
+                    return
+                backoff = min(_BACKOFF_CAP, backoff * 2)
+                continue
+
+            with self._send_lock:
+                self._transport = transport
+                self._epoch += 1
+            backoff = _BACKOFF_START
+            if self._on_open is not None:
+                try:
+                    self._on_open()
+                except Exception:
+                    # A failed replay (e.g. the socket dropped between connect and
+                    # send) is a transient drop, not a reason to die silently.
+                    logger.warning("on_open failed; reconnecting", exc_info=True)
+                    with self._send_lock:
+                        self._transport = None
+                    self._close_quietly(transport)
+                    if self._sleep_or_stop(backoff):
+                        return
+                    backoff = min(_BACKOFF_CAP, backoff * 2)
+                    continue
+
+            fatal = self._receive_until_closed(transport)
+            with self._send_lock:
+                self._transport = None
+            if fatal is not None:
+                self._finish_fatal(fatal)
+                return
+            if self._stopped.is_set():
+                return
+            if self._sleep_or_stop(backoff):
+                return
+            backoff = min(_BACKOFF_CAP, backoff * 2)
+
+    def _receive_until_closed(self, transport: Transport) -> exceptions.SahiFeedException | None:
+        """Read frames until the socket closes. Return a fatal error, or None to retry."""
+        while not self._stopped.is_set():
+            try:
+                opcode, payload = transport.recv_data()
+            except Exception:
+                # A transport error (timeout, reset, our own stop) carries no
+                # close code: the server never said why, so reconnect.
+                return None
+            if opcode == _OPCODE_CLOSE:
+                # websocket-client has already answered the close; the reason is
+                # the status code at the front of the payload.
+                return _fatal_error_for(_close_code_of(payload))
+            if opcode == _OPCODE_TEXT:
+                frame: Any = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+            elif opcode == _OPCODE_BINARY:
+                frame = payload
+            else:
+                continue  # ping/pong are answered inside recv_data; nothing to deliver
+            try:
+                self._on_message(frame)
+            except Exception:
+                # One undecodable or unhandled frame must not end the stream.
+                logger.warning("dropping frame the handler could not process", exc_info=True)
+        return None
+
+    def _finish_fatal(self, fatal: exceptions.SahiFeedException) -> None:
+        self._fatal_error = fatal
+        if self._on_fatal is not None:
+            self._on_fatal(fatal)
+
+    @staticmethod
+    def _close_quietly(transport: Transport) -> None:
+        try:
+            transport.close()
+        except Exception:
+            pass
+
+    def _sleep_or_stop(self, seconds: float) -> bool:
+        """Wait about ``seconds``, returning True if a stop was requested meanwhile.
+
+        The wait is jittered by up to half either way. Clients dropped together
+        (a deploy closes every socket at once) would otherwise retry at the same
+        1, 2, 4 s marks, and each upgrade counts against the stream rate limit.
+        """
+        return self._stopped.wait(timeout=seconds * random.uniform(*_BACKOFF_JITTER))

sahiapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: sahiapi
+Version: 0.1.0
+Summary: The official Python client library for the Sahi APIs.
+Project-URL: Homepage, https://docs.sahi.com/
+Project-URL: Documentation, https://docs.sahi.com/
+Project-URL: Repository, https://github.com/aarityatech/sahi-python
+Author: Aaritya Technologies
+License: Copyright (c) 2026 Aaritya Technologies Private Limited. All rights reserved.
+        
+        This software and its source code are proprietary and confidential. Until an
+        open-source license is applied by the copyright holder, no permission is granted
+        to copy, use, modify, or distribute this software outside Aaritya Technologies.
+        
+        An open-source license will replace this file when the project is published.
+License-File: LICENSE
+Keywords: bse,market-data,nse,options,sahi,stocks,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: protobuf>=4.25
+Requires-Dist: websocket-client>=1.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sahiapi
+
+The official Python client library for the [Sahi APIs](https://docs.sahi.com/):
+orders, portfolio, funds, market data and live streams.
+
+> Early development. The public interface is not yet stable.
+
+## Install
+
+```bash
+pip install sahiapi
+```
+
+Requires Python 3.9 or newer.
+
+## Quickstart
+
+Create an API key in your Sahi account and approve it for the trading day, then:
+
+```python
+import os
+from sahiapi import SahiAPI
+
+api = SahiAPI.from_credentials(
+    key_id=os.environ["SAHI_KEY_ID"],
+    secret=os.environ["SAHI_SECRET"],
+)
+print(api.get_profile())
+print(api.get_funds())
+```
+
+Tokens expire at 06:00 IST, so mint a fresh one each trading day.
+
+## Documentation
+
+Guides, the full API reference and examples are at **https://docs.sahi.com/**.
+
+The SDK returns the API's JSON exactly as documented there: money is integer
+paise, timestamps are epoch milliseconds, and field names are unchanged.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run mypy
+```
+
+The tick-stream protobuf bindings are generated and committed; regenerate them
+with `tools/regen_proto.sh` after editing the `.proto`. Releases are cut with
+`tools/release.sh`; see `.github/workflows/release.yml`.
+
+## License
+
+Proprietary during development; an open-source license will be applied before
+public release. See [LICENSE](LICENSE).

sahiapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+sahiapi/__init__.py,sha256=AhwVUCc2pDjODD1HoEKtmTHq8X8FWKQenbOQmOJb6A0,2713
+sahiapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sahiapi/sahi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sahiapi/sahi/account.py,sha256=U1P6Q42BUV0e6FhEsCDV3zzRHztEZ6f_J8CTYVXjVSs,781
+sahiapi/sahi/auth.py,sha256=fugQpiaSyvoDuyOaM5Gyeq8rVLgAEuc4_SdVUpN3frY,6191
+sahiapi/sahi/base.py,sha256=Gr7JFPuu31jhCPzYe50TMjaDS0OME9Pfw7e7p1TlDYc,1085
+sahiapi/sahi/client.py,sha256=bRO3m5BbRiMITm--YvAXezwsKSLk6LH0OkAOidX6dN0,12458
+sahiapi/sahi/constants.py,sha256=ZeVu3FljUDBDtWd8Ngr0HHxzu-B7lyuAsfVebRvPD80,5170
+sahiapi/sahi/env.py,sha256=ApBmTYa2c6RLl7P9AsE0JlPJuPdKH_tf-NrtTfbR2g8,1361
+sahiapi/sahi/exceptions.py,sha256=0lo3vlCBSlxmnY9XTuz2TtfqUVeA0nQkZ-kawOywjnY,14924
+sahiapi/sahi/feed.py,sha256=K0hW7gIxIKrcXIicm1MEZRbjdmHvcKWsg-clcUHGIwQ,31370
+sahiapi/sahi/funds.py,sha256=4BNnZh024D-gZu5Nd2mX-OYPuKGrrzvImdekHEZvxuE,5599
+sahiapi/sahi/http.py,sha256=AHDEnZvrIQu8Zk4Z2Clp-eKxChy-srGCkEtwLdR74ts,11329
+sahiapi/sahi/instruments.py,sha256=RtgDm0i3xCjNj0IeEXoJuNop8gObNudHZHG-at8jY60,14169
+sahiapi/sahi/marketdata.py,sha256=Cjw05P87SqKhEFZiUcCQ1QygcPRdK8PijO23awBNfrA,10208
+sahiapi/sahi/orders.py,sha256=9qWqzjBXAMlm3i89HXm5u3ufWoIHfmh47H6Hs2NYcUg,8595
+sahiapi/sahi/portfolio.py,sha256=AKYL6NevAsyra_KYAIDbXms5S4yaakdP2Peplvfuh3g,1905
+sahiapi/sahi/ws_client.py,sha256=fKhcutQPIpu-w-qbqik25q-aej4Z4BL-QcarZi1koa0,15054
+sahiapi/sahi/proto/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sahiapi/sahi/proto/codec.py,sha256=pRuysMnlb4d2554uJ9xeXf30CC27DZLDstt8HOTvSXk,4622
+sahiapi/sahi/proto/marketdata.proto,sha256=yVUMl26SKt-nvi8wGfFlU33L0cBceNlD3JkBC3fu7rE,3171
+sahiapi/sahi/proto/marketdata_pb2.py,sha256=XDokj9dyu0ZGC-SeYv7E7f8LSxrePeDNbnU8hLbSoZc,6963
+sahiapi-0.1.0.dist-info/METADATA,sha256=21QMm1vKdTQZ8Rislfejfva5SmnB4ILCxxXhyuX8SYI,3116
+sahiapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sahiapi-0.1.0.dist-info/licenses/LICENSE,sha256=0IoMnDb-h6e1mLOCDhfEmXzVZTmiD2CQN7ZdP7ctfXE,395
+sahiapi-0.1.0.dist-info/RECORD,,

sahiapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

sahiapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Aaritya Technologies Private Limited. All rights reserved.
+
+This software and its source code are proprietary and confidential. Until an
+open-source license is applied by the copyright holder, no permission is granted
+to copy, use, modify, or distribute this software outside Aaritya Technologies.
+
+An open-source license will replace this file when the project is published.