stx-python 0.6.0rc1__py3-none-any.whl

stx/_base.py

@@ -0,0 +1,64 @@
+"""Base class for every response model the SDK returns.
+
+Two rules shape it:
+
+1. Every field is optional and unknown fields are kept. The server adds
+   fields over time, and a response missing a field the SDK knows about
+   should not stop a trading loop. Extra fields are reachable as
+   attributes and through ``model_dump()``.
+2. A field whose value does not match its declared type is kept as the
+   raw value rather than failing the whole response. The specification
+   and the server can disagree on a display field, and that should cost
+   the caller one field, not the whole list of markets. Each such field
+   is logged once at WARNING so the mismatch is visible.
+
+Money and quantity fields are declared ``str`` and the API sends strings,
+so they pass through untouched: ``"0.5600"`` stays ``"0.5600"``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Set, Tuple
+
+from pydantic import BaseModel, ConfigDict, ValidationError, model_validator
+
+logger = logging.getLogger("stx")
+
+_warned: Set[Tuple[str, str]] = set()
+
+
+class STXModel(BaseModel):
+    """Pydantic v2 model with lenient parsing. See the module docstring."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    @model_validator(mode="wrap")
+    @classmethod
+    def _lenient(cls, data: Any, handler: Any) -> Any:
+        # Normal path: the payload matches the declared types.
+        try:
+            return handler(data)
+        except ValidationError as exc:
+            if not isinstance(data, dict):
+                raise
+            # Collect the top-level fields that failed, validate without
+            # them, then put their raw values back.
+            bad = {err["loc"][0] for err in exc.errors() if err.get("loc")}
+            bad = {name for name in bad if isinstance(name, str) and name in data}
+            if not bad:
+                raise
+            clean: Dict[str, Any] = {k: v for k, v in data.items() if k not in bad}
+            model = handler(clean)
+            for name in sorted(bad):
+                key = (cls.__name__, name)
+                if key not in _warned:
+                    _warned.add(key)
+                    logger.warning(
+                        "%s.%s did not match its declared type; keeping the raw value %r",
+                        cls.__name__,
+                        name,
+                        data[name],
+                    )
+                object.__setattr__(model, name, data[name])
+            return model

stx/_client.py

@@ -0,0 +1,502 @@
+"""``STX``: the blocking client, a thin wrapper over :class:`stx.AsyncSTX`.
+
+Each method runs the matching ``AsyncSTX`` coroutine on a private event
+loop in a background thread and returns its result, so the sync and async
+clients cannot drift apart: there is one implementation. Because the loop
+is private, ``STX`` also works inside Jupyter or any program that already
+runs an event loop.
+
+``iter_*`` methods return ordinary iterators that fetch the next page when
+the current one runs out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import (
+    Any,
+    AsyncIterator,
+    Coroutine,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    TypeVar,
+)
+
+from stx import models
+from stx._async_client import Amount, AsyncSTX, StrList
+from stx._paging import Page
+from stx._results import BatchOrderResult
+
+T = TypeVar("T")
+
+
+class _LoopThread:
+    """An event loop running forever in a daemon thread."""
+
+    def __init__(self) -> None:
+        self.loop = asyncio.new_event_loop()
+        self.thread = threading.Thread(target=self.loop.run_forever, name="stx-sync", daemon=True)
+        self.thread.start()
+
+    def run(self, coro: Coroutine[Any, Any, T]) -> T:
+        return asyncio.run_coroutine_threadsafe(coro, self.loop).result()
+
+    def stop(self) -> None:
+        self.loop.call_soon_threadsafe(self.loop.stop)
+        self.thread.join(timeout=5)
+        self.loop.close()
+
+
+class STX:
+    """Blocking client for the STX exchange.
+
+    Takes the same arguments as :class:`stx.AsyncSTX` and has the same
+    methods, without ``await``::
+
+        with STX(profile="us-demo") as client:
+            print(client.me().user_id)
+            for market in client.markets(status="open", limit=5):
+                print(market.symbol, market.last_traded_price)
+
+    For WebSocket channels use :class:`stx.STXWebSocket`, which is async.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._loop = _LoopThread()
+        try:
+            self._async = self._loop.run(self._make(kwargs))
+        except BaseException:
+            self._loop.stop()
+            raise
+        self.base_url = self._async.base_url
+        self.socket_url = self._async.socket_url
+        self.credentials = self._async.credentials
+        self.profile = self._async.profile
+
+    @staticmethod
+    async def _make(kwargs: Mapping[str, Any]) -> AsyncSTX:
+        return AsyncSTX(**kwargs)
+
+    def __repr__(self) -> str:
+        key = self.credentials.key_id if self.credentials else None
+        return f"STX(base_url={self.base_url!r}, key_id={key!r})"
+
+    @property
+    def async_client(self) -> AsyncSTX:
+        """The underlying ``AsyncSTX`` (bound to this client's private loop)."""
+        return self._async
+
+    def __enter__(self) -> STX:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close connections and stop the background loop. Safe to call twice."""
+        if self._loop is None:
+            return
+        try:
+            self._loop.run(self._async.close())
+        finally:
+            self._loop.stop()
+            self._loop = None  # type: ignore[assignment]
+
+    def _run(self, coro: Coroutine[Any, Any, T]) -> T:
+        if self._loop is None:
+            coro.close()
+            raise RuntimeError("This STX client is closed.")
+        return self._loop.run(coro)
+
+    def _iterate(self, agen: AsyncIterator[T]) -> Iterator[T]:
+        async def step() -> Any:
+            return await agen.__anext__()
+
+        try:
+            while True:
+                try:
+                    yield self._run(step())
+                except StopAsyncIteration:
+                    return
+        finally:
+            closer = getattr(agen, "aclose", None)
+            if closer is not None and self._loop is not None:
+                self._run(closer())
+
+    # Identity --------------------------------------------------------
+
+    def me(self) -> models.Me:
+        """``GET /api/v1/me``. See :meth:`AsyncSTX.me`."""
+        return self._run(self._async.me())
+
+    def user_id(self) -> str:
+        """Your user id, fetched once. See :meth:`AsyncSTX.user_id`."""
+        return self._run(self._async.user_id())
+
+    # Markets and events ---------------------------------------------
+
+    def markets(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        status: StrList = None,
+        trading: Optional[bool] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Market]:
+        """``GET /api/v1/markets``. See :meth:`AsyncSTX.markets`."""
+        return self._run(
+            self._async.markets(
+                market_ids=market_ids, event_ids=event_ids, status=status, trading=trading,
+                sports=sports, competitions=competitions, sort_by=sort_by,
+                sort_direction=sort_direction, limit=limit, cursor=cursor,
+            )
+        )  # fmt: skip
+
+    def iter_markets(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        status: StrList = None,
+        trading: Optional[bool] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[models.Market]:
+        """Every matching market, page by page."""
+        return self._iterate(
+            self._async.iter_markets(
+                market_ids=market_ids, event_ids=event_ids, status=status, trading=trading,
+                sports=sports, competitions=competitions, sort_by=sort_by,
+                sort_direction=sort_direction, limit=limit,
+            )
+        )  # fmt: skip
+
+    def market(self, market_id: str) -> models.Market:
+        """One market by id. See :meth:`AsyncSTX.market`."""
+        return self._run(self._async.market(market_id))
+
+    def events(
+        self,
+        *,
+        event_ids: StrList = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        event_types: StrList = None,
+        title: Optional[str] = None,
+        status: Optional[str] = None,
+        promoted: Optional[bool] = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Event]:
+        """``GET /api/v1/events``. See :meth:`AsyncSTX.events`."""
+        return self._run(
+            self._async.events(
+                event_ids=event_ids, sports=sports, competitions=competitions,
+                event_types=event_types, title=title, status=status, promoted=promoted,
+                sort_by=sort_by, sort_direction=sort_direction, limit=limit, cursor=cursor,
+            )
+        )  # fmt: skip
+
+    def iter_events(
+        self,
+        *,
+        event_ids: StrList = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        event_types: StrList = None,
+        title: Optional[str] = None,
+        status: Optional[str] = None,
+        promoted: Optional[bool] = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[models.Event]:
+        """Every matching event, page by page."""
+        return self._iterate(
+            self._async.iter_events(
+                event_ids=event_ids, sports=sports, competitions=competitions,
+                event_types=event_types, title=title, status=status, promoted=promoted,
+                sort_by=sort_by, sort_direction=sort_direction, limit=limit,
+            )
+        )  # fmt: skip
+
+    # Orders ------------------------------------------------------------
+
+    def orders(
+        self,
+        *,
+        order_ids: StrList = None,
+        client_order_ids: StrList = None,
+        market_ids: StrList = None,
+        status: StrList = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Order]:
+        """``GET /api/v1/orders``. See :meth:`AsyncSTX.orders`."""
+        return self._run(
+            self._async.orders(
+                order_ids=order_ids, client_order_ids=client_order_ids, market_ids=market_ids,
+                status=status, limit=limit, cursor=cursor,
+            )
+        )  # fmt: skip
+
+    def iter_orders(
+        self,
+        *,
+        order_ids: StrList = None,
+        client_order_ids: StrList = None,
+        market_ids: StrList = None,
+        status: StrList = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[models.Order]:
+        """Every matching order, page by page."""
+        return self._iterate(
+            self._async.iter_orders(
+                order_ids=order_ids, client_order_ids=client_order_ids, market_ids=market_ids,
+                status=status, limit=limit,
+            )
+        )  # fmt: skip
+
+    def order(self, order_id: str) -> models.Order:
+        """``GET /api/v1/orders/{order_id}``."""
+        return self._run(self._async.order(order_id))
+
+    def place_order(
+        self,
+        market_id: str,
+        action: str,
+        order_type: str,
+        *,
+        price: Optional[Amount] = None,
+        quantity: Amount,
+        client_order_id: Optional[str] = None,
+        expiration: Optional[str] = None,
+        expiration_time: Optional[int] = None,
+        cancel_on_disconnect: Optional[bool] = None,
+        device_id: Optional[str] = None,
+    ) -> models.Order:
+        """``POST /api/v1/orders``. See :meth:`AsyncSTX.place_order`."""
+        return self._run(
+            self._async.place_order(
+                market_id, action, order_type, price=price, quantity=quantity,
+                client_order_id=client_order_id, expiration=expiration,
+                expiration_time=expiration_time, cancel_on_disconnect=cancel_on_disconnect,
+                device_id=device_id,
+            )
+        )  # fmt: skip
+
+    def place_orders(
+        self, orders: Sequence[Mapping[str, Any]], *, geo_location: Optional[str] = None
+    ) -> List[BatchOrderResult]:
+        """``POST /api/v1/orders/batched``. See :meth:`AsyncSTX.place_orders`."""
+        return self._run(self._async.place_orders(orders, geo_location=geo_location))
+
+    def cancel_order(self, order_id: str) -> models.Cancellation:
+        """``DELETE /api/v1/orders/{order_id}``."""
+        return self._run(self._async.cancel_order(order_id))
+
+    def cancel_orders(self, order_ids: Sequence[str]) -> List[models.Cancellation]:
+        """``DELETE /api/v1/orders/batched``."""
+        return self._run(self._async.cancel_orders(order_ids))
+
+    def cancel_all_orders(self) -> List[models.Cancellation]:
+        """``DELETE /api/v1/orders/all``."""
+        return self._run(self._async.cancel_all_orders())
+
+    # Fills, positions, balance ----------------------------------------
+
+    def fills(
+        self,
+        *,
+        market_ids: StrList = None,
+        order_ids: StrList = None,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Fill]:
+        """``GET /api/v1/fills``. See :meth:`AsyncSTX.fills`."""
+        return self._run(
+            self._async.fills(
+                market_ids=market_ids, order_ids=order_ids, status=status, limit=limit,
+                cursor=cursor,
+            )
+        )  # fmt: skip
+
+    def iter_fills(
+        self,
+        *,
+        market_ids: StrList = None,
+        order_ids: StrList = None,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[models.Fill]:
+        """Every matching fill, page by page."""
+        return self._iterate(
+            self._async.iter_fills(
+                market_ids=market_ids, order_ids=order_ids, status=status, limit=limit
+            )
+        )
+
+    def positions(self, *, market_ids: StrList = None) -> List[models.Position]:
+        """``GET /api/v1/positions``. See :meth:`AsyncSTX.positions`."""
+        return self._run(self._async.positions(market_ids=market_ids))
+
+    def balance(self) -> models.Balance:
+        """``GET /api/v1/account/balance``."""
+        return self._run(self._async.balance())
+
+    def account_market_stats(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        exclude_zero_settlements: Optional[bool] = None,
+        from_time: Optional[int] = None,
+        to_time: Optional[int] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.MarketStat]:
+        """``GET /api/v1/account/market_stats``."""
+        return self._run(
+            self._async.account_market_stats(
+                market_ids=market_ids, event_ids=event_ids,
+                exclude_zero_settlements=exclude_zero_settlements, from_time=from_time,
+                to_time=to_time, sports=sports, competitions=competitions, limit=limit,
+                cursor=cursor,
+            )
+        )  # fmt: skip
+
+    def iter_account_market_stats(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        exclude_zero_settlements: Optional[bool] = None,
+        from_time: Optional[int] = None,
+        to_time: Optional[int] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[models.MarketStat]:
+        """Every per-market stat row, page by page."""
+        return self._iterate(
+            self._async.iter_account_market_stats(
+                market_ids=market_ids, event_ids=event_ids,
+                exclude_zero_settlements=exclude_zero_settlements, from_time=from_time,
+                to_time=to_time, sports=sports, competitions=competitions, limit=limit,
+            )
+        )  # fmt: skip
+
+    # Portfolio history --------------------------------------------------
+
+    def settlements(
+        self,
+        *,
+        market_ids: StrList = None,
+        type: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Settlement]:
+        """``GET /api/v1/portfolio/settlements``."""
+        return self._run(
+            self._async.settlements(market_ids=market_ids, type=type, limit=limit, cursor=cursor)
+        )
+
+    def iter_settlements(
+        self, *, market_ids: StrList = None, type: Optional[str] = None, limit: Optional[int] = None
+    ) -> Iterator[models.Settlement]:
+        """Every settlement, page by page."""
+        return self._iterate(
+            self._async.iter_settlements(market_ids=market_ids, type=type, limit=limit)
+        )
+
+    def deposits(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/deposits``."""
+        return self._run(self._async.deposits(limit=limit, cursor=cursor))
+
+    def iter_deposits(self, *, limit: Optional[int] = None) -> Iterator[models.PaymentTransaction]:
+        """Every deposit, page by page."""
+        return self._iterate(self._async.iter_deposits(limit=limit))
+
+    def withdrawals(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/withdrawals``."""
+        return self._run(self._async.withdrawals(limit=limit, cursor=cursor))
+
+    def iter_withdrawals(
+        self, *, limit: Optional[int] = None
+    ) -> Iterator[models.PaymentTransaction]:
+        """Every withdrawal, page by page."""
+        return self._iterate(self._async.iter_withdrawals(limit=limit))
+
+    def adjustments(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/adjustments``."""
+        return self._run(self._async.adjustments(limit=limit, cursor=cursor))
+
+    def iter_adjustments(
+        self, *, limit: Optional[int] = None
+    ) -> Iterator[models.PaymentTransaction]:
+        """Every adjustment, page by page."""
+        return self._iterate(self._async.iter_adjustments(limit=limit))
+
+    def fees(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.FeeTransaction]:
+        """``GET /api/v1/portfolio/fees``."""
+        return self._run(self._async.fees(limit=limit, cursor=cursor))
+
+    def iter_fees(self, *, limit: Optional[int] = None) -> Iterator[models.FeeTransaction]:
+        """Every fee entry, page by page."""
+        return self._iterate(self._async.iter_fees(limit=limit))
+
+    def loyalty(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.Transaction]:
+        """``GET /api/v1/portfolio/loyalty``."""
+        return self._run(self._async.loyalty(limit=limit, cursor=cursor))
+
+    def iter_loyalty(self, *, limit: Optional[int] = None) -> Iterator[models.Transaction]:
+        """Every loyalty entry, page by page."""
+        return self._iterate(self._async.iter_loyalty(limit=limit))
+
+    # Terms ----------------------------------------------------------------
+
+    def accept_terms(
+        self,
+        device_id: str,
+        *,
+        accept_terms: bool = True,
+        accept_privacy: bool = True,
+        accept_house_rules: Optional[bool] = None,
+    ) -> str:
+        """``POST /api/v1/tnc/accept``."""
+        return self._run(
+            self._async.accept_terms(
+                device_id,
+                accept_terms=accept_terms,
+                accept_privacy=accept_privacy,
+                accept_house_rules=accept_house_rules,
+            )
+        )

stx/_config.py

@@ -0,0 +1,107 @@
+"""Where the SDK connects: (region, env) to a host, and host to URLs."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Tuple, Union
+from urllib.parse import urlparse
+
+from stx.enums import Environment, Region
+from stx.exceptions import STXConfigException
+
+# (Region, Environment) -> hostname, for the environments published at
+# https://docs.stxapp.io/environments/. United States production is absent
+# until that host serves the API. Any other host, such as a local server, is
+# reachable through ``host=``.
+#
+# API keys do not carry across exchanges: an Ontario key will not
+# authenticate against the United States exchange.
+HOSTS: Dict[Tuple[Region, Environment], str] = {
+    (Region.US, Environment.DEMO): "demo.stxapp.io",
+    (Region.ONTARIO, Environment.DEMO): "demo.stxapp.ca",
+    (Region.ONTARIO, Environment.PRODUCTION): "api.on.stxapp.ca",
+}
+
+# Spellings accepted for ``env`` on top of the Environment values.
+_ENV_ALIASES: Dict[str, Environment] = {
+    "prod": Environment.PRODUCTION,
+    "live": Environment.PRODUCTION,
+}
+
+SOCKET_PATH = "/socket/websocket"
+
+
+def _coerce_region(value: Union[Region, str, None]) -> Optional[Region]:
+    if value is None or isinstance(value, Region):
+        return value
+    try:
+        return Region(value.lower())
+    except ValueError:
+        raise STXConfigException(
+            f"Unknown region: {value!r}. Known: {[r.value for r in Region]}."
+        ) from None
+
+
+def _coerce_env(value: Union[Environment, str, None]) -> Optional[Environment]:
+    if value is None or isinstance(value, Environment):
+        return value
+    lowered = value.lower()
+    if lowered in _ENV_ALIASES:
+        return _ENV_ALIASES[lowered]
+    try:
+        return Environment(lowered)
+    except ValueError:
+        raise STXConfigException(
+            f"Unknown env: {value!r}. Known: {[e.value for e in Environment]}."
+        ) from None
+
+
+def resolve_host(
+    region: Union[Region, str, None],
+    env: Union[Environment, str, None],
+) -> str:
+    """Hostname for a (region, env) pair, or ``STXConfigException``."""
+    region_enum = _coerce_region(region)
+    env_enum = _coerce_env(env)
+    if region_enum is None or env_enum is None:
+        raise STXConfigException(
+            "No host configured. Pass region= and env= (for example "
+            "region='us', env='demo'), or host=, or set them in a profile "
+            "in ~/.stx/credentials."
+        )
+    host = HOSTS.get((region_enum, env_enum))
+    if host is None:
+        raise STXConfigException(
+            f"No host configured for region={region_enum.value}, env={env_enum.value}. "
+            "Pass host= explicitly."
+        )
+    return host
+
+
+def base_url_for(
+    region: Union[Region, str, None],
+    env: Union[Environment, str, None],
+    host: Optional[str],
+) -> str:
+    """The API base URL (scheme and authority, no path).
+
+    ``host`` may be a bare hostname (``demo.stxapp.io``, ``localhost:4000``),
+    which gets ``https://``, or a URL (``http://localhost:4000``) whose
+    scheme is kept. Any path on the URL is ignored: the API lives at
+    ``/api/v1`` on every host.
+    """
+    if host:
+        host = host.strip()
+        if host.startswith(("http://", "https://")):
+            parsed = urlparse(host)
+            if not parsed.netloc:
+                raise STXConfigException(f"Cannot parse host {host!r}.")
+            return f"{parsed.scheme}://{parsed.netloc}"
+        return f"https://{host.rstrip('/')}"
+    return f"https://{resolve_host(region, env)}"
+
+
+def socket_url_for(base_url: str) -> str:
+    """The WebSocket URL for an API base URL: https maps to wss, http to ws."""
+    parsed = urlparse(base_url)
+    scheme = "ws" if parsed.scheme == "http" else "wss"
+    return f"{scheme}://{parsed.netloc}{SOCKET_PATH}?vsn=2.0.0"