owls-insight 0.2.0__tar.gz

owls_insight-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.so
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Env
+.env
+.env.*

owls_insight-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owls Insight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

owls_insight-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: owls-insight
+Version: 0.2.0
+Summary: Official Python SDK for the Owls Insight real-time sports betting odds API
+Project-URL: Homepage, https://owlsinsight.com
+Project-URL: Documentation, https://owlsinsight.com/docs
+Project-URL: Repository, https://github.com/Davidgsilva/owls-insight-sdk-python
+Author-email: Owls Insight <david@wisesportsai.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,betting,draftkings,fanduel,mlb,nba,nfl,nhl,odds,pinnacle,real-time,soccer,sports,tennis,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-socketio>=5.11
+Requires-Dist: websocket-client>=1.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Owls Insight Python SDK
+
+Official Python SDK for the [Owls Insight](https://owlsinsight.com) real-time sports betting odds API. Sync **and** async clients, fully typed with Pydantic v2, plus a Socket.io WebSocket client for live streams.
+
+```bash
+pip install owls-insight
+```
+
+Requires Python 3.9+. Get an API key at [owlsinsight.com](https://owlsinsight.com).
+
+## Quick start (sync)
+
+```python
+from owls_insight import OwlsInsight
+
+client = OwlsInsight(api_key="owlsinsight_...")
+
+# REST: current NBA odds. `data` is keyed by sportsbook -> list of events.
+odds = client.rest.get_odds("nba", books=["pinnacle", "fanduel"])
+for book, events in odds.data.items():
+    for event in events:
+        print(book, event.home_team, "vs", event.away_team)
+
+# WebSocket: stream live updates
+client.ws.connect()
+client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+client.ws.on("odds-update", lambda data: print("live:", data))
+
+# or block for the next event
+update = client.ws.wait_for("odds-update", timeout=15)
+
+client.destroy()
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from owls_insight import AsyncOwlsInsight
+
+async def main():
+    async with AsyncOwlsInsight(api_key="owlsinsight_...") as client:
+        odds = await client.rest.get_odds("nba", books=["pinnacle"])
+        print(sum(len(events) for events in odds.data.values()), "games")
+
+        await client.ws.connect()
+        await client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+        update = await client.ws.wait_for("pinnacle-realtime", timeout=30)
+        print("realtime:", update)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass your API key to the constructor. REST uses the `Authorization: Bearer` header; the WebSocket uses the `?apiKey=` query string. Both are handled for you.
+
+```python
+import os
+client = OwlsInsight(api_key=os.environ["OWLS_INSIGHT_API_KEY"])
+```
+
+## REST
+
+Method names are `snake_case` (the JS SDK's `getOdds` is `get_odds` here). Every method returns a typed Pydantic model; unknown fields from the evolving API are preserved (`model_extra`), never dropped.
+
+Full parity with the TypeScript SDK — every endpoint is available on both `client.rest` (sync) and the async client.
+
+| Area | Methods |
+|------|---------|
+| Odds | `get_odds`, `get_moneyline`, `get_spreads`, `get_totals`, `get_realtime`, `get_ps3838_realtime`, `get_esports_realtime`, `get_ev`, `list_events`, `get_one_x_bet_soccer`, `get_prophetx_odds` |
+| Props | `get_props`, `get_book_props`, `get_props_history`, `get_props_stats`, `get_book_props_stats` |
+| Scores / schedule | `get_scores`, `get_schedule`, `get_results`, `get_splits`, `normalize`, `normalize_batch` |
+| Stats | `get_stats`, `get_match_stats`, `get_h2h`, `get_player_averages` |
+| Line history | `get_odds_history`, `get_moneyline_history`, `get_spread_history`, `get_totals_history` |
+| Historical | `get_history_games`, `get_history_odds`, `get_history_props`, `get_history_stats`, `get_history_tennis_stats`, `get_game_stats_detail`, `get_closing_odds`, `get_historical_player_props`, `get_public_betting`, `get_cs2_matches`, `get_cs2_match`, `get_cs2_players` |
+| v2 Source API | `get_stake_v2`, `get_hard_rock_events`/`_leagues`/`get_hard_rock_ladder`, `get_bet365_v2`/`_leagues`, `get_draftkings_v2`/`_leagues`, `get_fanduel_v2`/`_leagues`, `get_mybookie_v2`, `get_thunderpick_v2`, `get_underdog_v2`, `get_bookmaker_v2`/`_leagues`, `get_kalshi_v2`/`_leagues`, `get_polymarket_v2`/`_leagues`, `get_pinnacle_v2`/`_leagues` |
+
+> Methods whose response shape isn't individually modelled yet return a permissive `ApiResponse` envelope (`success`/`data`/`meta`, all fields preserved). Deep per-endpoint Pydantic typing is the remaining follow-on; the method surface is complete.
+
+### Hard Rock odds decoding
+
+Hard Rock v2 selections carry a `rootIdx`, not inline odds. Decode it client-side:
+
+```python
+from owls_insight import root_idx_to_american_odds
+root_idx_to_american_odds(42)  # -325
+root_idx_to_american_odds(72)  #  100  (even)
+```
+
+## WebSocket events
+
+`odds-update`, `props-update` (and per-book `{book}-props-update`), `pinnacle-realtime`, `ps3838-realtime`, `esports-update`, `prophetx-update`, and the v2 `{book}-v2-update` deltas.
+
+```python
+client.ws.connect()
+client.ws.subscribe(sports=["nba", "nhl"], books=["pinnacle", "fanduel"])
+client.ws.subscribe_props(book="fanduel")           # props stream
+client.ws.update_subscription(prophetx=True)        # merge, don't replace
+client.ws.on("props-update", handle_props)
+```
+
+## Errors
+
+```python
+from owls_insight import AuthenticationError, RateLimitError, OwlsInsightError
+
+try:
+    client.rest.get_odds("nba")
+except AuthenticationError:
+    ...  # 401
+except RateLimitError as e:
+    print("retry after", e.retry_after_ms, "ms")
+except OwlsInsightError as e:
+    print(e.status, e.message)
+```
+
+## License
+
+MIT

owls_insight-0.2.0/README.md

@@ -0,0 +1,120 @@
+# Owls Insight Python SDK
+
+Official Python SDK for the [Owls Insight](https://owlsinsight.com) real-time sports betting odds API. Sync **and** async clients, fully typed with Pydantic v2, plus a Socket.io WebSocket client for live streams.
+
+```bash
+pip install owls-insight
+```
+
+Requires Python 3.9+. Get an API key at [owlsinsight.com](https://owlsinsight.com).
+
+## Quick start (sync)
+
+```python
+from owls_insight import OwlsInsight
+
+client = OwlsInsight(api_key="owlsinsight_...")
+
+# REST: current NBA odds. `data` is keyed by sportsbook -> list of events.
+odds = client.rest.get_odds("nba", books=["pinnacle", "fanduel"])
+for book, events in odds.data.items():
+    for event in events:
+        print(book, event.home_team, "vs", event.away_team)
+
+# WebSocket: stream live updates
+client.ws.connect()
+client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+client.ws.on("odds-update", lambda data: print("live:", data))
+
+# or block for the next event
+update = client.ws.wait_for("odds-update", timeout=15)
+
+client.destroy()
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from owls_insight import AsyncOwlsInsight
+
+async def main():
+    async with AsyncOwlsInsight(api_key="owlsinsight_...") as client:
+        odds = await client.rest.get_odds("nba", books=["pinnacle"])
+        print(sum(len(events) for events in odds.data.values()), "games")
+
+        await client.ws.connect()
+        await client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+        update = await client.ws.wait_for("pinnacle-realtime", timeout=30)
+        print("realtime:", update)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Pass your API key to the constructor. REST uses the `Authorization: Bearer` header; the WebSocket uses the `?apiKey=` query string. Both are handled for you.
+
+```python
+import os
+client = OwlsInsight(api_key=os.environ["OWLS_INSIGHT_API_KEY"])
+```
+
+## REST
+
+Method names are `snake_case` (the JS SDK's `getOdds` is `get_odds` here). Every method returns a typed Pydantic model; unknown fields from the evolving API are preserved (`model_extra`), never dropped.
+
+Full parity with the TypeScript SDK — every endpoint is available on both `client.rest` (sync) and the async client.
+
+| Area | Methods |
+|------|---------|
+| Odds | `get_odds`, `get_moneyline`, `get_spreads`, `get_totals`, `get_realtime`, `get_ps3838_realtime`, `get_esports_realtime`, `get_ev`, `list_events`, `get_one_x_bet_soccer`, `get_prophetx_odds` |
+| Props | `get_props`, `get_book_props`, `get_props_history`, `get_props_stats`, `get_book_props_stats` |
+| Scores / schedule | `get_scores`, `get_schedule`, `get_results`, `get_splits`, `normalize`, `normalize_batch` |
+| Stats | `get_stats`, `get_match_stats`, `get_h2h`, `get_player_averages` |
+| Line history | `get_odds_history`, `get_moneyline_history`, `get_spread_history`, `get_totals_history` |
+| Historical | `get_history_games`, `get_history_odds`, `get_history_props`, `get_history_stats`, `get_history_tennis_stats`, `get_game_stats_detail`, `get_closing_odds`, `get_historical_player_props`, `get_public_betting`, `get_cs2_matches`, `get_cs2_match`, `get_cs2_players` |
+| v2 Source API | `get_stake_v2`, `get_hard_rock_events`/`_leagues`/`get_hard_rock_ladder`, `get_bet365_v2`/`_leagues`, `get_draftkings_v2`/`_leagues`, `get_fanduel_v2`/`_leagues`, `get_mybookie_v2`, `get_thunderpick_v2`, `get_underdog_v2`, `get_bookmaker_v2`/`_leagues`, `get_kalshi_v2`/`_leagues`, `get_polymarket_v2`/`_leagues`, `get_pinnacle_v2`/`_leagues` |
+
+> Methods whose response shape isn't individually modelled yet return a permissive `ApiResponse` envelope (`success`/`data`/`meta`, all fields preserved). Deep per-endpoint Pydantic typing is the remaining follow-on; the method surface is complete.
+
+### Hard Rock odds decoding
+
+Hard Rock v2 selections carry a `rootIdx`, not inline odds. Decode it client-side:
+
+```python
+from owls_insight import root_idx_to_american_odds
+root_idx_to_american_odds(42)  # -325
+root_idx_to_american_odds(72)  #  100  (even)
+```
+
+## WebSocket events
+
+`odds-update`, `props-update` (and per-book `{book}-props-update`), `pinnacle-realtime`, `ps3838-realtime`, `esports-update`, `prophetx-update`, and the v2 `{book}-v2-update` deltas.
+
+```python
+client.ws.connect()
+client.ws.subscribe(sports=["nba", "nhl"], books=["pinnacle", "fanduel"])
+client.ws.subscribe_props(book="fanduel")           # props stream
+client.ws.update_subscription(prophetx=True)        # merge, don't replace
+client.ws.on("props-update", handle_props)
+```
+
+## Errors
+
+```python
+from owls_insight import AuthenticationError, RateLimitError, OwlsInsightError
+
+try:
+    client.rest.get_odds("nba")
+except AuthenticationError:
+    ...  # 401
+except RateLimitError as e:
+    print("retry after", e.retry_after_ms, "ms")
+except OwlsInsightError as e:
+    print(e.status, e.message)
+```
+
+## License
+
+MIT

owls_insight-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "owls-insight"
+version = "0.2.0"
+description = "Official Python SDK for the Owls Insight real-time sports betting odds API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Owls Insight", email = "david@wisesportsai.com" }]
+keywords = [
+    "sports", "betting", "odds", "nba", "nfl", "nhl", "mlb", "soccer",
+    "tennis", "pinnacle", "fanduel", "draftkings", "websocket", "real-time", "api",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.5",
+    "python-socketio>=5.11",
+    "websocket-client>=1.7",  # sync Socket.io websocket transport
+    "aiohttp>=3.9",           # async Socket.io websocket transport
+]
+
+[project.urls]
+Homepage = "https://owlsinsight.com"
+Documentation = "https://owlsinsight.com/docs"
+Repository = "https://github.com/Davidgsilva/owls-insight-sdk-python"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.8", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/owls_insight"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+plugins = ["pydantic.mypy"]
+ignore_missing_imports = true

owls_insight-0.2.0/src/owls_insight/__init__.py

@@ -0,0 +1,46 @@
+"""Owls Insight — Official Python SDK for the real-time sports betting odds API.
+
+>>> from owls_insight import OwlsInsight
+>>> client = OwlsInsight(api_key="owlsinsight_...")
+>>> odds = client.rest.get_odds("nba", books=["pinnacle", "fanduel"])
+"""
+
+from __future__ import annotations
+
+from . import models
+from .client import AsyncOwlsInsight, OwlsInsight
+from .errors import (
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    OwlsInsightError,
+    RateLimitError,
+)
+from .hardrock import (
+    HARDROCK_LADDER_EVEN_ROOTIDX,
+    HARDROCK_PRICE_LADDER,
+    root_idx_to_american_odds,
+)
+from .rest import AsyncRestClient, RestClient
+from .websocket import AsyncWebSocketClient, WebSocketClient
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "OwlsInsight",
+    "AsyncOwlsInsight",
+    "RestClient",
+    "AsyncRestClient",
+    "WebSocketClient",
+    "AsyncWebSocketClient",
+    "OwlsInsightError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "root_idx_to_american_odds",
+    "HARDROCK_PRICE_LADDER",
+    "HARDROCK_LADDER_EVEN_ROOTIDX",
+    "models",
+    "__version__",
+]

owls_insight-0.2.0/src/owls_insight/_base.py

@@ -0,0 +1,33 @@
+"""Shared Pydantic base + common types for all model modules.
+
+Lives in its own module so per-domain model files can import ``_Model``/``Meta``
+without importing the public ``models`` facade (which re-exports everything,
+which would create an import cycle).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+# Enums are string literals upstream; permissive ``str`` aliases here.
+Sport = str
+Book = str
+MarketKey = str
+GameStatus = str
+SubscriptionTier = str
+
+
+class _Model(BaseModel):
+    """Base for all response models: preserves unknown fields, allows aliases."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class Meta(_Model):
+    source: Optional[str] = None
+    status: Optional[str] = None
+    cached: Optional[bool] = None
+    timestamp: Optional[str] = None
+    age_seconds: Optional[float] = None  # camelCase ageSeconds tolerated via extra

owls_insight-0.2.0/src/owls_insight/_http.py

@@ -0,0 +1,67 @@
+"""Shared HTTP plumbing for the sync and async REST clients."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type, TypeVar
+
+import httpx
+from pydantic import BaseModel
+
+from .errors import error_from_response
+
+DEFAULT_BASE_URL = "https://api.owlsinsight.com"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "owls-insight-python/0.2.0"
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def clean_params(params: Optional[Dict[str, Any]]) -> Dict[str, str]:
+    """Drop ``None`` values and stringify the rest (booleans -> 'true'/'false')."""
+    out: Dict[str, str] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        out[key] = "true" if value is True else "false" if value is False else str(value)
+    return out
+
+
+def auth_headers(api_key: str) -> Dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+
+
+def parse_response(resp: httpx.Response, model: Optional[Type[T]]) -> Any:
+    """Raise the right error on non-2xx, otherwise validate JSON into ``model``."""
+    if resp.status_code >= 400:
+        try:
+            body: Any = resp.json()
+        except Exception:
+            body = resp.text
+        raise error_from_response(resp.status_code, body, resp.headers)
+    data = resp.json()
+    if model is None:
+        return data
+    return model.model_validate(data)
+
+
+class _BaseRest:
+    """Holds config common to the sync and async REST clients."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+
+    def _full_url(self, path: str) -> str:
+        return f"{self._base_url}{path}"

owls_insight-0.2.0/src/owls_insight/client.py

@@ -0,0 +1,70 @@
+"""Top-level Owls Insight clients bundling REST + WebSocket."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .rest import AsyncRestClient, RestClient
+from .websocket import AsyncWebSocketClient, WebSocketClient
+
+
+class OwlsInsight:
+    """Synchronous Owls Insight client.
+
+    >>> from owls_insight import OwlsInsight
+    >>> client = OwlsInsight(api_key="...")
+    >>> odds = client.rest.get_odds("nba", books=["pinnacle", "fanduel"])
+    >>> client.ws.connect()
+    >>> client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+    >>> client.ws.on("odds-update", lambda data: print(data))
+    """
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None, ws_url: Optional[str] = None, timeout: Optional[float] = None) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.rest = RestClient(api_key, base_url=base_url, timeout=timeout)
+        self.ws = WebSocketClient(api_key, ws_url=ws_url, base_url=base_url)
+
+    def destroy(self) -> None:
+        """Disconnect the WebSocket and close the HTTP session."""
+        self.ws.disconnect()
+        self.rest.close()
+
+    def __enter__(self) -> "OwlsInsight":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.destroy()
+
+
+class AsyncOwlsInsight:
+    """Asynchronous Owls Insight client.
+
+    >>> import asyncio
+    >>> from owls_insight import AsyncOwlsInsight
+    >>> async def main():
+    ...     client = AsyncOwlsInsight(api_key="...")
+    ...     odds = await client.rest.get_odds("nba", books=["pinnacle"])
+    ...     await client.ws.connect()
+    ...     await client.ws.subscribe(sports=["nba"], books=["pinnacle"])
+    ...     update = await client.ws.wait_for("odds-update", timeout=15)
+    ...     await client.destroy()
+    >>> asyncio.run(main())
+    """
+
+    def __init__(self, api_key: str, base_url: Optional[str] = None, ws_url: Optional[str] = None, timeout: Optional[float] = None) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.rest = AsyncRestClient(api_key, base_url=base_url, timeout=timeout)
+        self.ws = AsyncWebSocketClient(api_key, ws_url=ws_url, base_url=base_url)
+
+    async def destroy(self) -> None:
+        """Disconnect the WebSocket and close the HTTP session."""
+        await self.ws.disconnect()
+        await self.rest.close()
+
+    async def __aenter__(self) -> "AsyncOwlsInsight":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.destroy()