sharpapi 0.2.5__tar.gz → 0.3.1__tar.gz

{sharpapi-0.2.5 → sharpapi-0.3.1}/.gitignore

@@ -10,3 +10,9 @@ build/
 .ruff_cache/
 *.egg
 .mypy_cache/
+.coverage
+htmlcov/
+.claude/
+.DS_Store
+tests/
+.benchmarks/

sharpapi-0.3.1/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to the `sharpapi` Python SDK are documented here.
+
+## 0.3.1 — 2026-05-06
+
+### Added — TeamRef metadata
+
+`TeamRef` now exposes five additional optional fields:
+
+- `logo` — full CDN URL. ~93% of teams are populated.
+- `city` — e.g. `"Arizona"` for the Diamondbacks.
+- `mascot` — e.g. `"Diamondbacks"`.
+- `conference` — e.g. `"NL"`, `"AFC"`, `"Western"`.
+- `division` — e.g. `"West Division"`, `"NL East"`, `"Pacific Division"`.
+
+All five default to `None` and are additive — existing 0.3.0 code keeps
+working unchanged.
+
+## 0.3.0 — 2026-05-06
+
+### Added — nested refs
+
+Every odds row, opportunity row, and reference-list row may now carry
+optional structured reference objects alongside the existing flat fields.
+All new fields are **optional and additive** — clients on older API
+versions (or talking to older API servers) see `None` and behave
+identically.
+
+New models:
+
+- `TeamRef` — `id`, `numerical_id`, `name`, `abbreviation` (latter only on
+  team-sport competitors)
+- `SportRef` — `id`, `name`, `numerical_id`
+- `EntityRef` — `id`, `label`, `numerical_id` (used for league / market /
+  sportsbook refs)
+
+New optional fields:
+
+- `OddsLine`, `EVOpportunity`, `ArbitrageOpportunity`, `MiddleOpportunity`,
+  `LowHoldOpportunity` — all gain `home`, `away`, `sport_ref`, `league_ref`,
+  `market_ref`, `sportsbook_ref` (legs / opps without a single book skip
+  `sportsbook_ref`).
+- `ArbitrageLeg` — gains `sportsbook_ref`.
+- `ClosingOddsLine` — gains `market_ref`, `sportsbook_ref`.
+- `ClosingSnapshot` — gains `home`, `away`, `sport_ref`, `league_ref`.
+- `Sport`, `League`, `Sportsbook`, `Market` — gain `numerical_id`.
+- `Event` — gains `home`, `away`, `sport_ref`, `league_ref`.
+
+New reference model:
+
+- `Team` — for the `/teams` reference endpoint, includes optional
+  `abbreviation` and `numerical_id`.
+
+### Backward compatibility
+
+No existing field was renamed, retyped, or removed. Code that does not
+reference the new attributes continues to work without changes.

sharpapi-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharpAPI LLC
+
+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.

{sharpapi-0.2.5 → sharpapi-0.3.1}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: sharpapi
-Version: 0.2.5
+Version: 0.3.1
 Summary: Official Python SDK for the SharpAPI real-time sports betting odds API
 Project-URL: Homepage, https://sharpapi.io
 Project-URL: Documentation, https://docs.sharpapi.io/sdks/python
 Project-URL: Repository, https://github.com/Sharp-API/sharpapi-python
 Project-URL: Changelog, https://github.com/Sharp-API/sharpapi-python/releases
-Author-email: SharpAPI <support@sharpapi.io>
+Author-email: SharpAPI <hello@sharpapi.io>
 License-Expression: MIT
+License-File: LICENSE
 Keywords: api,arbitrage,ev,odds,pinnacle,real-time,sports-betting
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers

sharpapi-0.3.1/SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this SDK or in
+the SharpAPI service, please report it privately to:
+
+**hello@sharpapi.io** (subject line: `[SECURITY] <short summary>`)
+
+Please do not open a public GitHub issue for security reports.
+
+We will acknowledge receipt within 72 hours and aim to provide a status
+update within 7 days. If the issue is confirmed, we will work with you on
+disclosure timing.
+
+## Scope
+
+In scope:
+- This SDK package and its published artifact on PyPI
+- The SharpAPI HTTP and WebSocket APIs (`api.sharpapi.io`, `ws.sharpapi.io`)
+
+Out of scope:
+- Findings in third-party dependencies (please report those upstream)
+- Denial of service via brute-force or volumetric attacks against the API
+- Issues that require physical access to a user's device

{sharpapi-0.2.5 → sharpapi-0.3.1}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.2.5"
+version = "0.3.1"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
-authors = [{ name = "SharpAPI", email = "support@sharpapi.io" }]
+authors = [{ name = "SharpAPI", email = "hello@sharpapi.io" }]
 keywords = ["sports-betting", "odds", "arbitrage", "ev", "api", "real-time", "pinnacle"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -41,6 +41,25 @@ Changelog = "https://github.com/Sharp-API/sharpapi-python/releases"
 [tool.hatch.build.targets.wheel]
 packages = ["src/sharpapi"]
 
+# Explicit sdist whitelist. Hatchling's default sdist would otherwise
+# include everything not gitignored (CI workflows, dependabot config,
+# .gitignore itself), all of which would land on PyPI on every release.
+# Keep this in sync with what we actually want users who do
+# `pip install --no-binary :all: sharpapi` to receive.
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/sharpapi",
+  "README.md",
+  "LICENSE",
+  "CHANGELOG.md",
+  "SECURITY.md",
+  "pyproject.toml",
+]
+exclude = [
+  ".gitignore",
+  ".github",
+]
+
 [tool.ruff]
 target-version = "py310"
 line-length = 100

{sharpapi-0.2.5 → sharpapi-0.3.1}/src/sharpapi/__init__.py

@@ -38,6 +38,7 @@ from .models import (
     ArbitrageOpportunity,
     ClosingOddsLine,
     ClosingSnapshot,
+    EntityRef,
     Event,
     EVOpportunity,
     GameState,
@@ -53,11 +54,14 @@ from .models import (
     RateLimitInfo,
     ResponseMeta,
     Sport,
+    SportRef,
     Sportsbook,
+    Team,
+    TeamRef,
 )
 from .streaming import EventStream
 
-__version__ = "0.2.5"
+__version__ = "0.3.1"
 
 __all__ = [
     # Clients
@@ -71,6 +75,7 @@ __all__ = [
     "ArbitrageOpportunity",
     "ClosingOddsLine",
     "ClosingSnapshot",
+    "EntityRef",
     "EVOpportunity",
     "Event",
     "GameState",
@@ -86,7 +91,10 @@ __all__ = [
     "RateLimitInfo",
     "ResponseMeta",
     "Sport",
+    "SportRef",
     "Sportsbook",
+    "Team",
+    "TeamRef",
     # Streaming
     "EventStream",
     # Exceptions

{sharpapi-0.2.5 → sharpapi-0.3.1}/src/sharpapi/async_client.py

@@ -29,6 +29,7 @@ from .models import (
     ClosingSnapshot,
     Event,
     EVOpportunity,
+    GameState,
     League,
     LowHoldOpportunity,
     Market,
@@ -103,6 +104,7 @@ class AsyncSharpAPI:
         self.arbitrage = _AsyncArbitrageResource(self)
         self.middles = _AsyncMiddlesResource(self)
         self.low_hold = _AsyncLowHoldResource(self)
+        self.gamestate = _AsyncGameStateResource(self)
         self.sports = _AsyncSportsResource(self)
         self.leagues = _AsyncLeaguesResource(self)
         self.sportsbooks = _AsyncSportsbooksResource(self)
@@ -426,6 +428,41 @@ class _AsyncLowHoldResource:
         return parse_response(data, LowHoldOpportunity)
 
 
+class _AsyncGameStateResource:
+    """Async access to live game state — scores, period, clock —
+    merged across sportsbooks.
+
+    Requires the Game State add-on ($79/mo) or Enterprise tier.
+    """
+
+    def __init__(self, client: AsyncSharpAPI):
+        self._client = client
+
+    async def get(self, sport: str | None = None) -> dict[str, dict[str, GameState]]:
+        """Fetch the current game state.
+
+        Args:
+            sport: Limit to a single sport (e.g. ``"basketball"``).
+                Omit to fetch every sport at once.
+
+        Returns:
+            Nested mapping ``{sport: {event_id: GameState}}``.
+        """
+        path = f"/gamestate/{sport}" if sport else "/gamestate"
+        data = await self._client._get(path)
+        raw = data.get("data", {}) or {}
+        result: dict[str, dict[str, GameState]] = {}
+        for sport_key, events in raw.items():
+            if not isinstance(events, dict):
+                continue
+            result[sport_key] = {
+                eid: GameState.model_validate(state)
+                for eid, state in events.items()
+                if isinstance(state, dict)
+            }
+        return result
+
+
 class _AsyncSportsResource:
     def __init__(self, client: AsyncSharpAPI):
         self._client = client

{sharpapi-0.2.5 → sharpapi-0.3.1}/src/sharpapi/client.py

@@ -29,6 +29,7 @@ from .models import (
     ClosingSnapshot,
     Event,
     EVOpportunity,
+    GameState,
     League,
     LowHoldOpportunity,
     Market,
@@ -111,6 +112,7 @@ class SharpAPI:
         self.arbitrage = _ArbitrageResource(self)
         self.middles = _MiddlesResource(self)
         self.low_hold = _LowHoldResource(self)
+        self.gamestate = _GameStateResource(self)
         self.sports = _SportsResource(self)
         self.leagues = _LeaguesResource(self)
         self.sportsbooks = _SportsbooksResource(self)
@@ -542,6 +544,44 @@ class _LowHoldResource:
         return _parse_response(data, LowHoldOpportunity)
 
 
+class _GameStateResource:
+    """Live game state — scores, period, clock — merged across sportsbooks.
+
+    Requires the Game State add-on ($79/mo) or Enterprise tier.
+    Pair with EV / arb / low-hold rows: those endpoints no longer carry
+    ``game_state`` themselves — look up the row's ``event_id`` here.
+    """
+
+    def __init__(self, client: SharpAPI):
+        self._client = client
+
+    def get(self, sport: str | None = None) -> dict[str, dict[str, GameState]]:
+        """Fetch the current game state.
+
+        Args:
+            sport: Limit to a single sport (e.g. ``"basketball"``,
+                ``"football"``). Omit to fetch every sport at once.
+
+        Returns:
+            Nested mapping ``{sport: {event_id: GameState}}``. Look up an
+            opportunity's state with
+            ``result.get(opp.sport, {}).get(opp.event_id)``.
+        """
+        path = f"/gamestate/{sport}" if sport else "/gamestate"
+        data = self._client._get(path)
+        raw = data.get("data", {}) or {}
+        result: dict[str, dict[str, GameState]] = {}
+        for sport_key, events in raw.items():
+            if not isinstance(events, dict):
+                continue
+            result[sport_key] = {
+                eid: GameState.model_validate(state)
+                for eid, state in events.items()
+                if isinstance(state, dict)
+            }
+        return result
+
+
 class _SportsResource:
     def __init__(self, client: SharpAPI):
         self._client = client
@@ -781,6 +821,15 @@ class _StreamResource:
             "market": market,
         })
 
+    def gamestate(self) -> EventStream:
+        """Stream live game state updates (scores, period, clock).
+
+        Emits ``gamestate:snapshot`` (initial dump on connect) and
+        ``gamestate:update`` / ``gamestate:removed`` events. Requires the
+        Game State add-on or Enterprise tier.
+        """
+        return self._build_stream("/stream/gamestate")
+
 
 # =============================================================================
 # Helpers

{sharpapi-0.2.5 → sharpapi-0.3.1}/src/sharpapi/exceptions.py

@@ -1,8 +1,7 @@
 """SharpAPI exceptions and canonical error-code registry.
 
-The error codes here mirror ``pkg/errcodes/errcodes.go`` in sharp-api-go, which
-is the single source of truth for every code the API emits. Keep this file in
-sync when new codes are added upstream.
+The codes here mirror the canonical set the SharpAPI server emits.
+Keep this file in sync when new codes are added upstream.
 """
 
 from __future__ import annotations
@@ -65,9 +64,10 @@ class StreamError(SharpAPIError):
 # =============================================================================
 # Canonical error-code registry
 #
-# Mirrors sharp-api-go/pkg/errcodes/errcodes.go. When upstream adds a new code,
-# add it here too and update the matching description. Each code maps to the
-# Python exception class that ``handle_errors`` (in ``_base.py``) raises for it.
+# Mirrors the canonical SharpAPI server error-code set. When upstream adds
+# a new code, add it here too and update the matching description. Each
+# code maps to the Python exception class that ``handle_errors`` (in
+# ``_base.py``) raises for it.
 # =============================================================================
 
 # HTTP error codes — emitted via REST handlers (httputil.WriteJSONError).
@@ -82,6 +82,8 @@ INVALID_TOKEN = "invalid_token"
 METHOD_NOT_ALLOWED = "method_not_allowed"
 MISSING_API_KEY = "missing_api_key"
 NOT_FOUND = "not_found"
+NOT_READY = "not_ready"
+OFFSET_TOO_LARGE = "offset_too_large"
 RATE_LIMITED = "rate_limited"
 SERVICE_UNAVAILABLE = "service_unavailable"
 TIER_RESTRICTED = "tier_restricted"
@@ -113,6 +115,11 @@ ERROR_CODE_DESCRIPTIONS: dict[str, str] = {
     METHOD_NOT_ALLOWED: "HTTP method not allowed on this endpoint.",
     MISSING_API_KEY: "No API key provided.",
     NOT_FOUND: "Resource not found.",
+    NOT_READY: "A required backing store is not yet ready to serve this request; retry shortly.",
+    OFFSET_TOO_LARGE: (
+        "offset exceeds the per-endpoint maximum; "
+        "use cursor-based pagination or advance `since`."
+    ),
     RATE_LIMITED: "Rate limit exceeded; see Retry-After header.",
     SERVICE_UNAVAILABLE: "Service is temporarily unavailable.",
     TIER_RESTRICTED: "Current subscription tier does not include this feature.",
@@ -148,6 +155,7 @@ ERROR_CODE_TO_EXCEPTION: dict[str, type[SharpAPIError]] = {
     TOO_MANY_STREAMS: RateLimitedError,
     # Validation
     VALIDATION_ERROR: ValidationError,
+    OFFSET_TOO_LARGE: ValidationError,
     # Streaming frames
     WS_ALREADY_AUTHENTICATED: StreamError,
     WS_INVALID_MESSAGE: StreamError,
@@ -160,15 +168,16 @@ ERROR_CODE_TO_EXCEPTION: dict[str, type[SharpAPIError]] = {
     INTERNAL_ERROR: SharpAPIError,
     METHOD_NOT_ALLOWED: SharpAPIError,
     NOT_FOUND: SharpAPIError,
+    NOT_READY: SharpAPIError,
     SERVICE_UNAVAILABLE: SharpAPIError,
     UNKNOWN_ENDPOINT: SharpAPIError,
     UPSTREAM_ERROR: SharpAPIError,
 }
 
-# Deprecated aliases. ``bad_request`` and ``invalid_request`` were both collapsed
-# into ``validation_error`` in sharp-api-go. Kept here so that older API
-# responses (or user code still checking these strings) resolve correctly.
-# TODO: remove after 2026-10.
+# Deprecated aliases. ``bad_request`` and ``invalid_request`` were both
+# collapsed into ``validation_error`` server-side. Kept here so that older
+# API responses (or user code still checking these strings) resolve
+# correctly. Will be removed after 2026-10.
 DEPRECATED_CODE_ALIASES: dict[str, str] = {
     "bad_request": VALIDATION_ERROR,
     "invalid_request": VALIDATION_ERROR,