sahiapi 0.2.0__tar.gz → 0.3.0__tar.gz

{sahiapi-0.2.0 → sahiapi-0.3.0}/CHANGELOG.md

@@ -6,6 +6,18 @@ follow [Semantic Versioning](https://semver.org/) once it reaches `1.0.0`.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-28
+
+### Added
+- TOTP keys: `SahiAPI.from_credentials` and `get_access_token` take `totp`, the
+  key's current six-digit authenticator code, which doubles as the day's
+  approval. A wrong code raises `SahiInvalidTotpException`, carrying the
+  server's `server_time` for clock comparison.
+
+### Changed
+- The `SahiKeyNotApprovedException` hint also covers an account that does not
+  have API keys enabled yet. A TOTP key gets this exception only for that reason.
+
 ## [0.2.0] - 2026-10-22
 
 First public release. Includes everything listed under 0.1.0.
@@ -64,6 +76,7 @@ Pre-launch placeholder; yanked on PyPI. Use 0.2.0 or later.
 - 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.2.0...HEAD
+[Unreleased]: https://github.com/aarityatech/sahi-python/compare/sahiapi/v0.3.0...HEAD
+[0.3.0]: https://github.com/aarityatech/sahi-python/compare/sahiapi/v0.2.0...sahiapi/v0.3.0
 [0.2.0]: https://github.com/aarityatech/sahi-python/compare/sahiapi/v0.1.0...sahiapi/v0.2.0
 [0.1.0]: https://github.com/aarityatech/sahi-python/releases/tag/sahiapi/v0.1.0

{sahiapi-0.2.0 → sahiapi-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sahiapi
-Version: 0.2.0
+Version: 0.3.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/sdk/python/
@@ -85,6 +85,9 @@ print(api.get_profile())
 print(api.get_funds())
 ```
 
+For a TOTP key, also pass the current authenticator code as `totp`. See
+[Mint with a TOTP key](https://docs.sahi.com/sdk/python/authentication/#mint-with-a-totp-key).
+
 ### Example: place a limit order
 
 Prices are in paise, so ₹2,499.55 is `249955`.

{sahiapi-0.2.0 → sahiapi-0.3.0}/README.md

@@ -53,6 +53,9 @@ print(api.get_profile())
 print(api.get_funds())
 ```
 
+For a TOTP key, also pass the current authenticator code as `totp`. See
+[Mint with a TOTP key](https://docs.sahi.com/sdk/python/authentication/#mint-with-a-totp-key).
+
 ### Example: place a limit order
 
 Prices are in paise, so ₹2,499.55 is `249955`.

{sahiapi-0.2.0 → sahiapi-0.3.0}/src/sahiapi/__init__.py

@@ -35,6 +35,7 @@ from .sahi.exceptions import (
     SahiFeedForbiddenException,
     SahiFeedNotSubscribedException,
     SahiInvalidOrderStateException,
+    SahiInvalidTotpException,
     SahiIpNotAllowedException,
     SahiKeyNotApprovedException,
     SahiMaintenanceException,
@@ -72,6 +73,7 @@ __all__ = [
     "SahiFeedForbiddenException",
     "SahiFeedNotSubscribedException",
     "SahiInvalidOrderStateException",
+    "SahiInvalidTotpException",
     "SahiIpNotAllowedException",
     "SahiKeyNotApprovedException",
     "SahiMaintenanceException",

{sahiapi-0.2.0 → sahiapi-0.3.0}/src/sahiapi/sahi/auth.py

@@ -1,10 +1,13 @@
 """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.
+A Sahi access token is minted from an API key with :func:`get_access_token`.
+A REGULAR key is approved for the trading day in your Sahi account and then
+exchanges its key id and secret for a token. A TOTP key skips the daily click:
+its six-digit authenticator code goes with the key id and secret, and the first
+correct code of the day is that day's approval, so a strategy can mint
+unattended. 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
@@ -40,6 +43,7 @@ def get_access_token(
     key_id: str,
     secret: str,
     *,
+    totp: str | None = None,
     scopes: list[str] | None = None,
     timeout: float = 10.0,
 ) -> dict[str, Any]:
@@ -51,6 +55,11 @@ def get_access_token(
     Args:
         key_id: The key id from your Sahi account.
         secret: The secret shown once when the key was created.
+        totp: The current six-digit code for a TOTP key, from the authenticator
+            enrolled when the key was created. Required for a TOTP key and
+            refused for a REGULAR one. The SDK never holds the TOTP secret:
+            generate the code yourself (for example with ``pyotp``) and pass it
+            in, so the TOTP secret stays wherever you keep it.
         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.
@@ -60,20 +69,28 @@ def get_access_token(
         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.
+    The key id, secret and code 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).
+            key (401). The message names a revoked key; the other two read the same.
+        SahiInvalidTotpException: The secret was right but the TOTP code was
+            not; carries the server's clock for comparison.
         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.
+        SahiKeyNotApprovedException: A REGULAR key not approved for the current
+            trading day, or any key whose account does not have API keys
+            enabled yet.
+        SahiBadRequestException: A field is malformed, ``scopes`` is not a
+            subset of the key's scopes, ``totp`` is missing or not six digits
+            for a TOTP key, or ``totp`` was sent for a REGULAR key.
+        SahiRateLimitException: Too many mint attempts, or ten wrong TOTP codes
+            within a minute; wait for the next minute.
     """
     body: dict[str, Any] = {"key_id": key_id, "secret": secret}
+    # Absent when not given: the server reads a missing, null or empty code the same way.
+    if totp is not None:
+        body["totp"] = totp
     if scopes is not None:
         body["scopes"] = scopes
 

{sahiapi-0.2.0 → sahiapi-0.3.0}/src/sahiapi/sahi/client.py

@@ -207,6 +207,7 @@ class SahiAPI(_Orders, _Portfolio, _Funds, _Account, _MarketData, _Instruments):
         key_id: str,
         secret: str,
         *,
+        totp: str | None = None,
         scopes: list[str] | None = None,
         scrip_master_url: str | None = None,
         timeout: float = 10.0,
@@ -222,11 +223,14 @@ class SahiAPI(_Orders, _Portfolio, _Funds, _Account, _MarketData, _Instruments):
         Args:
             key_id: The key id from your Sahi account.
             secret: The secret shown once at key creation.
+            totp: The current six-digit code for a TOTP key; its first correct
+                code of the day approves the key, so no dashboard click is
+                needed. Omit it for a REGULAR key.
             scopes: Optional subset of the key's scopes to narrow the token to.
             scrip_master_url: Scrip-master CSV URL, as on the constructor.
             timeout: Default per-request timeout in seconds, also used for the mint.
         """
-        token = auth.get_access_token(key_id, secret, scopes=scopes, timeout=timeout)
+        token = auth.get_access_token(key_id, secret, totp=totp, scopes=scopes, timeout=timeout)
         return cls(token, scrip_master_url=scrip_master_url, timeout=timeout)
 
     def set_access_token(self, token: Token) -> None:

{sahiapi-0.2.0 → sahiapi-0.3.0}/src/sahiapi/sahi/exceptions.py

@@ -38,6 +38,7 @@ __all__ = [
     "SahiFeedForbiddenException",
     "SahiFeedNotSubscribedException",
     "SahiInvalidOrderStateException",
+    "SahiInvalidTotpException",
     "SahiIpNotAllowedException",
     "SahiKeyNotApprovedException",
     "SahiMaintenanceException",
@@ -156,6 +157,46 @@ class SahiAccountLockedException(SahiAuthenticationException):
     hint = "The account is locked or frozen. Contact Sahi support to restore access."
 
 
+class SahiInvalidTotpException(SahiAuthenticationException):
+    """401 ``InvalidTotp``: the key id and secret were right but the TOTP code was not.
+
+    Raised only for a TOTP key, and only after the secret verified, so the
+    credentials themselves are fine. The code was wrong or came from a clock
+    more than one step (30 s) away from the server's. Ten wrong codes in a
+    minute turn into :class:`SahiRateLimitException`.
+
+    Attributes:
+        server_time: The server's clock at the refusal, as the RFC 3339 string
+            it sent, or ``None`` if the envelope carried none. Compare it with
+            this host's clock: drift is the usual cause of a code that looks
+            right in the authenticator app yet fails here.
+    """
+
+    hint = (
+        "Mint again with a fresh code from the key's authenticator. If it fails again, "
+        "compare this machine's clock with the server_time on the exception."
+    )
+
+    def __init__(
+        self,
+        message: str | None = None,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+        server_time: str | None = None,
+    ) -> None:
+        # Set before super().__init__: _render() runs there and reads it.
+        self.server_time = server_time
+        super().__init__(message, status=status, code=code, request_id=request_id)
+
+    def _render(self) -> str:
+        text = super()._render()
+        if self.server_time:
+            text = f"{text} [server_time={self.server_time}]"
+        return text
+
+
 class SahiAuthorisationException(SahiAPIException):
     """403: the token is valid but not permitted to do this.
 
@@ -174,9 +215,19 @@ class SahiKeyNotApprovedException(SahiAuthorisationException):
 
     Approval is a daily act and lapses at 06:00 IST; it is an exchange
     requirement, not something the SDK can bypass.
+
+    The auth host also answers 403 when API keys are not enabled for the
+    account. That check runs after the secret is verified but before the
+    TOTP code is read. So a TOTP key, whose code is its approval, lands here
+    only for that reason, and the server message says so; nothing done to the
+    key can fix it.
     """
 
-    hint = "Approve the key for today's trading day in your Sahi account, then mint again."
+    hint = (
+        "Approve the key for today's trading day in your Sahi account, then mint again. "
+        "If the message says API keys are not available for this account, the account "
+        "is not enabled yet; contact Sahi."
+    )
 
 
 class SahiIpNotAllowedException(SahiAuthorisationException):
@@ -361,6 +412,7 @@ def exception_for(
     request_id: str | None = None,
     retry_after: int | None = None,
     envelope: bool = True,
+    server_time: str | None = None,
 ) -> SahiAPIException:
     """Build the right :class:`SahiAPIException` for a non-2xx response.
 
@@ -386,6 +438,8 @@ def exception_for(
             would hand the user a scope or key hint for a problem that is the
             request's size, so it comes back as the base class with a message
             that says where it was refused.
+        server_time: The envelope's ``server_time``, which only a wrong TOTP
+            code carries; ignored for every other class.
 
     Returns:
         An unraised exception instance for the caller to raise.
@@ -416,6 +470,10 @@ def exception_for(
         return build(SahiAccountLockedException)
     if key == "UNDERMAINTENANCE":
         return build(SahiMaintenanceException)
+    if key == "INVALIDTOTP":
+        return SahiInvalidTotpException(
+            message, status=status, code=code, request_id=request_id, server_time=server_time
+        )
 
     if status == 400:
         return build(SahiBadRequestException)

{sahiapi-0.2.0 → sahiapi-0.3.0}/src/sahiapi/sahi/http.py

@@ -275,6 +275,7 @@ class HttpClient:
         code: str | None = None
         message: str | None = None
         envelope = True
+        server_time: str | None = None
         try:
             body = response.json()
             if isinstance(body, dict):
@@ -282,6 +283,10 @@ class HttpClient:
                 # 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")
+                # Only a wrong TOTP code carries it; kept verbatim so a caller
+                # can compare clocks without the SDK parsing a timestamp.
+                raw_time = body.get("server_time")
+                server_time = raw_time if isinstance(raw_time, str) else None
         except ValueError:
             # HTML or plain text: the edge answered, not the API.
             envelope = False
@@ -297,6 +302,7 @@ class HttpClient:
             request_id=server_request_id,
             retry_after=retry_after,
             envelope=envelope,
+            server_time=server_time,
         )
 
     @staticmethod