oddspush 0.1.0__py3-none-any.whl

oddspush/__init__.py

@@ -0,0 +1,29 @@
+"""Python client for the OddsPush API: real-time Pinnacle odds over WebSocket and REST,
+with no-vig, fair and closing-line prices.
+
+- :class:`Stream`: the WebSocket stream, with reconnection and a local price book.
+- :class:`Client` / :class:`AsyncClient`: the REST API.
+- :class:`Book`: the price book, if you feed it yourself.
+- :mod:`oddspush.odds`: American/decimal odds, margin, no-vig and CLV.
+
+Docs: https://oddspush.com/docs
+"""
+
+from ._constants import CHANNELS, PRICE_CHANNELS, REST_URL, SPORTS, STREAM_URL
+from ._version import __version__
+from .book import Book, channel_of
+from .errors import (BadRequest, FatalError, IpNotAllowed, NotFound, NotInPlan,
+                     OddsPushError, RateLimited, StreamClosed, SubscriptionExpired,
+                     TokenReplaced, Unauthorized, Unavailable)
+from .odds import american_to_decimal, clv, decimal_to_american, implied_probability
+from .rest import AsyncClient, Client
+from .stream import Stream
+
+__all__ = [
+    "__version__", "Stream", "Client", "AsyncClient", "Book", "channel_of",
+    "SPORTS", "CHANNELS", "PRICE_CHANNELS", "STREAM_URL", "REST_URL",
+    "american_to_decimal", "decimal_to_american", "implied_probability", "clv",
+    "OddsPushError", "FatalError", "Unauthorized", "SubscriptionExpired", "NotInPlan",
+    "IpNotAllowed", "TokenReplaced", "RateLimited", "NotFound", "BadRequest",
+    "Unavailable", "StreamClosed",
+]

oddspush/_constants.py

@@ -0,0 +1,30 @@
+"""Endpoints, sport IDs and channel names of the OddsPush API."""
+
+from __future__ import annotations
+
+STREAM_URL = "wss://feed.oddspush.com/v1/stream"
+REST_URL = "https://feed.oddspush.com"
+
+#: Sport IDs accepted by ``subscribe`` and the REST API.
+SPORTS = {
+    1: "Soccer",
+    2: "Tennis",
+    3: "Basketball",
+    4: "Hockey",
+    5: "American football",
+    6: "Baseball",
+    7: "Rugby",
+    8: "MMA",
+    9: "Boxing",
+    10: "Other (volleyball and handball)",
+    11: "Esports",
+    12: "Golf",
+    13: "Cricket",
+}
+
+#: Channels whose prices make up the main price book.
+PRICE_CHANNELS = ("ld", "both")
+
+#: Every channel name the API knows. ``dz`` carries volatile moments and ``pre`` pre-match
+#: prices; anything else is reported as ``other``.
+CHANNELS = ("ld", "both", "dz", "pre", "other")

oddspush/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

oddspush/book.py

@@ -0,0 +1,263 @@
+"""A local price book: the current open markets of every event, kept up to date from the
+stream.
+
+The rules (the same as in the API documentation):
+
+- markets are ordered by ``version``: an update older than the one held is ignored;
+- a market whose ``status`` is not ``open`` is removed;
+- when a period turns ``closed`` or ``settled``, every market of that period is removed;
+- ``op: "del"`` removes the whole event, whatever channel it comes on;
+- a snapshot is merged by version, never used to clear the book.
+
+:class:`~oddspush.Stream` keeps one up to date for you (``stream.book``); you can also feed
+one yourself with :meth:`Book.apply_message`.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple
+
+from ._constants import PRICE_CHANNELS
+
+Market = Dict[str, Any]
+_CLOSED_PERIOD = ("closed", "settled")
+_REMOVED_MAX = 20000      # removed event ids remembered, so a late snapshot cannot revive them
+
+
+def channel_of(topic: Optional[str]) -> str:
+    """The channel of an ``odds`` update, from the last segment of its ``topic``."""
+    last = (topic or "").rsplit("/", 1)[-1]
+    return last if last in ("ld", "both", "dz", "pre") else "other"
+
+
+class _Event:
+    __slots__ = ("meta", "markets", "versions", "fair", "updated", "live")
+
+    def __init__(self) -> None:
+        self.updated = time.monotonic()
+        self.live = False           # got a live update: snapshots no longer rewind it
+        self.meta: Dict[str, Any] = {}
+        self.markets: Dict[str, Market] = {}
+        # The highest version seen per key, closed markets included: a late update of a
+        # market that has since closed must not bring it back.
+        self.versions: Dict[str, int] = {}
+        # key -> {"version", "margin", "prices"} as sent in `fair` messages.
+        self.fair: Dict[str, Dict[str, Any]] = {}
+
+
+class Book:
+    """Open markets per event, merged by version.
+
+    ``channels`` are the channels whose live updates go into the book: ``ld`` and ``both``
+    by default, which are the prices. Keep ``dz`` (volatile moments) out of a price book.
+    Add ``pre`` to follow pre-match prices.
+    """
+
+    def __init__(self, channels: Iterable[str] = PRICE_CHANNELS) -> None:
+        self.channels = frozenset(channels)
+        self._events: Dict[int, _Event] = {}
+        self._removed: "OrderedDict[Any, None]" = OrderedDict()
+
+    # ------------------------------------------------------------------ feeding it
+    def apply_message(self, msg: Dict[str, Any]) -> bool:
+        """Apply one message from the stream. Returns ``True`` if it touched the book.
+
+        Handles ``odds`` (live updates, removals and the state resent by the source),
+        ``snapshot`` parts and ``fair``. Any other message is ignored.
+        """
+        kind = msg.get("type")
+        if kind == "odds":
+            data = msg.get("data") or {}
+            dtype = data.get("type")
+            if dtype == "snapshot":
+                for rec in data.get("events") or ():
+                    self.apply_rec(rec, snapshot=True)
+                return True
+            if dtype != "live":
+                return False
+            rec = data.get("rec") or {}
+            if data.get("op") == "del":
+                return self.remove(rec.get("id"))
+            if channel_of(data.get("topic")) not in self.channels:
+                return False
+            self.apply_rec(rec)
+            return True
+        if kind == "snapshot":
+            for rec in msg.get("events") or ():
+                self.apply_rec(rec, snapshot=True)
+            return True
+        if kind == "fair":
+            return self.apply_fair(msg.get("data") or {})
+        return False
+
+    def apply_rec(self, rec: Dict[str, Any], snapshot: bool = False) -> None:
+        """Merge one event (a ``rec``) into the book.
+
+        ``snapshot=True`` for a rec from a snapshot. A snapshot is taken when it is asked
+        for and can arrive after newer live updates, so it never brings back a removed
+        event, and for an event already updated live it only adds what is newer: its
+        details and closed periods do not overwrite the live ones.
+        """
+        event_id = rec.get("id")
+        if event_id is None:
+            return
+        if snapshot and event_id in self._removed:
+            return
+        ev = self._events.get(event_id)
+        if ev is None:
+            ev = self._events[event_id] = _Event()
+            if not snapshot:
+                self._removed.pop(event_id, None)
+        ev.updated = time.monotonic()
+        rewind = snapshot and ev.live
+        if rewind:
+            for k, v in rec.items():
+                if k != "markets":
+                    ev.meta.setdefault(k, v)
+        else:
+            ev.meta.update((k, v) for k, v in rec.items() if k != "markets")
+            if not snapshot:
+                ev.live = True
+        newest = None
+        for m in rec.get("markets") or ():
+            key = m.get("key")
+            if key is None:
+                continue
+            version = m.get("version")
+            if version is not None and (newest is None or version > newest):
+                newest = version
+            seen = ev.versions.get(key)
+            if version is not None:
+                if seen is not None and version < seen:
+                    continue                    # an older update arriving late
+                ev.versions[key] = version
+            if m.get("status") == "open":
+                fair = m.get("fair")
+                if fair is not None:            # snapshot parts carry it inline
+                    m = {k: v for k, v in m.items() if k != "fair"}
+                    ev.fair[key] = {"version": version, **fair}
+                ev.markets[key] = m
+            else:
+                ev.markets.pop(key, None)
+                ev.fair.pop(key, None)
+        if rewind:
+            # An older picture of the periods: close only markets no newer than it.
+            if newest is not None:
+                self._close_periods(ev, rec.get("periods"), up_to=newest)
+        else:
+            self._close_periods(ev, rec.get("periods"))
+
+    @staticmethod
+    def _close_periods(ev: _Event, periods: Any, up_to: Optional[int] = None) -> None:
+        closed = set()
+        if isinstance(periods, dict):           # {"0": {"status": ...}} or {"0": "open"}
+            for num, p in periods.items():
+                status = p.get("status") if isinstance(p, dict) else p
+                if status in _CLOSED_PERIOD:
+                    closed.add(str(num))
+        elif isinstance(periods, list):
+            for p in periods:
+                if isinstance(p, dict) and p.get("status") in _CLOSED_PERIOD:
+                    closed.add(str(p.get("period")))
+        if not closed:
+            return
+        for key in [k for k, m in ev.markets.items() if str(m.get("period")) in closed
+                    and (up_to is None or (m.get("version") or 0) <= up_to)]:
+            del ev.markets[key]
+            ev.fair.pop(key, None)
+
+    def apply_fair(self, data: Dict[str, Any]) -> bool:
+        """Store the no-vig and fair prices of a ``fair`` message: only for the book's
+        channels, and only for the very market version the book holds."""
+        ev = self._events.get(data.get("event_id"))
+        if ev is None:
+            return False
+        channel = data.get("channel")
+        if channel not in ("ld", "both", "dz", "pre"):
+            channel = "other"
+        if channel not in self.channels:
+            return False
+        stored = False
+        for m in data.get("markets") or ():
+            key = m.get("key")
+            held = ev.markets.get(key) if key is not None else None
+            if held is None or held.get("version") != m.get("version"):
+                continue
+            ev.fair[key] = {"version": m.get("version"), "margin": m.get("margin"),
+                            "prices": m.get("prices") or []}
+            stored = True
+        return stored
+
+    def remove(self, event_id: Any) -> bool:
+        """Remove a whole event. Returns ``True`` if it was in the book. A snapshot that
+        arrives later will not bring it back; a live update will."""
+        self._removed[event_id] = None
+        self._removed.move_to_end(event_id)
+        while len(self._removed) > _REMOVED_MAX:
+            self._removed.popitem(last=False)
+        return self._events.pop(event_id, None) is not None
+
+    def prune(self, max_idle_s: float) -> List[int]:
+        """Remove the events with no update for ``max_idle_s`` seconds and no open market
+        left, and return their ids. Useful in a long-running bot: an event whose removal you
+        missed (while disconnected, say) otherwise stays in the book."""
+        limit = time.monotonic() - max_idle_s
+        gone = [eid for eid, ev in self._events.items()
+                if ev.updated < limit and not ev.markets]
+        for eid in gone:
+            del self._events[eid]
+        return gone
+
+    def clear(self) -> None:
+        self._events.clear()
+        self._removed.clear()
+
+    # ------------------------------------------------------------------ reading it
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def __contains__(self, event_id: object) -> bool:
+        return event_id in self._events
+
+    def __iter__(self) -> Iterator[int]:
+        return iter(list(self._events))
+
+    def event_ids(self) -> List[int]:
+        return list(self._events)
+
+    def event(self, event_id: int) -> Optional[Dict[str, Any]]:
+        """The event's details (``league``, ``participants``, ``state``, ``startTime``...),
+        without its markets, or ``None``."""
+        ev = self._events.get(event_id)
+        return ev.meta if ev is not None else None
+
+    def markets(self, event_id: int) -> Dict[str, Market]:
+        """The open markets of an event, by ``key`` (empty if unknown)."""
+        ev = self._events.get(event_id)
+        return dict(ev.markets) if ev is not None else {}
+
+    def market(self, event_id: int, key: str) -> Optional[Market]:
+        ev = self._events.get(event_id)
+        return ev.markets.get(key) if ev is not None else None
+
+    def fair(self, event_id: int, key: str) -> Optional[Dict[str, Any]]:
+        """``{"version", "margin", "prices"}`` for the market held, or ``None``.
+
+        Only returned when it belongs to the very ``version`` of the market in the book: an
+        older or newer one would be another price.
+        """
+        ev = self._events.get(event_id)
+        if ev is None:
+            return None
+        m = ev.markets.get(key)
+        f = ev.fair.get(key)
+        if m is None or f is None or f.get("version") != m.get("version"):
+            return None
+        return f
+
+    def items(self) -> Iterator[Tuple[int, Dict[str, Market]]]:
+        """``(event_id, markets)`` for every event."""
+        for event_id, ev in list(self._events.items()):
+            yield event_id, dict(ev.markets)

oddspush/errors.py

@@ -0,0 +1,107 @@
+"""Exceptions raised by the OddsPush client.
+
+Every error carries the API's ``code`` (``unauthorized``, ``rate_limited``...). Errors that
+retrying with the same token cannot fix (an unknown token, an expired plan, a plan without
+the stream) are :class:`FatalError`; the stream stops reconnecting when it gets one.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class OddsPushError(Exception):
+    """Base class of every error raised by this package."""
+
+    def __init__(self, code: str, message: Optional[str] = None, *,
+                 status: Optional[int] = None, close_code: Optional[int] = None,
+                 retry_after: Optional[float] = None) -> None:
+        self.code = code
+        self.status = status
+        self.close_code = close_code
+        self.retry_after = retry_after
+        super().__init__(message or code)
+
+
+class FatalError(OddsPushError):
+    """Retrying with the same token will not help."""
+
+
+class Unauthorized(FatalError):
+    """Unknown or revoked token (HTTP 401, close 4101)."""
+
+
+class SubscriptionExpired(FatalError):
+    """The plan has expired (close 4103)."""
+
+
+class NotInPlan(FatalError):
+    """The plan does not include this: ``stream_not_in_plan`` (4109), ``rest_not_in_plan``
+    or ``sport_not_in_plan``."""
+
+
+class IpNotAllowed(FatalError):
+    """Only for accounts set up with a fixed IP (close 4105)."""
+
+
+class TokenReplaced(FatalError):
+    """The token was used from another IP or connection, which now holds it (close 4107).
+
+    Reconnecting would close the other machine's stream, which would close this one again,
+    and so on. Run each token from one machine only.
+    """
+
+
+class RateLimited(OddsPushError):
+    """Too many requests, reconnects or snapshots: wait ``retry_after`` seconds."""
+
+
+class NotFound(OddsPushError):
+    """No such event, or no closing line yet (HTTP 404)."""
+
+
+class BadRequest(OddsPushError):
+    """A parameter is not valid (HTTP 400)."""
+
+
+class Unavailable(OddsPushError):
+    """The service is temporarily unavailable (HTTP 503)."""
+
+
+class StreamClosed(OddsPushError):
+    """The stream closed and is not going to be reopened (``reconnect=False``)."""
+
+
+_BY_CODE = {
+    "unauthorized": Unauthorized,
+    "subscription_expired": SubscriptionExpired,
+    "stream_not_in_plan": NotInPlan,
+    "rest_not_in_plan": NotInPlan,
+    "sport_not_in_plan": NotInPlan,
+    "ip_not_allowed": IpNotAllowed,
+    "replaced": TokenReplaced,
+    "rate_limited": RateLimited,
+    "reconnect_rate_limited": RateLimited,
+    "snapshot_rate_limited": RateLimited,
+    "not_found": NotFound,
+    "bad_request": BadRequest,
+    "unavailable": Unavailable,
+}
+
+#: Close codes of the stream, by number.
+CLOSE_CODES = {
+    4101: "unauthorized",
+    4102: "server_full",
+    4103: "subscription_expired",
+    4104: "connection_limit",
+    4105: "ip_not_allowed",
+    4106: "reconnect_rate_limited",
+    4107: "replaced",
+    4108: "too_slow",
+    4109: "stream_not_in_plan",
+}
+
+
+def error_for(code: str, message: Optional[str] = None, **kw) -> OddsPushError:
+    """The exception that matches an API error ``code``."""
+    return _BY_CODE.get(code, OddsPushError)(code, message, **kw)

oddspush/odds.py

@@ -0,0 +1,60 @@
+"""Odds arithmetic: American and decimal odds, implied probability, margin and CLV.
+
+The API sends prices in American odds and, with ``fair`` on, the no-vig and fair prices
+already worked out. These helpers cover the rest: converting your own prices and
+measuring your closing line value.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List
+
+
+def american_to_decimal(american: float) -> float:
+    """``-155`` -> ``1.6452``; ``+450`` -> ``5.5``. ``|american|`` must be at least 100."""
+    a = float(american)
+    if a >= 100:
+        return 1.0 + a / 100.0
+    if a <= -100:
+        return 1.0 + 100.0 / -a
+    raise ValueError(f"not valid American odds: {american!r}")
+
+
+def decimal_to_american(decimal: float) -> float:
+    """``2.5`` -> ``150``; ``1.5`` -> ``-200``. ``decimal`` must be above 1."""
+    d = float(decimal)
+    if d <= 1.0:
+        raise ValueError(f"not valid decimal odds: {decimal!r}")
+    if d >= 2.0:
+        return (d - 1.0) * 100.0
+    return -100.0 / (d - 1.0)
+
+
+def implied_probability(american: float) -> float:
+    """The probability the price implies, margin included: ``1 / decimal odds``."""
+    return 1.0 / american_to_decimal(american)
+
+
+def margin(prices: Iterable[float]) -> float:
+    """The bookmaker's margin of a market, from the American prices of all its legs:
+    the sum of their implied probabilities minus 1."""
+    return sum(implied_probability(p) for p in prices) - 1.0
+
+
+def no_vig(prices: Iterable[float]) -> List[float]:
+    """No-vig probabilities, multiplicative method: each implied probability divided by
+    their sum. The API sends these as ``no_vig`` (with ``fair`` on)."""
+    implied = [implied_probability(p) for p in prices]
+    total = sum(implied)
+    return [q / total for q in implied]
+
+
+def clv(decimal_odds: float, closing_decimal: float) -> float:
+    """Closing line value of a bet: ``decimal_odds / closing_decimal - 1``.
+
+    ``closing_decimal`` is usually the ``fair_decimal`` of the same market and leg in the
+    closing line. ``0.05`` means you beat the close by 5 %.
+    """
+    if closing_decimal <= 1.0:
+        raise ValueError(f"not valid decimal odds: {closing_decimal!r}")
+    return float(decimal_odds) / float(closing_decimal) - 1.0