sahiapi 0.1.0__py3-none-any.whl

sahiapi/sahi/funds.py

@@ -0,0 +1,134 @@
+"""Funds endpoints: available balances and pre-trade margin checks.
+
+Mirrors the Funds page of the API reference. All three methods need the
+``funds.read`` scope. The margin checks take the same order body as
+:meth:`place_order`, so one order object serves both placing and sizing.
+Balances and margins are integer paise, returned unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import EndpointGroup
+from .orders import build_order_body
+
+__all__ = ["_Funds"]
+
+
+class _Funds(EndpointGroup):
+    """Funds and margin methods mixed into :class:`SahiAPI`."""
+
+    def get_funds(self, *, timeout: float | None = None) -> dict[str, Any]:
+        """Return available balances (``GET /v1/funds``).
+
+        Budgeted at one request per second, the tightest limit on the page:
+        read it when you need it, not in a polling loop.
+
+        Returns:
+            The funds dict, with ``available``, ``balance``, ``utilised`` and
+            ``option_premium`` sections, all in paise.
+        """
+        return self._request(  # type: ignore[no-any-return]
+            "GET", "/v1/funds", timeout=timeout, retry_on_rate_limit=True
+        )
+
+    def get_order_margin(
+        self,
+        *,
+        exchange_segment: str,
+        symbol: str,
+        txn_type: str,
+        qty: int,
+        order_type: str,
+        product: str,
+        validity: str,
+        price: int,
+        trigger_price: int | None = None,
+        disclosed_qty: int | None = None,
+        market_protection: float | None = None,
+        variant: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Quote the margin a single order would need (``POST /v1/margins/order``).
+
+        Takes the same fields as :meth:`place_order`, all keyword-only; ``qty`` is
+        not capped at the freeze quantity here, so you can size a full position
+        before slicing it. Nothing is placed and the call is not IP-checked.
+
+        A ``429`` is raised as :class:`~sahiapi.SahiRateLimitException`, not
+        retried: the SDK retries only ``GET`` requests, and this is a ``POST``.
+
+        Returns:
+            ``{"required_margin": ..., "available_margin": ...}``, in paise.
+
+        Raises:
+            SahiServerException: ``503 UNDER_MAINTENANCE`` between 04:45 and
+                07:00 IST, while the OMS runs its beginning-of-day processing.
+                Retry after 07:00 IST; the exception's generic hint of a short
+                wait does not apply here.
+        """
+        body = build_order_body(
+            exchange_segment,
+            symbol,
+            txn_type,
+            qty,
+            order_type,
+            product,
+            validity,
+            price,
+            trigger_price=trigger_price,
+            disclosed_qty=disclosed_qty,
+            market_protection=market_protection,
+            variant=variant,
+        )
+        # A margin quote is a read in POST clothing, but the core only retries a
+        # GET on 429: a 429 here surfaces as SahiRateLimitException for the caller.
+        return self._request(  # type: ignore[no-any-return]
+            "POST", "/v1/margins/order", json=body, timeout=timeout
+        )
+
+    def get_basket_margin(
+        self, legs: list[dict[str, Any]], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Quote the margin a basket would need, netted (``POST /v1/margins/basket``).
+
+        Args:
+            legs: 1 to 10 order bodies, each shaped exactly like a
+                :meth:`place_order` request. Every leg is built through the same
+                body builder :meth:`place_order` and :meth:`get_order_margin`
+                use, so a key the API does not define — a misspelled
+                ``market_protection``, say — raises :class:`TypeError` naming the
+                leg rather than being dropped in transit. One bad leg refuses the
+                whole request, and the server's message names it by zero-based
+                index.
+
+        Returns:
+            ``{"required_margin": ..., "available_margin": ...}``, in paise, with
+            the legs netted against each other and existing positions.
+            ``available_margin`` is quoted from a single margin pool, so for a
+            basket that mixes pools (an equity delivery leg beside a commodity
+            option, say) the comparison can overstate what the account can fund.
+
+        A ``429`` is raised, not retried, as on :meth:`get_order_margin`.
+
+        Raises:
+            TypeError: If a leg is missing a required field or carries one the
+                API does not define. The message names the leg by zero-based
+                index, as the server's own leg errors do.
+            SahiServerException: ``503 UNDER_MAINTENANCE`` between 04:45 and
+                07:00 IST, as on :meth:`get_order_margin`. Retry after 07:00 IST.
+        """
+        # The server ignores fields it does not know, so a misspelled key would
+        # otherwise be quoted at a value the caller never asked for; building each
+        # leg here gives the basket the check get_order_margin already has.
+        body: list[dict[str, Any]] = []
+        for index, leg in enumerate(legs):
+            try:
+                body.append(build_order_body(**leg))
+            except TypeError as e:
+                raise TypeError(f"leg {index}: {e}") from None
+        # Not retried on 429: only a GET may opt in (see get_order_margin).
+        return self._request(  # type: ignore[no-any-return]
+            "POST", "/v1/margins/basket", json={"legs": body}, timeout=timeout
+        )

sahiapi/sahi/http.py

@@ -0,0 +1,301 @@
+"""The HTTP core shared by every REST call.
+
+:class:`HttpClient` wraps a single :class:`httpx.Client`. It owns the concerns
+that are identical for every endpoint so the domain modules stay a thin list of
+methods:
+
+* the base URL and, optionally, the ``Authorization: Bearer`` header,
+* a ``User-Agent`` and a per-request ``X-Request-Id``,
+* turning a non-2xx response into the right :class:`SahiAPIException` via
+  :func:`exception_for`, carrying the server's request id,
+* a deliberately minimal retry policy.
+
+Retries are conservative on purpose. A ``GET`` that hits ``429`` with a short
+``Retry-After`` is retried once, because reads are idempotent and the header
+tells us exactly how long to wait. The wait is capped: the API's rate limits
+include per-minute and per-day windows whose ``Retry-After`` can run to hours,
+and a library call must never block that long on the caller's behalf — those
+are raised for the caller to decide. Nothing else is retried: an order write
+must never be sent twice, and the auth host sends no ``Retry-After`` anyway.
+The core enforces this: opting anything but a ``GET`` into the retry raises
+:class:`SahiConfigurationException` before the request is sent.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+import uuid
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from . import exceptions
+from .exceptions import exception_for
+
+__all__ = ["HttpClient"]
+
+_REQUEST_ID_HEADER = "X-Request-Id"
+
+# Longest Retry-After the single automatic retry will honour. Covers the
+# per-second windows a burst of reads trips; longer waits come from the
+# per-minute or per-day windows and are the caller's decision.
+_MAX_AUTO_RETRY_SECONDS = 5
+
+# How long an idle pooled connection is kept. httpx's default is 5s, which makes
+# a client that polls every 30s, or idles between signals and then places an
+# order, pay a fresh TCP and TLS handshake on the call that matters most. Keep
+# this below the API host's load-balancer idle timeout so pooled connections are
+# never stale.
+_KEEPALIVE_EXPIRY_SECONDS = 30.0
+
+
+def _sdk_version() -> str:
+    # Reuse the package's resolved __version__ rather than looking it up again.
+    # Imported lazily to avoid a cycle: this module is imported while the package
+    # __init__ is still executing.
+    from sahiapi import __version__
+
+    return __version__
+
+
+def _user_agent() -> str:
+    py = f"{sys.version_info.major}.{sys.version_info.minor}"
+    return f"sahiapi/{_sdk_version()} python/{py}"
+
+
+def _new_request_id() -> str:
+    """A per-request id, prefixed so it is recognisable in server logs."""
+    return f"sahiapi-{uuid.uuid4().hex}"
+
+
+def _parse_retry_after(value: str | None) -> int | None:
+    """Parse a ``Retry-After`` header expressed in whole seconds."""
+    if not value:
+        return None
+    try:
+        return int(value.strip())
+    except ValueError:
+        return None
+
+
+def _auto_retry_wait(error: exceptions.SahiAPIException) -> int | None:
+    """Seconds to wait before the automatic retry, or ``None`` if ``error`` gets none.
+
+    Only a ``429`` whose ``Retry-After`` is at most ``_MAX_AUTO_RETRY_SECONDS``
+    is waited out on the caller's behalf.
+    """
+    if not isinstance(error, exceptions.SahiRateLimitException):
+        return None
+    if error.retry_after is None or error.retry_after > _MAX_AUTO_RETRY_SECONDS:
+        return None
+    return error.retry_after
+
+
+class HttpClient:
+    """A configured HTTP client for one Sahi host.
+
+    Args:
+        base_url: The host base URL, without a trailing slash.
+        host: Which host this is — :data:`sahiapi.sahi.exceptions.HOST_API` or
+            ``HOST_AUTH`` — so errors map to the right class.
+        access_token: Bearer token to send on every request. ``None`` for the
+            auth host, whose token endpoint takes no ``Authorization`` header.
+        timeout: Default timeout in seconds. httpx applies it to each phase of
+            a request separately (connect, write, read, pool), so it bounds no
+            single phase to more than this, not the call as a whole.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        host: exceptions.Host,
+        access_token: str | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        self._host = host
+        self._default_timeout = timeout
+        headers = {
+            "User-Agent": _user_agent(),
+            "Accept": "application/json",
+        }
+        if access_token is not None:
+            headers["Authorization"] = f"Bearer {access_token}"
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+            limits=httpx.Limits(keepalive_expiry=_KEEPALIVE_EXPIRY_SECONDS),
+        )
+
+    # -- lifecycle ------------------------------------------------------------
+
+    def set_access_token(self, access_token: str) -> None:
+        """Replace the Bearer token used on subsequent requests."""
+        self._client.headers["Authorization"] = f"Bearer {access_token}"
+
+    def close(self) -> None:
+        """Close the underlying connection pool."""
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # -- requests -------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        timeout: float | None = None,
+        retry_on_rate_limit: bool = False,
+    ) -> Any:
+        """Send a request and return the parsed JSON body.
+
+        Args:
+            method: HTTP method.
+            path: Path relative to the host base URL (for example ``/v1/orders``).
+            params: Query parameters. Sequence values become repeated params.
+            json: JSON body to send.
+            timeout: Per-call timeout override, per phase like the client
+                default; falls back to the client default.
+            retry_on_rate_limit: When true, a single retry is made on a ``429``
+                whose ``Retry-After`` is at most ``_MAX_AUTO_RETRY_SECONDS``.
+                Only a ``GET`` may opt in; anything else is refused.
+
+        Returns:
+            The decoded JSON body, or ``None`` for an empty ``204`` response.
+
+        Raises:
+            SahiConfigurationException: If ``retry_on_rate_limit`` is set on a
+                method other than ``GET``.
+            SahiConnectionException: If the connection could not be opened.
+            SahiTimeoutException: If the request timed out.
+            SahiAPIException: For any non-2xx response, as the matching
+                subclass, or for a 2xx whose body is not JSON.
+        """
+        if retry_on_rate_limit and method.upper() != "GET":
+            raise exceptions.SahiConfigurationException(
+                f"retry_on_rate_limit is only allowed on GET, not {method.upper()} {path}: "
+                "a retried write could be applied twice."
+            )
+        request_id = _new_request_id()
+        headers = {_REQUEST_ID_HEADER: request_id}
+        effective_timeout = self._default_timeout if timeout is None else timeout
+
+        attempted_retry = False
+        while True:
+            response = self._send_once(
+                method,
+                path,
+                params=params,
+                json=json,
+                headers=headers,
+                timeout=effective_timeout,
+                request_id=request_id,
+            )
+            if response.is_success:
+                return self._decode(response, request_id)
+
+            error = self._error_from(response, request_id)
+            if retry_on_rate_limit and not attempted_retry:
+                wait = _auto_retry_wait(error)
+                if wait is not None:
+                    attempted_retry = True
+                    self._sleep(wait)
+                    continue
+            raise error
+
+    # -- helpers --------------------------------------------------------------
+
+    def _send_once(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None,
+        json: Any,
+        headers: dict[str, str],
+        timeout: float,
+        request_id: str,
+    ) -> httpx.Response:
+        """Send one attempt, mapping httpx's transport errors to Sahi exceptions."""
+        try:
+            return self._client.request(
+                method,
+                path,
+                params=params,
+                json=json,
+                headers=headers,
+                timeout=timeout,
+            )
+        except (httpx.ConnectError, httpx.ConnectTimeout) as e:  # DNS, refused, TLS
+            raise exceptions.SahiConnectionException(
+                f"could not connect to {self._client.base_url}: {e}. "
+                "Check network access and the base URL.",
+                request_id=request_id,
+            ) from e
+        except httpx.TimeoutException as e:
+            raise exceptions.SahiTimeoutException("request timed out", request_id=request_id) from e
+        except httpx.HTTPError as e:  # protocol errors after the connection opened
+            raise exceptions.SahiAPIException(
+                f"could not complete the request to {self._client.base_url}: {e}.",
+                request_id=request_id,
+            ) from e
+
+    @staticmethod
+    def _decode(response: httpx.Response, request_id: str) -> Any:
+        if response.status_code == 204 or not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError as e:
+            # A 2xx that is not JSON: typically a proxy or WAF interstitial.
+            raise exceptions.SahiAPIException(
+                f"expected a JSON body but got {response.headers.get('content-type', 'unknown')} "
+                f"with status {response.status_code}",
+                status=response.status_code,
+                request_id=response.headers.get(_REQUEST_ID_HEADER) or request_id,
+            ) from e
+
+    def _error_from(self, response: httpx.Response, request_id: str) -> exceptions.SahiAPIException:
+        code: str | None = None
+        message: str | None = None
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                raw_code = body.get("code")
+                # A gateway may send a numeric code; the mapper needs a string.
+                code = raw_code if isinstance(raw_code, str) else None
+                message = body.get("message")
+        except ValueError:
+            message = response.text or None
+
+        server_request_id = response.headers.get(_REQUEST_ID_HEADER) or request_id
+        retry_after = _parse_retry_after(response.headers.get("Retry-After"))
+        return exception_for(
+            response.status_code,
+            host=self._host,
+            code=code,
+            message=message,
+            request_id=server_request_id,
+            retry_after=retry_after,
+        )
+
+    @staticmethod
+    def _sleep(seconds: float) -> None:
+        # Kept as its own method so the wait can be substituted.
+        time.sleep(seconds)