cfb-data 0.4.1__py3-none-any.whl

cfb_data/adjusted_metrics/resource.py

@@ -0,0 +1,220 @@
+"""Expose typed Adjusted Metrics endpoints through the primary client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TypeVar, overload
+
+from pydantic import BaseModel, TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor
+from cfb_data._requests import _resolve_request
+from cfb_data.adjusted_metrics.models.pydantic.requests import (
+    AdjustedPlayerPassingRequest,
+    AdjustedPlayerRushingRequest,
+    AdjustedTeamMetricsRequest,
+    KickerPAARRequest,
+)
+from cfb_data.adjusted_metrics.models.pydantic.responses import (
+    AdjustedTeamMetrics,
+    KickerPAAR,
+    PlayerWeightedEPA,
+)
+
+_RequestT = TypeVar("_RequestT", bound=BaseModel)
+_RowT = TypeVar("_RowT", bound=BaseModel)
+
+_ADJUSTED_TEAM_ROWS = TypeAdapter(list[AdjustedTeamMetrics])
+_PLAYER_WEIGHTED_EPA_ROWS = TypeAdapter(list[PlayerWeightedEPA])
+_KICKER_PAAR_ROWS = TypeAdapter(list[KickerPAAR])
+
+
+class AdjustedMetricsResource[FrameT]:
+    """Provide validated opponent-adjusted metrics as selected frames."""
+
+    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 team_season(self, request: AdjustedTeamMetricsRequest, /) -> FrameT: ...
+
+    @overload
+    async def team_season(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def team_season(
+        self, request: AdjustedTeamMetricsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return opponent-adjusted team metrics by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated adjusted-team 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="/wepa/team/season",
+            request_type=AdjustedTeamMetricsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_ADJUSTED_TEAM_ROWS,
+            row_model=AdjustedTeamMetrics,
+        )
+
+    @overload
+    async def player_passing(
+        self, request: AdjustedPlayerPassingRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def player_passing(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+        position: str | None = None,
+    ) -> FrameT: ...
+
+    async def player_passing(
+        self,
+        request: AdjustedPlayerPassingRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return opponent-adjusted player passing EPA.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated player WEPA 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="/wepa/players/passing",
+            request_type=AdjustedPlayerPassingRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_PLAYER_WEIGHTED_EPA_ROWS,
+            row_model=PlayerWeightedEPA,
+        )
+
+    @overload
+    async def player_rushing(
+        self, request: AdjustedPlayerRushingRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def player_rushing(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+        position: str | None = None,
+    ) -> FrameT: ...
+
+    async def player_rushing(
+        self,
+        request: AdjustedPlayerRushingRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return opponent-adjusted player rushing EPA.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated player WEPA 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="/wepa/players/rushing",
+            request_type=AdjustedPlayerRushingRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_PLAYER_WEIGHTED_EPA_ROWS,
+            row_model=PlayerWeightedEPA,
+        )
+
+    @overload
+    async def kicker_paar(self, request: KickerPAARRequest, /) -> FrameT: ...
+
+    @overload
+    async def kicker_paar(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def kicker_paar(
+        self, request: KickerPAARRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return Points Added Above Replacement ratings for kickers.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated kicker PAAR 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="/wepa/players/kicking",
+            request_type=KickerPAARRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_KICKER_PAAR_ROWS,
+            row_model=KickerPAAR,
+        )
+
+    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:
+        """Resolve, validate, fetch, and tabularize one list endpoint."""
+        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__ = ["AdjustedMetricsResource"]

cfb_data/base/__init__.py

@@ -0,0 +1,6 @@
+"""Base module for College Football Data API package.
+
+This module contains shared components and base classes used throughout
+the CFB Data package, including API foundations, validation utilities,
+and common data transformation tools.
+"""

cfb_data/base/types.py

@@ -0,0 +1,112 @@
+"""Define and validate values crossing API serialization boundaries."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+type JSONScalar = str | int | float | bool | None
+type JSONValue = JSONScalar | list["JSONValue"] | dict[str, "JSONValue"]
+type JSONObject = dict[str, JSONValue]
+type JSONResponse = JSONObject | list[JSONObject]
+type QueryValue = str | int | float | bool
+type QueryParameters = dict[str, QueryValue]
+
+
+def json_value(value: object) -> JSONValue:
+    """Validate and return a recursively JSON-compatible value.
+
+    :param value: Untrusted value from a JSON decoder or serializer.
+    :return: A value containing only JSON-compatible primitives and containers.
+    :raises TypeError: If the value is not JSON-compatible or has non-string keys.
+    """
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    if isinstance(value, list):
+        return [json_value(item) for item in value]
+    if isinstance(value, dict):
+        result: JSONObject = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TypeError("JSON object keys must be strings")
+            result[key] = json_value(item)
+        return result
+    raise TypeError(f"Unsupported JSON value type: {type(value).__name__}")
+
+
+def json_response(value: object) -> JSONResponse:
+    """Validate and return the supported top-level API response shape.
+
+    :param value: Untrusted value returned by the HTTP JSON decoder.
+    :return: A JSON object or a list of JSON objects.
+    :raises TypeError: If the value is not a supported API response.
+    """
+    parsed = json_value(value)
+    if isinstance(parsed, dict):
+        return parsed
+    if isinstance(parsed, list):
+        objects: list[JSONObject] = []
+        for item in parsed:
+            if not isinstance(item, dict):
+                raise TypeError("API response lists must contain only JSON objects")
+            objects.append(item)
+        return objects
+    raise TypeError("API response must be a JSON object or a list of JSON objects")
+
+
+def json_object(value: object) -> JSONObject:
+    """Validate and return a JSON object.
+
+    :param value: Untrusted value expected to contain a JSON object.
+    :return: A recursively validated JSON object.
+    :raises TypeError: If the value is not a JSON object.
+    """
+    parsed = json_value(value)
+    if isinstance(parsed, dict):
+        return parsed
+    raise TypeError("Expected a JSON object")
+
+
+def json_object_list(value: object) -> list[JSONObject]:
+    """Validate and return a list of JSON objects.
+
+    :param value: Untrusted value expected to contain JSON objects.
+    :return: A recursively validated list of JSON objects.
+    :raises TypeError: If the value is not a list of JSON objects.
+    """
+    parsed = json_response(value)
+    if isinstance(parsed, list):
+        return parsed
+    raise TypeError("Expected a list of JSON objects")
+
+
+def json_list(value: object) -> list[JSONValue]:
+    """Validate and return a list of recursively JSON-compatible values.
+
+    :param value: Untrusted value expected to contain a JSON array.
+    :return: Recursively validated JSON values in their original order.
+    :raises TypeError: If the value is not a JSON array.
+    """
+    parsed = json_value(value)
+    if isinstance(parsed, list):
+        return parsed
+    raise TypeError("Expected a JSON array")
+
+
+def query_parameters(value: object) -> QueryParameters:
+    """Validate and return URL query parameters.
+
+    :param value: Serialized request-model data.
+    :return: Query parameters containing scalar URL values.
+    :raises TypeError: If a key or value cannot be represented in a query string.
+    """
+    if not isinstance(value, Mapping):
+        raise TypeError("Query parameters must be a mapping")
+
+    result: QueryParameters = {}
+    for key, item in value.items():
+        if not isinstance(key, str):
+            raise TypeError("Query parameter keys must be strings")
+        if not isinstance(item, str | int | float | bool):
+            raise TypeError(f"Unsupported query parameter type for {key!r}")
+        result[key] = item
+    return result

cfb_data/betting/__init__.py

@@ -0,0 +1,15 @@
+"""Export the supported Betting namespace and public contracts."""
+
+from cfb_data.enums import Classification, SeasonType
+
+from .models.pydantic import BettingGame, BettingLinesRequest, GameLine
+from .resource import BettingResource
+
+__all__ = [
+    "BettingGame",
+    "BettingLinesRequest",
+    "BettingResource",
+    "Classification",
+    "GameLine",
+    "SeasonType",
+]

cfb_data/betting/models/__init__.py

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

cfb_data/betting/models/pydantic/__init__.py

@@ -0,0 +1,6 @@
+"""Export validated Betting request and response models."""
+
+from .requests import BettingLinesRequest
+from .responses import BettingGame, GameLine
+
+__all__ = ["BettingGame", "BettingLinesRequest", "GameLine"]

cfb_data/betting/models/pydantic/requests.py

@@ -0,0 +1,35 @@
+"""Validate request parameters for implemented Betting endpoints."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from cfb_data._request_rules import _validate_year_or_game_id
+from cfb_data.enums import SeasonType
+
+
+class BettingLinesRequest(BaseModel):
+    """Validate filters accepted by ``GET /lines``."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    game_id: int | None = Field(default=None, alias="gameId", gt=0)
+    year: int | None = Field(default=None, ge=1869)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    week: int | None = Field(default=None, ge=0)
+    team: str | None = Field(default=None, min_length=1)
+    home: str | None = Field(default=None, min_length=1)
+    away: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+    provider: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or game identifier."""
+        _validate_year_or_game_id(self.year, self.game_id)
+        return self
+
+
+__all__ = ["BettingLinesRequest"]

cfb_data/betting/models/pydantic/responses.py

@@ -0,0 +1,62 @@
+"""Validate responses from implemented CFBD Betting endpoints."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cfb_data.enums import Classification, SeasonType
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Betting responses."""
+
+    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."""
+        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 GameLine(_ResponseModel):
+    """Represent one provider's line for a game."""
+
+    provider: str
+    spread: float | None
+    formatted_spread: str = Field(alias="formattedSpread")
+    spread_open: float | None = Field(alias="spreadOpen")
+    over_under: float | None = Field(alias="overUnder")
+    over_under_open: float | None = Field(alias="overUnderOpen")
+    home_moneyline: int | None = Field(alias="homeMoneyline")
+    away_moneyline: int | None = Field(alias="awayMoneyline")
+
+
+class BettingGame(_ResponseModel):
+    """Represent one game and all returned provider lines."""
+
+    id: int = Field(gt=0)
+    season: int = Field(ge=1869)
+    season_type: SeasonType = Field(alias="seasonType")
+    week: int = Field(ge=0)
+    start_date: datetime = Field(alias="startDate")
+    home_team_id: int = Field(alias="homeTeamId", gt=0)
+    home_team: str = Field(alias="homeTeam")
+    home_conference: str | None = Field(alias="homeConference")
+    home_classification: Classification | None = Field(alias="homeClassification")
+    home_score: int | None = Field(alias="homeScore", ge=0)
+    away_team_id: int = Field(alias="awayTeamId", gt=0)
+    away_team: str = Field(alias="awayTeam")
+    away_conference: str | None = Field(alias="awayConference")
+    away_classification: Classification | None = Field(alias="awayClassification")
+    away_score: int | None = Field(alias="awayScore", ge=0)
+    lines: list[GameLine]
+
+
+__all__ = ["BettingGame", "GameLine"]

cfb_data/betting/resource.py

@@ -0,0 +1,91 @@
+"""Expose typed Betting endpoints through the primary client."""
+
+from __future__ import annotations
+
+from typing import Literal, overload
+
+from pydantic import TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor
+from cfb_data._requests import _resolve_request
+from cfb_data.betting.models.pydantic.requests import BettingLinesRequest
+from cfb_data.betting.models.pydantic.responses import BettingGame
+from cfb_data.enums import SeasonType
+
+type _SeasonTypeArgument = (
+    SeasonType
+    | Literal[
+        "regular",
+        "postseason",
+        "both",
+        "allstar",
+        "spring_regular",
+        "spring_postseason",
+    ]
+)
+
+_BETTING_GAME_ROWS = TypeAdapter(list[BettingGame])
+
+
+class BettingResource[FrameT]:
+    """Provide validated Betting endpoints with selected 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 lines(self, request: BettingLinesRequest, /) -> FrameT: ...
+
+    @overload
+    async def lines(
+        self,
+        request: None = None,
+        /,
+        *,
+        game_id: int | None = None,
+        year: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        week: int | None = None,
+        team: str | None = None,
+        home: str | None = None,
+        away: str | None = None,
+        conference: str | None = None,
+        provider: str | None = None,
+    ) -> FrameT: ...
+
+    async def lines(
+        self, request: BettingLinesRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return games with nested historical provider lines.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated betting-game rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/lines"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=BettingLinesRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_BETTING_GAME_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=BettingGame, models=rows
+        )
+
+
+__all__ = ["BettingResource"]