55tech 0.1.0__py3-none-any.whl

fiftyfivetech/fixtures/endpoints.py

@@ -0,0 +1,158 @@
+from collections.abc import Sequence
+from datetime import datetime
+
+from fiftyfivetech.endpoints import Endpoints
+from fiftyfivetech.exceptions import FiftyFiveTechInvalidRequestError
+from fiftyfivetech.fixtures.resources import (
+    FixtureMappingResponse,
+    FixtureOddsResponse,
+    FixturesResponse,
+)
+from fiftyfivetech.utils import to_epoch_seconds
+
+
+class FixturesEndpoints(Endpoints):
+    """
+    Fixtures, fixture mappings and per-fixture odds.
+    """
+
+    def get_fixtures(
+        self,
+        *,
+        fixture_ids: Sequence[str] | None = None,
+        sport_id: int | None = None,
+        tournament_id: int | None = None,
+        start_time_from: datetime | int | None = None,
+        start_time_to: datetime | int | None = None,
+        bookmakers: Sequence[str] | None = None,
+    ) -> FixturesResponse:
+        """
+        Fetch fixtures: ``GET /fixtures``. Give ``fixture_ids``, or filters.
+
+        :param fixture_ids: These fixtures (the fast path).
+        :param sport_id: Fixtures of one sport, e.g. ``10`` for soccer.
+        :param tournament_id: Fixtures of one tournament.
+        :param start_time_from: Earliest scheduled start; datetime or epoch seconds.
+        :param start_time_to: Latest scheduled start; datetime or epoch seconds.
+        :param bookmakers: Include each fixture's ``bookmakers`` state for these slugs,
+            and keep only fixtures they are mapped to.
+        :returns: The matching fixtures.
+        """
+        return self.conn.call(FixturesResponse, "GET", "/fixtures", wrap="fixtures", params={
+            "fixtureIds": fixture_ids,
+            "sportId": sport_id,
+            "tournamentId": tournament_id,
+            "startTimeFrom": to_epoch_seconds(start_time_from),
+            "startTimeTo": to_epoch_seconds(start_time_to),
+            "bookmakers": bookmakers,
+        })
+
+    def get_fixtures_live(
+        self,
+        *,
+        sport_id: int | None = None,
+        tournament_id: int | None = None,
+        bookmakers: Sequence[str] | None = None,
+    ) -> FixturesResponse:
+        """
+        Fetch fixtures in play: ``GET /fixtures/live``.
+
+        :param sport_id: Fixtures of one sport.
+        :param tournament_id: Fixtures of one tournament.
+        :param bookmakers: Bookmaker slugs to include state for, and filter by.
+        :returns: The live fixtures.
+        """
+        return self.conn.call(
+            FixturesResponse, "GET", "/fixtures/live", wrap="fixtures", params={
+                "sportId": sport_id,
+                "tournamentId": tournament_id,
+                "bookmakers": bookmakers,
+            })
+
+    def get_fixtures_today(
+        self,
+        *,
+        sport_id: int | None = None,
+        tournament_id: int | None = None,
+        bookmakers: Sequence[str] | None = None,
+    ) -> FixturesResponse:
+        """
+        Fetch today's fixtures: ``GET /fixtures/today``.
+
+        :param sport_id: Fixtures of one sport.
+        :param tournament_id: Fixtures of one tournament.
+        :param bookmakers: Bookmaker slugs to include state for, and filter by.
+        :returns: Today's fixtures.
+        """
+        return self.conn.call(
+            FixturesResponse, "GET", "/fixtures/today", wrap="fixtures", params={
+                "sportId": sport_id,
+                "tournamentId": tournament_id,
+                "bookmakers": bookmakers,
+            })
+
+    def get_fixture_mapping(
+        self,
+        *,
+        bookmaker: str,
+        fixture_ids: Sequence[str] | None = None,
+        bookmaker_fixture_ids: Sequence[str] | None = None,
+    ) -> FixtureMappingResponse:
+        """
+        Pair 55Tech fixtures with a bookmaker's: ``GET /fixtures/mapping``. Give
+        exactly one of ``fixture_ids`` or ``bookmaker_fixture_ids``.
+
+        Send long lists with ``utils.batch``.
+
+        :param bookmaker: Bookmaker slug, e.g. ``"pinnacle"``. The spec makes it
+            optional, but the API rejects a request without it.
+        :param fixture_ids: 55Tech fixture ids to find the bookmaker's ids for.
+        :param bookmaker_fixture_ids: The bookmaker's ids to find 55Tech fixtures for.
+        :returns: One row per id; the other side of an unpaired id is ``None``.
+        :raises FiftyFiveTechInvalidRequestError: Unless exactly one non-empty id list is given.
+        """
+        given = [ids for ids in (fixture_ids, bookmaker_fixture_ids) if ids]
+        if len(given) != 1:
+            raise FiftyFiveTechInvalidRequestError(
+                "get_fixture_mapping needs one of fixture_ids or bookmaker_fixture_ids")
+        return self.conn.call(
+            FixtureMappingResponse, "GET", "/fixtures/mapping", wrap="mappings", params={
+                "bookmaker": bookmaker,
+                "fixtureIds": fixture_ids,
+                "bookmakerFixtureIds": (
+                    [str(i) for i in bookmaker_fixture_ids] if bookmaker_fixture_ids else None),
+            })
+
+    def get_fixture_odds(
+        self,
+        fixture_id: str,
+        *,
+        bookmakers: Sequence[str] | None = None,
+        since: int | None = None,
+        market_active: bool | None = None,
+        main_line: bool | None = None,
+    ) -> FixtureOddsResponse:
+        """
+        Fetch one fixture's current odds: ``GET /fixtures/odds``.
+
+        One fixture per call: a comma-joined id is treated as a single unknown one.
+        Every line is returned, alternates included, unless ``main_line`` says otherwise.
+        Merge into streamed state per ``oddsId``, keeping the later ``changed_at``.
+
+        :param fixture_id: 55Tech fixture id.
+        :param bookmakers: Bookmaker slugs to include; all the key allows if omitted.
+        :param since: Only records with ``changedAt`` at or after this, epoch milliseconds.
+        :param market_active: Only records whose ``marketActive`` is this.
+        :param main_line: Only records whose ``mainLine`` is this.
+        :returns: The fixture with each bookmaker's records.
+        :raises FiftyFiveTechInvalidRequestError: If ``fixture_id`` is empty.
+        """
+        if not fixture_id:
+            raise FiftyFiveTechInvalidRequestError("get_fixture_odds needs a fixture_id")
+        return self.conn.call(FixtureOddsResponse, "GET", "/fixtures/odds", params={
+            "fixtureId": fixture_id,
+            "bookmakers": bookmakers,
+            "since": since,
+            "marketActive": market_active,
+            "mainLine": main_line,
+        })

fiftyfivetech/fixtures/resources.py

@@ -0,0 +1,216 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from fiftyfivetech.resources import BaseModel, Response
+from fiftyfivetech.utils import from_timestamp
+
+
+@dataclass(kw_only=True, slots=True)
+class FixtureStatus(BaseModel):
+    """
+    Where a fixture is in its lifecycle.
+    """
+    live: bool
+    status_id: int | None = None
+    status_name: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Sport(BaseModel):
+    """
+    A sport, e.g. ``10`` Soccer.
+    """
+    sport_id: int
+    sport_name: str
+
+
+@dataclass(kw_only=True, slots=True)
+class Tournament(BaseModel):
+    """
+    A competition, e.g. a league; ``category_name`` is usually its country.
+    """
+    tournament_id: int
+    tournament_name: str
+    category_name: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Season(BaseModel):
+    """
+    The season a fixture belongs to.
+    """
+    season_id: int | None = None
+    season_name: str | None = None
+    season_round: int | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Venue(BaseModel):
+    """
+    Where a fixture is played.
+    """
+    venue_id: int | None = None
+    venue_name: str | None = None
+    venue_location: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Participants(BaseModel):
+    """
+    A fixture's two sides, in 55Tech's order: outcome ``"1"`` is ``participant1``.
+    """
+    participant1_id: int
+    participant1_name: str
+    participant1_short_name: str | None = None
+    participant1_abbr: str | None = None
+    participant1_rot_nr: int | None = None
+    participant2_id: int
+    participant2_name: str
+    participant2_short_name: str | None = None
+    participant2_abbr: str | None = None
+    participant2_rot_nr: int | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Score(BaseModel):
+    """
+    The score of one period, e.g. ``"p1"``, ``"fulltime"``, ``"result"``.
+    """
+    period: str
+    participant1_score: int | None = None
+    participant2_score: int | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Clock(BaseModel):
+    """
+    A live fixture's match clock; every field is ``None`` before kick-off.
+    """
+    current_period: str | None = None
+    current_time: str | None = None
+    remaining_time: str | None = None
+    remaining_time_in_period: str | None = None
+    stopped: bool | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class BookmakerFixtureMeta(BaseModel):
+    """
+    One bookmaker's state on one fixture, from ``GET /fixtures?bookmakers=...`` or the
+    ``bookmakers`` stream channel. Present only while the bookmaker has valid odds on it.
+    """
+    bookmaker: str
+    bookmaker_fixture_id: str | None = None
+    fixture_path: str | None = None
+    has_odds: bool
+    stale_odds: bool
+    suspended: bool
+    participants_rotated: bool
+    updated_at: datetime
+    meta: dict[str, Any] | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Fixture(BaseModel):
+    """
+    A fixture (an event): who plays, when, and its live state.
+    """
+    fixture_id: str
+    reissued_fixture_id: str | None = None
+    status: FixtureStatus
+    sport: Sport
+    tournament: Tournament
+    season: Season | None = None
+    venue: Venue | None = None
+    start_time: int
+    true_start_time: datetime | None = None
+    true_end_time: datetime | None = None
+    participants: Participants
+    scores: dict[str, Score] = field(default_factory=dict)
+    clock: Clock | None = None
+    expected_periods: int | None = None
+    period_length: int | None = None
+    external_providers: dict[str, Any] = field(default_factory=dict)
+    bookmakers: dict[str, BookmakerFixtureMeta] = field(default_factory=dict)
+
+    @property
+    def starts_at(self) -> datetime:
+        """
+        ``start_time`` as an aware UTC datetime.
+        """
+        return from_timestamp(self.start_time)
+
+
+@dataclass(kw_only=True, slots=True)
+class FixturesResponse(Response):
+    """
+    Fixtures (``GET /fixtures``; the array is wrapped as ``fixtures``).
+    """
+    fixtures: list[Fixture] = field(default_factory=list)
+
+
+@dataclass(kw_only=True, slots=True)
+class FixtureMapping(BaseModel):
+    """
+    One bookmaker fixture id resolved to a 55Tech fixture.
+    One row per id asked for. The unknown side of an unpaired id is ``None`` (the
+    spec says otherwise, the API does this); pairings fill in as coverage catches up.
+    """
+    bookmaker: str
+    fixture_id: str | None = None
+    bookmaker_fixture_id: str | None = None
+    participants_rotated: bool | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class FixtureMappingResponse(Response):
+    """
+    Fixture pairings (``GET /fixtures/mapping``; the array is wrapped as ``mappings``),
+    one per id asked for, paired or not.
+    """
+    mappings: list[FixtureMapping] = field(default_factory=list)
+
+
+@dataclass(kw_only=True, slots=True)
+class OddsRecord(BaseModel):
+    """
+    One bookmaker's price on one outcome, as REST and the stream both send it.
+
+    Keyed by its ``oddsId``, ``"{fixtureId}:{bookmaker}:{outcomeId}:{playerId}"``;
+    treat the key as opaque and read the fields. Each record is the latest state,
+    not a delta. Kind and line come from the market dictionary, via ``outcome_id``;
+    the bookmaker's own ids sit beside them as sent.
+    """
+    bookmaker: str
+    outcome_id: int
+    player_id: int
+    price: float
+    active: bool
+    changed_at: int
+    market_id: int | None = None
+    market_active: bool | None = None
+    main_line: bool | None = None
+    limit: float | None = None
+    bookmaker_changed_at: int | None = None
+    bookmaker_market_id: str | None = None
+    bookmaker_outcome_id: str | None = None
+    price_fractional: str | None = None
+    price_american: int | None = None
+    meta: dict[str, Any] | None = None
+    betslip: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class FixtureOddsResponse(Fixture):
+    """
+    One fixture with its current odds (``GET /fixtures/odds``): every ``Fixture``
+    field, plus ``odds`` and the response timings.
+    """
+    odds: dict[str, dict[str, OddsRecord]] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+    sent_at: datetime = field(init=False, repr=False, compare=False)
+    received_at: datetime = field(init=False, repr=False, compare=False)
+    latency_ms: float = field(init=False, repr=False, compare=False)

fiftyfivetech/markets/__init__.py

@@ -0,0 +1,9 @@
+from fiftyfivetech.markets.endpoints import MarketsEndpoints
+from fiftyfivetech.markets.resources import Market, MarketOutcome, MarketsResponse
+
+__all__ = [
+    "MarketsEndpoints",
+    "Market",
+    "MarketOutcome",
+    "MarketsResponse",
+]

fiftyfivetech/markets/endpoints.py

@@ -0,0 +1,37 @@
+from collections.abc import Sequence
+
+from fiftyfivetech.endpoints import Endpoints
+from fiftyfivetech.exceptions import FiftyFiveTechInvalidRequestError
+from fiftyfivetech.markets.resources import MarketsResponse
+
+
+class MarketsEndpoints(Endpoints):
+    """
+    The market dictionary.
+    """
+
+    def get_markets(
+        self,
+        *,
+        sport_id: int | None = None,
+        market_ids: Sequence[int] | None = None,
+        outcome_ids: Sequence[int] | None = None,
+    ) -> MarketsResponse:
+        """
+        Fetch market definitions: ``GET /markets``. Give exactly one filter.
+
+        :param sport_id: Every market of one sport, e.g. ``10`` for soccer.
+        :param market_ids: These markets.
+        :param outcome_ids: The markets these outcomes belong to.
+        :returns: The matching definitions.
+        :raises FiftyFiveTechInvalidRequestError: Unless exactly one filter is given.
+        """
+        given = [v for v in (sport_id, market_ids, outcome_ids) if v is not None]
+        if len(given) != 1:
+            raise FiftyFiveTechInvalidRequestError(
+                "get_markets needs exactly one of sport_id, market_ids or outcome_ids")
+        return self.conn.call(MarketsResponse, "GET", "/markets", wrap="markets", params={
+            "sportId": sport_id,
+            "marketIds": market_ids,
+            "outcomeIds": outcome_ids,
+        })

fiftyfivetech/markets/resources.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field
+
+from fiftyfivetech.resources import BaseModel, Response
+
+
+@dataclass(kw_only=True, slots=True)
+class MarketOutcome(BaseModel):
+    """
+    One outcome (side) of a market definition.
+    """
+    outcome_id: int
+    outcome_name: str | None = None
+
+
+@dataclass(kw_only=True, slots=True)
+class Market(BaseModel):
+    """
+    What a 55Tech market id is: odds records name markets and outcomes only by id.
+
+    A market is the coordinates ``market_type -> period -> handicap``; every line is its
+    own ``market_id``, so "Over 2.5" and "Over 3.5" are two markets. Corners and
+    bookings have their own types (``spreads-corners``, ``totals-bookings``, ...).
+    ``market_type`` and ``period`` are open vocabularies that grow, and have been
+    renamed (see the 2026-10-05 changelog): key on ``market_id`` where you can.
+    """
+    market_id: int
+    sport_id: int | None = None
+    market_type: str | None = None
+    period: str | None = None
+    handicap: float | None = None
+    market_length: int | None = None
+    player_prop: bool | None = None
+    market_name: str | None = None
+    market_name_short: str | None = None
+    outcomes: list[MarketOutcome] = field(default_factory=list)
+
+
+@dataclass(kw_only=True, slots=True)
+class MarketsResponse(Response):
+    """
+    Market definitions (``GET /markets``; the array is wrapped as ``markets``).
+    """
+    markets: list[Market] = field(default_factory=list)

fiftyfivetech/resources.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from fiftyfivetech.utils import decode, encode
+
+
+@dataclass(kw_only=True, slots=True)
+class BaseModel:
+    """
+    Base class for every model.
+    """
+
+    @classmethod
+    def from_json(cls: Any, data: dict[str, Any]) -> Any:
+        """
+        Build the model from a decoded JSON object.
+
+        :param data: Object as the API returns it; undeclared keys are ignored.
+        :returns: The model.
+        """
+        return decode(cls, data)
+
+    def to_json(self) -> dict[str, Any]:
+        """
+        Convert the model to a JSON-ready dict.
+
+        :returns: The non-``None`` fields, with camelCase keys.
+        """
+        return encode(self)
+
+
+@dataclass(kw_only=True, slots=True)
+class Response(BaseModel):
+    """
+    Base class for a top-level API response.
+
+    Endpoints whose body is a JSON array are wrapped in an object, e.g.
+    ``{"markets": [...]}``, so every response has named fields and a ``raw``.
+    """
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+    sent_at: datetime = field(init=False, repr=False, compare=False)
+    received_at: datetime = field(init=False, repr=False, compare=False)
+    latency_ms: float = field(init=False, repr=False, compare=False)

fiftyfivetech/streaming/__init__.py

@@ -0,0 +1,55 @@
+from fiftyfivetech.streaming.endpoints import StreamingEndpoints
+from fiftyfivetech.streaming.listener import BaseListener, StreamListener, parse
+from fiftyfivetech.streaming.resources import (
+    BOOKMAKERS_CHANNEL,
+    CHANNEL_TYPES,
+    CONTROL_TYPES,
+    ODDS_CHANNEL,
+    Access,
+    BookmakersPayload,
+    BookmakersUpdate,
+    ChannelUpdate,
+    Control,
+    DictFrame,
+    ErrorMessage,
+    FixtureBook,
+    LoginOk,
+    OddsPayload,
+    OddsUpdate,
+    ReceiveType,
+    Reconnect,
+    ResumeComplete,
+    ResumeInfo,
+    SnapshotRequired,
+    Update,
+)
+from fiftyfivetech.streaming.stream import FiftyFiveTechStream
+
+__all__ = [
+    "BOOKMAKERS_CHANNEL",
+    "CHANNEL_TYPES",
+    "CONTROL_TYPES",
+    "ODDS_CHANNEL",
+    "Access",
+    "BaseListener",
+    "BookmakersPayload",
+    "BookmakersUpdate",
+    "ChannelUpdate",
+    "Control",
+    "DictFrame",
+    "ErrorMessage",
+    "FixtureBook",
+    "LoginOk",
+    "FiftyFiveTechStream",
+    "OddsPayload",
+    "OddsUpdate",
+    "ReceiveType",
+    "Reconnect",
+    "ResumeComplete",
+    "ResumeInfo",
+    "SnapshotRequired",
+    "StreamListener",
+    "StreamingEndpoints",
+    "Update",
+    "parse",
+]

fiftyfivetech/streaming/endpoints.py

@@ -0,0 +1,61 @@
+from collections.abc import Sequence
+
+from fiftyfivetech.endpoints import Endpoints
+from fiftyfivetech.streaming.listener import BaseListener, StreamListener
+from fiftyfivetech.streaming.resources import ODDS_CHANNEL, ReceiveType
+from fiftyfivetech.streaming.stream import FiftyFiveTechStream
+
+
+class StreamingEndpoints(Endpoints):
+    """
+    The WebSocket gateway.
+    """
+
+    def create_stream(
+        self,
+        listener: BaseListener | None = None,
+        *,
+        url: str | None = None,
+        channels: Sequence[str] = (ODDS_CHANNEL,),
+        bookmakers: Sequence[str] | None = None,
+        sport_ids: Sequence[int] | None = None,
+        tournament_ids: Sequence[int] | None = None,
+        fixture_ids: Sequence[str] | None = None,
+        receive_type: ReceiveType = "zstd",
+        lang: str | None = None,
+        client_name: str | None = None,
+        timeout: float = 30.0,
+        keepalive: float | None = 60.0,
+    ) -> FiftyFiveTechStream:
+        """
+        Create a stream on this connection; nothing is sent until it connects.
+
+        :param listener: Receives every frame; a new ``StreamListener`` if omitted.
+        :param url: Gateway URL; defaults to the connection's ``stream_url``.
+        :param channels: Channels to receive.
+        :param bookmakers: Bookmaker slugs to receive; all the key allows if omitted.
+        :param sport_ids: Sports to receive; all if omitted.
+        :param tournament_ids: Tournaments to receive; all if omitted.
+        :param fixture_ids: Fixtures to receive; all if omitted.
+        :param receive_type: ``"zstd"``, ``"zstd-dict"`` or ``"json"``.
+        :param lang: Language for translated names, e.g. ``"en"``.
+        :param client_name: Name to identify this client to the gateway.
+        :param timeout: Seconds to wait to connect, or for the login reply.
+        :param keepalive: Seconds without a frame before sending a ping; ``None`` never pings.
+        :returns: The stream.
+        """
+        return FiftyFiveTechStream(
+            self.conn,
+            listener if listener is not None else StreamListener(),
+            url=url,
+            channels=channels,
+            bookmakers=bookmakers,
+            sport_ids=sport_ids,
+            tournament_ids=tournament_ids,
+            fixture_ids=fixture_ids,
+            receive_type=receive_type,
+            lang=lang,
+            client_name=client_name,
+            timeout=timeout,
+            keepalive=keepalive,
+        )