cfb-data 0.4.1__py3-none-any.whl

cfb_data/info/resource.py

@@ -0,0 +1,88 @@
+"""Expose typed Info endpoints through the primary client."""
+
+from __future__ import annotations
+
+from typing import Literal, overload
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from cfb_data._executor import _EndpointExecutor
+from cfb_data._requests import _resolve_request
+from cfb_data.enums import UserUsageApi
+from cfb_data.info.models.pydantic.requests import InfoUsageRequest
+from cfb_data.info.models.pydantic.responses import UserInfo, UserUsage
+
+type _UserUsageApiArgument = UserUsageApi | Literal["all", "cfb", "cbb"]
+
+_USER_INFO = TypeAdapter(UserInfo)
+_USER_USAGE = TypeAdapter(UserUsage)
+
+
+class _EmptyRequest(BaseModel):
+    """Represent the empty filter set accepted by ``GET /info``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+_EMPTY_REQUEST = _EmptyRequest()
+
+
+class InfoResource:
+    """Provide validated operational account and usage metadata."""
+
+    def __init__(self, executor: _EndpointExecutor) -> None:
+        """Bind the namespace to shared endpoint execution."""
+        self._executor = executor
+
+    async def account(self) -> UserInfo:
+        """Return metadata for the authenticated API account.
+
+        :return: Validated account tier, quota, products, and feature access.
+        :raises CFBDError: If transport or response validation fails.
+        """
+        return await self._executor.fetch_one(
+            endpoint="/info",
+            request=_EMPTY_REQUEST,
+            response_adapter=_USER_INFO,
+        )
+
+    @overload
+    async def usage(self, request: InfoUsageRequest, /) -> UserUsage: ...
+
+    @overload
+    async def usage(
+        self,
+        request: None = None,
+        /,
+        *,
+        days: int | None = None,
+        limit: int | None = None,
+        api: _UserUsageApiArgument | None = None,
+    ) -> UserUsage: ...
+
+    async def usage(
+        self, request: InfoUsageRequest | None = None, /, **filters: object
+    ) -> UserUsage:
+        """Return recent shared-pool usage for the authenticated account.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Validated request totals, endpoint aggregates, and recent calls.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, or response validation fails.
+        """
+        endpoint = "/info/usage"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=InfoUsageRequest,
+            request=request,
+            filters=filters,
+        )
+        return await self._executor.fetch_one(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_USER_USAGE,
+        )
+
+
+__all__ = ["InfoResource"]

cfb_data/metrics/__init__.py

@@ -0,0 +1,53 @@
+"""Export the supported Metrics namespace and public contracts."""
+
+from cfb_data.enums import Classification, SeasonType
+
+from .models.pydantic import (
+    FieldGoalExpectedPoints,
+    PlayerGamePPAAverage,
+    PlayerGamePPARequest,
+    PlayerGamePredictedPointsAdded,
+    PlayerSeasonPPARequest,
+    PlayerSeasonPPASplit,
+    PlayerSeasonPredictedPointsAdded,
+    PlayWinProbability,
+    PredictedPointsRequest,
+    PredictedPointsValue,
+    PregameWinProbability,
+    PregameWinProbabilityRequest,
+    TeamGamePPARequest,
+    TeamGamePPAUnit,
+    TeamGamePredictedPointsAdded,
+    TeamPPACumulative,
+    TeamSeasonPPARequest,
+    TeamSeasonPPAUnit,
+    TeamSeasonPredictedPointsAdded,
+    WinProbabilityRequest,
+)
+from .resource import MetricsResource
+
+__all__ = [
+    "Classification",
+    "FieldGoalExpectedPoints",
+    "MetricsResource",
+    "PlayerGamePPAAverage",
+    "PlayerGamePPARequest",
+    "PlayerGamePredictedPointsAdded",
+    "PlayerSeasonPPARequest",
+    "PlayerSeasonPPASplit",
+    "PlayerSeasonPredictedPointsAdded",
+    "PlayWinProbability",
+    "PredictedPointsRequest",
+    "PredictedPointsValue",
+    "PregameWinProbability",
+    "PregameWinProbabilityRequest",
+    "SeasonType",
+    "TeamGamePPARequest",
+    "TeamGamePPAUnit",
+    "TeamGamePredictedPointsAdded",
+    "TeamPPACumulative",
+    "TeamSeasonPPARequest",
+    "TeamSeasonPPAUnit",
+    "TeamSeasonPredictedPointsAdded",
+    "WinProbabilityRequest",
+]

cfb_data/metrics/models/__init__.py

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

cfb_data/metrics/models/pydantic/__init__.py

@@ -0,0 +1,49 @@
+"""Export validated Metrics request and response models."""
+
+from .requests import (
+    PlayerGamePPARequest,
+    PlayerSeasonPPARequest,
+    PredictedPointsRequest,
+    PregameWinProbabilityRequest,
+    TeamGamePPARequest,
+    TeamSeasonPPARequest,
+    WinProbabilityRequest,
+)
+from .responses import (
+    FieldGoalExpectedPoints,
+    PlayerGamePPAAverage,
+    PlayerGamePredictedPointsAdded,
+    PlayerSeasonPPASplit,
+    PlayerSeasonPredictedPointsAdded,
+    PlayWinProbability,
+    PredictedPointsValue,
+    PregameWinProbability,
+    TeamGamePPAUnit,
+    TeamGamePredictedPointsAdded,
+    TeamPPACumulative,
+    TeamSeasonPPAUnit,
+    TeamSeasonPredictedPointsAdded,
+)
+
+__all__ = [
+    "FieldGoalExpectedPoints",
+    "PlayerGamePPAAverage",
+    "PlayerGamePPARequest",
+    "PlayerGamePredictedPointsAdded",
+    "PlayerSeasonPPARequest",
+    "PlayerSeasonPPASplit",
+    "PlayerSeasonPredictedPointsAdded",
+    "PlayWinProbability",
+    "PredictedPointsRequest",
+    "PredictedPointsValue",
+    "PregameWinProbability",
+    "PregameWinProbabilityRequest",
+    "TeamGamePPARequest",
+    "TeamGamePPAUnit",
+    "TeamGamePredictedPointsAdded",
+    "TeamPPACumulative",
+    "TeamSeasonPPARequest",
+    "TeamSeasonPPAUnit",
+    "TeamSeasonPredictedPointsAdded",
+    "WinProbabilityRequest",
+]

cfb_data/metrics/models/pydantic/requests.py

@@ -0,0 +1,121 @@
+"""Validate request parameters for implemented Metrics endpoints."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from cfb_data.enums import Classification, SeasonType
+
+
+class _MetricsRequest(BaseModel):
+    """Apply the closed-object contract shared by Metrics requests."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+def _require_year_or_team(year: int | None, team: str | None) -> None:
+    """Require a season or team selector."""
+    if year is None and team is None:
+        raise ValueError("year is required when team is not specified")
+
+
+class PredictedPointsRequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /ppa/predicted``."""
+
+    down: int = Field(ge=1, le=4)
+    distance: int = Field(ge=1, le=99)
+
+
+class TeamSeasonPPARequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /ppa/teams``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+    classification: Classification | None = None
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or team selector."""
+        _require_year_or_team(self.year, self.team)
+        return self
+
+
+class TeamGamePPARequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /ppa/games``."""
+
+    year: int = Field(ge=1869)
+    week: int | None = Field(default=None, ge=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    team: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+    classification: Classification | None = None
+
+
+class PlayerGamePPARequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /ppa/players/games``."""
+
+    year: int = Field(ge=1869)
+    week: int | None = Field(default=None, ge=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    team: str | None = Field(default=None, min_length=1)
+    position: str | None = Field(default=None, min_length=1)
+    player_id: int | None = Field(default=None, alias="playerId", gt=0)
+    threshold: int | None = Field(default=None, ge=0)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a week or team selector."""
+        if self.week is None and self.team is None:
+            raise ValueError("week is required when team is not specified")
+        return self
+
+
+class PlayerSeasonPPARequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /ppa/players/season``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    conference: str | None = Field(default=None, min_length=1)
+    team: str | None = Field(default=None, min_length=1)
+    position: str | None = Field(default=None, min_length=1)
+    player_id: int | None = Field(default=None, alias="playerId", gt=0)
+    threshold: int | None = Field(default=None, ge=0)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or player selector."""
+        if self.year is None and self.player_id is None:
+            raise ValueError("year is required when player_id is not specified")
+        return self
+
+
+class WinProbabilityRequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /metrics/wp``."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+
+
+class PregameWinProbabilityRequest(_MetricsRequest):
+    """Validate filters accepted by ``GET /metrics/wp/pregame``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    week: int | None = Field(default=None, ge=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    team: str | None = Field(default=None, min_length=1)
+
+
+__all__ = [
+    "PlayerGamePPARequest",
+    "PlayerSeasonPPARequest",
+    "PredictedPointsRequest",
+    "PregameWinProbabilityRequest",
+    "TeamGamePPARequest",
+    "TeamSeasonPPARequest",
+    "WinProbabilityRequest",
+]

cfb_data/metrics/models/pydantic/responses.py

@@ -0,0 +1,182 @@
+"""Validate responses from implemented CFBD Metrics endpoints."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cfb_data.enums import SeasonType
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Metrics responses."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class PredictedPointsValue(_ResponseModel):
+    """Represent expected points at one field position."""
+
+    yard_line: int = Field(alias="yardLine", ge=0, le=100)
+    predicted_points: float = Field(alias="predictedPoints")
+
+
+class TeamPPACumulative(_ResponseModel):
+    """Represent cumulative team predicted-points-added values."""
+
+    total: float
+    passing: float
+    rushing: float
+
+
+class TeamSeasonPPAUnit(_ResponseModel):
+    """Represent one side of a team's season PPA metrics."""
+
+    overall: float
+    passing: float
+    rushing: float
+    first_down: float = Field(alias="firstDown")
+    second_down: float = Field(alias="secondDown")
+    third_down: float = Field(alias="thirdDown")
+    cumulative: TeamPPACumulative
+
+
+class TeamSeasonPredictedPointsAdded(_ResponseModel):
+    """Represent team predicted-points-added metrics for a season."""
+
+    season: int = Field(ge=1869)
+    conference: str
+    team: str
+    offense: TeamSeasonPPAUnit
+    defense: TeamSeasonPPAUnit
+
+
+class TeamGamePPAUnit(_ResponseModel):
+    """Represent one side of a team's game PPA metrics."""
+
+    overall: float
+    passing: float
+    rushing: float
+    first_down: float = Field(alias="firstDown")
+    second_down: float = Field(alias="secondDown")
+    third_down: float = Field(alias="thirdDown")
+
+
+class TeamGamePredictedPointsAdded(_ResponseModel):
+    """Represent team predicted-points-added metrics for one game."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+    season: int = Field(ge=1869)
+    week: int = Field(ge=0)
+    season_type: SeasonType = Field(alias="seasonType")
+    team: str
+    conference: str
+    opponent: str
+    offense: TeamGamePPAUnit
+    defense: TeamGamePPAUnit
+
+
+class PlayerGamePPAAverage(_ResponseModel):
+    """Represent a player's per-play PPA averages for one game."""
+
+    all: float
+    passing: float | None = Field(default=None, alias="pass")
+    rush: float | None = None
+
+
+class PlayerGamePredictedPointsAdded(_ResponseModel):
+    """Represent player predicted-points-added metrics for one game."""
+
+    season: int = Field(ge=1869)
+    week: int = Field(ge=0)
+    season_type: SeasonType = Field(alias="seasonType")
+    id: str
+    name: str
+    position: str
+    team: str
+    opponent: str
+    average_ppa: PlayerGamePPAAverage = Field(alias="averagePPA")
+
+
+class PlayerSeasonPPASplit(_ResponseModel):
+    """Represent average or total player PPA split by play context."""
+
+    all: float
+    passing: float | None = Field(default=None, alias="pass")
+    rush: float | None = None
+    first_down: float | None = Field(default=None, alias="firstDown")
+    second_down: float | None = Field(default=None, alias="secondDown")
+    third_down: float | None = Field(default=None, alias="thirdDown")
+    standard_downs: float | None = Field(default=None, alias="standardDowns")
+    passing_downs: float | None = Field(default=None, alias="passingDowns")
+
+
+class PlayerSeasonPredictedPointsAdded(_ResponseModel):
+    """Represent player predicted-points-added metrics for a season."""
+
+    season: int = Field(ge=1869)
+    id: str
+    name: str
+    position: str
+    team: str
+    conference: str
+    average_ppa: PlayerSeasonPPASplit = Field(alias="averagePPA")
+    total_ppa: PlayerSeasonPPASplit = Field(alias="totalPPA")
+
+
+class PlayWinProbability(_ResponseModel):
+    """Represent the modeled home win probability after one play."""
+
+    game_id: int = Field(alias="gameId", gt=0)
+    play_id: str = Field(alias="playId")
+    play_text: str = Field(alias="playText")
+    home_id: int = Field(alias="homeId", gt=0)
+    home: str
+    away_id: int = Field(alias="awayId", gt=0)
+    away: str
+    spread: float
+    home_ball: bool = Field(alias="homeBall")
+    home_score: int = Field(alias="homeScore", ge=0)
+    away_score: int = Field(alias="awayScore", ge=0)
+    yard_line: int = Field(alias="yardLine", ge=0, le=100)
+    down: int = Field(ge=0, le=4)
+    distance: int = Field(ge=0)
+    home_win_probability: float = Field(alias="homeWinProbability", ge=0, le=1)
+    play_number: int = Field(alias="playNumber", ge=0)
+
+
+class PregameWinProbability(_ResponseModel):
+    """Represent one game's pregame home win probability."""
+
+    season: int = Field(ge=1869)
+    season_type: SeasonType = Field(alias="seasonType")
+    week: int = Field(ge=0)
+    game_id: int = Field(alias="gameId", gt=0)
+    home_team: str = Field(alias="homeTeam")
+    away_team: str = Field(alias="awayTeam")
+    spread: float
+    home_win_probability: float = Field(alias="homeWinProbability", ge=0, le=1)
+
+
+class FieldGoalExpectedPoints(_ResponseModel):
+    """Represent expected points for a field-goal distance."""
+
+    yards_to_goal: int = Field(alias="yardsToGoal", ge=0, le=100)
+    distance: int = Field(ge=0)
+    expected_points: float = Field(alias="expectedPoints")
+
+
+__all__ = [
+    "FieldGoalExpectedPoints",
+    "PlayerGamePPAAverage",
+    "PlayerGamePredictedPointsAdded",
+    "PlayerSeasonPPASplit",
+    "PlayerSeasonPredictedPointsAdded",
+    "PlayWinProbability",
+    "PredictedPointsValue",
+    "PregameWinProbability",
+    "TeamGamePPAUnit",
+    "TeamGamePredictedPointsAdded",
+    "TeamPPACumulative",
+    "TeamSeasonPPAUnit",
+    "TeamSeasonPredictedPointsAdded",
+]