cfb-data 0.4.1__py3-none-any.whl

cfb_data/ratings/resource.py

@@ -0,0 +1,342 @@
+"""Expose typed Ratings endpoints through the primary client."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal, 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.enums import Classification, SeasonType
+from cfb_data.ratings.models.pydantic.requests import (
+    ConferenceSPRatingsRequest,
+    CoreRatingsRequest,
+    EloRatingsRequest,
+    ExpandedSRSRatingsRequest,
+    FPIRatingsRequest,
+    SPRatingsRequest,
+    SRSRatingsRequest,
+)
+from cfb_data.ratings.models.pydantic.responses import (
+    ConferenceSP,
+    ExpandedTeamSRS,
+    TeamCoreRating,
+    TeamElo,
+    TeamFPI,
+    TeamSP,
+    TeamSRS,
+)
+
+_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",
+    ]
+)
+
+_CORE_ROWS = TypeAdapter(list[TeamCoreRating])
+_SP_ROWS = TypeAdapter(list[TeamSP])
+_CONFERENCE_SP_ROWS = TypeAdapter(list[ConferenceSP])
+_SRS_ROWS = TypeAdapter(list[TeamSRS])
+_EXPANDED_SRS_ROWS = TypeAdapter(list[ExpandedTeamSRS])
+_ELO_ROWS = TypeAdapter(list[TeamElo])
+_FPI_ROWS = TypeAdapter(list[TeamFPI])
+
+
+class RatingsResource[FrameT]:
+    """Provide validated Ratings 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 core(self, request: CoreRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def core(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def core(
+        self, request: CoreRatingsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return Context and Opponent-Relative Efficiency ratings.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated CORE 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="/ratings/core",
+            request_type=CoreRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_CORE_ROWS,
+            row_model=TeamCoreRating,
+        )
+
+    @overload
+    async def sp(self, request: SPRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def sp(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+    ) -> FrameT: ...
+
+    async def sp(
+        self, request: SPRatingsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team SP+ ratings by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated team SP+ 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="/ratings/sp",
+            request_type=SPRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_SP_ROWS,
+            row_model=TeamSP,
+        )
+
+    @overload
+    async def conference_sp(self, request: ConferenceSPRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def conference_sp(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        conference: str | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def conference_sp(
+        self,
+        request: ConferenceSPRatingsRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return conference-level SP+ ratings by season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated conference SP+ 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="/ratings/sp/conferences",
+            request_type=ConferenceSPRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_CONFERENCE_SP_ROWS,
+            row_model=ConferenceSP,
+        )
+
+    @overload
+    async def srs(self, request: SRSRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def srs(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def srs(
+        self, request: SRSRatingsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return Simple Rating System ratings by team and season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated SRS 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="/ratings/srs",
+            request_type=SRSRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_SRS_ROWS,
+            row_model=TeamSRS,
+        )
+
+    @overload
+    async def expanded_srs(self, request: ExpandedSRSRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def expanded_srs(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def expanded_srs(
+        self,
+        request: ExpandedSRSRatingsRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return expanded SRS ratings including lower classifications.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated expanded SRS 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="/ratings/srs/expanded",
+            request_type=ExpandedSRSRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_EXPANDED_SRS_ROWS,
+            row_model=ExpandedTeamSRS,
+        )
+
+    @overload
+    async def elo(self, request: EloRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def elo(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        week: int | None = None,
+        season_type: _SeasonTypeArgument | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def elo(
+        self, request: EloRatingsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return historical Elo ratings for the selected period.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated Elo 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="/ratings/elo",
+            request_type=EloRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_ELO_ROWS,
+            row_model=TeamElo,
+        )
+
+    @overload
+    async def fpi(self, request: FPIRatingsRequest, /) -> FrameT: ...
+
+    @overload
+    async def fpi(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        conference: str | None = None,
+    ) -> FrameT: ...
+
+    async def fpi(
+        self, request: FPIRatingsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return Football Power Index ratings by team and season.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated FPI 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="/ratings/fpi",
+            request_type=FPIRatingsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_FPI_ROWS,
+            row_model=TeamFPI,
+        )
+
+    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__ = ["RatingsResource"]

cfb_data/recruiting/__init__.py

@@ -0,0 +1,26 @@
+"""Export the supported Recruiting namespace and public contracts."""
+
+from cfb_data.enums import RecruitClassification
+
+from .models.pydantic import (
+    AggregatedTeamRecruiting,
+    Recruit,
+    RecruitHometown,
+    RecruitingGroupsRequest,
+    RecruitingPlayersRequest,
+    RecruitingTeamsRequest,
+    TeamRecruitingRanking,
+)
+from .resource import RecruitingResource
+
+__all__ = [
+    "AggregatedTeamRecruiting",
+    "Recruit",
+    "RecruitClassification",
+    "RecruitHometown",
+    "RecruitingGroupsRequest",
+    "RecruitingPlayersRequest",
+    "RecruitingResource",
+    "RecruitingTeamsRequest",
+    "TeamRecruitingRanking",
+]

cfb_data/recruiting/models/__init__.py

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

cfb_data/recruiting/models/pydantic/__init__.py

@@ -0,0 +1,23 @@
+"""Export validated Recruiting request and response models."""
+
+from .requests import (
+    RecruitingGroupsRequest,
+    RecruitingPlayersRequest,
+    RecruitingTeamsRequest,
+)
+from .responses import (
+    AggregatedTeamRecruiting,
+    Recruit,
+    RecruitHometown,
+    TeamRecruitingRanking,
+)
+
+__all__ = [
+    "AggregatedTeamRecruiting",
+    "Recruit",
+    "RecruitHometown",
+    "RecruitingGroupsRequest",
+    "RecruitingPlayersRequest",
+    "RecruitingTeamsRequest",
+    "TeamRecruitingRanking",
+]

cfb_data/recruiting/models/pydantic/requests.py

@@ -0,0 +1,69 @@
+"""Validate request parameters for implemented Recruiting endpoints."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from cfb_data.enums import RecruitClassification
+
+
+class _RecruitingRequest(BaseModel):
+    """Apply the closed-object contract shared by Recruiting requests."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class RecruitingPlayersRequest(_RecruitingRequest):
+    """Validate filters accepted by ``GET /recruiting/players``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    position: str | None = Field(default=None, min_length=1)
+    state: str | None = Field(default=None, min_length=1)
+    classification: RecruitClassification | None = None
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a recruiting year or committed team."""
+        if self.year is None and self.team is None:
+            raise ValueError("year is required when team is not specified")
+        return self
+
+
+class RecruitingTeamsRequest(_RecruitingRequest):
+    """Validate filters accepted by ``GET /recruiting/teams``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+
+
+class RecruitingGroupsRequest(_RecruitingRequest):
+    """Validate filters accepted by ``GET /recruiting/groups``."""
+
+    team: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+    recruit_type: RecruitClassification | None = Field(
+        default=None, alias="recruitType"
+    )
+    start_year: int | None = Field(default=None, alias="startYear", ge=1869)
+    end_year: int | None = Field(default=None, alias="endYear", ge=1869)
+
+    @model_validator(mode="after")
+    def validate_year_range(self) -> Self:
+        """Require the recruiting year range to be ascending."""
+        if (
+            self.start_year is not None
+            and self.end_year is not None
+            and self.start_year > self.end_year
+        ):
+            raise ValueError("start_year must be less than or equal to end_year")
+        return self
+
+
+__all__ = [
+    "RecruitingGroupsRequest",
+    "RecruitingPlayersRequest",
+    "RecruitingTeamsRequest",
+]

cfb_data/recruiting/models/pydantic/responses.py

@@ -0,0 +1,70 @@
+"""Validate responses from implemented CFBD Recruiting endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cfb_data.enums import RecruitClassification
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Recruiting responses."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class RecruitHometown(_ResponseModel):
+    """Represent normalized geographic details for a recruit's hometown."""
+
+    latitude: float | None
+    longitude: float | None
+    fips_code: str | None = Field(alias="fipsCode")
+
+
+class Recruit(_ResponseModel):
+    """Represent one ranked recruiting prospect."""
+
+    id: str
+    athlete_id: str | None = Field(alias="athleteId")
+    recruit_type: RecruitClassification = Field(alias="recruitType")
+    year: int = Field(ge=1869)
+    ranking: int | None = Field(ge=1)
+    name: str
+    school: str | None
+    committed_to: str | None = Field(alias="committedTo")
+    position: str | None
+    height: float | None = Field(ge=0)
+    weight: int | None = Field(ge=0)
+    stars: int | None = Field(ge=0, le=5)
+    rating: float | None = Field(ge=0)
+    city: str | None
+    state_province: str | None = Field(alias="stateProvince")
+    country: str | None
+    hometown_info: RecruitHometown = Field(alias="hometownInfo")
+
+
+class TeamRecruitingRanking(_ResponseModel):
+    """Represent one team's recruiting class ranking."""
+
+    year: int = Field(ge=1869)
+    rank: int = Field(ge=1)
+    team: str
+    points: float
+
+
+class AggregatedTeamRecruiting(_ResponseModel):
+    """Represent recruiting quality aggregated by team and position group."""
+
+    team: str
+    conference: str
+    position_group: str | None = Field(alias="positionGroup")
+    average_rating: float = Field(alias="averageRating")
+    total_rating: float = Field(alias="totalRating")
+    commits: int = Field(ge=0)
+    average_stars: float = Field(alias="averageStars", ge=0, le=5)
+
+
+__all__ = [
+    "AggregatedTeamRecruiting",
+    "Recruit",
+    "RecruitHometown",
+    "TeamRecruitingRanking",
+]