cfb-data 0.4.1__py3-none-any.whl

cfb_data/teams/__init__.py

@@ -0,0 +1,40 @@
+"""Export the supported Teams namespace and public contracts."""
+
+from cfb_data.conferences import ConferenceClassification
+from cfb_data.enums import Classification
+from cfb_data.venues import Venue
+
+from .models.pydantic import (
+    FBSTeamsRequest,
+    Matchup,
+    MatchupGame,
+    RosterPlayer,
+    RosterRequest,
+    TalentRequest,
+    Team,
+    TeamATS,
+    TeamATSRequest,
+    TeamMatchupRequest,
+    TeamsRequest,
+    TeamTalent,
+)
+from .resource import TeamsResource
+
+__all__ = [
+    "Classification",
+    "ConferenceClassification",
+    "FBSTeamsRequest",
+    "Matchup",
+    "MatchupGame",
+    "RosterPlayer",
+    "RosterRequest",
+    "TalentRequest",
+    "Team",
+    "TeamATS",
+    "TeamATSRequest",
+    "TeamMatchupRequest",
+    "TeamsRequest",
+    "TeamsResource",
+    "TeamTalent",
+    "Venue",
+]

cfb_data/teams/models/__init__.py

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

cfb_data/teams/models/pydantic/__init__.py

@@ -0,0 +1,26 @@
+"""Export Pydantic models for Teams endpoints."""
+
+from .requests import (
+    FBSTeamsRequest,
+    RosterRequest,
+    TalentRequest,
+    TeamATSRequest,
+    TeamMatchupRequest,
+    TeamsRequest,
+)
+from .responses import Matchup, MatchupGame, RosterPlayer, Team, TeamATS, TeamTalent
+
+__all__ = [
+    "FBSTeamsRequest",
+    "Matchup",
+    "MatchupGame",
+    "RosterPlayer",
+    "RosterRequest",
+    "TalentRequest",
+    "Team",
+    "TeamATS",
+    "TeamATSRequest",
+    "TeamMatchupRequest",
+    "TeamsRequest",
+    "TeamTalent",
+]

cfb_data/teams/models/pydantic/requests.py

@@ -0,0 +1,96 @@
+"""Validate request parameters for implemented Teams endpoints."""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from cfb_data.enums import Classification
+
+
+class TeamsRequest(BaseModel):
+    """Validate filters accepted by ``GET /teams``.
+
+    :param conference: Conference abbreviation.
+    :param year: Season used for historical affiliation membership.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    conference: str | None = None
+    year: int | None = Field(default=None, ge=1869)
+
+
+class FBSTeamsRequest(BaseModel):
+    """Validate filters accepted by ``GET /teams/fbs``.
+
+    :param year: Season used for historical FBS membership.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    year: int | None = Field(default=None, ge=1869)
+
+
+class TeamMatchupRequest(BaseModel):
+    """Validate filters accepted by ``GET /teams/matchup``.
+
+    :param team1: First team name.
+    :param team2: Second team name.
+    :param min_year: Earliest season to include.
+    :param max_year: Latest season to include.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    team1: str = Field(min_length=1)
+    team2: str = Field(min_length=1)
+    min_year: int | None = Field(default=None, ge=1869, alias="minYear")
+    max_year: int | None = Field(default=None, ge=1869, alias="maxYear")
+
+    @model_validator(mode="after")
+    def validate_year_range(self) -> Self:
+        """Reject a reversed matchup season range."""
+        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
+
+
+class TeamATSRequest(BaseModel):
+    """Validate filters accepted by ``GET /teams/ats``.
+
+    :param year: Required season year.
+    :param conference: Conference name or abbreviation.
+    :param team: Team name.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    year: int = Field(ge=1869)
+    conference: str | None = None
+    team: str | None = None
+
+
+class RosterRequest(BaseModel):
+    """Validate filters accepted by ``GET /roster``.
+
+    :param team: Team name.
+    :param year: Roster season, or ``None`` to retain the upstream default.
+    :param classification: Division classification selector.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    team: str | None = None
+    year: int | None = Field(default=None, ge=1869)
+    classification: Classification | None = None
+
+
+class TalentRequest(BaseModel):
+    """Validate filters accepted by ``GET /talent``.
+
+    :param year: Required talent-composite season.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    year: int = Field(ge=1869)

cfb_data/teams/models/pydantic/responses.py

@@ -0,0 +1,116 @@
+"""Validate responses from implemented CFBD Teams endpoints."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cfb_data.conferences.models.pydantic.responses import ConferenceClassification
+from cfb_data.venues.models.pydantic.responses import Venue
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to response models."""
+
+    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 Team(_ResponseModel):
+    """Represent one team and its current or historical affiliation."""
+
+    id: int = Field(gt=0)
+    school: str
+    mascot: str | None
+    abbreviation: str | None
+    alternate_names: list[str] | None = Field(alias="alternateNames")
+    conference: str | None
+    division: str | None
+    classification: ConferenceClassification | None
+    color: str | None
+    alternate_color: str | None = Field(alias="alternateColor")
+    logos: list[str] | None
+    twitter: str | None
+    location: Venue | None
+
+
+class MatchupGame(_ResponseModel):
+    """Represent one completed game in a historical matchup."""
+
+    season: int = Field(ge=1869)
+    week: int = Field(ge=0)
+    season_type: str = Field(alias="seasonType")
+    date: datetime
+    neutral_site: bool = Field(alias="neutralSite")
+    venue: str | None
+    home_team: str = Field(alias="homeTeam")
+    home_score: int | None = Field(alias="homeScore", ge=0)
+    away_team: str = Field(alias="awayTeam")
+    away_score: int | None = Field(alias="awayScore", ge=0)
+    winner: str | None
+
+
+class Matchup(_ResponseModel):
+    """Represent a matchup summary and its nested completed games."""
+
+    team1: str
+    team2: str
+    start_year: int | None = Field(default=None, alias="startYear", ge=1869)
+    end_year: int | None = Field(default=None, alias="endYear", ge=1869)
+    team1_wins: int = Field(alias="team1Wins", ge=0)
+    team2_wins: int = Field(alias="team2Wins", ge=0)
+    ties: int = Field(ge=0)
+    games: list[MatchupGame]
+
+
+class RosterPlayer(_ResponseModel):
+    """Represent one player on a historical team roster."""
+
+    id: str
+    first_name: str = Field(alias="firstName")
+    last_name: str = Field(alias="lastName")
+    team: str
+    height: float | None
+    weight: int | None = Field(ge=0)
+    jersey: int | None = Field(ge=0)
+    year: int = Field(ge=0)
+    position: str | None
+    home_city: str | None = Field(alias="homeCity")
+    home_state: str | None = Field(alias="homeState")
+    home_country: str | None = Field(alias="homeCountry")
+    home_latitude: float | None = Field(alias="homeLatitude")
+    home_longitude: float | None = Field(alias="homeLongitude")
+    home_county_fips: str | None = Field(alias="homeCountyFIPS")
+    recruit_ids: list[str] | None = Field(alias="recruitIds")
+
+
+class TeamTalent(_ResponseModel):
+    """Represent one team's 247Sports Team Talent Composite rating."""
+
+    year: int = Field(ge=1869)
+    team: str
+    talent: float
+
+
+class TeamATS(_ResponseModel):
+    """Represent one team's against-the-spread season record."""
+
+    year: int = Field(ge=1869)
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    conference: str | None
+    games: int = Field(ge=0)
+    ats_wins: int = Field(alias="atsWins", ge=0)
+    ats_losses: int = Field(alias="atsLosses", ge=0)
+    ats_pushes: int = Field(alias="atsPushes", ge=0)
+    avg_cover_margin: float | None = Field(alias="avgCoverMargin")

cfb_data/teams/resource.py

@@ -0,0 +1,270 @@
+"""Expose typed Teams 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.enums import Classification
+from cfb_data.teams.models.pydantic.requests import (
+    FBSTeamsRequest,
+    RosterRequest,
+    TalentRequest,
+    TeamATSRequest,
+    TeamMatchupRequest,
+    TeamsRequest,
+)
+from cfb_data.teams.models.pydantic.responses import (
+    Matchup,
+    RosterPlayer,
+    Team,
+    TeamATS,
+    TeamTalent,
+)
+
+type _ClassificationArgument = Classification | Literal["fbs", "fcs", "ii", "iii"]
+_TEAM_ROWS = TypeAdapter(list[Team])
+_MATCHUP = TypeAdapter(Matchup)
+_ATS_ROWS = TypeAdapter(list[TeamATS])
+_ROSTER_ROWS = TypeAdapter(list[RosterPlayer])
+_TALENT_ROWS = TypeAdapter(list[TeamTalent])
+
+
+class TeamsResource[FrameT]:
+    """Provide validated Teams endpoints with backend-specific 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: TeamsRequest, /) -> FrameT: ...
+
+    @overload
+    async def list(
+        self,
+        request: None = None,
+        /,
+        *,
+        conference: str | None = None,
+        year: int | None = None,
+    ) -> FrameT: ...
+
+    async def list(
+        self, request: TeamsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return teams as the selected DataFrame type.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``Team`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/teams"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=TeamsRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint, request=validated, response_adapter=_TEAM_ROWS
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=Team, models=rows
+        )
+
+    @overload
+    async def fbs(self, request: FBSTeamsRequest, /) -> FrameT: ...
+
+    @overload
+    async def fbs(
+        self, request: None = None, /, *, year: int | None = None
+    ) -> FrameT: ...
+
+    async def fbs(
+        self, request: FBSTeamsRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return FBS teams as the selected DataFrame type.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``Team`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/teams/fbs"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=FBSTeamsRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint, request=validated, response_adapter=_TEAM_ROWS
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=Team, models=rows
+        )
+
+    @overload
+    async def matchup(self, request: TeamMatchupRequest, /) -> FrameT: ...
+
+    @overload
+    async def matchup(
+        self,
+        request: None = None,
+        /,
+        *,
+        team1: str,
+        team2: str,
+        min_year: int | None = None,
+        max_year: int | None = None,
+    ) -> FrameT: ...
+
+    async def matchup(
+        self, request: TeamMatchupRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return one matchup summary with nested games as a selected frame.
+
+        pandas stores ``games`` in an ``object`` column. Polars stores the same
+        logical values in a native ``List[Struct]`` column.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: One-row eager frame containing the validated matchup summary.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/teams/matchup"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=TeamMatchupRequest,
+            request=request,
+            filters=filters,
+        )
+        matchup = await self._executor.fetch_one(
+            endpoint=endpoint, request=validated, response_adapter=_MATCHUP
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=Matchup, models=[matchup]
+        )
+
+    @overload
+    async def ats(self, request: TeamATSRequest, /) -> FrameT: ...
+
+    @overload
+    async def ats(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int,
+        conference: str | None = None,
+        team: str | None = None,
+    ) -> FrameT: ...
+
+    async def ats(
+        self, request: TeamATSRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team against-the-spread records as the selected frame.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``TeamATS`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/teams/ats"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=TeamATSRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint, request=validated, response_adapter=_ATS_ROWS
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=TeamATS, models=rows
+        )
+
+    @overload
+    async def roster(self, request: RosterRequest, /) -> FrameT: ...
+
+    @overload
+    async def roster(
+        self,
+        request: None = None,
+        /,
+        *,
+        team: str | None = None,
+        year: int | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def roster(
+        self, request: RosterRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return historical roster players as the selected frame.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``RosterPlayer`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/roster"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=RosterRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint, request=validated, response_adapter=_ROSTER_ROWS
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=RosterPlayer, models=rows
+        )
+
+    @overload
+    async def talent(self, request: TalentRequest, /) -> FrameT: ...
+
+    @overload
+    async def talent(self, request: None = None, /, *, year: int) -> FrameT: ...
+
+    async def talent(
+        self, request: TalentRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team talent ratings as the selected frame.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated ``TeamTalent`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/talent"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=TalentRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint, request=validated, response_adapter=_TALENT_ROWS
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=TeamTalent, models=rows
+        )

cfb_data/venues/__init__.py

@@ -0,0 +1,6 @@
+"""Export the supported Venues namespace and public contracts."""
+
+from .models.pydantic import Venue
+from .resource import VenuesResource
+
+__all__ = ["Venue", "VenuesResource"]

cfb_data/venues/models/__init__.py

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

cfb_data/venues/models/pydantic/__init__.py

@@ -0,0 +1,5 @@
+"""Export Pydantic models for Venues endpoints."""
+
+from .responses import Venue
+
+__all__ = ["Venue"]

cfb_data/venues/models/pydantic/responses.py

@@ -0,0 +1,24 @@
+"""Validate responses from implemented CFBD Venues endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Venue(BaseModel):
+    """Represent one venue or a Team's nested home location."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    id: int | None = Field(ge=0)
+    name: str | None
+    city: str | None
+    state: str | None
+    zip: str | None
+    country_code: str | None = Field(alias="countryCode")
+    timezone: str | None
+    latitude: float | None
+    longitude: float | None
+    elevation: str | None
+    capacity: int | None = Field(ge=0)
+    construction_year: int | None = Field(default=None, alias="constructionYear")
+    grass: bool | None = None
+    dome: bool | None = None

cfb_data/venues/resource.py

@@ -0,0 +1,51 @@
+"""Expose typed Venues endpoints through the primary client."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor
+from cfb_data.venues.models.pydantic.responses import Venue
+
+_VENUE_ROWS = TypeAdapter(list[Venue])
+
+
+class _VenuesRequest(BaseModel):
+    """Represent the empty filter set accepted by ``GET /venues``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+_VENUES_REQUEST = _VenuesRequest()
+
+
+class VenuesResource[FrameT]:
+    """Provide validated Venues endpoints with backend-specific 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
+
+    async def list(self) -> FrameT:
+        """Return venues in upstream order as the selected DataFrame type.
+
+        :return: Eager frame containing validated ``Venue`` rows.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        endpoint = "/venues"
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=_VENUES_REQUEST,
+            response_adapter=_VENUE_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=Venue,
+            models=rows,
+        )