cfb-data 0.4.1__py3-none-any.whl

cfb_data/plays/__init__.py

@@ -0,0 +1,43 @@
+"""Export the supported Plays namespace and public contracts."""
+
+from cfb_data.enums import Classification, SeasonType
+
+from .models.pydantic import (
+    DownType,
+    HomeAway,
+    LiveGame,
+    LiveGameDrive,
+    LiveGamePlay,
+    LiveGameTeam,
+    LivePlaysRequest,
+    Play,
+    PlayClock,
+    PlaysRequest,
+    PlayStat,
+    PlayStatsRequest,
+    PlayStatType,
+    PlayType,
+    RushPass,
+)
+from .resource import PlaysResource
+
+__all__ = [
+    "Classification",
+    "DownType",
+    "HomeAway",
+    "LiveGame",
+    "LiveGameDrive",
+    "LiveGamePlay",
+    "LiveGameTeam",
+    "LivePlaysRequest",
+    "Play",
+    "PlayClock",
+    "PlayStat",
+    "PlayStatsRequest",
+    "PlayStatType",
+    "PlayType",
+    "PlaysRequest",
+    "PlaysResource",
+    "RushPass",
+    "SeasonType",
+]

cfb_data/plays/models/__init__.py

@@ -0,0 +1 @@
+"""Provide authoritative Pydantic models for Plays endpoints."""

cfb_data/plays/models/pydantic/__init__.py

@@ -0,0 +1,35 @@
+"""Export Pydantic models for Plays endpoints."""
+
+from .requests import LivePlaysRequest, PlaysRequest, PlayStatsRequest
+from .responses import (
+    DownType,
+    HomeAway,
+    LiveGame,
+    LiveGameDrive,
+    LiveGamePlay,
+    LiveGameTeam,
+    Play,
+    PlayClock,
+    PlayStat,
+    PlayStatType,
+    PlayType,
+    RushPass,
+)
+
+__all__ = [
+    "DownType",
+    "HomeAway",
+    "LiveGame",
+    "LiveGameDrive",
+    "LiveGamePlay",
+    "LiveGameTeam",
+    "LivePlaysRequest",
+    "Play",
+    "PlayClock",
+    "PlayStat",
+    "PlayStatsRequest",
+    "PlayStatType",
+    "PlayType",
+    "PlaysRequest",
+    "RushPass",
+]

cfb_data/plays/models/pydantic/requests.py

@@ -0,0 +1,85 @@
+"""Validate request parameters for implemented Plays endpoints."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cfb_data.enums import Classification, SeasonType
+
+
+class PlaysRequest(BaseModel):
+    """Validate filters accepted by ``GET /plays``.
+
+    :param year: Required season year.
+    :param week: Required non-negative season week.
+    :param team: Team appearing on either side of the play.
+    :param offense: Offensive-team selector.
+    :param defense: Defensive-team selector.
+    :param offense_conference: Offensive-team conference selector.
+    :param defense_conference: Defensive-team conference selector.
+    :param conference: Conference appearing on either side of the play.
+    :param play_type: Play-type abbreviation.
+    :param season_type: Optional season phase.
+    :param classification: Division classification selector.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int = Field(ge=1869)
+    week: int = Field(ge=0)
+    team: str | None = None
+    offense: str | None = None
+    defense: str | None = None
+    offense_conference: str | None = Field(
+        default=None,
+        alias="offenseConference",
+    )
+    defense_conference: str | None = Field(
+        default=None,
+        alias="defenseConference",
+    )
+    conference: str | None = None
+    play_type: str | None = Field(default=None, alias="playType")
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    classification: Classification | None = None
+
+
+class PlayStatsRequest(BaseModel):
+    """Validate filters accepted by ``GET /plays/stats``.
+
+    The upstream endpoint permits an unfiltered request and limits every
+    response to 2,000 rows.
+
+    :param year: Optional season year.
+    :param week: Optional non-negative season week.
+    :param team: Team selector.
+    :param game_id: Positive game identifier.
+    :param athlete_id: Positive athlete identifier.
+    :param stat_type_id: Positive play-stat type identifier.
+    :param season_type: Optional season phase.
+    :param conference: Conference name or abbreviation.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int | None = Field(default=None, ge=1869)
+    week: int | None = Field(default=None, ge=0)
+    team: str | None = None
+    game_id: int | None = Field(default=None, gt=0, serialization_alias="gameId")
+    athlete_id: int | None = Field(default=None, gt=0, serialization_alias="athleteId")
+    stat_type_id: int | None = Field(
+        default=None, gt=0, serialization_alias="statTypeId"
+    )
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    conference: str | None = None
+
+
+class LivePlaysRequest(BaseModel):
+    """Validate filters accepted by ``GET /live/plays``.
+
+    :param game_id: Positive game identifier.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    game_id: int = Field(gt=0, serialization_alias="gameId")

cfb_data/plays/models/pydantic/responses.py

@@ -0,0 +1,231 @@
+"""Validate responses from implemented CFBD Plays endpoints."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to response models."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    @field_validator("*", mode="after", check_fields=False)
+    @classmethod
+    def require_utc_datetimes(cls, value: object) -> object:
+        """Require aware response timestamps and normalize them to UTC.
+
+        :param value: Validated response field value.
+        :return: UTC-normalized datetime or the unchanged non-datetime value.
+        :raises ValueError: If a datetime does not identify an instant.
+        """
+        if not isinstance(value, datetime):
+            return value
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("Response timestamps must be timezone-aware")
+        return value.astimezone(UTC)
+
+
+class PlayClock(_ResponseModel):
+    """Represent time remaining in a play's period."""
+
+    minutes: int | None = Field(ge=0)
+    seconds: int | None = Field(ge=0)
+
+
+class Play(_ResponseModel):
+    """Represent one historical play returned by ``GET /plays``."""
+
+    id: str
+    drive_id: str = Field(alias="driveId")
+    game_id: int = Field(alias="gameId", gt=0)
+    drive_number: int | None = Field(alias="driveNumber", ge=0)
+    play_number: int | None = Field(alias="playNumber", ge=0)
+    offense: str
+    offense_conference: str | None = Field(alias="offenseConference")
+    offense_score: int = Field(alias="offenseScore", ge=0)
+    defense: str
+    home: str
+    away: str
+    defense_conference: str | None = Field(alias="defenseConference")
+    defense_score: int = Field(alias="defenseScore", ge=0)
+    period: int = Field(ge=0)
+    clock: PlayClock
+    offense_timeouts: int | None = Field(alias="offenseTimeouts")
+    defense_timeouts: int | None = Field(alias="defenseTimeouts")
+    yardline: int = Field(ge=0)
+    yards_to_goal: int = Field(alias="yardsToGoal", ge=0)
+    down: int = Field(ge=0)
+    distance: int = Field(ge=0)
+    yards_gained: int = Field(alias="yardsGained")
+    scoring: bool
+    play_type: str = Field(alias="playType")
+    play_text: str | None = Field(alias="playText")
+    ppa: float | None
+    wallclock: datetime | None
+
+
+class PlayType(_ResponseModel):
+    """Represent one available historical play type."""
+
+    id: int = Field(gt=0)
+    text: str
+    abbreviation: str | None
+
+
+class PlayStat(_ResponseModel):
+    """Represent one athlete statistic associated with a play."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+    season: int = Field(ge=1869)
+    week: int = Field(ge=0)
+    team: str
+    conference: str
+    opponent: str
+    team_score: int = Field(alias="teamScore", ge=0)
+    opponent_score: int = Field(alias="opponentScore", ge=0)
+    drive_id: str = Field(alias="driveId")
+    play_id: str = Field(alias="playId")
+    period: int = Field(ge=0)
+    clock: PlayClock
+    yards_to_goal: int = Field(alias="yardsToGoal", ge=0)
+    down: int = Field(ge=0)
+    distance: int = Field(ge=0)
+    athlete_id: str = Field(alias="athleteId")
+    athlete_name: str = Field(alias="athleteName")
+    stat_type: str = Field(alias="statType")
+    stat: int
+
+
+class PlayStatType(_ResponseModel):
+    """Represent one available athlete play-stat type."""
+
+    id: int = Field(gt=0)
+    name: str
+
+
+class HomeAway(StrEnum):
+    """Identify whether a live-game team is home or away."""
+
+    home = "home"
+    away = "away"
+
+
+class RushPass(StrEnum):
+    """Classify a live play by its offensive action."""
+
+    rush = "rush"
+    pass_ = "pass"
+    other = "other"
+
+
+class DownType(StrEnum):
+    """Classify a live play's down and distance."""
+
+    passing = "passing"
+    standard = "standard"
+
+
+class LiveGamePlay(_ResponseModel):
+    """Represent one play nested within a live drive."""
+
+    id: str
+    home_score: int = Field(alias="homeScore", ge=0)
+    away_score: int = Field(alias="awayScore", ge=0)
+    period: int = Field(ge=0)
+    clock: str | None
+    wall_clock: datetime = Field(alias="wallClock")
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    down: int = Field(ge=0)
+    distance: int = Field(ge=0)
+    yards_to_goal: int = Field(alias="yardsToGoal", ge=0)
+    yards_gained: int = Field(alias="yardsGained")
+    play_type_id: int = Field(alias="playTypeId", gt=0)
+    play_type: str = Field(alias="playType")
+    epa: float | None
+    garbage_time: bool = Field(alias="garbageTime")
+    success: bool
+    rush_pass: RushPass = Field(alias="rushPass")
+    down_type: DownType = Field(alias="downType")
+    play_text: str = Field(alias="playText")
+
+
+class LiveGameDrive(_ResponseModel):
+    """Represent one drive nested within a live game."""
+
+    id: str
+    offense_id: int = Field(alias="offenseId", gt=0)
+    offense: str
+    defense_id: int = Field(alias="defenseId", gt=0)
+    defense: str
+    play_count: int = Field(alias="playCount", ge=0)
+    yards: int
+    start_period: int = Field(alias="startPeriod", ge=0)
+    start_clock: str | None = Field(alias="startClock")
+    start_yards_to_goal: int = Field(alias="startYardsToGoal", ge=0)
+    end_period: int | None = Field(alias="endPeriod", ge=0)
+    end_clock: str | None = Field(alias="endClock")
+    end_yards_to_goal: int | None = Field(alias="endYardsToGoal", ge=0)
+    duration: str | None
+    scoring_opportunity: bool = Field(alias="scoringOpportunity")
+    result: str
+    points_gained: int = Field(alias="pointsGained")
+    plays: list[LiveGamePlay]
+
+
+class LiveGameTeam(_ResponseModel):
+    """Represent one team's live-game aggregate metrics."""
+
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    home_away: HomeAway = Field(alias="homeAway")
+    line_scores: list[int] = Field(alias="lineScores")
+    points: int = Field(ge=0)
+    drives: int = Field(ge=0)
+    scoring_opportunities: int = Field(alias="scoringOpportunities", ge=0)
+    points_per_opportunity: float = Field(alias="pointsPerOpportunity")
+    average_start_yard_line: float | None = Field(alias="averageStartYardLine")
+    plays: int = Field(ge=0)
+    line_yards: float = Field(alias="lineYards")
+    line_yards_per_rush: float = Field(alias="lineYardsPerRush")
+    second_level_yards: float = Field(alias="secondLevelYards")
+    second_level_yards_per_rush: float = Field(alias="secondLevelYardsPerRush")
+    open_field_yards: float = Field(alias="openFieldYards")
+    open_field_yards_per_rush: float = Field(alias="openFieldYardsPerRush")
+    epa_per_play: float = Field(alias="epaPerPlay")
+    total_epa: float = Field(alias="totalEpa")
+    passing_epa: float = Field(alias="passingEpa")
+    epa_per_pass: float = Field(alias="epaPerPass")
+    rushing_epa: float = Field(alias="rushingEpa")
+    epa_per_rush: float = Field(alias="epaPerRush")
+    success_rate: float = Field(alias="successRate", ge=0, le=1)
+    standard_down_success_rate: float = Field(
+        alias="standardDownSuccessRate", ge=0, le=1
+    )
+    passing_down_success_rate: float = Field(alias="passingDownSuccessRate", ge=0, le=1)
+    explosiveness: float
+    deserve_to_win: float | None = Field(
+        default=None,
+        alias="deserveToWin",
+        ge=0,
+        le=1,
+    )
+
+
+class LiveGame(_ResponseModel):
+    """Represent the nested response returned by ``GET /live/plays``."""
+
+    id: int = Field(gt=0)
+    status: str
+    period: int | None = Field(ge=0)
+    clock: str
+    possession: str
+    down: int | None = Field(ge=0)
+    distance: int | None = Field(ge=0)
+    yards_to_goal: int | None = Field(alias="yardsToGoal", ge=0)
+    teams: list[LiveGameTeam]
+    drives: list[LiveGameDrive]

cfb_data/plays/resource.py

@@ -0,0 +1,249 @@
+"""Expose typed Plays endpoints through the primary client."""
+
+from __future__ import annotations
+
+from typing import Literal, overload
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor
+from cfb_data._requests import _resolve_request
+from cfb_data.enums import Classification, SeasonType
+from cfb_data.plays.models.pydantic.requests import (
+    LivePlaysRequest,
+    PlaysRequest,
+    PlayStatsRequest,
+)
+from cfb_data.plays.models.pydantic.responses import (
+    LiveGame,
+    Play,
+    PlayStat,
+    PlayStatType,
+    PlayType,
+)
+
+type _SeasonTypeArgument = (
+    SeasonType
+    | Literal[
+        "regular",
+        "postseason",
+        "both",
+        "allstar",
+        "spring_regular",
+        "spring_postseason",
+    ]
+)
+type _ClassificationArgument = Classification | Literal["fbs", "fcs", "ii", "iii"]
+
+_PLAY_ROWS = TypeAdapter(list[Play])
+_PLAY_TYPE_ROWS = TypeAdapter(list[PlayType])
+_PLAY_STAT_ROWS = TypeAdapter(list[PlayStat])
+_PLAY_STAT_TYPE_ROWS = TypeAdapter(list[PlayStatType])
+_LIVE_GAME = TypeAdapter(LiveGame)
+
+
+class _EmptyRequest(BaseModel):
+    """Represent a route with no query parameters."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+_EMPTY_REQUEST = _EmptyRequest()
+
+
+class PlaysResource[FrameT]:
+    """Provide validated Plays endpoints with backend-specific frame results."""
+
+    def __init__(
+        self,
+        executor: _EndpointExecutor,
+        dataframe_adapter: _DataFrameAdapter[FrameT],
+    ) -> None:
+        """Bind the namespace to shared execution and presentation services."""
+        self._executor = executor
+        self._dataframe_adapter = dataframe_adapter
+
+    @overload
+    async def list(self, request: PlaysRequest, /) -> FrameT: ...
+
+    @overload
+    async def list(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int,
+        week: int,
+        team: str | None = None,
+        offense: str | None = None,
+        defense: str | None = None,
+        offense_conference: str | None = None,
+        defense_conference: str | None = None,
+        conference: str | None = None,
+        play_type: str | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def list(
+        self,
+        request: PlaysRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return historical plays as the selected DataFrame type.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``Play`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/plays"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=PlaysRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_PLAY_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=Play,
+            models=rows,
+        )
+
+    async def types(self) -> FrameT:
+        """Return available play types as the selected DataFrame type.
+
+        :return: Eager frame containing validated ``PlayType`` rows.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        endpoint = "/plays/types"
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=_EMPTY_REQUEST,
+            response_adapter=_PLAY_TYPE_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=PlayType,
+            models=rows,
+        )
+
+    @overload
+    async def stats(self, request: PlayStatsRequest, /) -> FrameT: ...
+
+    @overload
+    async def stats(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        week: int | None = None,
+        team: str | None = None,
+        game_id: int | None = None,
+        athlete_id: int | None = None,
+        stat_type_id: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def stats(
+        self,
+        request: PlayStatsRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return athlete play statistics as the selected DataFrame type.
+
+        The upstream endpoint limits responses to 2,000 rows.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``PlayStat`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/plays/stats"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=PlayStatsRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_PLAY_STAT_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=PlayStat,
+            models=rows,
+        )
+
+    async def stat_types(self) -> FrameT:
+        """Return athlete play-stat types as the selected DataFrame type.
+
+        :return: Eager frame containing validated ``PlayStatType`` rows.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        endpoint = "/plays/stats/types"
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=_EMPTY_REQUEST,
+            response_adapter=_PLAY_STAT_TYPE_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=PlayStatType,
+            models=rows,
+        )
+
+    @overload
+    async def live(self, request: LivePlaysRequest, /) -> LiveGame: ...
+
+    @overload
+    async def live(
+        self,
+        request: None = None,
+        /,
+        *,
+        game_id: int,
+    ) -> LiveGame: ...
+
+    async def live(
+        self,
+        request: LivePlaysRequest | None = None,
+        /,
+        **filters: object,
+    ) -> LiveGame:
+        """Return live play-by-play and metrics as one validated model.
+
+        The upstream route requires Patreon Tier 2 access.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Validated nested live game, team, drive, and play data.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, decode, or validation fails.
+        """
+        endpoint = "/live/plays"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=LivePlaysRequest,
+            request=request,
+            filters=filters,
+        )
+        return await self._executor.fetch_one(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_LIVE_GAME,
+        )

cfb_data/rankings/__init__.py

@@ -0,0 +1,16 @@
+"""Export the supported Rankings namespace and public contracts."""
+
+from cfb_data.enums import RankingPoll, SeasonType
+
+from .models.pydantic import Poll, PollRank, PollWeek, RankingsRequest
+from .resource import RankingsResource
+
+__all__ = [
+    "Poll",
+    "PollRank",
+    "PollWeek",
+    "RankingPoll",
+    "RankingsRequest",
+    "RankingsResource",
+    "SeasonType",
+]

cfb_data/rankings/models/__init__.py

@@ -0,0 +1 @@
+"""Export Rankings model families."""

cfb_data/rankings/models/pydantic/__init__.py

@@ -0,0 +1,6 @@
+"""Export validated Rankings request and response models."""
+
+from .requests import RankingsRequest
+from .responses import Poll, PollRank, PollWeek
+
+__all__ = ["Poll", "PollRank", "PollWeek", "RankingsRequest"]