stx-python 0.6.0rc1__py3-none-any.whl

stx/_http.py

@@ -0,0 +1,131 @@
+"""Request building and response decoding shared by the REST clients.
+
+Nothing here does I/O. :func:`build_request` turns an operation id from
+``stx/_operations.py`` plus arguments into the method, path-with-query and
+JSON body that go on the wire; the clients sign exactly that path and send
+exactly that URL, so the signature always covers the query string the
+server sees.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Dict, Iterable, Mapping, Optional, Tuple, Union
+from urllib.parse import quote
+
+from stx._operations import OPERATIONS, Operation
+from stx.exceptions import STXException, error_for_status
+
+
+@dataclass(frozen=True)
+class PreparedRequest:
+    """One REST call, ready to sign and send."""
+
+    operation_id: str
+    method: str
+    path: str  # path plus "?query" when there is one; this is what gets signed
+    body: Optional[bytes]
+
+    @property
+    def idempotent(self) -> bool:
+        return self.method in ("GET", "DELETE")
+
+
+def _encode_value(value: Any) -> str:
+    # Multi-value filters are comma-separated, never repeated keys.
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return ",".join(_encode_value(v) for v in value)
+    return str(value)
+
+
+def encode_query(params: Mapping[str, Any]) -> str:
+    """``key=value&...`` for the params that are not ``None``, in the given order.
+
+    Lists become comma-separated values (``market_ids=a,b``); booleans
+    become ``true``/``false``. Keys and values are percent-encoded with
+    commas left literal, so the string is stable and readable in logs.
+    """
+    parts = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple, set, frozenset)) and not value:
+            continue
+        parts.append(f"{quote(key, safe='')}={quote(_encode_value(value), safe=',')}")
+    return "&".join(parts)
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return str(value)
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def build_request(
+    operation_id: str,
+    *,
+    path_params: Optional[Mapping[str, str]] = None,
+    query: Optional[Mapping[str, Any]] = None,
+    body: Any = None,
+) -> PreparedRequest:
+    """Prepare the call for ``operation_id``.
+
+    Raises ``ValueError`` for a query key the operation does not declare,
+    which catches a client method drifting away from the spec.
+    """
+    op: Operation = OPERATIONS[operation_id]
+    path = op.path
+    for name in op.path_params:
+        value = (path_params or {}).get(name)
+        if not value:
+            raise ValueError(f"{name} is required")
+        path = path.replace("{" + name + "}", quote(str(value), safe=""))
+    query = dict(query or {})
+    unknown = set(query) - set(op.query)
+    if unknown:
+        raise ValueError(f"{operation_id} does not take {sorted(unknown)}")
+    qs = encode_query(query)
+    if qs:
+        path = f"{path}?{qs}"
+    payload: Optional[bytes] = None
+    if op.has_body:
+        payload = json.dumps(body if body is not None else {}, default=_json_default).encode(
+            "utf-8"
+        )
+    return PreparedRequest(operation_id, op.method, path, payload)
+
+
+def decode_response(
+    request: PreparedRequest,
+    status_code: int,
+    content: bytes,
+    retry_after: Optional[str] = None,
+) -> Any:
+    """The parsed JSON body of a 2xx response, or raise the mapped exception."""
+    try:
+        body: Union[Dict[str, Any], str, None] = json.loads(content) if content else None
+    except ValueError:
+        body = content.decode("utf-8", errors="replace")
+    if 200 <= status_code < 300:
+        if not isinstance(body, dict):
+            raise STXException(
+                f"Expected a JSON object from {request.method} {request.path}, got {body!r:.200}",
+                status_code=status_code,
+                body=body,
+                method=request.method,
+                path=request.path,
+            )
+        return body
+    raise error_for_status(
+        status_code, body, method=request.method, path=request.path, retry_after=retry_after
+    )
+
+
+def split_page(operation_id: str, body: Dict[str, Any]) -> Tuple[Iterable[Any], Optional[str]]:
+    """(items, next cursor) from a list response."""
+    op = OPERATIONS[operation_id]
+    return body.get(op.response_key) or [], body.get("cursor")

stx/_money.py

@@ -0,0 +1,122 @@
+"""Convert the two market-metadata channels to the SDK's string format.
+
+Every channel the SDK exposes sends money as dollar strings (``"0.5600"``)
+and quantities as quantity strings (``"2.00"``), the same as REST, except
+two: ``markets`` and ``market_updates`` still send JSON numbers, with
+prices in cents. The SDK rewrites those fields so every amount it hands
+you is a string in one format. The field lists come from the channel
+reference pages (MarketPayload fields):
+
+Prices, cents to a dollar string with at least four decimals:
+    ``price``, ``last_traded_price``, ``max_price``, ``price`` inside each
+    ``bids``, ``offers`` and ``recent_trades`` entry, and ``from``, ``to``
+    and ``inc`` inside each ``order_price_rules`` entry.
+
+Contract counts, number to a quantity string with at least two decimals:
+    ``total_volume``, ``volume_24h``, ``open_interest``, and ``quantity``
+    inside each ``bids``, ``offers`` and ``recent_trades`` entry.
+
+Left as numbers, because they are not money or contracts:
+    ``probability``, ``price_change_24h`` (a percentage),
+    ``in_play_delay_sec``, ``unix_timestamp``, ``event_start``.
+
+Values that are already strings (a server that has moved these feeds to the
+dollar format) pass through unchanged, and ``null`` stays ``None``.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, Optional
+
+_CENTS = Decimal(100)
+
+PRICE_FIELDS = ("price", "last_traded_price", "max_price")
+QUANTITY_FIELDS = ("total_volume", "volume_24h", "open_interest")
+LEVEL_LISTS = ("bids", "offers", "recent_trades")
+PRICE_RULE_FIELDS = ("from", "to", "inc")
+
+
+def _fmt(value: Decimal, min_places: int) -> str:
+    # At least ``min_places`` decimals, more if the value carries them:
+    # the same rule the API uses for its own strings.
+    exponent = value.normalize().as_tuple().exponent
+    places = max(min_places, -exponent if isinstance(exponent, int) else 0)
+    return f"{value:.{places}f}"
+
+
+def _to_decimal(value: Any) -> Optional[Decimal]:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return Decimal(str(value))
+    except InvalidOperation:
+        return None
+
+
+def cents_to_dollars(value: Any) -> Any:
+    """``56`` to ``"0.5600"``; ``1.0e4`` to ``"100.0000"``. Strings and
+    ``None`` pass through."""
+    if value is None or isinstance(value, str):
+        return value
+    dec = _to_decimal(value)
+    if dec is None:
+        return value
+    return _fmt(dec / _CENTS, 4)
+
+
+def to_quantity(value: Any) -> Any:
+    """``2`` to ``"2.00"``. Strings and ``None`` pass through."""
+    if value is None or isinstance(value, str):
+        return value
+    dec = _to_decimal(value)
+    if dec is None:
+        return value
+    return _fmt(dec, 2)
+
+
+def convert_market_payload(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """One market object from ``markets`` or ``market_updates``, converted.
+
+    Returns a new dict; the input is not modified. Fields that are absent
+    stay absent, which matters for ``market_updated`` deltas.
+    """
+    out = dict(payload)
+    for key in PRICE_FIELDS:
+        if key in out:
+            out[key] = cents_to_dollars(out[key])
+    for key in QUANTITY_FIELDS:
+        if key in out:
+            out[key] = to_quantity(out[key])
+    for key in LEVEL_LISTS:
+        levels = out.get(key)
+        if isinstance(levels, list):
+            converted = []
+            for level in levels:
+                if isinstance(level, dict):
+                    level = dict(level)
+                    if "price" in level:
+                        level["price"] = cents_to_dollars(level["price"])
+                    if "quantity" in level:
+                        level["quantity"] = to_quantity(level["quantity"])
+                converted.append(level)
+            out[key] = converted
+    rules = out.get("order_price_rules")
+    if isinstance(rules, list):
+        out["order_price_rules"] = [
+            {k: (cents_to_dollars(v) if k in PRICE_RULE_FIELDS else v) for k, v in rule.items()}
+            if isinstance(rule, dict)
+            else rule
+            for rule in rules
+        ]
+    return out
+
+
+def convert_markets_frame(payload: Any) -> Any:
+    """A ``markets`` channel push: a map of market id to market object."""
+    if not isinstance(payload, dict):
+        return payload
+    return {
+        market_id: convert_market_payload(market) if isinstance(market, dict) else market
+        for market_id, market in payload.items()
+    }

stx/_operations.py

@@ -0,0 +1,259 @@
+"""REST operations, one per (method, path) in the vendored spec.
+
+Generated by ``python -m tools.generate_models`` from
+``spec/openapi.json`` (source commit ``6a6ca2731ac6870f65999f86c857a5e6a28b1f5b``).
+Do not edit by hand. The clients look up method, path and
+response envelope here, and the unit tests assert every
+operation has a client method.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, NamedTuple, Tuple
+
+
+class Operation(NamedTuple):
+    method: str
+    path: str
+    query: Tuple[str, ...]
+    path_params: Tuple[str, ...]
+    has_body: bool
+    response_key: str
+    model: str
+    is_list: bool
+    paginated: bool
+
+
+OPERATIONS: Dict[str, Operation] = {
+    'account_balance_get': Operation(
+        method='GET',
+        path='/api/v1/account/balance',
+        query=(),
+        path_params=(),
+        has_body=False,
+        response_key='balance',
+        model='Balance',
+        is_list=False,
+        paginated=False,
+    ),
+    'account_market_stats_get': Operation(
+        method='GET',
+        path='/api/v1/account/market_stats',
+        query=('market_ids', 'event_ids', 'exclude_zero_settlements', 'from_time', 'to_time', 'sports', 'competitions', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='market_stats',
+        model='MarketStat',
+        is_list=True,
+        paginated=True,
+    ),
+    'events_get': Operation(
+        method='GET',
+        path='/api/v1/events',
+        query=('event_ids', 'sports', 'competitions', 'event_types', 'title', 'status', 'promoted', 'sort_by[name]', 'sort_by[direction]', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='events',
+        model='Event',
+        is_list=True,
+        paginated=True,
+    ),
+    'fills_get': Operation(
+        method='GET',
+        path='/api/v1/fills',
+        query=('market_ids', 'order_ids', 'status', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='fills',
+        model='Fill',
+        is_list=True,
+        paginated=True,
+    ),
+    'markets_get': Operation(
+        method='GET',
+        path='/api/v1/markets',
+        query=('market_ids', 'event_ids', 'status', 'trading', 'sports', 'competitions', 'sort_by[name]', 'sort_by[direction]', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='markets',
+        model='Market',
+        is_list=True,
+        paginated=True,
+    ),
+    'me_get': Operation(
+        method='GET',
+        path='/api/v1/me',
+        query=(),
+        path_params=(),
+        has_body=False,
+        response_key='me',
+        model='Me',
+        is_list=False,
+        paginated=False,
+    ),
+    'orders_get': Operation(
+        method='GET',
+        path='/api/v1/orders',
+        query=('order_ids', 'client_order_ids', 'market_ids', 'status', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='orders',
+        model='Order',
+        is_list=True,
+        paginated=True,
+    ),
+    'orders_post': Operation(
+        method='POST',
+        path='/api/v1/orders',
+        query=(),
+        path_params=(),
+        has_body=True,
+        response_key='order',
+        model='Order',
+        is_list=False,
+        paginated=False,
+    ),
+    'orders_all_delete': Operation(
+        method='DELETE',
+        path='/api/v1/orders/all',
+        query=(),
+        path_params=(),
+        has_body=False,
+        response_key='cancellations',
+        model='Cancellation',
+        is_list=True,
+        paginated=False,
+    ),
+    'orders_batched_delete': Operation(
+        method='DELETE',
+        path='/api/v1/orders/batched',
+        query=(),
+        path_params=(),
+        has_body=True,
+        response_key='cancellations',
+        model='Cancellation',
+        is_list=True,
+        paginated=False,
+    ),
+    'orders_batched_post': Operation(
+        method='POST',
+        path='/api/v1/orders/batched',
+        query=(),
+        path_params=(),
+        has_body=True,
+        response_key='results',
+        model='',
+        is_list=True,
+        paginated=False,
+    ),
+    'orders__order_id_delete': Operation(
+        method='DELETE',
+        path='/api/v1/orders/{order_id}',
+        query=(),
+        path_params=('order_id',),
+        has_body=False,
+        response_key='',
+        model='',
+        is_list=False,
+        paginated=False,
+    ),
+    'orders__id_get': Operation(
+        method='GET',
+        path='/api/v1/orders/{order_id}',
+        query=(),
+        path_params=('order_id',),
+        has_body=False,
+        response_key='order',
+        model='Order',
+        is_list=False,
+        paginated=False,
+    ),
+    'portfolio_adjustments_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/adjustments',
+        query=('limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='adjustments',
+        model='PaymentTransaction',
+        is_list=True,
+        paginated=True,
+    ),
+    'portfolio_deposits_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/deposits',
+        query=('limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='deposits',
+        model='PaymentTransaction',
+        is_list=True,
+        paginated=True,
+    ),
+    'portfolio_fees_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/fees',
+        query=('limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='fees',
+        model='FeeTransaction',
+        is_list=True,
+        paginated=True,
+    ),
+    'portfolio_loyalty_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/loyalty',
+        query=('limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='loyalty',
+        model='Transaction',
+        is_list=True,
+        paginated=True,
+    ),
+    'portfolio_settlements_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/settlements',
+        query=('market_ids', 'type', 'limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='settlements',
+        model='Settlement',
+        is_list=True,
+        paginated=True,
+    ),
+    'portfolio_withdrawals_get': Operation(
+        method='GET',
+        path='/api/v1/portfolio/withdrawals',
+        query=('limit', 'cursor'),
+        path_params=(),
+        has_body=False,
+        response_key='withdrawals',
+        model='PaymentTransaction',
+        is_list=True,
+        paginated=True,
+    ),
+    'positions_get': Operation(
+        method='GET',
+        path='/api/v1/positions',
+        query=('market_ids',),
+        path_params=(),
+        has_body=False,
+        response_key='positions',
+        model='Position',
+        is_list=True,
+        paginated=False,
+    ),
+    'tnc_accept_post': Operation(
+        method='POST',
+        path='/api/v1/tnc/accept',
+        query=(),
+        path_params=(),
+        has_body=True,
+        response_key='message',
+        model='',
+        is_list=False,
+        paginated=False,
+    ),
+}

stx/_paging.py

@@ -0,0 +1,59 @@
+"""One page of a list endpoint.
+
+Every list endpoint pages by cursor: the response carries ``cursor``, an
+opaque string to pass back for the next page, or ``None`` on the last one.
+A list method returns a :class:`Page`, which behaves like a list of models
+and carries that cursor::
+
+    page = await client.markets(status="open", limit=50)
+    for market in page:
+        print(market.symbol, market.last_traded_price)
+    if page.cursor:
+        page = await client.markets(status="open", limit=50, cursor=page.cursor)
+
+To walk every page, use the matching ``iter_`` method, which follows the
+cursor for you::
+
+    async for market in client.iter_markets(status="open"):
+        ...
+"""
+
+from __future__ import annotations
+
+from typing import Generic, Iterator, List, Optional, Sequence, TypeVar, overload
+
+T = TypeVar("T")
+
+
+class Page(Sequence[T], Generic[T]):
+    """A ``Sequence`` of models plus the ``cursor`` for the next page."""
+
+    __slots__ = ("cursor", "items")
+
+    def __init__(self, items: List[T], cursor: Optional[str]) -> None:
+        self.items = items
+        self.cursor = cursor
+
+    @property
+    def has_more(self) -> bool:
+        """``True`` when another page exists."""
+        return bool(self.cursor)
+
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @overload
+    def __getitem__(self, idx: int) -> T: ...
+
+    @overload
+    def __getitem__(self, idx: slice) -> List[T]: ...
+
+    def __getitem__(self, idx):
+        return self.items[idx]
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self.items)
+
+    def __repr__(self) -> str:
+        more = ", more" if self.has_more else ""
+        return f"Page({len(self.items)} items{more})"

stx/_results.py

@@ -0,0 +1,29 @@
+"""Result types for calls whose response is not a single spec schema."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import Field
+
+from stx._base import STXModel
+from stx.models import Order
+
+
+class BatchOrderResult(STXModel):
+    """One entry of ``place_orders``: the order, or why it was not placed.
+
+    Results come back in the order the orders were sent. Exactly one of
+    ``order`` and ``errors`` is set.
+    """
+
+    order: Optional[Order] = Field(None, description="The placed order.")
+    errors: Optional[List[str]] = Field(None, description="Why this order was not placed.")
+
+    @property
+    def ok(self) -> bool:
+        """``True`` when the order was placed."""
+        return self.order is not None and not self.errors
+
+
+BatchOrderResult.model_rebuild()

stx/_retry.py

@@ -0,0 +1,80 @@
+"""Retry policy for REST calls.
+
+Which failures are retried:
+
+* ``STXRateLimitException`` (429), on every method. The server refused the
+  request before acting on it, so sending it again is safe. A
+  ``Retry-After`` header sets the wait.
+* ``STXServerException`` (5xx) and ``STXTransportException`` (connection
+  reset, timeout), on ``GET`` and ``DELETE`` only.
+
+``POST`` is not retried after a 5xx or a dropped connection, because the
+order may already be on the book: placing it again could double your
+position. Look it up with ``orders(client_order_ids=[...])`` instead, which
+is what ``client_order_id`` is for.
+
+Nothing else is retried: a 400, 401, 403, 404 or 422 will fail the same
+way the second time.
+
+Backoff is exponential with jitter, capped at ``max_backoff``.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from typing import Tuple, Type
+
+from stx.exceptions import (
+    STXException,
+    STXRateLimitException,
+    STXServerException,
+    STXTransportException,
+)
+
+_DEFAULT_RETRYABLE: Tuple[Type[STXException], ...] = (
+    STXServerException,
+    STXTransportException,
+    STXRateLimitException,
+)
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """How many times to try a call, and how long to wait between tries.
+
+    The default is 3 attempts, 0.5 s initial backoff doubling to a 30 s cap,
+    with jitter. ``RetryPolicy(max_attempts=1)`` (or ``stx.NO_RETRY``) turns
+    retries off.
+    """
+
+    max_attempts: int = 3
+    initial_backoff: float = 0.5
+    max_backoff: float = 30.0
+    jitter: bool = True
+    retryable_exceptions: Tuple[Type[STXException], ...] = field(
+        default_factory=lambda: _DEFAULT_RETRYABLE
+    )
+
+    def should_retry(self, exc: STXException, attempt: int, idempotent: bool) -> bool:
+        """Whether to try again after ``exc`` ended attempt number ``attempt``."""
+        if attempt >= self.max_attempts:
+            return False
+        if not isinstance(exc, self.retryable_exceptions):
+            return False
+        # A 429 was refused before it was acted on; anything else may have
+        # been acted on, so only repeat it when repeating is harmless.
+        return idempotent or isinstance(exc, STXRateLimitException)
+
+    def compute_backoff(self, attempt: int, exc: STXException) -> float:
+        """Seconds to wait after attempt ``attempt`` (1-based) failed."""
+        if isinstance(exc, STXRateLimitException) and exc.retry_after is not None:
+            return min(float(exc.retry_after), self.max_backoff)
+        capped = min(self.initial_backoff * (2 ** (attempt - 1)), self.max_backoff)
+        if self.jitter:
+            return capped * (0.5 + random.random() * 0.5)
+        return capped
+
+
+NO_RETRY = RetryPolicy(max_attempts=1)
+"""One attempt, no backoff."""