cfb-data 0.4.1__py3-none-any.whl

cfb_data/coaches/models/pydantic/responses.py

@@ -0,0 +1,261 @@
+"""Validate responses from implemented CFBD Coaches endpoints."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Coaches 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 CoachSeason(_ResponseModel):
+    """Represent one season in the historical coach summary route."""
+
+    team_id: int = Field(alias="teamId", gt=0)
+    school: str
+    conference: str | None
+    year: int = Field(ge=1869)
+    games: int = Field(ge=0)
+    wins: int = Field(ge=0)
+    losses: int = Field(ge=0)
+    ties: int = Field(ge=0)
+    win_percentage: float | None = Field(alias="winPercentage", ge=0, le=1)
+    preseason_rank: int | None = Field(alias="preseasonRank", ge=1)
+    postseason_rank: int | None = Field(alias="postseasonRank", ge=1)
+    srs: float | None
+    sp_overall: float | None = Field(alias="spOverall")
+    sp_offense: float | None = Field(alias="spOffense")
+    sp_defense: float | None = Field(alias="spDefense")
+
+
+class Coach(_ResponseModel):
+    """Represent one historical head coach and selected seasons."""
+
+    id: int = Field(gt=0)
+    first_name: str = Field(alias="firstName")
+    last_name: str = Field(alias="lastName")
+    hire_date: datetime | None = Field(alias="hireDate")
+    seasons: list[CoachSeason]
+
+
+class CoachRecord(_ResponseModel):
+    """Represent an attributed coaching win-loss record."""
+
+    games: int = Field(ge=0)
+    wins: int = Field(ge=0)
+    losses: int = Field(ge=0)
+    ties: int = Field(ge=0)
+    win_percentage: float | None = Field(alias="winPercentage", ge=0, le=1)
+
+
+class CoachReference(_ResponseModel):
+    """Represent the canonical identity of a coach."""
+
+    id: int = Field(gt=0)
+    first_name: str = Field(alias="firstName")
+    last_name: str = Field(alias="lastName")
+
+
+class CoachTeamReference(_ResponseModel):
+    """Represent a team associated with a coach."""
+
+    id: int = Field(gt=0)
+    school: str
+
+
+class CoachSeasonTeamReference(CoachTeamReference):
+    """Represent a team and conference within one coaching season."""
+
+    conference: str | None
+
+
+class CoachCareer(CoachRecord):
+    """Represent career totals in a coach profile."""
+
+    seasons: int = Field(ge=0)
+    teams: int = Field(ge=0)
+    first_year: int = Field(alias="firstYear", ge=1869)
+    last_year: int = Field(alias="lastYear", ge=1869)
+
+
+class CoachAlmaMater(_ResponseModel):
+    """Represent a coach's alma mater."""
+
+    id: int = Field(gt=0)
+    school: str
+
+
+class CoachProfile(_ResponseModel):
+    """Represent canonical identity and career totals for one coach."""
+
+    id: int = Field(gt=0)
+    first_name: str = Field(alias="firstName")
+    last_name: str = Field(alias="lastName")
+    display_name: str | None = Field(alias="displayName")
+    current_team: CoachSeasonTeamReference | None = Field(alias="currentTeam")
+    career: CoachCareer
+    birth_date: str | None = Field(alias="birthDate")
+    alma_mater: CoachAlmaMater | None = Field(alias="almaMater")
+    graduation_year: int | None = Field(alias="graduationYear", ge=1869)
+    wikidata_id: str | None = Field(alias="wikidataId")
+    hall_of_fame_year: int | None = Field(alias="hallOfFameYear", ge=1869)
+
+
+class CoachTenure(_ResponseModel):
+    """Represent one continuous head-coaching tenure."""
+
+    id: int = Field(gt=0)
+    coach: CoachReference
+    team: CoachTeamReference
+    hire_date: str | None = Field(alias="hireDate")
+    start_year: int = Field(alias="startYear", ge=1869)
+    end_year: int | None = Field(alias="endYear", ge=1869)
+    effective_start: datetime | None = Field(alias="effectiveStart")
+    effective_end: datetime | None = Field(alias="effectiveEnd")
+    is_interim: bool = Field(alias="isInterim")
+    active: bool
+    seasons: int = Field(ge=0)
+    record: CoachRecord
+    attribution_complete: bool = Field(alias="attributionComplete")
+
+
+class CoachYearOverYear(_ResponseModel):
+    """Represent change from the preceding team season."""
+
+    wins: int | None
+    srs: float | None
+    sp_overall: float | None = Field(alias="spOverall")
+
+
+class CoachRatingContext(_ResponseModel):
+    """Represent team rating context for a coaching season."""
+
+    sp_special_teams: float | None = Field(alias="spSpecialTeams")
+    strength_of_schedule: float | None = Field(alias="strengthOfSchedule")
+    second_order_wins: float | None = Field(alias="secondOrderWins")
+    fpi: float | None
+    year_over_year: CoachYearOverYear = Field(alias="yearOverYear")
+
+
+class CoachRecruitingContext(_ResponseModel):
+    """Represent recruiting context for a coaching season."""
+
+    rank: int | None = Field(ge=1)
+    points: float | None
+    talent: float | None
+
+
+class CoachPollResume(_ResponseModel):
+    """Represent poll résumé totals for a coaching season."""
+
+    preseason_rank: int | None = Field(alias="preseasonRank", ge=1)
+    postseason_rank: int | None = Field(alias="postseasonRank", ge=1)
+    best_rank: int | None = Field(alias="bestRank", ge=1)
+    weeks_ranked: int = Field(alias="weeksRanked", ge=0)
+    weeks_top_ten: int = Field(alias="weeksTopTen", ge=0)
+
+
+class CoachRecordSplits(_ResponseModel):
+    """Represent coaching records split by game context."""
+
+    conference: CoachRecord
+    postseason: CoachRecord
+    home: CoachRecord
+    away: CoachRecord
+    neutral: CoachRecord
+
+
+class CoachScoring(_ResponseModel):
+    """Represent aggregate scoring under a coach for one season."""
+
+    points_for: int = Field(alias="pointsFor", ge=0)
+    points_against: int = Field(alias="pointsAgainst", ge=0)
+    average_point_differential: float | None = Field(alias="averagePointDifferential")
+
+
+class CoachCfpOutcome(StrEnum):
+    """Identify a coach's College Football Playoff season outcome."""
+
+    active = "active"
+    eliminated = "eliminated"
+    champion = "champion"
+
+
+class CoachCfpContext(_ResponseModel):
+    """Represent College Football Playoff context for a coaching season."""
+
+    appeared: bool
+    seed: int | None = Field(ge=1)
+    outcome: CoachCfpOutcome | None
+
+
+class CoachDraftContext(_ResponseModel):
+    """Represent draft outcomes following a coaching season."""
+
+    year: int = Field(ge=1936)
+    total_picks: int = Field(alias="totalPicks", ge=0)
+    first_round_picks: int = Field(alias="firstRoundPicks", ge=0)
+
+
+class DetailedCoachSeason(CoachRecord):
+    """Represent one coach-season with results and team context."""
+
+    coach: CoachReference
+    team: CoachSeasonTeamReference
+    year: int = Field(ge=1869)
+    preseason_rank: int | None = Field(alias="preseasonRank", ge=1)
+    postseason_rank: int | None = Field(alias="postseasonRank", ge=1)
+    srs: float | None
+    sp_overall: float | None = Field(alias="spOverall")
+    sp_offense: float | None = Field(alias="spOffense")
+    sp_defense: float | None = Field(alias="spDefense")
+    team_metrics: CoachRatingContext = Field(alias="teamMetrics")
+    recruiting: CoachRecruitingContext
+    poll_resume: CoachPollResume | None = Field(alias="pollResume")
+    attribution_complete: bool = Field(alias="attributionComplete")
+    record_splits: CoachRecordSplits | None = Field(alias="recordSplits")
+    scoring: CoachScoring | None
+    cfp: CoachCfpContext
+    draft_following_season: CoachDraftContext | None = Field(
+        alias="draftFollowingSeason"
+    )
+
+
+__all__ = [
+    "Coach",
+    "CoachAlmaMater",
+    "CoachCareer",
+    "CoachCfpContext",
+    "CoachCfpOutcome",
+    "CoachDraftContext",
+    "CoachPollResume",
+    "CoachProfile",
+    "CoachRatingContext",
+    "CoachRecord",
+    "CoachRecordSplits",
+    "CoachRecruitingContext",
+    "CoachReference",
+    "CoachScoring",
+    "CoachSeason",
+    "CoachSeasonTeamReference",
+    "CoachTeamReference",
+    "CoachTenure",
+    "CoachYearOverYear",
+    "DetailedCoachSeason",
+]

cfb_data/coaches/resource.py

@@ -0,0 +1,216 @@
+"""Expose typed Coaches endpoints through the primary client."""
+
+from __future__ import annotations
+
+import builtins
+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.coaches.models.pydantic.requests import (
+    CoachesRequest,
+    CoachProfileRequest,
+    CoachSeasonsRequest,
+    CoachTenuresRequest,
+)
+from cfb_data.coaches.models.pydantic.responses import (
+    Coach,
+    CoachProfile,
+    CoachTenure,
+    DetailedCoachSeason,
+)
+
+_RequestT = TypeVar("_RequestT", bound=BaseModel)
+_RowT = TypeVar("_RowT", bound=BaseModel)
+
+_COACH_ROWS = TypeAdapter(list[Coach])
+_COACH_PROFILE = TypeAdapter(CoachProfile)
+_COACH_SEASON_ROWS = TypeAdapter(list[DetailedCoachSeason])
+_COACH_TENURE_ROWS = TypeAdapter(list[CoachTenure])
+
+
+class CoachesResource[FrameT]:
+    """Provide validated Coaches 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 list(self, request: CoachesRequest, /) -> FrameT: ...
+
+    @overload
+    async def list(
+        self,
+        request: None = None,
+        /,
+        *,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        team: str | None = None,
+        year: int | None = None,
+        min_year: int | None = None,
+        max_year: int | None = None,
+    ) -> FrameT: ...
+
+    async def list(
+        self, request: CoachesRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return historical head coaches with nested season summaries.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated coach 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="/coaches",
+            request_type=CoachesRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_COACH_ROWS,
+            row_model=Coach,
+        )
+
+    @overload
+    async def profile(self, request: CoachProfileRequest, /) -> FrameT: ...
+
+    @overload
+    async def profile(self, request: None = None, /, *, coach_id: int) -> FrameT: ...
+
+    async def profile(
+        self, request: CoachProfileRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return one canonical coach profile as a one-row frame.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: One-row eager frame containing the validated coach profile.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/coaches/profile"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=CoachProfileRequest,
+            request=request,
+            filters=filters,
+        )
+        profile = await self._executor.fetch_one(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_COACH_PROFILE,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=CoachProfile, models=[profile]
+        )
+
+    @overload
+    async def seasons(self, request: CoachSeasonsRequest, /) -> FrameT: ...
+
+    @overload
+    async def seasons(
+        self,
+        request: None = None,
+        /,
+        *,
+        coach_id: int | None = None,
+        team: str | None = None,
+        year: int | None = None,
+        min_year: int | None = None,
+        max_year: int | None = None,
+    ) -> FrameT: ...
+
+    async def seasons(
+        self, request: CoachSeasonsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return coach-season records with attributed results and context.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated detailed coach seasons.
+        :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="/coaches/seasons",
+            request_type=CoachSeasonsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_COACH_SEASON_ROWS,
+            row_model=DetailedCoachSeason,
+        )
+
+    @overload
+    async def tenures(self, request: CoachTenuresRequest, /) -> FrameT: ...
+
+    @overload
+    async def tenures(
+        self,
+        request: None = None,
+        /,
+        *,
+        coach_id: int | None = None,
+        team: str | None = None,
+        year: int | None = None,
+        active: bool | None = None,
+    ) -> FrameT: ...
+
+    async def tenures(
+        self, request: CoachTenuresRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return continuous head-coaching tenures and attributed records.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated coaching tenure 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="/coaches/tenures",
+            request_type=CoachTenuresRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_COACH_TENURE_ROWS,
+            row_model=CoachTenure,
+        )
+
+    async def _fetch_many(
+        self,
+        *,
+        endpoint: str,
+        request_type: type[_RequestT],
+        request: _RequestT | None,
+        filters: Mapping[str, object],
+        response_adapter: TypeAdapter[builtins.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: builtins.list[_RowT] = 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__ = ["CoachesResource"]

cfb_data/conferences/__init__.py

@@ -0,0 +1,23 @@
+"""Export the supported Conferences namespace and public contracts."""
+
+from .models.pydantic import (
+    Conference,
+    ConferenceAffiliationsRequest,
+    ConferenceChangesRequest,
+    ConferenceClassification,
+    ConferencesRequest,
+    TeamConferenceAffiliation,
+    TeamConferenceChange,
+)
+from .resource import ConferencesResource
+
+__all__ = [
+    "Conference",
+    "ConferenceAffiliationsRequest",
+    "ConferenceChangesRequest",
+    "ConferenceClassification",
+    "ConferencesRequest",
+    "ConferencesResource",
+    "TeamConferenceAffiliation",
+    "TeamConferenceChange",
+]

cfb_data/conferences/models/__init__.py

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

cfb_data/conferences/models/pydantic/__init__.py

@@ -0,0 +1,23 @@
+"""Export Pydantic models for Conferences endpoints."""
+
+from .requests import (
+    ConferenceAffiliationsRequest,
+    ConferenceChangesRequest,
+    ConferencesRequest,
+)
+from .responses import (
+    Conference,
+    ConferenceClassification,
+    TeamConferenceAffiliation,
+    TeamConferenceChange,
+)
+
+__all__ = [
+    "Conference",
+    "ConferenceAffiliationsRequest",
+    "ConferenceChangesRequest",
+    "ConferenceClassification",
+    "ConferencesRequest",
+    "TeamConferenceAffiliation",
+    "TeamConferenceChange",
+]

cfb_data/conferences/models/pydantic/requests.py

@@ -0,0 +1,69 @@
+"""Validate request parameters for implemented Conferences endpoints."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .responses import ConferenceClassification
+
+
+class ConferencesRequest(BaseModel):
+    """Validate filters accepted by ``GET /conferences``.
+
+    :param year: Season used to calculate membership.
+    :param classification: Conference division classification.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int | None = Field(default=None, ge=1869)
+    classification: ConferenceClassification | None = None
+
+
+class ConferenceChangesRequest(BaseModel):
+    """Validate filters accepted by ``GET /conferences/changes``.
+
+    :param year: Season whose effective conference changes are returned.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int = Field(ge=1869)
+
+
+class ConferenceAffiliationsRequest(BaseModel):
+    """Validate filters accepted by ``GET /conferences/affiliations``.
+
+    :param team: Team school name or abbreviation.
+    :param conference: Conference name or abbreviation.
+    :param year: Exact active-affiliation season.
+    :param min_year: Earliest overlapping affiliation season.
+    :param max_year: Latest overlapping affiliation season.
+    :param classification: Conference division classification.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    team: str | None = None
+    conference: str | None = None
+    year: int | None = Field(default=None, ge=1869)
+    min_year: int | None = Field(default=None, ge=1869, alias="minYear")
+    max_year: int | None = Field(default=None, ge=1869, alias="maxYear")
+    classification: ConferenceClassification | None = None
+
+    @model_validator(mode="after")
+    def validate_year_filters(self) -> Self:
+        """Reject mutually exclusive and reversed season filters."""
+        if self.year is not None and (
+            self.min_year is not None or self.max_year is not None
+        ):
+            raise ValueError("year cannot be combined with min_year or max_year")
+        if (
+            self.min_year is not None
+            and self.max_year is not None
+            and self.min_year > self.max_year
+        ):
+            raise ValueError("min_year cannot be greater than max_year")
+        return self

cfb_data/conferences/models/pydantic/responses.py

@@ -0,0 +1,64 @@
+"""Validate responses from implemented CFBD Conferences endpoints."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ConferenceClassification(StrEnum):
+    """Identify an official conference division classification."""
+
+    fbs = "fbs"
+    fcs = "fcs"
+    ii = "ii"
+    ii_or_iii = "ii/iii"
+    iii = "iii"
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to response models."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class Conference(_ResponseModel):
+    """Represent a conference and its membership count."""
+
+    id: int = Field(gt=0)
+    name: str
+    short_name: str | None = Field(alias="shortName")
+    abbreviation: str | None
+    classification: ConferenceClassification | None
+    member_count: int = Field(alias="memberCount", ge=0)
+
+
+class TeamConferenceAffiliation(_ResponseModel):
+    """Represent one historical team-to-conference affiliation."""
+
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    conference_id: int = Field(alias="conferenceId", gt=0)
+    conference: str
+    conference_abbreviation: str | None = Field(alias="conferenceAbbreviation")
+    classification: ConferenceClassification | None
+    conference_division: str | None = Field(alias="conferenceDivision")
+    start_year: int = Field(alias="startYear", ge=1869)
+    end_year: int | None = Field(alias="endYear", ge=1869)
+
+
+class TeamConferenceChange(_ResponseModel):
+    """Represent one team's conference change for a season."""
+
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    from_conference_id: int = Field(alias="fromConferenceId", gt=0)
+    from_conference: str = Field(alias="fromConference")
+    from_conference_abbreviation: str | None = Field(alias="fromConferenceAbbreviation")
+    from_classification: ConferenceClassification | None = Field(
+        alias="fromClassification"
+    )
+    to_conference_id: int = Field(alias="toConferenceId", gt=0)
+    to_conference: str = Field(alias="toConference")
+    to_conference_abbreviation: str | None = Field(alias="toConferenceAbbreviation")
+    to_classification: ConferenceClassification | None = Field(alias="toClassification")
+    effective_year: int = Field(alias="effectiveYear", ge=1869)