cfb-data 0.4.1__py3-none-any.whl

cfb_data/stats/models/pydantic/responses.py

@@ -0,0 +1,291 @@
+"""Validate responses from implemented CFBD Stats endpoints."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cfb_data.enums import SeasonType
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Stats responses."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class PlayerStat(_ResponseModel):
+    """Represent one player statistic aggregated by season."""
+
+    season: int = Field(ge=1869)
+    player_id: str = Field(alias="playerId")
+    player: str
+    position: str
+    team: str
+    conference: str
+    category: str
+    stat_type: str = Field(alias="statType")
+    stat: str
+
+
+class PlayerSuccessRateSplit(_ResponseModel):
+    """Represent passing or rushing success-rate totals."""
+
+    plays: int = Field(ge=0)
+    successes: int = Field(ge=0)
+    success_rate: float | None = Field(alias="successRate")
+
+
+class PlayerSeasonSuccessRate(_ResponseModel):
+    """Represent one player's passing and rushing season success rates."""
+
+    season: int = Field(ge=1869)
+    id: str
+    name: str
+    position: str
+    team: str
+    conference: str
+    passing: PlayerSuccessRateSplit
+    rushing: PlayerSuccessRateSplit
+
+
+class PlayerGameSuccessRate(_ResponseModel):
+    """Represent one player's passing and rushing success rates for a game."""
+
+    season: int = Field(ge=1869)
+    season_type: SeasonType = Field(alias="seasonType")
+    week: int = Field(ge=0)
+    game_id: int = Field(alias="gameId", gt=0)
+    id: str
+    name: str
+    position: str
+    team: str
+    conference: str
+    opponent: str
+    passing: PlayerSuccessRateSplit
+    rushing: PlayerSuccessRateSplit
+
+
+class TeamStat(_ResponseModel):
+    """Represent one season-level team statistic without scalar coercion."""
+
+    season: int = Field(ge=1869)
+    team: str
+    conference: str
+    stat_name: str = Field(alias="statName")
+    stat_value: str | int | float = Field(alias="statValue")
+
+    @field_validator("stat_value", mode="before")
+    @classmethod
+    def reject_non_stat_scalars(cls, value: object) -> object:
+        """Accept only upstream string and numeric statistic values."""
+        if isinstance(value, bool) or not isinstance(value, str | int | float):
+            raise ValueError("statValue must be a string or number")
+        return value
+
+
+class StatCategory(_ResponseModel):
+    """Represent one team-stat category for tabular presentation."""
+
+    category: str
+
+
+class FieldPosition(_ResponseModel):
+    """Represent average starting field position and predicted points."""
+
+    average_start: float | None = Field(alias="averageStart")
+    average_predicted_points: float | None = Field(alias="averagePredictedPoints")
+
+
+class Havoc(_ResponseModel):
+    """Represent aggregate havoc rates by position group."""
+
+    total: float | None
+    front_seven: float | None = Field(alias="frontSeven")
+    db: float | None
+
+
+class SeasonDownStats(_ResponseModel):
+    """Represent advanced season metrics for one down classification."""
+
+    rate: float
+    ppa: float
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+
+
+class SeasonPassingDownStats(SeasonDownStats):
+    """Represent defensive passing-down season metrics."""
+
+    total_ppa: float = Field(alias="totalPPA")
+
+
+class SeasonPlayStats(_ResponseModel):
+    """Represent advanced season metrics for one play classification."""
+
+    rate: float
+    ppa: float
+    total_ppa: float = Field(alias="totalPPA")
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+
+
+class AdvancedSeasonOffense(_ResponseModel):
+    """Represent a team's advanced season offense metrics."""
+
+    plays: int = Field(ge=0)
+    drives: int = Field(ge=0)
+    ppa: float
+    total_ppa: float = Field(alias="totalPPA")
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+    power_success: float | None = Field(alias="powerSuccess")
+    stuff_rate: float = Field(alias="stuffRate")
+    line_yards: float = Field(alias="lineYards")
+    line_yards_total: int = Field(alias="lineYardsTotal")
+    second_level_yards: float = Field(alias="secondLevelYards")
+    second_level_yards_total: int = Field(alias="secondLevelYardsTotal")
+    open_field_yards: float = Field(alias="openFieldYards")
+    open_field_yards_total: int = Field(alias="openFieldYardsTotal")
+    total_opportunities: int = Field(alias="totalOpportunies")
+    points_per_opportunity: float = Field(alias="pointsPerOpportunity")
+    field_position: FieldPosition = Field(alias="fieldPosition")
+    havoc: Havoc
+    standard_downs: SeasonDownStats = Field(alias="standardDowns")
+    passing_downs: SeasonDownStats = Field(alias="passingDowns")
+    rushing_plays: SeasonPlayStats = Field(alias="rushingPlays")
+    passing_plays: SeasonPlayStats = Field(alias="passingPlays")
+
+
+class AdvancedSeasonDefense(AdvancedSeasonOffense):
+    """Represent a team's advanced season defense metrics."""
+
+    passing_downs: SeasonPassingDownStats = Field(alias="passingDowns")
+
+
+class AdvancedSeasonStat(_ResponseModel):
+    """Represent advanced team metrics aggregated by season."""
+
+    season: int = Field(ge=1869)
+    team: str
+    conference: str
+    offense: AdvancedSeasonOffense
+    defense: AdvancedSeasonDefense
+
+
+class GameDownStats(_ResponseModel):
+    """Represent advanced game metrics for one down classification."""
+
+    ppa: float
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+
+
+class GamePlayStats(_ResponseModel):
+    """Represent advanced game metrics for one play classification."""
+
+    ppa: float
+    total_ppa: float = Field(alias="totalPPA")
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+
+
+class _AdvancedGameUnit(_ResponseModel):
+    """Represent fields shared by advanced game offense and defense."""
+
+    plays: int = Field(ge=0)
+    drives: int = Field(ge=0)
+    ppa: float
+    total_ppa: float = Field(alias="totalPPA")
+    success_rate: float = Field(alias="successRate")
+    explosiveness: float | None
+    power_success: float | None = Field(alias="powerSuccess")
+    stuff_rate: float = Field(alias="stuffRate")
+    line_yards: float = Field(alias="lineYards")
+    line_yards_total: int = Field(alias="lineYardsTotal")
+    second_level_yards: float = Field(alias="secondLevelYards")
+    second_level_yards_total: int = Field(alias="secondLevelYardsTotal")
+    open_field_yards: float | None = Field(alias="openFieldYards")
+    open_field_yards_total: int | None = Field(alias="openFieldYardsTotal")
+    standard_downs: GameDownStats = Field(alias="standardDowns")
+    passing_downs: GameDownStats = Field(alias="passingDowns")
+    rushing_plays: GamePlayStats = Field(alias="rushingPlays")
+    passing_plays: GamePlayStats = Field(alias="passingPlays")
+
+
+class AdvancedGameOffense(_AdvancedGameUnit):
+    """Represent a team's advanced offense metrics for one game."""
+
+    open_field_yards_total: int = Field(alias="openFieldYardsTotal")
+
+
+class AdvancedGameDefense(_AdvancedGameUnit):
+    """Represent a team's advanced defense metrics for one game."""
+
+    explosiveness: float
+    open_field_yards: float = Field(alias="openFieldYards")
+    open_field_yards_total: int | None = Field(alias="openFieldYardsTotal")
+
+
+class AdvancedGameStat(_ResponseModel):
+    """Represent advanced team metrics for one game."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+    season: int = Field(ge=1869)
+    season_type: SeasonType = Field(alias="seasonType")
+    week: int = Field(ge=0)
+    team: str
+    opponent: str
+    offense: AdvancedGameOffense
+    defense: AdvancedGameDefense
+
+
+class GameHavocUnit(_ResponseModel):
+    """Represent havoc event counts and rates for one side of a game."""
+
+    total_plays: float = Field(alias="totalPlays", ge=0)
+    total_havoc_events: float = Field(alias="totalHavocEvents", ge=0)
+    front_seven_havoc_events: float = Field(alias="frontSevenHavocEvents", ge=0)
+    db_havoc_events: float = Field(alias="dbHavocEvents", ge=0)
+    havoc_rate: float = Field(alias="havocRate")
+    front_seven_havoc_rate: float = Field(alias="frontSevenHavocRate")
+    db_havoc_rate: float = Field(alias="dbHavocRate")
+
+
+class GameHavocStats(_ResponseModel):
+    """Represent team havoc statistics for one game."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+    season: int = Field(ge=1869)
+    season_type: SeasonType = Field(alias="seasonType")
+    week: int = Field(ge=0)
+    team: str
+    conference: str | None
+    opponent: str
+    opponent_conference: str | None = Field(alias="opponentConference")
+    offense: GameHavocUnit
+    defense: GameHavocUnit
+
+
+__all__ = [
+    "AdvancedGameDefense",
+    "AdvancedGameOffense",
+    "AdvancedGameStat",
+    "AdvancedSeasonDefense",
+    "AdvancedSeasonOffense",
+    "AdvancedSeasonStat",
+    "FieldPosition",
+    "GameDownStats",
+    "GameHavocStats",
+    "GameHavocUnit",
+    "GamePlayStats",
+    "Havoc",
+    "PlayerGameSuccessRate",
+    "PlayerSeasonSuccessRate",
+    "PlayerStat",
+    "PlayerSuccessRateSplit",
+    "SeasonDownStats",
+    "SeasonPassingDownStats",
+    "SeasonPlayStats",
+    "StatCategory",
+    "TeamStat",
+]

cfb_data/stats/resource.py

@@ -0,0 +1,400 @@
+"""Expose typed Stats endpoints through the primary client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal, TypeVar, 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.stats.models.pydantic.requests import (
+    AdvancedGameStatsRequest,
+    AdvancedSeasonStatsRequest,
+    GameHavocRequest,
+    PlayerGameSuccessRequest,
+    PlayerSeasonStatsRequest,
+    PlayerSeasonSuccessRequest,
+    TeamSeasonStatsRequest,
+)
+from cfb_data.stats.models.pydantic.responses import (
+    AdvancedGameStat,
+    AdvancedSeasonStat,
+    GameHavocStats,
+    PlayerGameSuccessRate,
+    PlayerSeasonSuccessRate,
+    PlayerStat,
+    StatCategory,
+    TeamStat,
+)
+
+_RequestT = TypeVar("_RequestT", bound=BaseModel)
+_RowT = TypeVar("_RowT", bound=BaseModel)
+type _ClassificationArgument = Classification | Literal["fbs", "fcs", "ii", "iii"]
+type _SeasonTypeArgument = (
+    SeasonType
+    | Literal[
+        "regular",
+        "postseason",
+        "both",
+        "allstar",
+        "spring_regular",
+        "spring_postseason",
+    ]
+)
+
+_PLAYER_STAT_ROWS = TypeAdapter(list[PlayerStat])
+_PLAYER_SEASON_SUCCESS_ROWS = TypeAdapter(list[PlayerSeasonSuccessRate])
+_PLAYER_GAME_SUCCESS_ROWS = TypeAdapter(list[PlayerGameSuccessRate])
+_TEAM_STAT_ROWS = TypeAdapter(list[TeamStat])
+_CATEGORY_VALUES = TypeAdapter(list[str])
+_ADVANCED_SEASON_ROWS = TypeAdapter(list[AdvancedSeasonStat])
+_ADVANCED_GAME_ROWS = TypeAdapter(list[AdvancedGameStat])
+_GAME_HAVOC_ROWS = TypeAdapter(list[GameHavocStats])
+
+
+class _CategoriesRequest(BaseModel):
+    """Represent the empty filter set accepted by ``GET /stats/categories``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+_CATEGORIES_REQUEST = _CategoriesRequest()
+
+
+class StatsResource[FrameT]:
+    """Provide validated Stats 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 player_season(self, request: PlayerSeasonStatsRequest, /) -> FrameT: ...
+
+    @overload
+    async def player_season(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int,
+        conference: str | None = None,
+        team: str | None = None,
+        start_week: int | None = None,
+        end_week: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        category: str | None = None,
+    ) -> FrameT: ...
+
+    async def player_season(
+        self, request: PlayerSeasonStatsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return player statistics aggregated by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``PlayerStat`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/player/season",
+            request_type=PlayerSeasonStatsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_PLAYER_STAT_ROWS,
+            row_model=PlayerStat,
+        )
+
+    @overload
+    async def player_season_success(
+        self, request: PlayerSeasonSuccessRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def player_season_success(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        conference: str | None = None,
+        team: str | None = None,
+        player_id: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        start_week: int | None = None,
+        end_week: int | None = None,
+        threshold: int | None = None,
+        exclude_garbage_time: bool | None = None,
+    ) -> FrameT: ...
+
+    async def player_season_success(
+        self, request: PlayerSeasonSuccessRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return player passing and rushing success rates by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated season success-rate rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/player/success",
+            request_type=PlayerSeasonSuccessRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_PLAYER_SEASON_SUCCESS_ROWS,
+            row_model=PlayerSeasonSuccessRate,
+        )
+
+    @overload
+    async def player_game_success(
+        self, request: PlayerGameSuccessRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def player_game_success(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int,
+        week: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        conference: str | None = None,
+        team: str | None = None,
+        player_id: int | None = None,
+        threshold: int | None = None,
+        exclude_garbage_time: bool | None = None,
+    ) -> FrameT: ...
+
+    async def player_game_success(
+        self, request: PlayerGameSuccessRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return player passing and rushing success rates by game.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated game success-rate rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/player/success/game",
+            request_type=PlayerGameSuccessRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_PLAYER_GAME_SUCCESS_ROWS,
+            row_model=PlayerGameSuccessRate,
+        )
+
+    @overload
+    async def team_season(self, request: TeamSeasonStatsRequest, /) -> FrameT: ...
+
+    @overload
+    async def team_season(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+        start_week: int | None = None,
+        end_week: int | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def team_season(
+        self, request: TeamSeasonStatsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team statistics aggregated by season.
+
+        ``stat_value`` preserves upstream strings and numbers in an object-typed
+        column for both supported DataFrame backends.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``TeamStat`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/season",
+            request_type=TeamSeasonStatsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_TEAM_STAT_ROWS,
+            row_model=TeamStat,
+        )
+
+    async def categories(self) -> FrameT:
+        """Return team-stat categories as a one-column selected frame.
+
+        :return: Eager frame with one ``category`` column in upstream order.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        values = await self._executor.fetch_values(
+            endpoint="/stats/categories",
+            request=_CATEGORIES_REQUEST,
+            response_adapter=_CATEGORY_VALUES,
+        )
+        rows = [StatCategory(category=value) for value in values]
+        return self._dataframe_adapter.from_models(
+            endpoint="/stats/categories",
+            row_model=StatCategory,
+            models=rows,
+        )
+
+    @overload
+    async def advanced_season(
+        self, request: AdvancedSeasonStatsRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def advanced_season(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        exclude_garbage_time: bool | None = None,
+        start_week: int | None = None,
+        end_week: int | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def advanced_season(
+        self, request: AdvancedSeasonStatsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return advanced team statistics aggregated by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated advanced season rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/season/advanced",
+            request_type=AdvancedSeasonStatsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_ADVANCED_SEASON_ROWS,
+            row_model=AdvancedSeasonStat,
+        )
+
+    @overload
+    async def advanced_game(self, request: AdvancedGameStatsRequest, /) -> FrameT: ...
+
+    @overload
+    async def advanced_game(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        week: int | None = None,
+        opponent: str | None = None,
+        exclude_garbage_time: bool | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+    ) -> FrameT: ...
+
+    async def advanced_game(
+        self, request: AdvancedGameStatsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return advanced team statistics by game.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated advanced game rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/game/advanced",
+            request_type=AdvancedGameStatsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_ADVANCED_GAME_ROWS,
+            row_model=AdvancedGameStat,
+        )
+
+    @overload
+    async def game_havoc(self, request: GameHavocRequest, /) -> FrameT: ...
+
+    @overload
+    async def game_havoc(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        week: int | None = None,
+        opponent: str | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+    ) -> FrameT: ...
+
+    async def game_havoc(
+        self, request: GameHavocRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team havoc statistics by game.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated game havoc rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        return await self._fetch_many(
+            endpoint="/stats/game/havoc",
+            request_type=GameHavocRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_GAME_HAVOC_ROWS,
+            row_model=GameHavocStats,
+        )
+
+    async def _fetch_many(
+        self,
+        *,
+        endpoint: str,
+        request_type: type[_RequestT],
+        request: _RequestT | None,
+        filters: Mapping[str, object],
+        response_adapter: TypeAdapter[list[_RowT]],
+        row_model: type[_RowT],
+    ) -> FrameT:
+        """Validate, fetch, and convert one Stats list route."""
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=request_type,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=response_adapter,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=row_model,
+            models=rows,
+        )
+
+
+__all__ = ["StatsResource"]