sahiapi 0.1.0__tar.gz

sahiapi-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Environments
+.venv/
+venv/
+.env
+.env.uat
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Packaging / locks kept, editor noise dropped
+.DS_Store
+.idea/
+.vscode/
+
+# slop-mop working directory (machine-local state)
+.slopmop/

sahiapi-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/) once it reaches `1.0.0`.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+
+### Added
+- Initial SDK: authentication (`SahiAPI.from_credentials` for the one-call path,
+  `get_access_token` + `SahiAPI(token)` for a shared token, rotation via
+  `set_access_token`), and full REST coverage — orders, portfolio, funds,
+  account, market data (with `get_candle_history`) and the scrip master.
+- `SahiFeed` for the two WebSocket streams: the protobuf tick stream (LTP, quote,
+  depth) and JSON order updates, with reconnect, subscription replay and a local
+  tick cache whose reads raise the stream's error once it has closed fatally.
+- A typed exception hierarchy mapped from `(status, host, code)`. Every API
+  exception (`SahiAPIException`) carries the server `status`, `code`,
+  `message`, a `request_id` and an actionable `hint`, all included in `str()`;
+  a feed exception carries the WebSocket `close_code` instead.
+- Every wire enum as a constant and `SahiAPI` class attribute.
+- `on_connect` on the order stream for the API's Stream + Snapshot bootstrap;
+  transparent reconnect on heartbeat (4408) and slow-consumer (4409) drops.
+- Packaging, CI (ruff, mypy strict, pytest on Python 3.9–3.13) and a
+  trusted-publishing release workflow.
+
+[Unreleased]: https://github.com/aarityatech/sahi-python/compare/sahiapi/v0.1.0...HEAD
+[0.1.0]: https://github.com/aarityatech/sahi-python/releases/tag/sahiapi/v0.1.0

sahiapi-0.1.0/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.

sahiapi-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,57 @@
+# 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/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sahiapi"
+# Taken from the release tag (sahiapi/v0.2.0, sahiapi/v0.2.0-rc.1) at build time;
+# see [tool.hatch.version] and tools/release.sh.
+dynamic = ["version"]
+description = "The official Python client library for the Sahi APIs."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Aaritya Technologies" }]
+keywords = ["sahi", "trading", "stocks", "options", "market-data", "nse", "bse"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "websocket-client>=1.7",
+    "protobuf>=4.25",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+# Development-only tooling. PEP 735 groups are not part of the published
+# metadata, and uv installs the "dev" group by default on `uv sync`.
+[dependency-groups]
+dev = [
+    "sahiapi-uat",
+]
+
+[tool.uv.sources]
+sahiapi-uat = { path = "tools/sahiapi_uat" }
+
+[project.urls]
+Homepage = "https://docs.sahi.com/"
+Documentation = "https://docs.sahi.com/"
+Repository = "https://github.com/aarityatech/sahi-python"
+
+[tool.hatch.version]
+source = "vcs"
+# Only sahiapi/v* tags carry a version; "-rc.N" normalizes to the PEP 440 "rcN".
+tag-pattern = "^sahiapi/v(?P<version>.+)$"
+# A shallow clone or a tarball has no tags to read.
+fallback-version = "0.0.0"
+
+[tool.hatch.version.raw-options]
+git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "sahiapi/v*"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sahiapi"]
+
+# The sdist goes to PyPI too: ship the package and its docs, not the internal
+# tooling (tools/sahiapi_uat and its .pth hook), the tests or the CI files.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/sahiapi", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W", "N", "RUF"]
+# N818 wants an "Error" suffix on exceptions; the public hierarchy uses the
+# "Exception" suffix throughout by design, so this stays a deliberate choice.
+ignore = ["N818"]
+
+[tool.ruff.lint.per-file-ignores]
+# Generated protobuf code is not ours to lint.
+"src/sahiapi/sahi/proto/*_pb2.py" = ["ALL"]
+
+# The package runs on 3.9+ (guarded by the CI test matrix); mypy itself only
+# analyses at 3.10 and up, and `from __future__ import annotations` keeps modern
+# union syntax valid at 3.9 runtime.
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/sahiapi"]
+# Generated protobuf modules ship without stubs.
+[[tool.mypy.overrides]]
+module = ["sahiapi.sahi.proto.*"]
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

sahiapi-0.1.0/src/sahiapi/__init__.py

@@ -0,0 +1,88 @@
+"""sahiapi — the official Python client for the Sahi APIs.
+
+The public interface lives here. Everything under :mod:`sahiapi.sahi` is
+internal and may change without notice.
+
+    from sahiapi import SahiAPI
+
+    api = SahiAPI.from_credentials(key_id="...", secret="...")
+    print(api.get_profile())
+
+The SDK mirrors the API reference at https://docs.sahi.com/ exactly: it does
+not rename fields, build models, or convert units. Money is integer paise,
+quantities are integer units, timestamps are epoch milliseconds, and identifiers
+are opaque strings.
+"""
+
+from __future__ import annotations
+
+from .sahi import constants
+from .sahi.auth import get_access_token, token_expires_at, token_scopes
+from .sahi.client import SahiAPI
+from .sahi.constants import *  # noqa: F403 -- re-export every wire constant
+from .sahi.exceptions import (
+    SahiAccountLockedException,
+    SahiAPIException,
+    SahiAuthenticationException,
+    SahiAuthorisationException,
+    SahiBadRequestException,
+    SahiBaseException,
+    SahiConfigurationException,
+    SahiConnectionException,
+    SahiFeedAuthExpiredException,
+    SahiFeedConnectionException,
+    SahiFeedException,
+    SahiFeedForbiddenException,
+    SahiFeedNotSubscribedException,
+    SahiInvalidOrderStateException,
+    SahiIpNotAllowedException,
+    SahiKeyNotApprovedException,
+    SahiNotFoundException,
+    SahiOrderNotFoundException,
+    SahiRateLimitException,
+    SahiServerException,
+    SahiTimeoutException,
+    SahiValidationException,
+)
+from .sahi.feed import SahiFeed
+
+try:  # pragma: no cover - trivial metadata lookup
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("sahiapi")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    # Client and authentication
+    "SahiAPI",
+    "SahiAPIException",
+    "SahiAccountLockedException",
+    "SahiAuthenticationException",
+    "SahiAuthorisationException",
+    "SahiBadRequestException",
+    "SahiBaseException",
+    "SahiConfigurationException",
+    "SahiConnectionException",
+    "SahiFeed",
+    "SahiFeedAuthExpiredException",
+    "SahiFeedConnectionException",
+    "SahiFeedException",
+    "SahiFeedForbiddenException",
+    "SahiFeedNotSubscribedException",
+    "SahiInvalidOrderStateException",
+    "SahiIpNotAllowedException",
+    "SahiKeyNotApprovedException",
+    "SahiNotFoundException",
+    "SahiOrderNotFoundException",
+    "SahiRateLimitException",
+    "SahiServerException",
+    "SahiTimeoutException",
+    "SahiValidationException",
+    "__version__",
+    "constants",
+    "get_access_token",
+    "token_expires_at",
+    "token_scopes",
+]
+__all__ += list(constants.__all__)

sahiapi-0.1.0/src/sahiapi/sahi/account.py

@@ -0,0 +1,28 @@
+"""Account endpoint: profile.
+
+Mirrors the Account page of the API reference. ``get_profile`` needs the
+``profile.read`` scope. Read it once at start of day; it does not change during a
+session.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import EndpointGroup
+
+__all__ = ["_Account"]
+
+
+class _Account(EndpointGroup):
+    """Account methods mixed into :class:`SahiAPI`."""
+
+    def get_profile(self, *, timeout: float | None = None) -> dict[str, Any]:
+        """Return your identity and account status (``GET /v1/profile``).
+
+        Returns:
+            ``{"user_id": ..., "name": ...}``.
+        """
+        return self._request(  # type: ignore[no-any-return]
+            "GET", "/v1/profile", timeout=timeout, retry_on_rate_limit=True
+        )

sahiapi-0.1.0/src/sahiapi/sahi/auth.py

@@ -0,0 +1,163 @@
+"""Authentication: minting an access token and reading what it carries.
+
+A Sahi access token is minted from an API key. You create the key in your Sahi
+account, approve it for the trading day, and exchange the key id and secret for a
+token with :func:`get_access_token`. The token is a Bearer JWT that every REST
+and WebSocket call carries, and it expires at 06:00 IST — there is no refresh, so
+mint a fresh one each trading day.
+
+The helpers here also read a token's own claims without verifying its signature,
+to tell callers when a token expires and what it is allowed to do. They are for
+information only: the SDK never refuses a request on them, and the server is
+always the authority.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from . import env
+from .exceptions import HOST_AUTH, SahiConfigurationException
+from .http import HttpClient
+
+__all__ = [
+    "decode_token_payload",
+    "expiry_from_payload",
+    "get_access_token",
+    "scopes_from_payload",
+    "token_expires_at",
+    "token_scopes",
+]
+
+_TOKEN_PATH = "/api/v1/apikeys/token"
+
+
+def get_access_token(
+    key_id: str,
+    secret: str,
+    *,
+    scopes: list[str] | None = None,
+    timeout: float = 10.0,
+) -> dict[str, Any]:
+    """Exchange an API key for a short-lived access token.
+
+    Calls ``POST /api/v1/apikeys/token`` on the auth host and returns the token
+    response as-is.
+
+    Args:
+        key_id: The key id from your Sahi account.
+        secret: The secret shown once when the key was created.
+        scopes: Optional subset of the key's scopes to narrow the token to. A
+            token can only ever carry scopes the key holds. Omit it, or pass an
+            empty list, to get the key's full set.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        The token response dict, unchanged: ``access_token``, ``token_type``,
+        ``expires_in``, ``expires_at`` and ``scope``.
+
+    The key id and secret are sent as given: their format is the auth server's
+    to define, so the SDK does not check it.
+
+    Raises:
+        SahiAuthenticationException: Unknown key id, wrong secret, or a revoked
+            key (401 — deliberately indistinguishable).
+        SahiAccountLockedException: The account is frozen or locked.
+        SahiKeyNotApprovedException: The key is not approved for the current
+            trading day.
+        SahiBadRequestException: A field is malformed, or ``scopes`` is not a
+            subset of the key's scopes.
+        SahiRateLimitException: Too many mint attempts; wait for the next minute.
+    """
+    body: dict[str, Any] = {"key_id": key_id, "secret": secret}
+    if scopes is not None:
+        body["scopes"] = scopes
+
+    with HttpClient(env.AUTH_BASE_URL, host=HOST_AUTH, timeout=timeout) as client:
+        result = client.request("POST", _TOKEN_PATH, json=body)
+    return result  # type: ignore[no-any-return]  # token endpoint returns a JSON object
+
+
+def decode_token_payload(access_token: str) -> dict[str, Any]:
+    """Decode a JWT's payload claims without verifying the signature.
+
+    This reads what the token asserts about itself; it does not check that the
+    assertions are trustworthy. The server verifies the signature on every call.
+
+    Raises:
+        SahiConfigurationException: If the value is not a decodable JWT.
+    """
+    parts = access_token.split(".")
+    if len(parts) != 3:
+        raise SahiConfigurationException("access token is not a well-formed JWT")
+    payload_segment = parts[1]
+    padding = "=" * (-len(payload_segment) % 4)
+    try:
+        raw = base64.urlsafe_b64decode(payload_segment + padding)
+        payload = json.loads(raw)
+    except (binascii.Error, ValueError) as e:
+        raise SahiConfigurationException("could not decode the access token payload") from e
+    if not isinstance(payload, dict):
+        raise SahiConfigurationException("access token payload is not a JSON object")
+    return payload
+
+
+def expiry_from_payload(payload: dict[str, Any]) -> datetime | None:
+    """The ``exp`` claim as a timezone-aware UTC datetime, or ``None`` if absent.
+
+    Raises:
+        SahiConfigurationException: If ``exp`` is present but is not a number
+            of epoch seconds that fits in a datetime — a token minted by
+            something other than Sahi.
+    """
+    exp = payload.get("exp")
+    if exp is None:
+        return None
+    # bool is an int subclass; a literal true/false is not an epoch time.
+    if isinstance(exp, bool) or not isinstance(exp, (int, float)):
+        raise SahiConfigurationException(
+            f"access token 'exp' claim must be epoch seconds, got {type(exp).__name__}. "
+            "Use a token minted by get_access_token()."
+        )
+    try:
+        return datetime.fromtimestamp(exp, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError) as e:
+        raise SahiConfigurationException(
+            "access token 'exp' claim is out of range for an epoch time. "
+            "Use a token minted by get_access_token()."
+        ) from e
+
+
+def scopes_from_payload(payload: dict[str, Any]) -> frozenset[str]:
+    """The ``scope`` claim split on whitespace; an absent or empty claim is ``frozenset()``."""
+    scope = payload.get("scope")
+    if not scope or not isinstance(scope, str):
+        return frozenset()
+    return frozenset(scope.split())
+
+
+def token_expires_at(access_token: str) -> datetime | None:
+    """Return the token's expiry as a timezone-aware UTC datetime.
+
+    Reads the ``exp`` claim. Returns ``None`` if the token carries no ``exp``.
+
+    Raises:
+        SahiConfigurationException: If the value is not a decodable JWT, or its
+            ``exp`` is not an epoch time.
+    """
+    return expiry_from_payload(decode_token_payload(access_token))
+
+
+def token_scopes(access_token: str) -> frozenset[str]:
+    """Return the scopes the token carries, from its ``scope`` claim.
+
+    The claim is a space-separated string; an absent claim yields an empty set.
+
+    Raises:
+        SahiConfigurationException: If the value is not a decodable JWT.
+    """
+    return scopes_from_payload(decode_token_payload(access_token))

sahiapi-0.1.0/src/sahiapi/sahi/base.py

@@ -0,0 +1,32 @@
+"""Shared base for the per-domain endpoint groups.
+
+Each docs page maps to a mixin (``_Orders``, ``_Portfolio``, …) that lists the
+methods for that page. :class:`SahiAPI` inherits all of them, so the user sees
+one flat class while each file stays focused on a single resource. Every mixin
+subclasses :class:`EndpointGroup`, which declares the ``_request`` method the
+mixins call. :class:`SahiAPI` provides the real implementation; this base gives
+the mixins a typed reference to it and keeps them independent of the client
+module, so there is no import cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["EndpointGroup"]
+
+
+class EndpointGroup:
+    """Base for domain mixins. ``SahiAPI`` supplies the real ``_request``."""
+
+    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:  # pragma: no cover - overridden by SahiAPI
+        raise NotImplementedError