sahiapi 0.1.0__py3-none-any.whl

sahiapi/sahi/constants.py

@@ -0,0 +1,115 @@
+"""Wire constants for the Sahi APIs.
+
+Every enumerated value the API accepts or returns is named here, so callers use
+a symbol instead of a bare string and typos surface at import time rather than
+as a rejected order. The values are the exact wire strings from the API
+reference; the SDK never translates them.
+
+:class:`SahiAPI` re-exports these as class attributes (``SahiAPI.ORDER_TYPE_LIMIT``),
+which is the form most examples use. They are defined here, at module level,
+with no dependency on the rest of the package.
+"""
+
+from __future__ import annotations
+
+# --- Exchange segments -------------------------------------------------------
+# The market an instrument trades on, used by the order endpoints as part of the
+# (exchange_segment, symbol) pair.
+EXCHANGE_SEGMENT_NSE = "NSE"  # NSE cash
+EXCHANGE_SEGMENT_NFO = "NFO"  # NSE futures & options
+EXCHANGE_SEGMENT_BSE = "BSE"  # BSE cash
+EXCHANGE_SEGMENT_BFO = "BFO"  # BSE futures & options
+# Commodity segments. The order API accepts both values and the funds endpoint
+# reports an option-premium pool for each, but commodity trading is not enabled
+# on Sahi yet: an order on either segment is rejected by the server.
+EXCHANGE_SEGMENT_MCX = "MCX"  # MCX commodity derivatives
+EXCHANGE_SEGMENT_NCOM = "NCOM"  # NSE commodity derivatives
+
+# --- Transaction type --------------------------------------------------------
+TXN_TYPE_BUY = "B"
+TXN_TYPE_SELL = "S"
+
+# --- Order type --------------------------------------------------------------
+ORDER_TYPE_LIMIT = "LMT"
+ORDER_TYPE_MARKET = "MKT"
+ORDER_TYPE_SL_LIMIT = "SL-LMT"  # stop-loss limit
+ORDER_TYPE_SL_MARKET = "SL-MKT"  # stop-loss market
+
+# --- Product -----------------------------------------------------------------
+PRODUCT_DELIVERY = "C"  # delivery, cash segment
+PRODUCT_INTRADAY = "I"  # intraday
+PRODUCT_NORMAL = "M"  # carry-forward, F&O
+
+# --- Validity ----------------------------------------------------------------
+VALIDITY_DAY = "DAY"
+VALIDITY_IOC = "IOC"  # immediate-or-cancel
+
+# --- Order variant -----------------------------------------------------------
+VARIANT_REGULAR = "REGULAR"
+VARIANT_AMO = "AMO"  # after-market order
+
+# --- Order status (response only) --------------------------------------------
+# The six values the API returns. A stop order (SL-LMT / SL-MKT) whose trigger
+# has not yet fired, and an after-market order waiting for the next session,
+# both show as Open: the API has no separate "awaiting trigger" status.
+ORDER_STATUS_OPEN = "Open"
+ORDER_STATUS_OPEN_PARTIAL = "OpenPartial"
+ORDER_STATUS_PARTIAL_FILLED = "PartialFilled"
+ORDER_STATUS_COMPLETED = "Completed"
+ORDER_STATUS_CANCELLED = "Cancelled"
+ORDER_STATUS_REJECTED = "Rejected"
+
+# --- Candle sizes ------------------------------------------------------------
+# Case-sensitive: "1M" is not one minute and is rejected.
+CANDLE_1M = "1m"
+CANDLE_3M = "3m"
+CANDLE_5M = "5m"
+CANDLE_15M = "15m"
+CANDLE_30M = "30m"
+CANDLE_1H = "1h"
+CANDLE_1D = "1d"
+
+# --- Tick-stream modes -------------------------------------------------------
+# The subscription mode for the market-data WebSocket, from lightest to
+# richest: last price only, full quote, or quote plus market depth.
+MODE_LTP = "LTP"
+MODE_QUOTE = "QUOTE"
+MODE_DEPTH = "DEPTH"
+
+# --- Scopes ------------------------------------------------------------------
+# The permissions a key can hold and a token can carry.
+SCOPE_ORDERS_WRITE = "orders.write"
+SCOPE_ORDERS_READ = "orders.read"
+SCOPE_POSITIONS_READ = "positions.read"
+SCOPE_HOLDINGS_READ = "holdings.read"
+SCOPE_FUNDS_READ = "funds.read"
+SCOPE_PROFILE_READ = "profile.read"
+SCOPE_MARKETDATA_READ = "marketdata.read"
+
+# --- Instrument types --------------------------------------------------------
+# The instrument_type a tick reports (proto enum names with the prefix stripped
+# by the feed codec). The scrip master classifies instruments too, but with its
+# own short forms (STK, FUTIDX, ...); these are the tick-stream spellings.
+INSTRUMENT_TYPE_INDEX = "INDEX"
+INSTRUMENT_TYPE_STOCK = "STOCK"
+INSTRUMENT_TYPE_ETF = "ETF"
+INSTRUMENT_TYPE_INDEX_FUT = "INDEX_FUT"
+INSTRUMENT_TYPE_INDEX_OPT_CE = "INDEX_OPT_CE"
+INSTRUMENT_TYPE_INDEX_OPT_PE = "INDEX_OPT_PE"
+INSTRUMENT_TYPE_STOCK_FUT = "STOCK_FUT"
+INSTRUMENT_TYPE_STOCK_OPT_CE = "STOCK_OPT_CE"
+INSTRUMENT_TYPE_STOCK_OPT_PE = "STOCK_OPT_PE"
+
+# --- WebSocket close codes ---------------------------------------------------
+# Application close codes both streams use, beyond the standard 1000/1006. The
+# SDK reconnects on 4408 and 4409 and treats the others as final.
+WS_CLOSE_AUTH_EXPIRED = 4401  # token reached exp; mint a fresh one and reconnect
+WS_CLOSE_FORBIDDEN = 4403  # token lacks the stream's scope
+WS_CLOSE_HEARTBEAT = 4408  # no pong within 15 s of the server ping
+WS_CLOSE_DROPPED = 4409  # client fell too far behind (slow consumer); re-sync after reconnect
+WS_CLOSE_TOO_MANY = 4429  # over the 5-concurrent-connection limit for this token/account
+
+# Every module-level constant is public and re-exported at the package top level,
+# so callers can write `from sahiapi import ORDER_TYPE_LIMIT`. The names are all
+# upper-case; nothing else here is.
+__all__ = [name for name in dir() if name.isupper()]

sahiapi/sahi/env.py

@@ -0,0 +1,39 @@
+"""The hosts the SDK talks to.
+
+The SDK always talks to the production Sahi hosts. There is no argument or
+environment variable for pointing it anywhere else.
+
+The two hosts are separate: the **API** host serves everything under ``/v1``,
+and the **auth** host serves ``/api/v1/apikeys/token``. WebSocket URLs are
+derived from the API host by swapping the scheme, so there is only ever one
+host to know about.
+
+Code in this package reads these names through the module, as
+``env.API_BASE_URL``, rather than importing them by name.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "API_BASE_URL",
+    "AUTH_BASE_URL",
+    "websocket_base_url",
+]
+
+#: The API host (serves ``/v1``). No trailing slash.
+API_BASE_URL = "https://direct.sahi.com"
+#: The auth host (serves the token endpoint). No trailing slash.
+AUTH_BASE_URL = "https://apis.sahi.com"
+
+
+def websocket_base_url(api_base_url: str) -> str:
+    """Derive the WebSocket base URL from an API base URL by scheme swap.
+
+    ``https`` becomes ``wss`` and ``http`` becomes ``ws``; any other scheme is
+    returned unchanged so an explicitly ``wss://`` base is respected.
+    """
+    if api_base_url.startswith("https://"):
+        return "wss://" + api_base_url[len("https://") :]
+    if api_base_url.startswith("http://"):
+        return "ws://" + api_base_url[len("http://") :]
+    return api_base_url

sahiapi/sahi/exceptions.py

@@ -0,0 +1,412 @@
+"""Exception hierarchy for the Sahi SDK.
+
+Every error the SDK raises descends from :class:`SahiBaseException`, so one
+``except`` clause can handle anything the SDK might raise. Below it the tree
+splits three ways:
+
+* :class:`SahiConfigurationException` — the SDK was used wrongly before any
+  request was made: a credential of the wrong shape, a missing setting.
+* :class:`SahiAPIException` — a request reached a Sahi host and came back
+  non-2xx. It carries the server's ``status``, ``code`` and ``message``, the
+  request id for support, and a ``hint`` saying what to do about it.
+* :class:`SahiFeedException` — a WebSocket stream failed to connect, was closed
+  by the server for good, or was asked for data it does not hold.
+
+Match on the exception *type*, never on the message text. The two Sahi hosts use
+different code vocabularies for the same envelope — the auth host uses
+``PascalCase`` (``Unauthorized``), everything under ``/v1`` uses
+``SCREAMING_SNAKE_CASE`` (``IP_NOT_ALLOWED``) — and :func:`exception_for` folds
+that difference away so each subclass means one thing regardless of host.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+__all__ = [
+    "SahiAPIException",
+    "SahiAccountLockedException",
+    "SahiAuthenticationException",
+    "SahiAuthorisationException",
+    "SahiBadRequestException",
+    "SahiBaseException",
+    "SahiConfigurationException",
+    "SahiConnectionException",
+    "SahiFeedAuthExpiredException",
+    "SahiFeedConnectionException",
+    "SahiFeedException",
+    "SahiFeedForbiddenException",
+    "SahiFeedNotSubscribedException",
+    "SahiInvalidOrderStateException",
+    "SahiIpNotAllowedException",
+    "SahiKeyNotApprovedException",
+    "SahiNotFoundException",
+    "SahiOrderNotFoundException",
+    "SahiRateLimitException",
+    "SahiServerException",
+    "SahiTimeoutException",
+    "SahiValidationException",
+    "exception_for",
+]
+
+
+class SahiBaseException(Exception):
+    """Base class for every exception raised by the SDK."""
+
+
+class SahiConfigurationException(SahiBaseException):
+    """The SDK was misconfigured or misused before a request could be made.
+
+    Raised locally, never in response to a server reply. The message says what
+    was wrong and what to pass instead.
+    """
+
+
+class SahiAPIException(SahiBaseException):
+    """A request to a Sahi host failed.
+
+    Usually the host returned a non-2xx response. Two subclasses cover the cases
+    where no response arrived: :class:`SahiConnectionException` (nothing was
+    sent) and :class:`SahiTimeoutException` (the request may have been sent).
+
+    Attributes:
+        status: The HTTP status code, or ``None`` if no response arrived.
+        code: The stable ``code`` from the error envelope, verbatim as the host
+            sent it (``"Unauthorized"`` on the auth host, ``"IP_NOT_ALLOWED"``
+            under ``/v1``). ``None`` if the body carried none.
+        message: The server's human-readable ``message``, if any.
+        request_id: The request id, for quoting to Sahi support. Echoed from the
+            response when the host returns one, otherwise the value the SDK
+            sent with the request.
+        hint: What to do about it, per the API reference. Each subclass supplies
+            its own; the base class has none.
+
+    ``str(exc)`` combines all of these, so logging the exception is enough to
+    diagnose and act on it.
+    """
+
+    #: Actionable guidance appended to ``str()``; overridden per subclass.
+    hint: str = ""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(self._render())
+
+    def _render(self) -> str:
+        head = " ".join(
+            p for p in (f"HTTP {self.status}" if self.status else "", self.code or "") if p
+        )
+        body = self.message or ""
+        text = f"{head}: {body}" if head and body else head or body or self.__class__.__name__
+        if self.hint:
+            text = f"{text.rstrip('.')}. {self.hint}"
+        if self.request_id:
+            text = f"{text} [request_id={self.request_id}]"
+        return text
+
+
+class SahiBadRequestException(SahiAPIException):
+    """400: the request was malformed.
+
+    On the auth host this also covers ``scopes`` that are not a subset of the
+    key's scopes — a token can only ever narrow a key, never widen it.
+    """
+
+    hint = "Check the request fields against the API reference."
+
+
+class SahiValidationException(SahiBadRequestException):
+    """``VALIDATION_FAILED``: a field failed the API's business rules.
+
+    Arrives as ``400`` for a malformed field and as ``422`` for one the API
+    rejects on meaning — an unknown symbol, a quantity over the freeze quantity,
+    a contract past expiry. The server ``message`` names the field or rule.
+    """
+
+    hint = "The server message names the field or rule that failed."
+
+
+class SahiAuthenticationException(SahiAPIException):
+    """401: the credential or token was missing, unknown, wrong, or revoked.
+
+    The auth host deliberately does not say which: an unknown key id, a wrong
+    secret and a revoked key all return the same response.
+    """
+
+    hint = (
+        "Check the key id and secret. If a token was in use, it may have expired or "
+        "its key may have been revoked — mint a new token."
+    )
+
+
+class SahiAccountLockedException(SahiAuthenticationException):
+    """401 ``Locked``: the account behind the credential is frozen or locked."""
+
+    hint = "The account is locked or frozen. Contact Sahi support to restore access."
+
+
+class SahiAuthorisationException(SahiAPIException):
+    """403: the token is valid but not permitted to do this.
+
+    Under ``/v1`` this means the token lacks the scope the endpoint needs.
+    Scopes are fixed when the key is created and a token can only narrow them.
+    """
+
+    hint = (
+        "The token lacks the scope this endpoint needs. Mint a token with the required "
+        "scope, or create a key that holds it."
+    )
+
+
+class SahiKeyNotApprovedException(SahiAuthorisationException):
+    """403 on the auth host: the key is not approved for the current trading day.
+
+    Approval is a daily act and lapses at 06:00 IST; it is an exchange
+    requirement, not something the SDK can bypass.
+    """
+
+    hint = "Approve the key for today's trading day in your Sahi account, then mint again."
+
+
+class SahiIpNotAllowedException(SahiAuthorisationException):
+    """403 ``IP_NOT_ALLOWED``: an order write did not come from a registered IP.
+
+    Placing, modifying and cancelling orders must originate from a static IP
+    registered on the account. Reads and market data are not IP-checked.
+    """
+
+    hint = (
+        "Order writes must come from a static IP registered on your account. Check the "
+        "public egress address of this host — it usually means the address changed."
+    )
+
+
+class SahiNotFoundException(SahiAPIException):
+    """404: the route or resource does not exist.
+
+    Also returned by the funds, margin and profile endpoints when the account
+    behind the token is not yet set up for trading.
+    """
+
+    hint = (
+        "Check the path. For funds, margin and profile this can also mean the account "
+        "is not yet set up for trading."
+    )
+
+
+class SahiOrderNotFoundException(SahiNotFoundException):
+    """404 ``ORDER_NOT_FOUND``: no such order on today's book for this account."""
+
+    hint = "The order is not on today's book, or does not belong to this account."
+
+
+class SahiInvalidOrderStateException(SahiAPIException):
+    """``INVALID_ORDER_STATE``: the order cannot change from its current state.
+
+    Only ``Open`` and ``OpenPartial`` orders can be modified or cancelled; a
+    completed, cancelled or rejected order is final.
+    """
+
+    hint = "Only Open and OpenPartial orders can be modified or cancelled."
+
+
+class SahiRateLimitException(SahiAPIException):
+    """429: a rate-limit window was exhausted.
+
+    Attributes:
+        retry_after: Seconds until the window that tripped has run out, from the
+            ``Retry-After`` header. ``None`` on the auth host, which sends no
+            header — wait for the next minute instead.
+    """
+
+    hint = (
+        "Wait retry_after seconds before retrying (or until the next minute when it is "
+        "not given). Batch requests instead of looping per instrument."
+    )
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, status=status, code=code, request_id=request_id)
+
+
+class SahiServerException(SahiAPIException):
+    """5xx: something failed on Sahi's side."""
+
+    hint = (
+        "Retry an idempotent read after a short wait. Do not blindly retry an order write: "
+        "check the order book first so the order is not sent twice."
+    )
+
+
+class SahiTimeoutException(SahiAPIException):
+    """No response arrived within the timeout.
+
+    The request may or may not have reached the server. For an order write,
+    read the order book before retrying so the order is not placed twice.
+    """
+
+    hint = (
+        "The request may have reached the server. For an order write, check the order "
+        "book before retrying."
+    )
+
+
+class SahiConnectionException(SahiAPIException):
+    """The connection to the host could not be opened.
+
+    DNS failure, connection refused, a TLS handshake error or a connect timeout.
+    Nothing was sent, so the request is safe to retry once the network or the
+    base URL is fixed.
+    """
+
+    hint = "Nothing reached the server; the request is safe to retry."
+
+
+class SahiFeedException(SahiBaseException):
+    """Base class for WebSocket stream errors.
+
+    Attributes:
+        close_code: The close code the server sent when it ended the stream
+            (``4401``, ``4403`` or ``4429``; compare against the ``WS_CLOSE_*``
+            constants). ``None`` when no close frame was involved: the server
+            refused the HTTP handshake, or the SDK raised locally, for instance
+            a send on a socket that is not open.
+    """
+
+    def __init__(self, message: str, *, close_code: int | None = None) -> None:
+        self.close_code = close_code
+        super().__init__(message)
+
+
+class SahiFeedConnectionException(SahiFeedException):
+    """The stream could not be used because of a connection-level refusal.
+
+    Raised for close code ``4429`` (the per-token or per-account limit of five
+    concurrent connections is exceeded) and for a send attempted while the
+    stream is not connected. ``close_code`` tells the two apart: it is ``4429``
+    in the first case, which clears once another connection is closed, and
+    ``None`` in the second, which is a caller-side ordering problem. A missed
+    heartbeat (``4408``), a slow-consumer drop (``4409``) or an ordinary network
+    drop is *not* this exception: those reconnect transparently and nothing is
+    raised.
+    """
+
+
+class SahiFeedAuthExpiredException(SahiFeedException):
+    """The token was rejected: close code ``4401``, or ``401`` at the handshake.
+
+    A socket is never extended past its token's ``exp``. Mint a fresh token,
+    build a new feed, and re-subscribe.
+    """
+
+
+class SahiFeedForbiddenException(SahiFeedException):
+    """The token lacks the stream's scope: ``403`` at the handshake, or close ``4403``."""
+
+
+class SahiFeedNotSubscribedException(SahiFeedException):
+    """A cached value was requested for an instrument that is not subscribed."""
+
+
+# Host discriminators for exception_for. Typed as a Literal so a wrong host is a
+# type error rather than a silent fall-through to the API-host branch.
+Host = Literal["auth", "api"]
+HOST_AUTH: Host = "auth"
+HOST_API: Host = "api"
+
+
+def _normalise(code: str | None) -> str:
+    """Fold a code to a host-independent key: upper-case, no separators."""
+    if not code:
+        return ""
+    return code.upper().replace("_", "").replace("-", "")
+
+
+def exception_for(
+    status: int,
+    *,
+    host: Host,
+    code: str | None = None,
+    message: str | None = None,
+    request_id: str | None = None,
+    retry_after: int | None = None,
+) -> SahiAPIException:
+    """Build the right :class:`SahiAPIException` for a non-2xx response.
+
+    The mapping keys on the HTTP status, the ``host`` the call went to
+    (:data:`HOST_AUTH` or :data:`HOST_API`) and the envelope ``code``. A
+    recognised code selects its specific subclass whatever the status, so a
+    ``422 VALIDATION_FAILED`` and a ``400 VALIDATION_FAILED`` land in the same
+    place. Otherwise the status selects a status-level class; an unmapped status
+    falls back to :class:`SahiServerException` for 5xx and
+    :class:`SahiAPIException` for anything else.
+
+    Args:
+        status: HTTP status code of the response.
+        host: :data:`HOST_AUTH` or :data:`HOST_API`. A ``403`` means "key not
+            approved" on the auth host but "insufficient scope" under ``/v1``.
+        code: The envelope ``code``, verbatim.
+        message: The envelope ``message``.
+        request_id: The request id to attach for support.
+        retry_after: Parsed ``Retry-After`` seconds, for 429s.
+
+    Returns:
+        An unraised exception instance for the caller to raise.
+    """
+    key = _normalise(code)
+
+    def build(cls: type[SahiAPIException]) -> SahiAPIException:
+        return cls(message, status=status, code=code, request_id=request_id)
+
+    # Code-specific mappings first — they are unambiguous regardless of status.
+    if key == "VALIDATIONFAILED":
+        return build(SahiValidationException)
+    if key == "ORDERNOTFOUND":
+        return build(SahiOrderNotFoundException)
+    if key == "INVALIDORDERSTATE":
+        return build(SahiInvalidOrderStateException)
+    if key == "IPNOTALLOWED":
+        return build(SahiIpNotAllowedException)
+    if key == "LOCKED":
+        return build(SahiAccountLockedException)
+
+    if status == 400:
+        return build(SahiBadRequestException)
+    if status == 401:
+        return build(SahiAuthenticationException)
+    if status == 403:
+        if host == HOST_AUTH:
+            return build(SahiKeyNotApprovedException)
+        return build(SahiAuthorisationException)
+    if status == 404:
+        return build(SahiNotFoundException)
+    if status == 429:
+        return SahiRateLimitException(
+            message,
+            status=status,
+            code=code,
+            request_id=request_id,
+            retry_after=retry_after,
+        )
+    if 500 <= status < 600:
+        return build(SahiServerException)
+
+    return build(SahiAPIException)