cfb-data 0.4.1__py3-none-any.whl

cfb_data/conferences/resource.py

@@ -0,0 +1,175 @@
+"""Expose typed Conferences endpoints through the primary client."""
+
+from __future__ import annotations
+
+import builtins
+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.conferences.models.pydantic.requests import (
+    ConferenceAffiliationsRequest,
+    ConferenceChangesRequest,
+    ConferencesRequest,
+)
+from cfb_data.conferences.models.pydantic.responses import (
+    Conference,
+    ConferenceClassification,
+    TeamConferenceAffiliation,
+    TeamConferenceChange,
+)
+
+_RequestT = TypeVar("_RequestT", bound=BaseModel)
+_RowT = TypeVar("_RowT", bound=BaseModel)
+type _ClassificationArgument = (
+    ConferenceClassification | Literal["fbs", "fcs", "ii", "ii/iii", "iii"]
+)
+_CONFERENCE_ROWS = TypeAdapter(list[Conference])
+_CHANGE_ROWS = TypeAdapter(list[TeamConferenceChange])
+_AFFILIATION_ROWS = TypeAdapter(list[TeamConferenceAffiliation])
+
+
+class ConferencesResource[FrameT]:
+    """Provide Conferences 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: ConferencesRequest, /) -> FrameT: ...
+
+    @overload
+    async def list(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def list(
+        self, request: ConferencesRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return conferences 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 ``Conference`` 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="/conferences",
+            request_type=ConferencesRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_CONFERENCE_ROWS,
+            row_model=Conference,
+        )
+
+    @overload
+    async def changes(self, request: ConferenceChangesRequest, /) -> FrameT: ...
+
+    @overload
+    async def changes(self, request: None = None, /, *, year: int) -> FrameT: ...
+
+    async def changes(
+        self, request: ConferenceChangesRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return team conference changes 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 change 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="/conferences/changes",
+            request_type=ConferenceChangesRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_CHANGE_ROWS,
+            row_model=TeamConferenceChange,
+        )
+
+    @overload
+    async def affiliations(
+        self, request: ConferenceAffiliationsRequest, /
+    ) -> FrameT: ...
+
+    @overload
+    async def affiliations(
+        self,
+        request: None = None,
+        /,
+        *,
+        team: str | None = None,
+        conference: str | None = None,
+        year: int | None = None,
+        min_year: int | None = None,
+        max_year: int | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def affiliations(
+        self,
+        request: ConferenceAffiliationsRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return historical affiliations 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 affiliation 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="/conferences/affiliations",
+            request_type=ConferenceAffiliationsRequest,
+            request=request,
+            filters=filters,
+            response_adapter=_AFFILIATION_ROWS,
+            row_model=TeamConferenceAffiliation,
+        )
+
+    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:
+        """Validate, fetch, and convert one Conferences list route."""
+        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,
+        )

cfb_data/draft/__init__.py

@@ -0,0 +1,19 @@
+"""Export the supported Draft namespace and public contracts."""
+
+from .models.pydantic import (
+    DraftPick,
+    DraftPickHometown,
+    DraftPicksRequest,
+    DraftPosition,
+    DraftTeam,
+)
+from .resource import DraftResource
+
+__all__ = [
+    "DraftPick",
+    "DraftPickHometown",
+    "DraftPicksRequest",
+    "DraftPosition",
+    "DraftResource",
+    "DraftTeam",
+]

cfb_data/draft/models/__init__.py

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

cfb_data/draft/models/pydantic/__init__.py

@@ -0,0 +1,12 @@
+"""Export validated Draft request and response models."""
+
+from .requests import DraftPicksRequest
+from .responses import DraftPick, DraftPickHometown, DraftPosition, DraftTeam
+
+__all__ = [
+    "DraftPick",
+    "DraftPickHometown",
+    "DraftPicksRequest",
+    "DraftPosition",
+    "DraftTeam",
+]

cfb_data/draft/models/pydantic/requests.py

@@ -0,0 +1,18 @@
+"""Validate request parameters for implemented Draft endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DraftPicksRequest(BaseModel):
+    """Validate filters accepted by ``GET /draft/picks``."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int | None = Field(default=None, ge=1936)
+    team: str | None = Field(default=None, min_length=1)
+    school: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+    position: str | None = Field(default=None, min_length=1)
+
+
+__all__ = ["DraftPicksRequest"]

cfb_data/draft/models/pydantic/responses.py

@@ -0,0 +1,65 @@
+"""Validate responses from implemented CFBD Draft endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to Draft responses."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class DraftTeam(_ResponseModel):
+    """Represent an NFL team present in the historical draft data."""
+
+    location: str
+    nickname: str | None
+    display_name: str | None = Field(alias="displayName")
+    logo: str | None
+
+
+class DraftPosition(_ResponseModel):
+    """Represent an NFL Draft position category."""
+
+    name: str
+    abbreviation: str
+
+
+class DraftPickHometown(_ResponseModel):
+    """Represent the recorded hometown of an NFL Draft pick."""
+
+    city: str | None
+    state: str | None
+    country: str | None
+    latitude: str | None
+    longitude: str | None
+    county_fips: str | None = Field(alias="countyFips")
+
+
+class DraftPick(_ResponseModel):
+    """Represent one historical NFL Draft selection."""
+
+    college_athlete_id: int | None = Field(alias="collegeAthleteId", gt=0)
+    nfl_athlete_id: int = Field(alias="nflAthleteId", gt=0)
+    college_id: int = Field(alias="collegeId", gt=0)
+    college_team: str = Field(alias="collegeTeam")
+    college_conference: str | None = Field(alias="collegeConference")
+    nfl_team_id: int = Field(alias="nflTeamId", gt=0)
+    nfl_team: str = Field(alias="nflTeam")
+    year: int = Field(ge=1936)
+    overall: int = Field(gt=0)
+    round: int = Field(gt=0)
+    pick: int = Field(gt=0)
+    name: str
+    position: str
+    height: float | None = Field(ge=0)
+    weight: int | None = Field(ge=0)
+    pre_draft_ranking: int | None = Field(alias="preDraftRanking", gt=0)
+    pre_draft_position_ranking: int | None = Field(
+        alias="preDraftPositionRanking", gt=0
+    )
+    pre_draft_grade: int | None = Field(alias="preDraftGrade", ge=0)
+    hometown_info: DraftPickHometown = Field(alias="hometownInfo")
+
+
+__all__ = ["DraftPick", "DraftPickHometown", "DraftPosition", "DraftTeam"]

cfb_data/draft/resource.py

@@ -0,0 +1,132 @@
+"""Expose typed Draft endpoints through the primary client."""
+
+from __future__ import annotations
+
+from typing import TypeVar, overload
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor
+from cfb_data._requests import _resolve_request
+from cfb_data.draft.models.pydantic.requests import DraftPicksRequest
+from cfb_data.draft.models.pydantic.responses import (
+    DraftPick,
+    DraftPosition,
+    DraftTeam,
+)
+
+_RowT = TypeVar("_RowT", bound=BaseModel)
+
+_DRAFT_TEAM_ROWS = TypeAdapter(list[DraftTeam])
+_DRAFT_POSITION_ROWS = TypeAdapter(list[DraftPosition])
+_DRAFT_PICK_ROWS = TypeAdapter(list[DraftPick])
+
+
+class _EmptyRequest(BaseModel):
+    """Represent an endpoint that accepts no filters."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+_EMPTY_REQUEST = _EmptyRequest()
+
+
+class DraftResource[FrameT]:
+    """Provide validated Draft 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
+
+    async def teams(self) -> FrameT:
+        """Return NFL teams represented in historical draft data.
+
+        :return: Eager frame containing validated NFL team rows.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        return await self._fetch_without_filters(
+            endpoint="/draft/teams",
+            response_adapter=_DRAFT_TEAM_ROWS,
+            row_model=DraftTeam,
+        )
+
+    async def positions(self) -> FrameT:
+        """Return position categories used in NFL Draft data.
+
+        :return: Eager frame containing validated position rows.
+        :raises CFBDError: If transport, response, or conversion fails.
+        """
+        return await self._fetch_without_filters(
+            endpoint="/draft/positions",
+            response_adapter=_DRAFT_POSITION_ROWS,
+            row_model=DraftPosition,
+        )
+
+    @overload
+    async def picks(self, request: DraftPicksRequest, /) -> FrameT: ...
+
+    @overload
+    async def picks(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int | None = None,
+        team: str | None = None,
+        school: str | None = None,
+        conference: str | None = None,
+        position: str | None = None,
+    ) -> FrameT: ...
+
+    async def picks(
+        self, request: DraftPicksRequest | None = None, /, **filters: object
+    ) -> FrameT:
+        """Return historical NFL Draft picks.
+
+        :param request: Validated request model, mutually exclusive with filters.
+        :param filters: Explicit snake-case endpoint filters.
+        :return: Eager frame containing validated draft-pick rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/draft/picks"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=DraftPicksRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_DRAFT_PICK_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=DraftPick, models=rows
+        )
+
+    async def _fetch_without_filters(
+        self,
+        *,
+        endpoint: str,
+        response_adapter: TypeAdapter[list[_RowT]],
+        row_model: type[_RowT],
+    ) -> FrameT:
+        """Fetch and tabularize one filterless Draft endpoint."""
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=_EMPTY_REQUEST,
+            response_adapter=response_adapter,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint, row_model=row_model, models=rows
+        )
+
+
+__all__ = ["DraftResource"]

cfb_data/drives/__init__.py

@@ -0,0 +1,13 @@
+"""Export the supported Drives namespace and request contract."""
+
+from cfb_data.enums import Classification, SeasonType
+
+from .models.pydantic.requests import DrivesRequest
+from .resource import DrivesResource
+
+__all__ = [
+    "Classification",
+    "DrivesRequest",
+    "DrivesResource",
+    "SeasonType",
+]

cfb_data/drives/models/__init__.py

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

cfb_data/drives/models/pydantic/__init__.py

@@ -0,0 +1,17 @@
+"""Pydantic models for drives endpoints."""
+
+from .requests import (
+    DrivesRequest,
+)
+from .responses import (
+    Drive,
+    DriveTime,
+)
+
+__all__ = [
+    # Request models
+    "DrivesRequest",
+    # Response models
+    "DriveTime",
+    "Drive",
+]

cfb_data/drives/models/pydantic/requests.py

@@ -0,0 +1,42 @@
+"""Validate request parameters for the implemented Drives endpoint."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from cfb_data.enums import Classification, SeasonType
+
+
+class DrivesRequest(BaseModel):
+    """Validate filters accepted by ``GET /drives``.
+
+    :param year: Required season year.
+    :param season_type: Optional season phase.
+    :param week: Optional non-negative season week.
+    :param team: Team appearing on offense or defense.
+    :param offense: Offensive-team selector.
+    :param defense: Defensive-team selector.
+    :param conference: Conference appearing on offense or defense.
+    :param offense_conference: Offensive-team conference selector.
+    :param defense_conference: Defensive-team conference selector.
+    :param classification: Division classification selector.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    year: int = Field(ge=1869)
+    season_type: SeasonType | None = Field(default=None, alias="seasonType")
+    week: int | None = Field(default=None, ge=0)
+    team: str | None = None
+    offense: str | None = None
+    defense: str | None = None
+    conference: str | None = None
+    offense_conference: str | None = Field(
+        default=None,
+        alias="offenseConference",
+    )
+    defense_conference: str | None = Field(
+        default=None,
+        alias="defenseConference",
+    )
+    classification: Classification | None = None

cfb_data/drives/models/pydantic/responses.py

@@ -0,0 +1,46 @@
+"""Pydantic models for drives endpoint responses."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DriveTime(BaseModel):
+    """Time remaining in a period."""
+
+    seconds: int | None = Field(ge=0)
+    minutes: int | None = Field(ge=0)
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class Drive(BaseModel):
+    """Drive data model for `/drives` endpoint."""
+
+    offense: str = Field(alias="offense")
+    offense_conference: str | None = Field(alias="offenseConference")
+    defense: str = Field(alias="defense")
+    defense_conference: str | None = Field(alias="defenseConference")
+    game_id: int = Field(alias="gameId", ge=0)
+    id: str = Field(alias="id")
+    drive_number: int | None = Field(alias="driveNumber", ge=0)
+    scoring: bool = Field(alias="scoring")
+    start_period: int = Field(alias="startPeriod", ge=0)
+    start_yardline: int = Field(alias="startYardline", ge=0)
+    start_yards_to_goal: int = Field(alias="startYardsToGoal", ge=0)
+    start_time: DriveTime = Field(alias="startTime")
+    end_period: int = Field(alias="endPeriod", ge=0)
+    end_yardline: int = Field(alias="endYardline", ge=0)
+    end_yards_to_goal: int = Field(alias="endYardsToGoal", ge=0)
+    end_time: DriveTime = Field(alias="endTime")
+    elapsed: DriveTime
+    plays: int = Field(alias="plays", ge=0)
+    yards: int = Field(alias="yards")
+    drive_result: str = Field(alias="driveResult")
+    is_home_offense: bool = Field(alias="isHomeOffense")
+    start_offense_score: int = Field(alias="startOffenseScore", ge=0)
+    start_defense_score: int = Field(alias="startDefenseScore", ge=0)
+    end_offense_score: int = Field(alias="endOffenseScore", ge=0)
+    end_defense_score: int = Field(alias="endDefenseScore", ge=0)
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")

cfb_data/drives/resource.py

@@ -0,0 +1,94 @@
+"""Expose typed drive 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.drives.models.pydantic.requests import DrivesRequest
+from cfb_data.drives.models.pydantic.responses import Drive
+from cfb_data.enums import Classification, SeasonType
+
+type _SeasonTypeArgument = (
+    SeasonType
+    | Literal[
+        "regular",
+        "postseason",
+        "both",
+        "allstar",
+        "spring_regular",
+        "spring_postseason",
+    ]
+)
+type _ClassificationArgument = Classification | Literal["fbs", "fcs", "ii", "iii"]
+_DRIVE_ROWS = TypeAdapter(list[Drive])
+
+
+class DrivesResource[FrameT]:
+    """Provide validated Drives 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: DrivesRequest, /) -> FrameT: ...
+
+    @overload
+    async def list(
+        self,
+        request: None = None,
+        /,
+        *,
+        year: int,
+        season_type: _SeasonTypeArgument | None = None,
+        week: int | None = None,
+        team: str | None = None,
+        offense: str | None = None,
+        defense: str | None = None,
+        conference: str | None = None,
+        offense_conference: str | None = None,
+        defense_conference: str | None = None,
+        classification: _ClassificationArgument | None = None,
+    ) -> FrameT: ...
+
+    async def list(
+        self,
+        request: DrivesRequest | None = None,
+        /,
+        **filters: object,
+    ) -> FrameT:
+        """Return drives in upstream order 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 ``Drive`` rows.
+        :raises TypeError: If request styles are mixed or the model type is wrong.
+        :raises CFBDError: If request, transport, response, or conversion fails.
+        """
+        endpoint = "/drives"
+        validated = _resolve_request(
+            endpoint=endpoint,
+            request_type=DrivesRequest,
+            request=request,
+            filters=filters,
+        )
+        rows = await self._executor.fetch_many(
+            endpoint=endpoint,
+            request=validated,
+            response_adapter=_DRIVE_ROWS,
+        )
+        return self._dataframe_adapter.from_models(
+            endpoint=endpoint,
+            row_model=Drive,
+            models=rows,
+        )