stx-python 0.6.0rc1__py3-none-any.whl

stx/enums.py

@@ -0,0 +1,13 @@
+"""Region and environment names accepted by the clients."""
+
+from enum import Enum
+
+
+class Region(str, Enum):
+    US = "us"
+    ONTARIO = "ontario"
+
+
+class Environment(str, Enum):
+    PRODUCTION = "production"
+    DEMO = "demo"

stx/exceptions.py

@@ -0,0 +1,156 @@
+"""Exceptions raised by the SDK.
+
+REST errors arrive as ``{"error": "<message>"}`` with an HTTP status. The
+status picks the exception class; the message is kept verbatim on
+``.message`` (and ``str(exc)``), and the status on ``.status_code``.
+
+========  ===================================  =========================
+Status    Meaning                              Exception
+========  ===================================  =========================
+400       Bad parameters                       STXValidationException
+401       Missing or invalid signature         STXAuthenticationException
+403       Read-only key or account state       STXForbiddenException
+404       Not found, or not yours              STXNotFoundException
+422       Rejected by the exchange             STXRejectedException
+429       Rate limited                         STXRateLimitException
+5xx       Server error                         STXServerException
+========  ===================================  =========================
+
+Network failures (connection refused, timeouts, TLS) raise
+``STXTransportException``. Socket-level problems (a join the server
+refused, a channel reply with ``status: error``) raise
+``STXChannelException``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class STXException(Exception):
+    """Base for every error the SDK raises."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Any = None,
+        method: Optional[str] = None,
+        path: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+        self.method = method
+        self.path = path
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class STXConfigException(STXException):
+    """The client is misconfigured: unknown region, missing key, bad PEM."""
+
+
+class STXAPIException(STXException):
+    """The API answered with an error status. Base for the classes below."""
+
+
+class STXValidationException(STXAPIException):
+    """400: a parameter or body field was rejected, e.g. ``price is required``."""
+
+
+class STXAuthenticationException(STXAPIException):
+    """401: the signature, key id or timestamp was not accepted.
+
+    A machine clock more than 30 seconds off also lands here.
+    """
+
+
+class STXForbiddenException(STXAPIException):
+    """403: the key is read-only, or the account may not do this."""
+
+
+class STXNotFoundException(STXAPIException):
+    """404: the resource does not exist, or belongs to another account."""
+
+
+class STXRejectedException(STXAPIException):
+    """422: the exchange refused the request, e.g. insufficient funds or a
+    closed market."""
+
+
+class STXRateLimitException(STXAPIException):
+    """429: too many requests. ``retry_after`` is seconds, when sent."""
+
+    def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class STXServerException(STXAPIException):
+    """5xx: the server failed. Retried by the default policy."""
+
+
+class STXTransportException(STXException):
+    """The request never got an answer: connection, DNS, TLS or timeout."""
+
+
+class STXChannelException(STXException):
+    """A channel join or channel message was refused by the server.
+
+    ``reply`` holds the server's ``response`` object, for example
+    ``{"reason": "unauthorized"}``.
+    """
+
+    def __init__(self, message: str, *, topic: str = "", reply: Any = None) -> None:
+        super().__init__(message)
+        self.topic = topic
+        self.reply = reply
+
+
+_STATUS_MAP = {
+    400: STXValidationException,
+    401: STXAuthenticationException,
+    403: STXForbiddenException,
+    404: STXNotFoundException,
+    422: STXRejectedException,
+    429: STXRateLimitException,
+}
+
+
+def error_for_status(
+    status_code: int,
+    body: Any,
+    *,
+    method: str,
+    path: str,
+    retry_after: Optional[str] = None,
+) -> STXAPIException:
+    """Build the exception for one non-2xx response."""
+    # Message: the API's ``error`` string when the body has one, else the
+    # body text itself, else the status line.
+    if isinstance(body, dict) and isinstance(body.get("error"), str):
+        message = body["error"]
+    elif isinstance(body, str) and body.strip():
+        message = body.strip()[:500]
+    else:
+        message = f"HTTP {status_code}"
+    kwargs = {"status_code": status_code, "body": body, "method": method, "path": path}
+    if status_code == 429:
+        return STXRateLimitException(message, retry_after=_parse_retry_after(retry_after), **kwargs)
+    cls = _STATUS_MAP.get(status_code)
+    if cls is None:
+        cls = STXServerException if status_code >= 500 else STXAPIException
+    return cls(message, **kwargs)
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None