theoddsapi-client 1.0.1__py3-none-any.whl

theoddsapi/__init__.py

@@ -0,0 +1,12 @@
+"""theoddsapi: official Python client for TheOddsAPI (theoddsapi.com).
+
+Zero dependencies (standard library only). One class, one method per endpoint.
+
+    from theoddsapi import TheOddsAPI
+    client = TheOddsAPI("YOUR_API_KEY")
+    odds = client.odds("baseball_mlb", oddsFormat="decimal")
+"""
+from .client import TheOddsAPI, TheOddsAPIError
+
+__all__ = ["TheOddsAPI", "TheOddsAPIError"]
+__version__ = "1.0.1"

theoddsapi/client.py

@@ -0,0 +1,118 @@
+"""HTTP client for TheOddsAPI. Standard library only, retries on 5xx."""
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE_URL = "https://api.theoddsapi.com"
+RETRY_STATUSES = {502, 503, 504}
+
+
+class TheOddsAPIError(Exception):
+    """Raised for any non-2xx API response. Carries .status and .detail."""
+
+    def __init__(self, status, detail):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"HTTP {status}: {detail}")
+
+
+class TheOddsAPI:
+    """Thin client for TheOddsAPI. Docs: https://theoddsapi.com/docs/"""
+
+    def __init__(self, api_key, base_url=BASE_URL, timeout=15, max_retries=3):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # ------------------------------------------------------------- core ----
+    def _get(self, path, params=None):
+        query = urllib.parse.urlencode(
+            {k: v for k, v in (params or {}).items() if v is not None})
+        url = f"{self.base_url}{path}" + (f"?{query}" if query else "")
+        req = urllib.request.Request(url, headers={
+            "x-api-key": self.api_key,
+            "User-Agent": "theoddsapi-python/1.0.1",
+        })
+        delay = 1.0
+        for attempt in range(self.max_retries + 1):
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                if e.code in RETRY_STATUSES and attempt < self.max_retries:
+                    time.sleep(delay)
+                    delay = min(delay * 2, 30)
+                    continue
+                try:
+                    detail = json.loads(e.read().decode("utf-8")).get("detail", e.reason)
+                except Exception:
+                    detail = e.reason
+                raise TheOddsAPIError(e.code, detail) from None
+            except urllib.error.URLError as e:
+                if attempt < self.max_retries:
+                    time.sleep(delay)
+                    delay = min(delay * 2, 30)
+                    continue
+                raise TheOddsAPIError(0, f"connection failed: {e.reason}") from None
+
+    # -------------------------------------------------------- core data ----
+    def sports(self):
+        """List the sports available on your plan."""
+        return self._get("/sports/")
+
+    def odds(self, sport_key, **params):
+        """Current multi-book odds for a sport. Params: markets, regions,
+        bookmakers, event_id, commenceTimeFrom, commenceTimeTo, oddsFormat."""
+        return self._get("/odds/", {"sport_key": sport_key, **params})
+
+    def events(self, sport_key, **params):
+        """Upcoming events for a sport."""
+        return self._get("/events/", {"sport_key": sport_key, **params})
+
+    def best_lines(self, sport_key, **params):
+        """Best available price per outcome across all tracked books."""
+        return self._get("/best-lines/", {"sport_key": sport_key, **params})
+
+    # ---------------------------------------------- business endpoints ----
+    def props(self, sport_key, **params):
+        """Player props (Business plan)."""
+        return self._get("/props/", {"sport_key": sport_key, **params})
+
+    def edges(self, sport_key, **params):
+        """Pinnacle-anchored cross-book edges (Business plan)."""
+        return self._get("/edges/", {"sport_key": sport_key, **params})
+
+    def fair_odds(self, sport_key, **params):
+        """Vig-removed fair odds from sharp-anchored consensus (Business)."""
+        return self._get("/intelligence/fair-odds", {"sport_key": sport_key, **params})
+
+    def consensus(self, sport_key, **params):
+        """Median/mean market center per outcome (Business)."""
+        return self._get("/intelligence/consensus", {"sport_key": sport_key, **params})
+
+    def arbitrage(self, sport_key, **params):
+        """Precomputed cross-book arbitrage opportunities (Business)."""
+        return self._get("/intelligence/arbitrage", {"sport_key": sport_key, **params})
+
+    def value_bets(self, sport_key, **params):
+        """Value bets vs vig-removed consensus (Business)."""
+        return self._get("/intelligence/value", {"sport_key": sport_key, **params})
+
+    def historical_odds(self, sport_key, **params):
+        """Historical odds snapshots (Business). Params: from/to (use
+        from_/to_ or pass via dict), event_id, bookmakers, market,
+        limit, offset, oddsFormat."""
+        clean = {k.rstrip("_"): v for k, v in params.items()}
+        return self._get("/historical/odds", {"sport_key": sport_key, **clean})
+
+    def historical_settlements(self, sport_key, **params):
+        """Graded edge settlements joined with final scores (Business)."""
+        return self._get("/historical/settlements", {"sport_key": sport_key, **params})
+
+    # ------------------------------------------------------------ account --
+    def me(self):
+        """Your key's tier and usage."""
+        return self._get("/me/")

theoddsapi_client-1.0.1.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: theoddsapi-client
+Version: 1.0.1
+Summary: Official Python client for TheOddsAPI: real-time sports odds from 50+ sportsbooks across 26 sports, plus player props, Pinnacle-anchored edges, fair odds, and historical snapshots.
+Project-URL: Homepage, https://theoddsapi.com
+Project-URL: Documentation, https://theoddsapi.com/docs/
+Project-URL: Changelog, https://theoddsapi.com/changelog
+License: MIT
+Keywords: api,arbitrage,betting,odds,props,sports,sportsbook
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# theoddsapi
+
+Official Python client for [TheOddsAPI](https://theoddsapi.com): real-time sports odds from 50+ sportsbooks across 26 sports, normalized into one JSON shape, plus player props, Pinnacle-anchored edge detection, fair odds, and historical snapshots.
+
+Zero dependencies. Python 3.8+.
+
+## Install
+
+```
+pip install theoddsapi
+```
+
+## Quick start
+
+```python
+from theoddsapi import TheOddsAPI
+
+client = TheOddsAPI("YOUR_API_KEY")
+
+for sport in client.sports()["data"]:
+    print(sport)
+
+odds = client.odds("baseball_mlb", oddsFormat="decimal")
+```
+
+Get a free key in minutes at [theoddsapi.com/start](https://theoddsapi.com/start). No credit card.
+
+## Endpoints
+
+Every endpoint is one method. Core data: `sports()`, `odds()`, `events()`, `best_lines()`. Business plan: `props()`, `edges()`, `fair_odds()`, `consensus()`, `arbitrage()`, `value_bets()`, `historical_odds()`, `historical_settlements()`. Account: `me()`.
+
+```python
+edges = client.edges("basketball_nba", min_edge=50)
+history = client.historical_odds("baseball_mlb", bookmakers="pinnacle", limit=500)
+```
+
+## Errors
+
+Non-2xx responses raise `TheOddsAPIError` with `.status` and `.detail`. Transient 5xx responses are retried with exponential backoff automatically.
+
+```python
+from theoddsapi import TheOddsAPI, TheOddsAPIError
+
+try:
+    client.props("baseball_mlb")
+except TheOddsAPIError as e:
+    if e.status == 403:
+        print("Props require the Business plan:", e.detail)
+```
+
+## Links
+
+Full reference: [theoddsapi.com/docs](https://theoddsapi.com/docs/) · Guides: [theoddsapi.com/guides](https://theoddsapi.com/guides/) · Free calculators: [theoddsapi.com/tools](https://theoddsapi.com/tools/)

theoddsapi_client-1.0.1.dist-info/RECORD

@@ -0,0 +1,5 @@
+theoddsapi/__init__.py,sha256=VpPSodf0JpJR4RDo4sYpp4BYKq8ZpBqg8cvT9VxsoJE,410
+theoddsapi/client.py,sha256=FlFjVZWkwPBkkZIilZcLtuygWm6mKB5954YDA4d1PeU,5098
+theoddsapi_client-1.0.1.dist-info/METADATA,sha256=eLxPnsNYqxtW4KvT1LcfpoEBrHPEXHmD4MIrGC-WbNc,2464
+theoddsapi_client-1.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+theoddsapi_client-1.0.1.dist-info/RECORD,,

theoddsapi_client-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any