sharpapi 0.1.0__py3-none-any.whl

sharpapi/exceptions.py

@@ -0,0 +1,52 @@
+"""SharpAPI exceptions."""
+
+from __future__ import annotations
+
+
+class SharpAPIError(Exception):
+    """Base exception for all SharpAPI errors."""
+
+    def __init__(self, message: str, code: str | None = None, status: int | None = None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class AuthenticationError(SharpAPIError):
+    """API key is missing or invalid (401)."""
+
+
+class TierRestrictedError(SharpAPIError):
+    """Feature not available on current tier (403)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        status: int | None = None,
+        required_tier: str | None = None,
+    ):
+        super().__init__(message, code, status)
+        self.required_tier = required_tier
+
+
+class RateLimitedError(SharpAPIError):
+    """Too many requests (429)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        status: int | None = None,
+        retry_after: float | None = None,
+    ):
+        super().__init__(message, code, status)
+        self.retry_after = retry_after
+
+
+class ValidationError(SharpAPIError):
+    """Invalid request parameters (400)."""
+
+
+class StreamError(SharpAPIError):
+    """Error during SSE streaming."""

sharpapi/models.py

@@ -0,0 +1,433 @@
+"""Pydantic models for SharpAPI responses."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+# =============================================================================
+# Common
+# =============================================================================
+
+
+class OddsValue(BaseModel):
+    """Odds in multiple formats."""
+
+    american: int | float
+    decimal: float
+    probability: float
+
+
+class Pagination(BaseModel):
+    limit: int
+    offset: int
+    has_more: bool
+    next_offset: Optional[int] = None
+    total: Optional[int] = None
+
+
+class ResponseMeta(BaseModel):
+    """Metadata returned with API responses."""
+
+    count: Optional[int] = None
+    total: Optional[int] = None
+    pagination: Optional[Pagination] = None
+    updated: Optional[str] = None
+    source: Optional[str] = None
+    last_update: Optional[str] = None
+    data_age_seconds: Optional[float] = None
+    filters: Optional[dict[str, Any]] = None
+    summary: Optional[dict[str, Any]] = None
+    books_analyzed: Optional[int] = None
+
+
+class APIResponse(BaseModel, Generic[T]):
+    """Standard API response wrapper."""
+
+    success: Optional[bool] = None
+    data: T
+    meta: Optional[ResponseMeta] = None
+    timestamp: Optional[str] = None
+    tier: Optional[str] = None
+
+    def to_dataframe(self, flatten: bool = True):
+        """Convert response data to a pandas DataFrame.
+
+        Requires ``pip install sharpapi[pandas]``.
+
+        Args:
+            flatten: If True (default), flatten nested objects like
+                ``game_state.period`` into ``game_state_period`` columns.
+                Nested lists (like ``legs``) remain as-is.
+
+        Returns:
+            pandas.DataFrame with one row per item in ``data``.
+        """
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError(
+                "pandas is required for to_dataframe(). "
+                "Install it with: pip install sharpapi[pandas]"
+            ) from None
+
+        data = self.data
+        if not data:
+            return pd.DataFrame()
+
+        if not isinstance(data, list):
+            data = [data]
+
+        rows = []
+        for item in data:
+            if hasattr(item, "model_dump"):
+                row = item.model_dump()
+            else:
+                row = dict(item) if isinstance(item, dict) else {"value": item}
+
+            if flatten:
+                row = _flatten_dict(row)
+            rows.append(row)
+
+        return pd.DataFrame(rows)
+
+
+def _flatten_dict(d: dict, parent_key: str = "", sep: str = "_") -> dict:
+    """Flatten nested dicts, skip lists."""
+    items: list[tuple[str, Any]] = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+        if isinstance(v, dict):
+            items.extend(_flatten_dict(v, new_key, sep).items())
+        else:
+            items.append((new_key, v))
+    return dict(items)
+
+
+class GameState(BaseModel):
+    """Live game state."""
+
+    period: Optional[str] = None
+    clock: Optional[str] = None
+    score_home: Optional[int] = None
+    score_away: Optional[int] = None
+
+
+# =============================================================================
+# Odds
+# =============================================================================
+
+
+class OddsLine(BaseModel):
+    """A single odds line from a sportsbook."""
+
+    id: str
+    sportsbook: str
+    sportsbook_name: Optional[str] = None
+    event_id: str
+    sport: str
+    league: str
+    home_team: str
+    away_team: str
+    market_type: str
+    selection: str
+    selection_type: Optional[str] = None
+    odds_american: int | float
+    odds_decimal: float
+    probability: float
+    line: Optional[float] = None
+    event_start_time: Optional[str] = None
+    timestamp: Optional[str] = None
+    is_live: bool = False
+    deep_link: Optional[str] = None
+    player_name: Optional[str] = None
+    stat_category: Optional[str] = None
+    home_score: Optional[int] = None
+    away_score: Optional[int] = None
+    game_period: Optional[str] = None
+    game_clock: Optional[str] = None
+
+
+# =============================================================================
+# EV Opportunities
+# =============================================================================
+
+
+class EVOpportunity(BaseModel):
+    """A positive expected value (+EV) opportunity."""
+
+    id: str
+    event_id: Optional[str] = Field(None, alias="game_id")
+    event_name: Optional[str] = Field(None, alias="game")
+    sport: str
+    league: str
+    market_type: Optional[str] = Field(None, alias="market")
+    selection: str
+    sportsbook: str
+    odds_american: int | float
+    odds_decimal: float
+    no_vig_odds: Optional[float] = None
+    true_probability: Optional[float] = None
+    ev_percent: float = Field(alias="ev_percent")
+    kelly_fraction: Optional[float] = None
+    confidence_score: Optional[float] = None
+    book_count: Optional[int] = None
+    market_width: Optional[float] = None
+    devig_method: Optional[str] = None
+    devig_book: Optional[str] = None
+    sharp_odds_american: Optional[int | float] = None
+    sharp_odds_decimal: Optional[float] = None
+    line: Optional[float] = None
+    home_team: Optional[str] = None
+    away_team: Optional[str] = None
+    start_time: Optional[str] = None
+    is_live: bool = False
+    arb_available: Optional[bool] = None
+    arb_profit: Optional[float] = None
+    is_player_prop: bool = False
+    player_name: Optional[str] = None
+    stat_category: Optional[str] = None
+    possibly_stale: bool = False
+    oldest_odds_age_seconds: Optional[float] = None
+    warnings: List[str] = Field(default_factory=list)
+    detected_at: Optional[str] = None
+    external_event_id: Optional[str] = None
+    selection_id: Optional[str] = None
+
+    model_config = {"populate_by_name": True}
+
+
+# =============================================================================
+# Arbitrage Opportunities
+# =============================================================================
+
+
+class ArbitrageLeg(BaseModel):
+    """One leg of an arbitrage opportunity."""
+
+    sportsbook: str
+    selection: str
+    odds_american: int | float
+    odds_decimal: float
+    implied_probability: Optional[float] = None
+    stake_percent: float
+    timestamp: Optional[str] = None
+    external_event_id: Optional[str] = None
+    selection_id: Optional[str] = None
+    market_id: Optional[str] = None
+
+
+class ArbitrageOpportunity(BaseModel):
+    """A guaranteed-profit arbitrage opportunity."""
+
+    id: str
+    event_id: Optional[str] = None
+    event_name: str
+    sport: str
+    league: Optional[str] = None
+    market_type: str
+    line: Optional[float] = None
+    profit_percent: float
+    implied_total: Optional[float] = None
+    estimated_net_profit_percent: Optional[float] = None
+    start_time: Optional[str] = None
+    is_live: bool = False
+    is_alternate_line: bool = False
+    possibly_stale: bool = False
+    oldest_odds_age_seconds: Optional[float] = None
+    warnings: List[str] = Field(default_factory=list)
+    game_state: Optional[GameState] = None
+    ev_available: Optional[bool] = None
+    ev_percentage: Optional[float] = None
+    is_player_prop: bool = False
+    player_name: Optional[str] = None
+    stat_category: Optional[str] = None
+    legs: List[ArbitrageLeg]
+    detected_at: Optional[str] = None
+
+
+# =============================================================================
+# Middle Opportunities
+# =============================================================================
+
+
+class MiddleSide(BaseModel):
+    """One side of a middle opportunity."""
+
+    book: str
+    selection: str
+    line: float
+    odds: OddsValue
+    stake_percent: Optional[float] = None
+    odds_age_seconds: Optional[float] = None
+    deep_link: Optional[str] = None
+
+
+class MiddleOpportunity(BaseModel):
+    """A middle opportunity where both sides can win."""
+
+    id: str
+    event_id: Optional[str] = None
+    event_name: str
+    sport: str
+    league: Optional[str] = None
+    market_type: str
+    home_team: Optional[str] = None
+    away_team: Optional[str] = None
+    start_time: Optional[str] = None
+    side1: Optional[MiddleSide] = None
+    side2: Optional[MiddleSide] = None
+    middle_size: Optional[float] = None
+    middle_numbers: Optional[List[int]] = None
+    middle_probability: Optional[float] = None
+    expected_value: Optional[float] = None
+    roi_percentage: Optional[float] = None
+    worst_case_loss: Optional[float] = None
+    best_case_profit: Optional[float] = None
+    break_even_percent: Optional[float] = None
+    is_guaranteed_profit: bool = False
+    guaranteed_roi: Optional[float] = None
+    key_numbers: Optional[List[int]] = None
+    key_number_probability: Optional[float] = None
+    quality_score: Optional[float] = None
+    market_overround: Optional[float] = None
+    is_live: bool = False
+    game_state: Optional[GameState] = None
+    is_player_prop: bool = False
+    player_name: Optional[str] = None
+    stat_category: Optional[str] = None
+    odds_age_seconds: Optional[float] = None
+    warnings: List[str] = Field(default_factory=list)
+    detected_at: Optional[str] = None
+    # Flat fields (alternative to side1/side2 nesting)
+    gap_size: Optional[float] = Field(None, alias="gapSize")
+    potential_profit: Optional[float] = Field(None, alias="potentialProfit")
+    legs: Optional[List[ArbitrageLeg]] = None
+
+    model_config = {"populate_by_name": True}
+
+
+# =============================================================================
+# Low Hold
+# =============================================================================
+
+
+class LowHoldSide(BaseModel):
+    """One side of a low-hold opportunity."""
+
+    selection: str
+    books: Optional[List[str]] = None
+    line: Optional[float] = None
+    odds: Optional[OddsValue] = None
+    deep_links: Optional[dict[str, str]] = None
+
+
+class LowHoldOpportunity(BaseModel):
+    """A low-hold (low vig) market."""
+
+    id: str
+    event_id: Optional[str] = None
+    event_name: str
+    sport: str
+    league: Optional[str] = None
+    market_type: str
+    line: Optional[float] = None
+    home_team: Optional[str] = None
+    away_team: Optional[str] = None
+    start_time: Optional[str] = None
+    hold_percentage: float
+    side1: Optional[LowHoldSide] = None
+    side2: Optional[LowHoldSide] = None
+    side3: Optional[LowHoldSide] = None
+    is_live: bool = False
+    game_state: Optional[GameState] = None
+    is_alternate_line: bool = False
+    all_books: Optional[List[str]] = None
+    confidence: Optional[float] = None
+    odds_age_seconds: Optional[float] = None
+    possibly_stale: bool = False
+    is_player_prop: bool = False
+    player_name: Optional[str] = None
+    stat_category: Optional[str] = None
+    detected_at: Optional[str] = None
+
+
+# =============================================================================
+# Reference Data
+# =============================================================================
+
+
+class Sport(BaseModel):
+    id: str
+    name: str
+    slug: str
+    active: bool
+    event_count: Optional[int] = None
+
+
+class League(BaseModel):
+    id: str
+    name: str
+    slug: str
+    sport_id: Optional[str] = None
+    country: Optional[str] = None
+    active: bool
+
+
+class Sportsbook(BaseModel):
+    id: str
+    name: str
+    slug: str
+    active: bool
+    regions: Optional[List[str]] = None
+    features: Optional[List[str]] = None
+
+
+class Event(BaseModel):
+    id: str
+    sport: str
+    league: str
+    home_team: str
+    away_team: str
+    start_time: Optional[str] = None
+    is_live: bool = False
+    status: Optional[str] = None
+
+
+# =============================================================================
+# Account
+# =============================================================================
+
+
+class AccountLimits(BaseModel):
+    requests_per_minute: Optional[int] = None
+    max_streams: Optional[int] = None
+    odds_delay_seconds: Optional[int] = None
+    max_books: Optional[int] = None
+
+
+class AccountFeatures(BaseModel):
+    ev: bool = False
+    arbitrage: bool = False
+    middles: bool = False
+    streaming: bool = False
+
+
+class AccountInfo(BaseModel):
+    key: Optional[dict[str, Any]] = None
+    limits: Optional[AccountLimits] = None
+    features: Optional[AccountFeatures] = None
+    add_ons: Optional[List[str]] = None
+
+
+class RateLimitInfo(BaseModel):
+    """Rate limit state from response headers."""
+
+    limit: Optional[int] = None
+    remaining: Optional[int] = None
+    reset: Optional[float] = None
+    tier: Optional[str] = None

sharpapi/streaming.py

@@ -0,0 +1,200 @@
+"""SSE streaming client for SharpAPI real-time data."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Callable, Iterator
+
+import httpx
+
+from .exceptions import AuthenticationError, StreamError
+
+logger = logging.getLogger("sharpapi.stream")
+
+EventHandler = Callable[[Any], None]
+
+
+class EventStream:
+    """Server-Sent Events (SSE) stream client.
+
+    Connects to the SharpAPI streaming endpoint and dispatches typed events
+    to registered handlers.
+
+    Example::
+
+        stream = client.stream.opportunities(league="nba")
+
+        @stream.on("ev:detected")
+        def handle_ev(data):
+            print(f"+EV: {data}")
+
+        @stream.on("arb:detected")
+        def handle_arb(data):
+            print(f"Arb: {data}")
+
+        stream.connect()  # Blocks, processing events
+    """
+
+    def __init__(
+        self,
+        url: str,
+        headers: dict[str, str],
+        timeout: float = 90.0,
+        max_reconnects: int = 5,
+    ):
+        self._url = url
+        self._headers = headers
+        self._timeout = timeout
+        self._max_reconnects = max_reconnects
+        self._handlers: dict[str, list[EventHandler]] = {}
+        self._running = False
+        self._last_event_id: str | None = None
+
+    def on(self, event_type: str, handler: EventHandler | None = None):
+        """Register a handler for an event type. Can be used as a decorator.
+
+        Args:
+            event_type: SSE event name (e.g. "ev:detected", "arb:detected",
+                "odds:update", "snapshot", "heartbeat", "error")
+            handler: Callback receiving parsed event data. If None, returns
+                a decorator.
+
+        Example::
+
+            @stream.on("ev:detected")
+            def handle_ev(data):
+                print(data)
+
+            # Or without decorator:
+            stream.on("arb:detected", my_handler)
+        """
+        if handler is not None:
+            self._handlers.setdefault(event_type, []).append(handler)
+            return handler
+
+        def decorator(fn: EventHandler) -> EventHandler:
+            self._handlers.setdefault(event_type, []).append(fn)
+            return fn
+
+        return decorator
+
+    def off(self, event_type: str, handler: EventHandler) -> None:
+        """Remove a handler for an event type."""
+        handlers = self._handlers.get(event_type, [])
+        if handler in handlers:
+            handlers.remove(handler)
+
+    def _emit(self, event_type: str, data: Any) -> None:
+        for handler in self._handlers.get(event_type, []):
+            try:
+                handler(data)
+            except Exception:
+                logger.exception("Handler error for event %s", event_type)
+        # Also emit to wildcard handlers
+        for handler in self._handlers.get("*", []):
+            try:
+                handler({"type": event_type, "data": data})
+            except Exception:
+                logger.exception("Wildcard handler error for event %s", event_type)
+
+    def connect(self) -> None:
+        """Connect and block, processing events until disconnect() or error.
+
+        Automatically reconnects with exponential backoff on connection loss.
+        """
+        self._running = True
+        reconnect_attempts = 0
+
+        while self._running and reconnect_attempts <= self._max_reconnects:
+            try:
+                self._stream_loop()
+                if not self._running:
+                    break
+            except (httpx.ConnectError, httpx.ReadTimeout, httpx.RemoteProtocolError) as e:
+                reconnect_attempts += 1
+                if reconnect_attempts > self._max_reconnects:
+                    raise StreamError(
+                        f"Max reconnection attempts ({self._max_reconnects}) reached",
+                        code="max_reconnects",
+                    ) from e  # noqa: B904
+                delay = min(2**reconnect_attempts, 30)
+                logger.warning(
+                    "Connection lost, reconnecting in %ds (attempt %d/%d)",
+                    delay,
+                    reconnect_attempts,
+                    self._max_reconnects,
+                )
+                time.sleep(delay)
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 401:
+                    raise AuthenticationError(
+                        "Invalid API key", code="invalid_api_key", status=401
+                    ) from e
+                raise StreamError(
+                    f"HTTP {e.response.status_code}", code="http_error", status=e.response.status_code
+                ) from e
+
+    def _stream_loop(self) -> None:
+        headers = {**self._headers, "Accept": "text/event-stream"}
+        if self._last_event_id:
+            headers["Last-Event-ID"] = self._last_event_id
+
+        with httpx.Client(timeout=httpx.Timeout(self._timeout, connect=10.0)) as http:
+            with http.stream("GET", self._url, headers=headers) as response:
+                response.raise_for_status()
+                for event_type, data in _parse_sse(response.iter_lines()):
+                    if not self._running:
+                        break
+                    self._emit(event_type, data)
+
+    def disconnect(self) -> None:
+        """Stop the stream."""
+        self._running = False
+
+    def iter_events(self) -> Iterator[tuple[str, Any]]:
+        """Iterate over events as (event_type, data) tuples.
+
+        Example::
+
+            for event_type, data in stream.iter_events():
+                if event_type == "ev:detected":
+                    print(data)
+        """
+        self._running = True
+        headers = {**self._headers, "Accept": "text/event-stream"}
+        if self._last_event_id:
+            headers["Last-Event-ID"] = self._last_event_id
+
+        with httpx.Client(timeout=httpx.Timeout(self._timeout, connect=10.0)) as http:
+            with http.stream("GET", self._url, headers=headers) as response:
+                response.raise_for_status()
+                for event_type, data in _parse_sse(response.iter_lines()):
+                    if not self._running:
+                        break
+                    yield event_type, data
+
+
+def _parse_sse(lines: Iterator[str]) -> Iterator[tuple[str, Any]]:
+    """Parse SSE text stream into (event_type, parsed_data) tuples."""
+    event_type = "message"
+    data_lines: list[str] = []
+
+    for line in lines:
+        if line.startswith("event:"):
+            event_type = line[6:].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[5:].strip())
+        elif line.startswith("id:"):
+            pass  # Tracked by httpx/EventSource
+        elif line == "" and data_lines:
+            # End of event
+            raw = "\n".join(data_lines)
+            try:
+                parsed = json.loads(raw)
+            except json.JSONDecodeError:
+                parsed = raw
+            yield event_type, parsed
+            event_type = "message"
+            data_lines = []