Skip to content

feat(types): nested refs + numerical_id #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Mlaz-code wants to merge 1 commit into from
Closed

feat(types): nested refs + numerical_id #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Changelog

All notable changes to the `sharpapi` Python SDK are documented here.

## 0.3.0 — 2026-05-06

### Added — OpticOdds-parity nested refs (Phase 1f)

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.
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "sharpapi"
version = "0.2.6"
version = "0.3.0"
description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
readme = "README.md"
license = "MIT"
Expand Down
10 changes: 9 additions & 1 deletion src/sharpapi/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@
ArbitrageOpportunity,
ClosingOddsLine,
ClosingSnapshot,
EntityRef,
Event,
EVOpportunity,
GameState,
Expand All @@ -54,10 +55,13 @@
ResponseMeta,
Sport,
Sportsbook,
SportRef,
Team,
TeamRef,
)
from .streaming import EventStream

__version__ = "0.2.6"
__version__ = "0.3.0"

__all__ = [
# Clients
Expand All @@ -71,6 +75,7 @@
"ArbitrageOpportunity",
"ClosingOddsLine",
"ClosingSnapshot",
"EntityRef",
"EVOpportunity",
"Event",
"GameState",
Expand All @@ -86,7 +91,10 @@
"RateLimitInfo",
"ResponseMeta",
"Sport",
"SportRef",
"Sportsbook",
"Team",
"TeamRef",
# Streaming
"EventStream",
# Exceptions
Expand Down
123 changes: 123 additions & 0 deletions src/sharpapi/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,57 @@ class OddsValue(BaseModel):
probability: float


# =============================================================================
# Nested reference objects (Phase 1f — OpticOdds parity)
# =============================================================================
#
# These structured ref objects ship alongside the legacy flat fields on every
# odds row, opportunity row, and reference-list row. All fields are optional
# and additive — clients on older API versions simply receive ``None``.
#
# Wire format uses snake_case (``sport_ref``, ``league_ref``, ``market_ref``,
# ``sportsbook_ref``) which Python attribute names match directly.


class TeamRef(BaseModel):
"""Structured team reference attached to ``home`` / ``away``.

``abbreviation`` is only present for ~1500 team-sport entities; absent
for individual-sport competitors (tennis players, MMA fighters, etc).
"""

id: str | None = None
numerical_id: int | None = None
name: str | None = None
abbreviation: str | None = None

model_config = {"extra": "allow"}


class SportRef(BaseModel):
"""Structured sport reference attached to ``sport_ref``."""

id: str | None = None
name: str | None = None
numerical_id: int | None = None

model_config = {"extra": "allow"}


class EntityRef(BaseModel):
"""Structured reference for league / market / sportsbook objects.

Used by ``league_ref``, ``market_ref``, and ``sportsbook_ref`` on
every odds, opportunity, and reference row.
"""

id: str | None = None
label: str | None = None
numerical_id: int | None = None

model_config = {"extra": "allow"}


class Pagination(BaseModel):
limit: int
offset: int
Expand Down Expand Up @@ -163,6 +214,13 @@ class OddsLine(BaseModel):
deep_link: str | None = None
player_name: str | None = None
stat_category: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None
market_ref: EntityRef | None = None
sportsbook_ref: EntityRef | None = None


# =============================================================================
Expand Down Expand Up @@ -218,6 +276,13 @@ class EVOpportunity(BaseModel):
detected_at: str | None = None
external_event_id: str | None = None
selection_id: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None
market_ref: EntityRef | None = None
sportsbook_ref: EntityRef | None = None

model_config = {"populate_by_name": True}

Expand All @@ -240,6 +305,8 @@ class ArbitrageLeg(BaseModel):
external_event_id: str | None = None
selection_id: str | None = None
market_id: str | None = None
# Phase 1f — optional structured book ref on each leg.
sportsbook_ref: EntityRef | None = None


class ArbitrageOpportunity(BaseModel):
Expand Down Expand Up @@ -268,6 +335,12 @@ class ArbitrageOpportunity(BaseModel):
stat_category: str | None = None
legs: list[ArbitrageLeg]
detected_at: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None
market_ref: EntityRef | None = None


# =============================================================================
Expand Down Expand Up @@ -326,6 +399,12 @@ class MiddleOpportunity(BaseModel):
gap_size: float | None = Field(None, alias="gapSize")
potential_profit: float | None = Field(None, alias="potentialProfit")
legs: list[ArbitrageLeg] | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None
market_ref: EntityRef | None = None

model_config = {"populate_by_name": True}

Expand Down Expand Up @@ -372,6 +451,12 @@ class LowHoldOpportunity(BaseModel):
player_name: str | None = None
stat_category: str | None = None
detected_at: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None
market_ref: EntityRef | None = None


# =============================================================================
Expand All @@ -385,6 +470,8 @@ class Sport(BaseModel):
slug: str
active: bool
event_count: int | None = None
# Phase 1f — optional integer atlas ID, additive.
numerical_id: int | None = None


class League(BaseModel):
Expand All @@ -394,6 +481,8 @@ class League(BaseModel):
sport_id: str | None = None
country: str | None = None
active: bool
# Phase 1f — optional integer atlas ID, additive.
numerical_id: int | None = None


class Sportsbook(BaseModel):
Expand All @@ -403,6 +492,25 @@ class Sportsbook(BaseModel):
active: bool
regions: list[str] | None = None
features: list[str] | None = None
# Phase 1f — optional integer atlas ID, additive.
numerical_id: int | None = None


class Team(BaseModel):
"""A team / competitor returned by the ``/teams`` reference endpoint.

Phase 1f addition. ``abbreviation`` is only present for ~1500 team-sport
entities and is absent for individual-sport competitors.
"""

id: str
name: str | None = None
sport: str | None = None
league: str | None = None
abbreviation: str | None = None
numerical_id: int | None = None

model_config = {"extra": "allow"}


class Event(BaseModel):
Expand All @@ -414,6 +522,11 @@ class Event(BaseModel):
start_time: str | None = None
is_live: bool = False
status: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None


class Market(BaseModel):
Expand All @@ -424,6 +537,8 @@ class Market(BaseModel):
selection_count: int | None = None
book_count: int | None = None
books: list[str] | None = None
# Phase 1f — optional integer atlas ID, additive.
numerical_id: int | None = None


# =============================================================================
Expand All @@ -443,6 +558,9 @@ class ClosingOddsLine(BaseModel):
line: float | None = None
player_name: str | None = None
stat_category: str | None = None
# Phase 1f — optional structured refs (additive, non-breaking).
market_ref: EntityRef | None = None
sportsbook_ref: EntityRef | None = None


class ClosingSnapshot(BaseModel):
Expand All @@ -456,6 +574,11 @@ class ClosingSnapshot(BaseModel):
event_start_time: str | None = None
captured_at: str | None = None
books: dict[str, list[ClosingOddsLine]] = Field(default_factory=dict)
# Phase 1f — optional structured refs (additive, non-breaking).
home: TeamRef | None = None
away: TeamRef | None = None
sport_ref: SportRef | None = None
league_ref: EntityRef | None = None


# =============================================================================
Expand Down
Loading