finance_dev 0.9.0__py3-none-any.whl

finance_dev/websocket/__init__.py

@@ -0,0 +1,57 @@
+"""Synchronous and asynchronous Aries WebSocket clients."""
+
+from .auth import (
+    AsyncCallbackTokenProvider,
+    AsyncClientCredentialsTokenProvider,
+    AsyncTokenProvider,
+    CallbackTokenProvider,
+    ClientCredentialsTokenProvider,
+    StaticTokenProvider,
+    TokenProvider,
+)
+from .config import WebSocketConfig
+from .errors import *
+from .models import *
+from .sdk import WebSocketSDK
+
+__all__ = [
+    "WebSocketSDK",
+    "WebSocketConfig",
+    "TokenProvider",
+    "AsyncTokenProvider",
+    "StaticTokenProvider",
+    "CallbackTokenProvider",
+    "AsyncCallbackTokenProvider",
+    "ClientCredentialsTokenProvider",
+    "AsyncClientCredentialsTokenProvider",
+    "AriesWebSocketError",
+    "WebSocketConfigurationError",
+    "WebSocketConnectionError",
+    "WebSocketConnectionStateError",
+    "WebSocketReconnectExhaustedError",
+    "WebSocketAuthenticationError",
+    "WebSocketRequestError",
+    "WebSocketProtocolError",
+    "WebSocketBackpressureError",
+    "MarketEvent",
+    "MarketSubscription",
+    "MarketUnsubscribe",
+    "QuoteData",
+    "TradeData",
+    "Level2Data",
+    "TimeAndSalesData",
+    "GreeksData",
+    "ChartEvent",
+    "ChartSubscription",
+    "TradingViewQuote",
+    "TradingViewQuoteValues",
+    "TradingViewTrade",
+    "AccountEvent",
+    "PnlEvent",
+    "TopicEvent",
+    "AccountSnapshot",
+    "AccountSubscription",
+    "NewsSubscription",
+    "PnlSubscription",
+    "WatchlistSubscription",
+]

finance_dev/websocket/account.py

@@ -0,0 +1,5 @@
+from .resources import AccountResource
+
+
+class AccountWebSocket(AccountResource):
+    pass

finance_dev/websocket/auth.py

@@ -0,0 +1,124 @@
+"""WebSocket access-token providers."""
+
+import asyncio
+import inspect
+import threading
+import time
+from typing import Callable, Protocol
+import httpx
+from .errors import WebSocketAuthenticationError
+
+
+class TokenProvider(Protocol):
+    def get_token(self) -> str: ...
+class AsyncTokenProvider(Protocol):
+    async def get_token(self) -> str: ...
+
+
+class StaticTokenProvider:
+    def __init__(self, token: str):
+        self.token = token
+
+    def get_token(self) -> str:
+        return self.token
+
+
+class CallbackTokenProvider:
+    def __init__(self, callback: Callable[[], str]):
+        self.callback = callback
+
+    def get_token(self) -> str:
+        return self.callback()
+
+
+class AsyncCallbackTokenProvider:
+    def __init__(self, callback):
+        self.callback = callback
+
+    async def get_token(self) -> str:
+        result = self.callback()
+        return await result if inspect.isawaitable(result) else result
+
+
+class ClientCredentialsTokenProvider:
+    def __init__(self, token_url: str, client_id: str, client_secret: str):
+        self.token_url, self.client_id, self.client_secret = (
+            token_url,
+            client_id,
+            client_secret,
+        )
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires = 0.0
+
+    def get_token(self) -> str:
+        with self._lock:
+            if self._token and time.monotonic() < self._expires - 30:
+                return self._token
+            try:
+                response = httpx.post(
+                    self.token_url,
+                    data={
+                        "grant_type": "client_credentials",
+                        "client_id": self.client_id,
+                        "client_secret": self.client_secret,
+                    },
+                    timeout=15,
+                )
+                data = response.json()
+                if response.is_error:
+                    raise WebSocketAuthenticationError(
+                        "Client credentials were rejected. For partner/business clients, supply a token obtained through Authorization Code or PKCE."
+                    )
+                token: str = data["access_token"]
+                self._token = token
+                self._expires = time.monotonic() + float(data.get("expires_in", 3600))
+                return token
+            except WebSocketAuthenticationError:
+                raise
+            except Exception as exc:
+                raise WebSocketAuthenticationError(
+                    "Unable to obtain websocket access token"
+                ) from exc
+
+
+class AsyncClientCredentialsTokenProvider:
+    def __init__(self, token_url, client_id, client_secret):
+        self.token_url, self.client_id, self.client_secret = (
+            token_url,
+            client_id,
+            client_secret,
+        )
+        self._lock = asyncio.Lock()
+        self._token = None
+        self._expires = 0.0
+
+    async def get_token(self):
+        async with self._lock:
+            if self._token and time.monotonic() < self._expires - 30:
+                return self._token
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.post(
+                        self.token_url,
+                        data={
+                            "grant_type": "client_credentials",
+                            "client_id": self.client_id,
+                            "client_secret": self.client_secret,
+                        },
+                        timeout=15,
+                    )
+                data = response.json()
+                if response.is_error:
+                    raise WebSocketAuthenticationError(
+                        "Client credentials were rejected. For partner/business clients, supply a token obtained through Authorization Code or PKCE."
+                    )
+                self._token = data["access_token"]
+                self._expires = time.monotonic() + float(data.get("expires_in", 3600))
+                return self._token
+            except WebSocketAuthenticationError:
+                raise
+            except Exception as exc:
+                raise WebSocketAuthenticationError(
+                    "Unable to obtain websocket access token"
+                ) from exc

finance_dev/websocket/chart.py

@@ -0,0 +1,5 @@
+from .resources import ChartResource
+
+
+class ChartWebSocket(ChartResource):
+    pass

finance_dev/websocket/codec.py

@@ -0,0 +1,66 @@
+"""JSON/NDJSON wire codec."""
+
+import json
+from typing import Any
+from .errors import WebSocketProtocolError
+from .models.common import (
+    EventMessage,
+    PingMessage,
+    PongMessage,
+    RequestMessage,
+    ResponseMessage,
+    SubscribeMessage,
+    SubscribedMessage,
+    UnknownMessage,
+    UnsubscribeMessage,
+)
+
+_MODELS = {
+    "request": RequestMessage,
+    "response": ResponseMessage,
+    "event": EventMessage,
+    "subscribe": SubscribeMessage,
+    "unsubscribe": UnsubscribeMessage,
+    "subscribed": SubscribedMessage,
+    "ping": PingMessage,
+    "pong": PongMessage,
+}
+
+
+def decode_frame(frame: str | bytes) -> list[Any]:
+    if isinstance(frame, bytes):
+        try:
+            frame = frame.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise WebSocketProtocolError(
+                "invalid UTF-8 websocket frame at line 1"
+            ) from exc
+    messages: list[Any] = []
+    for line_no, line in enumerate(frame.splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            value = json.loads(line)
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise WebSocketProtocolError(f"invalid JSON at line {line_no}") from exc
+        if not isinstance(value, dict):
+            raise WebSocketProtocolError(
+                f"JSON value must be an object at line {line_no}"
+            )
+        model_type: Any = _MODELS.get(str(value.get("type")))
+        if model_type is None:
+            messages.append(UnknownMessage(original=value))
+            continue
+        try:
+            messages.append(model_type.model_validate(value))
+        except Exception as exc:
+            raise WebSocketProtocolError(
+                f"invalid {value.get('type')} message at line {line_no}"
+            ) from exc
+    return messages
+
+
+def encode_message(message: Any) -> str:
+    if hasattr(message, "model_dump"):
+        message = message.model_dump(by_alias=True, exclude_none=True)
+    return json.dumps(message, separators=(",", ":"), ensure_ascii=False)

finance_dev/websocket/config.py

@@ -0,0 +1,52 @@
+"""WebSocket endpoint URLs and validated connection settings."""
+
+from dataclasses import dataclass
+import math
+from .errors import WebSocketConfigurationError
+
+MARKET_URL = "wss://api.aries.com/v1/market/ws"
+CHART_URL = "wss://api.aries.com/v1/charts/ws"
+ACCOUNT_URL = "wss://api.aries.com/v1/accounts/ws"
+
+
+@dataclass(frozen=True)
+class WebSocketConfig:
+    connect_timeout: float = 10.0
+    auth_timeout: float = 4.0
+    request_timeout: float = 10.0
+    ping_interval: float = 30.0
+    pong_timeout: float = 10.0
+    close_timeout: float = 10.0
+    reconnect: bool = True
+    replay_subscriptions: bool = True
+    reconnect_initial_delay: float = 1.0
+    reconnect_max_delay: float = 60.0
+    reconnect_jitter: float = 0.2
+    incoming_queue_size: int = 1000
+    max_message_size: int = 1_048_576
+
+    def __post_init__(self):
+        for key in (
+            "connect_timeout",
+            "auth_timeout",
+            "request_timeout",
+            "ping_interval",
+            "pong_timeout",
+            "close_timeout",
+            "reconnect_initial_delay",
+            "reconnect_max_delay",
+        ):
+            if not math.isfinite(getattr(self, key)) or getattr(self, key) <= 0:
+                raise WebSocketConfigurationError(f"{key} must be positive")
+        if self.reconnect_max_delay < self.reconnect_initial_delay:
+            raise WebSocketConfigurationError(
+                "reconnect_max_delay must be at least reconnect_initial_delay"
+            )
+        if not 0 <= self.reconnect_jitter <= 1:
+            raise WebSocketConfigurationError(
+                "reconnect_jitter must be between 0 and 1"
+            )
+        if self.incoming_queue_size < 1 or self.max_message_size < 1:
+            raise WebSocketConfigurationError(
+                "queue size and max_message_size must be positive"
+            )

finance_dev/websocket/errors.py

@@ -0,0 +1,54 @@
+"""Errors raised by Aries WebSocket clients."""
+
+import re
+
+_SECRET_PATTERN = re.compile(
+    r"(?i)(token|client[_-]?secret|authorization)(\s*[=:]\s*)([^\s,}\]]+)"
+)
+_BEARER_PATTERN = re.compile(r"(?i)(authorization\s*:\s*bearer\s+)[^\s,}\]]+")
+
+
+def _redact(message: str) -> str:
+    message = _BEARER_PATTERN.sub(r"\1[REDACTED]", message)
+    return _SECRET_PATTERN.sub(r"\1\2[REDACTED]", message)
+
+
+class AriesWebSocketError(Exception):
+    """Base class for websocket SDK failures."""
+
+    def __init__(self, message=""):
+        super().__init__(_redact(str(message)))
+
+
+class WebSocketConfigurationError(AriesWebSocketError):
+    pass
+
+
+class WebSocketConnectionError(AriesWebSocketError):
+    pass
+
+
+class WebSocketConnectionStateError(WebSocketConnectionError):
+    pass
+
+
+class WebSocketReconnectExhaustedError(WebSocketConnectionError):
+    pass
+
+
+class WebSocketAuthenticationError(AriesWebSocketError):
+    pass
+
+
+class WebSocketRequestError(AriesWebSocketError):
+    def __init__(self, message: str, *, status=None, code=None, request_id=None):
+        super().__init__(message)
+        self.status, self.code, self.request_id = status, code, request_id
+
+
+class WebSocketProtocolError(AriesWebSocketError):
+    pass
+
+
+class WebSocketBackpressureError(AriesWebSocketError):
+    pass

finance_dev/websocket/market.py

@@ -0,0 +1,5 @@
+from .resources import MarketResource
+
+
+class MarketWebSocket(MarketResource):
+    pass

finance_dev/websocket/models/__init__.py

@@ -0,0 +1,52 @@
+from .common import *
+from .market import (
+    GreeksData,
+    Level2Data,
+    MarketEvent,
+    MarketSubscription,
+    MarketUnsubscribe,
+    QuoteData,
+    TimeAndSalesData,
+    TradeData,
+)
+from .chart import (
+    ChartEvent,
+    ChartSubscription,
+    TradingViewQuote,
+    TradingViewQuoteValues,
+    TradingViewTrade,
+)
+from .account import (
+    AccountEvent,
+    AccountSnapshot,
+    AccountSubscription,
+    NewsSubscription,
+    PnlEvent,
+    PnlSubscription,
+    TopicEvent,
+    WatchlistSubscription,
+)
+
+__all__ = [
+    "MarketEvent",
+    "MarketSubscription",
+    "MarketUnsubscribe",
+    "QuoteData",
+    "TradeData",
+    "Level2Data",
+    "TimeAndSalesData",
+    "GreeksData",
+    "ChartEvent",
+    "ChartSubscription",
+    "TradingViewQuote",
+    "TradingViewQuoteValues",
+    "TradingViewTrade",
+    "AccountEvent",
+    "PnlEvent",
+    "TopicEvent",
+    "AccountSnapshot",
+    "AccountSubscription",
+    "NewsSubscription",
+    "PnlSubscription",
+    "WatchlistSubscription",
+]

finance_dev/websocket/models/account.py

@@ -0,0 +1,60 @@
+"""Account topic subscription models."""
+
+from datetime import datetime
+from typing import Any
+from pydantic import Field, field_validator
+from .common import WireModel
+
+
+class AccountSubscription(WireModel):
+    account_id: str = Field(alias="accountId")
+
+
+class PnlSubscription(WireModel):
+    account_id: str = Field(alias="accountId")
+    start_time: datetime | str
+    interval: str = "1m"
+
+    @field_validator("start_time")
+    @classmethod
+    def aware_start(cls, value):
+        if isinstance(value, datetime) and value.tzinfo is None:
+            raise ValueError("start_time must be timezone-aware")
+        if isinstance(value, str) and (
+            "T" not in value
+            or not (value.endswith("Z") or "+" in value[10:] or "-" in value[10:])
+        ):
+            raise ValueError("start_time must be an RFC3339 timestamp")
+        return value
+
+
+class WatchlistSubscription(WireModel):
+    pass
+
+
+class NewsSubscription(WireModel):
+    symbols: list[str] | None = None
+    topics: list[str] | None = None
+
+
+class AccountSnapshot(WireModel):
+    account: dict
+    positions: list[dict]
+    ordersV2: list[dict]
+
+
+class AccountEvent(WireModel):
+    topic: str = "account"
+    name: str
+    target: str | None = None
+    data: dict[str, Any]
+
+
+class PnlEvent(WireModel):
+    topic: str = "pnl"
+    data: dict[str, Any]
+
+
+class TopicEvent(WireModel):
+    topic: str
+    data: list[dict[str, Any]]

finance_dev/websocket/models/chart.py

@@ -0,0 +1,44 @@
+"""TradingView-compatible chart models."""
+
+from typing import Any
+from pydantic import Field
+from .common import WireModel
+
+
+class ChartSubscription(WireModel):
+    symbol: str
+    type: str = "quotes"
+    symbol_type: str | None = Field(default=None, alias="symbolType")
+
+
+class ChartEvent(WireModel):
+    symbol: str | None = None
+    data: Any = None
+
+
+class TradingViewQuoteValues(WireModel):
+    change: float | None = Field(default=None, alias="ch")
+    change_percent: float | None = Field(default=None, alias="chp")
+    last_price: float | None = Field(default=None, alias="lp")
+    ask: float | None = None
+    bid: float | None = None
+    open_price: float | None = Field(default=None, alias="open_price")
+    high_price: float | None = Field(default=None, alias="high_price")
+    low_price: float | None = Field(default=None, alias="low_price")
+    previous_close_price: float | None = Field(default=None, alias="prev_close_price")
+    volume: float | None = None
+    exchange: str | None = None
+    short_name: str | None = None
+
+
+class TradingViewQuote(WireModel):
+    status: str | None = Field(default=None, alias="s")
+    name: str | None = Field(default=None, alias="n")
+    values: TradingViewQuoteValues | None = Field(default=None, alias="v")
+
+
+class TradingViewTrade(WireModel):
+    status: str | None = Field(default=None, alias="s")
+    timestamp: int | None = Field(default=None, alias="t")
+    last_price: float | None = Field(default=None, alias="lp")
+    volume: float | None = Field(default=None, alias="v")

finance_dev/websocket/models/common.py

@@ -0,0 +1,85 @@
+"""Forward-compatible common protocol models."""
+
+from typing import Any, Literal
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WireModel(BaseModel):
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class RequestMessage(WireModel):
+    type: Literal["request"] = "request"
+    id: str
+    payload: dict[str, Any]
+
+
+class ResponseMessage(WireModel):
+    type: Literal["response"] = "response"
+    id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class ErrorResponse(ResponseMessage):
+    pass
+
+
+class AuthRequest(RequestMessage):
+    pass
+
+
+class AuthEvent(WireModel):
+    type: str | None = None
+    id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class SubscribeMessage(WireModel):
+    type: Literal["subscribe"] = "subscribe"
+    id: str | None = None
+    payload: Any
+
+
+class UnsubscribeMessage(WireModel):
+    type: Literal["unsubscribe"] = "unsubscribe"
+    id: str | None = None
+    payload: Any
+
+
+class SubscribedMessage(WireModel):
+    type: Literal["subscribed"] = "subscribed"
+    id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class EventMessage(WireModel):
+    type: Literal["event"] = "event"
+    id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class PingMessage(WireModel):
+    type: Literal["ping"] = "ping"
+    id: str | None = None
+
+
+class PongMessage(WireModel):
+    type: Literal["pong"] = "pong"
+    id: str | None = None
+
+
+class UnknownMessage(WireModel):
+    original: dict[str, Any]
+
+
+InboundMessage = (
+    RequestMessage
+    | ResponseMessage
+    | EventMessage
+    | SubscribeMessage
+    | UnsubscribeMessage
+    | SubscribedMessage
+    | PingMessage
+    | PongMessage
+    | UnknownMessage
+)