cfb-data 0.4.1__py3-none-any.whl

cfb_data/recruiting/resource.py

@@ -0,0 +1,180 @@
+"""Expose typed Recruiting 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 RecruitClassification
+from cfb_data.recruiting.models.pydantic.requests import (
+    RecruitingGroupsRequest,
+    RecruitingPlayersRequest,
+    RecruitingTeamsRequest,
+)
+from cfb_data.recruiting.models.pydantic.responses import (
+    AggregatedTeamRecruiting,
+    Recruit,
+    TeamRecruitingRanking,
+)
+
+_RequestT = TypeVar("_RequestT", bound=BaseModel)
+_RowT = TypeVar("_RowT", bound=BaseModel)
+type _RecruitClassificationArgument = (
+    RecruitClassification | Literal["JUCO", "PrepSchool", "HighSchool"]
+)
+
+_RECRUIT_ROWS = TypeAdapter(list[Recruit])
+_TEAM_RANKING_ROWS = TypeAdapter(list[TeamRecruitingRanking])
+_GROUP_ROWS = TypeAdapter(list[AggregatedTeamRecruiting])
+
+
+class RecruitingResource[FrameT]:
+    """Provide validated Recruiting 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 players(self, request: RecruitingPlayersRequest, /) -> FrameT: ...
+
+    @overload
+    async def players(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        position: str | None = None,
+        state: str | None = None,
+        classification: _RecruitClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def players(
+        self, request: RecruitingPlayersRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return ranked recruiting prospects.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated recruit 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="/recruiting/players",
+            request_type=RecruitingPlayersRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_RECRUIT_ROWS,
+            row_model=Recruit,
+        )
+
+    @overload
+    async def teams(self, request: RecruitingTeamsRequest, /) -> FrameT: ...
+
+    @overload
+    async def teams(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+    ) -> FrameT: ...
+
+    async def teams(
+        self, request: RecruitingTeamsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team recruiting class rankings.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated team ranking 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="/recruiting/teams",
+            request_type=RecruitingTeamsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_TEAM_RANKING_ROWS,
+            row_model=TeamRecruitingRanking,
+        )
+
+    @overload
+    async def groups(self, request: RecruitingGroupsRequest, /) -> FrameT: ...
+
+    @overload
+    async def groups(
+        self,
+        request: None = None,
+        /,
+        *,
+        team: str | None = None,
+        conference: str | None = None,
+        recruit_type: _RecruitClassificationArgument | None = None,
+        start_year: int | None = None,
+        end_year: int | None = None,
+    ) -> FrameT: ...
+
+    async def groups(
+        self, request: RecruitingGroupsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return recruiting ratings aggregated by team and position group.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated recruiting aggregates.
+        :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="/recruiting/groups",
+            request_type=RecruitingGroupsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_GROUP_ROWS,
+            row_model=AggregatedTeamRecruiting,
+        )
+
+    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__ = ["RecruitingResource"]

cfb_data/retry.py

@@ -0,0 +1,49 @@
+"""Configure retry behavior for safe CFBD GET requests."""
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Configure bounded retries and backoff.
+
+    ``max_attempts`` counts the initial request. Set it to ``1`` to disable
+    retries.
+
+    :param max_attempts: Maximum total attempts for one endpoint call.
+    :param base_delay_seconds: Initial exponential-backoff ceiling.
+    :param max_backoff_seconds: Maximum client-selected backoff ceiling.
+    :param max_retry_after_seconds: Largest server delay the client will honor.
+    :raises ValueError: If an option is outside its valid range.
+    """
+
+    max_attempts: int = 3
+    base_delay_seconds: float = 0.5
+    max_backoff_seconds: float = 8.0
+    max_retry_after_seconds: float = 90.0
+
+    def __post_init__(self) -> None:
+        """Validate retry-policy invariants."""
+        if isinstance(self.max_attempts, bool) or not isinstance(
+            self.max_attempts, int
+        ):
+            raise ValueError("max_attempts must be an integer")
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be at least 1")
+        if not math.isfinite(self.base_delay_seconds) or self.base_delay_seconds < 0:
+            raise ValueError("base_delay_seconds must be finite and non-negative")
+        if not math.isfinite(self.max_backoff_seconds):
+            raise ValueError("max_backoff_seconds must be finite")
+        if self.max_backoff_seconds < self.base_delay_seconds:
+            raise ValueError(
+                "max_backoff_seconds cannot be less than base_delay_seconds"
+            )
+        if (
+            not math.isfinite(self.max_retry_after_seconds)
+            or self.max_retry_after_seconds < 0
+        ):
+            raise ValueError("max_retry_after_seconds must be finite and non-negative")
+
+
+__all__ = ["RetryPolicy"]

cfb_data/stats/__init__.py

@@ -0,0 +1,69 @@
+"""Export the supported Stats namespace and public contracts."""
+
+from cfb_data.enums import Classification, SeasonType
+
+from .models.pydantic import (
+    AdvancedGameDefense,
+    AdvancedGameOffense,
+    AdvancedGameStat,
+    AdvancedGameStatsRequest,
+    AdvancedSeasonDefense,
+    AdvancedSeasonOffense,
+    AdvancedSeasonStat,
+    AdvancedSeasonStatsRequest,
+    FieldPosition,
+    GameDownStats,
+    GameHavocRequest,
+    GameHavocStats,
+    GameHavocUnit,
+    GamePlayStats,
+    Havoc,
+    PlayerGameSuccessRate,
+    PlayerGameSuccessRequest,
+    PlayerSeasonStatsRequest,
+    PlayerSeasonSuccessRate,
+    PlayerSeasonSuccessRequest,
+    PlayerStat,
+    PlayerSuccessRateSplit,
+    SeasonDownStats,
+    SeasonPassingDownStats,
+    SeasonPlayStats,
+    StatCategory,
+    TeamSeasonStatsRequest,
+    TeamStat,
+)
+from .resource import StatsResource
+
+__all__ = [
+    "AdvancedGameDefense",
+    "AdvancedGameOffense",
+    "AdvancedGameStat",
+    "AdvancedGameStatsRequest",
+    "AdvancedSeasonDefense",
+    "AdvancedSeasonOffense",
+    "AdvancedSeasonStat",
+    "AdvancedSeasonStatsRequest",
+    "Classification",
+    "FieldPosition",
+    "GameDownStats",
+    "GameHavocRequest",
+    "GameHavocStats",
+    "GameHavocUnit",
+    "GamePlayStats",
+    "Havoc",
+    "PlayerGameSuccessRate",
+    "PlayerGameSuccessRequest",
+    "PlayerSeasonStatsRequest",
+    "PlayerSeasonSuccessRate",
+    "PlayerSeasonSuccessRequest",
+    "PlayerStat",
+    "PlayerSuccessRateSplit",
+    "SeasonDownStats",
+    "SeasonPassingDownStats",
+    "SeasonPlayStats",
+    "SeasonType",
+    "StatCategory",
+    "StatsResource",
+    "TeamSeasonStatsRequest",
+    "TeamStat",
+]

cfb_data/stats/models/__init__.py

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

cfb_data/stats/models/pydantic/__init__.py

@@ -0,0 +1,65 @@
+"""Export validated Stats request and response models."""
+
+from .requests import (
+    AdvancedGameStatsRequest,
+    AdvancedSeasonStatsRequest,
+    GameHavocRequest,
+    PlayerGameSuccessRequest,
+    PlayerSeasonStatsRequest,
+    PlayerSeasonSuccessRequest,
+    TeamSeasonStatsRequest,
+)
+from .responses import (
+    AdvancedGameDefense,
+    AdvancedGameOffense,
+    AdvancedGameStat,
+    AdvancedSeasonDefense,
+    AdvancedSeasonOffense,
+    AdvancedSeasonStat,
+    FieldPosition,
+    GameDownStats,
+    GameHavocStats,
+    GameHavocUnit,
+    GamePlayStats,
+    Havoc,
+    PlayerGameSuccessRate,
+    PlayerSeasonSuccessRate,
+    PlayerStat,
+    PlayerSuccessRateSplit,
+    SeasonDownStats,
+    SeasonPassingDownStats,
+    SeasonPlayStats,
+    StatCategory,
+    TeamStat,
+)
+
+__all__ = [
+    "AdvancedGameDefense",
+    "AdvancedGameOffense",
+    "AdvancedGameStat",
+    "AdvancedGameStatsRequest",
+    "AdvancedSeasonDefense",
+    "AdvancedSeasonOffense",
+    "AdvancedSeasonStat",
+    "AdvancedSeasonStatsRequest",
+    "FieldPosition",
+    "GameDownStats",
+    "GameHavocRequest",
+    "GameHavocStats",
+    "GameHavocUnit",
+    "GamePlayStats",
+    "Havoc",
+    "PlayerGameSuccessRate",
+    "PlayerGameSuccessRequest",
+    "PlayerSeasonStatsRequest",
+    "PlayerSeasonSuccessRate",
+    "PlayerSeasonSuccessRequest",
+    "PlayerStat",
+    "PlayerSuccessRateSplit",
+    "SeasonDownStats",
+    "SeasonPassingDownStats",
+    "SeasonPlayStats",
+    "StatCategory",
+    "TeamSeasonStatsRequest",
+    "TeamStat",
+]

cfb_data/stats/models/pydantic/requests.py

@@ -0,0 +1,167 @@
+"""Validate request parameters for implemented Stats 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 _StatsRequest(BaseModel):
+    """Apply the closed-object contract shared by Stats requests."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+def _validate_week_range(start_week: int | None, end_week: int | None) -> None:
+    """Reject a reversed inclusive week range."""
+    if start_week is not None and end_week is not None and start_week > end_week:
+        raise ValueError("start_week cannot be greater than end_week")
+
+
+def _validate_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 PlayerSeasonStatsRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/player/season``."""
+
+    year: int = Field(ge=1869)
+    conference: str | None = Field(default=None, min_length=1)
+    team: str | None = Field(default=None, min_length=1)
+    start_week: int | None = Field(default=None, alias="startWeek", ge=0)
+    end_week: int | None = Field(default=None, alias="endWeek", ge=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    category: str | None = Field(default=None, min_length=1)
+
+    @model_validator(mode="after")
+    def validate_week_range(self) -> Self:
+        """Reject a reversed week range."""
+        _validate_week_range(self.start_week, self.end_week)
+        return self
+
+
+class PlayerSeasonSuccessRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/player/success``."""
+
+    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)
+    player_id: int | None = Field(default=None, alias="playerId", gt=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    start_week: int | None = Field(default=None, alias="startWeek", ge=0)
+    end_week: int | None = Field(default=None, alias="endWeek", ge=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 and reject a reversed week range."""
+        if self.year is None and self.player_id is None:
+            raise ValueError("year is required when player_id is not specified")
+        _validate_week_range(self.start_week, self.end_week)
+        return self
+
+
+class PlayerGameSuccessRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/player/success/game``."""
+
+    year: int = Field(ge=1869)
+    week: int | None = Field(default=None, ge=0)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    conference: str | None = Field(default=None, min_length=1)
+    team: 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, team, or player selector."""
+        if self.week is None and self.team is None and self.player_id is None:
+            raise ValueError("At least one of week, team, or player_id is required")
+        return self
+
+
+class TeamSeasonStatsRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/season``."""
+
+    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)
+    start_week: int | None = Field(default=None, alias="startWeek", ge=0)
+    end_week: int | None = Field(default=None, alias="endWeek", ge=0)
+    classification: Classification | None = None
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or team and reject a reversed week range."""
+        _validate_year_or_team(self.year, self.team)
+        _validate_week_range(self.start_week, self.end_week)
+        return self
+
+
+class AdvancedSeasonStatsRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/season/advanced``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+    start_week: int | None = Field(default=None, alias="startWeek", ge=0)
+    end_week: int | None = Field(default=None, alias="endWeek", ge=0)
+    classification: Classification | None = None
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or team and reject a reversed week range."""
+        _validate_year_or_team(self.year, self.team)
+        _validate_week_range(self.start_week, self.end_week)
+        return self
+
+
+class AdvancedGameStatsRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/game/advanced``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    week: int | None = Field(default=None, ge=0)
+    opponent: str | None = Field(default=None, min_length=1)
+    exclude_garbage_time: bool | None = Field(default=None, alias="excludeGarbageTime")
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or team selector."""
+        _validate_year_or_team(self.year, self.team)
+        return self
+
+
+class GameHavocRequest(_StatsRequest):
+    """Validate filters accepted by ``GET /stats/game/havoc``."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    week: int | None = Field(default=None, ge=0)
+    opponent: str | None = Field(default=None, min_length=1)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+
+    @model_validator(mode="after")
+    def validate_selectors(self) -> Self:
+        """Require a season or team selector."""
+        _validate_year_or_team(self.year, self.team)
+        return self
+
+
+__all__ = [
+    "AdvancedGameStatsRequest",
+    "AdvancedSeasonStatsRequest",
+    "GameHavocRequest",
+    "PlayerGameSuccessRequest",
+    "PlayerSeasonStatsRequest",
+    "PlayerSeasonSuccessRequest",
+    "TeamSeasonStatsRequest",
+]