radion-sdk 0.2.0__py3-none-any.whl

radion/__init__.py

@@ -0,0 +1,85 @@
+"""Official async SDK for the Radion platform."""
+
+from __future__ import annotations
+
+from ._config import DEFAULT_BASE_URL, DEFAULT_WS_URL, RadionConfig
+from .client import Radion
+from .errors import RadionConnectionError, RadionError, RadionServerError
+from .realtime import (
+    CHANNELS,
+    FILTER_REQUIREMENTS,
+    ActivityPayload,
+    AnyChannelPayload,
+    AnyConfirmedPayload,
+    Channel,
+    ChannelEvent,
+    ChannelFilters,
+    CollateralPayload,
+    CombosPayload,
+    ErrorFrame,
+    EventDispatcher,
+    EventFrame,
+    FilterKey,
+    InboundFrame,
+    LifecyclePayload,
+    MempoolChannel,
+    OraclePayload,
+    PongFrame,
+    PricesPayload,
+    RealtimeClient,
+    ReconnectManager,
+    SubscribableChannel,
+    SubscribedFrame,
+    Subscription,
+    SubscriptionManager,
+    TradesPayload,
+    UnsubscribedFrame,
+    is_channel,
+    is_mempool_channel,
+    is_subscribable_channel,
+    validate_subscription_filters,
+)
+
+__all__ = [
+    "CHANNELS",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_WS_URL",
+    "FILTER_REQUIREMENTS",
+    "ActivityPayload",
+    "AnyChannelPayload",
+    "AnyConfirmedPayload",
+    "Channel",
+    "ChannelEvent",
+    "ChannelFilters",
+    "CollateralPayload",
+    "CombosPayload",
+    "ErrorFrame",
+    "EventDispatcher",
+    "EventFrame",
+    "FilterKey",
+    "InboundFrame",
+    "LifecyclePayload",
+    "MempoolChannel",
+    "OraclePayload",
+    "PongFrame",
+    "PricesPayload",
+    "Radion",
+    "RadionConfig",
+    "RadionConnectionError",
+    "RadionError",
+    "RadionServerError",
+    "RealtimeClient",
+    "ReconnectManager",
+    "SubscribableChannel",
+    "SubscribedFrame",
+    "Subscription",
+    "SubscriptionManager",
+    "TradesPayload",
+    "UnsubscribedFrame",
+    "is_channel",
+    "is_mempool_channel",
+    "is_subscribable_channel",
+    "validate_subscription_filters",
+]
+
+__version__ = "0.2.0"

radion/_config.py

@@ -0,0 +1,25 @@
+"""Shared configuration for the Radion SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.radion.app"
+"""Default base URL for the Radion REST API."""
+
+DEFAULT_WS_URL = "wss://api.radion.app/ws"
+"""Default endpoint for the Radion realtime (WebSocket) API."""
+
+
+@dataclass(frozen=True, slots=True)
+class RadionConfig:
+    """Shared configuration for every Radion product surface.
+
+    ``base_url`` is reserved for the forthcoming REST resource namespaces
+    (``markets``, ``traders``, ``backtests``, …); the realtime client uses
+    ``ws_url``.
+    """
+
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    ws_url: str = DEFAULT_WS_URL

radion/client.py

@@ -0,0 +1,50 @@
+"""The unified :class:`Radion` platform client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._config import DEFAULT_BASE_URL, DEFAULT_WS_URL
+from .errors import RadionConnectionError
+from .realtime import RealtimeClient
+
+
+class Radion:
+    """Unified async entry point for the Radion platform.
+
+    Holds shared configuration and exposes each product surface as an
+    attribute. Today that is :attr:`realtime`; REST resource namespaces
+    (``markets``, ``traders``, ``backtests``, ``auth``, ``health``) attach here
+    as they ship, built from ``base_url`` over a shared HTTP transport — the
+    constructor shape stays stable so adding them is purely additive.
+
+    Extra keyword arguments are forwarded to the realtime client (for example
+    ``reconnect``, ``heartbeat``, ``heartbeat_interval``).
+
+    Example::
+
+        radion = Radion(api_key=os.getenv("RADION_API_KEY"))
+        await radion.realtime.connect()
+        await radion.realtime.subscribe("trades")
+
+        @radion.realtime.on("trades")
+        async def handle_trade(event):
+            print(event.data)
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        ws_url: str = DEFAULT_WS_URL,
+        **realtime_options: Any,
+    ) -> None:
+        if not api_key:
+            raise RadionConnectionError("api_key is required")
+        self._base_url = base_url
+        self.realtime = RealtimeClient(
+            api_key=api_key,
+            url=ws_url,
+            **realtime_options,
+        )

radion/errors.py

@@ -0,0 +1,28 @@
+"""Error types raised by the SDK."""
+
+from __future__ import annotations
+
+
+class RadionError(Exception):
+    """Base class for every error surfaced by the SDK."""
+
+
+class RadionConnectionError(RadionError):
+    """Raised when the SDK is used against an invalid connection state."""
+
+
+class RadionServerError(RadionError):
+    """Raised when the server reports an ``error`` frame."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        channel: str | None = None,
+        id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.channel = channel
+        self.id = id

radion/realtime/__init__.py

@@ -0,0 +1,79 @@
+"""Radion realtime (WebSocket) product surface."""
+
+from __future__ import annotations
+
+from .channels import (
+    CHANNELS,
+    FILTER_REQUIREMENTS,
+    Channel,
+    FilterKey,
+    MempoolChannel,
+    SubscribableChannel,
+    is_channel,
+    is_mempool_channel,
+    is_subscribable_channel,
+)
+from .client import RealtimeClient
+from .dispatcher import EventDispatcher
+from .payloads import (
+    ActivityPayload,
+    AnyChannelPayload,
+    AnyConfirmedPayload,
+    CollateralPayload,
+    CombosPayload,
+    LifecyclePayload,
+    OraclePayload,
+    PricesPayload,
+    TradesPayload,
+)
+from .protocol import (
+    ChannelEvent,
+    ChannelFilters,
+    ErrorFrame,
+    EventFrame,
+    InboundFrame,
+    PongFrame,
+    SubscribedFrame,
+    Subscription,
+    UnsubscribedFrame,
+    parse_inbound_frame,
+    validate_subscription_filters,
+)
+from .reconnect_manager import ReconnectManager
+from .subscription_manager import SubscriptionManager
+
+__all__ = [
+    "CHANNELS",
+    "FILTER_REQUIREMENTS",
+    "ActivityPayload",
+    "AnyChannelPayload",
+    "AnyConfirmedPayload",
+    "Channel",
+    "ChannelEvent",
+    "ChannelFilters",
+    "CollateralPayload",
+    "CombosPayload",
+    "ErrorFrame",
+    "EventDispatcher",
+    "EventFrame",
+    "FilterKey",
+    "InboundFrame",
+    "LifecyclePayload",
+    "MempoolChannel",
+    "OraclePayload",
+    "PongFrame",
+    "PricesPayload",
+    "RealtimeClient",
+    "ReconnectManager",
+    "SubscribableChannel",
+    "SubscribedFrame",
+    "Subscription",
+    "SubscriptionManager",
+    "TradesPayload",
+    "UnsubscribedFrame",
+    "is_channel",
+    "is_mempool_channel",
+    "is_subscribable_channel",
+    "parse_inbound_frame",
+    "validate_subscription_filters",
+]

radion/realtime/channels.py

@@ -0,0 +1,71 @@
+"""Typed channel names for the Radion realtime API."""
+
+from __future__ import annotations
+
+from typing import Literal, TypeGuard, get_args
+
+Channel = Literal[
+    "global",
+    "trades",
+    "activity",
+    "lifecycle",
+    "oracle",
+    "collateral",
+    "combos",
+    "prices",
+    "wallets",
+    "markets",
+    "large_trades",
+]
+"""A confirmed channel name the SDK can subscribe to."""
+
+CHANNELS: tuple[Channel, ...] = get_args(Channel)
+"""Every supported confirmed channel, as a tuple."""
+
+MempoolChannel = Literal[
+    "mempool.global",
+    "mempool.trades",
+    "mempool.activity",
+    "mempool.lifecycle",
+    "mempool.oracle",
+    "mempool.collateral",
+    "mempool.combos",
+    "mempool.prices",
+    "mempool.wallets",
+    "mempool.markets",
+    "mempool.large_trades",
+]
+"""A ``mempool.``-prefixed companion channel."""
+
+SubscribableChannel = Channel | MempoolChannel
+"""Any channel accepted by :meth:`RealtimeClient.subscribe`."""
+
+FilterKey = Literal["wallets", "market_ids", "token_ids", "min_usd"]
+"""A server-side filter key."""
+
+_MEMPOOL_PREFIX = "mempool."
+
+#: Per-channel filter requirements. ``required_any_of`` means at least one of
+#: the listed filters must be present. Channels absent from this map accept no
+#: required filters. Mempool companions share their confirmed channel's rules.
+FILTER_REQUIREMENTS: dict[Channel, tuple[FilterKey, ...]] = {
+    "wallets": ("wallets",),
+    "markets": ("market_ids", "token_ids"),
+}
+
+
+def is_channel(value: str) -> TypeGuard[Channel]:
+    """Return whether ``value`` is a known confirmed channel name."""
+    return value in CHANNELS
+
+
+def is_mempool_channel(value: str) -> bool:
+    """Return whether ``value`` is a ``mempool.``-prefixed channel."""
+    return value.startswith(_MEMPOOL_PREFIX) and is_channel(
+        value[len(_MEMPOOL_PREFIX) :]
+    )
+
+
+def is_subscribable_channel(value: str) -> bool:
+    """Return whether ``value`` is any subscribable channel."""
+    return is_channel(value) or is_mempool_channel(value)