cfb-data 0.4.1__py3-none-any.whl

cfb_data/__init__.py

@@ -0,0 +1,234 @@
+"""Access validated CollegeFootballData endpoints as pandas or Polars frames."""
+
+from .adjusted_metrics.models.pydantic.requests import (
+    AdjustedPlayerPassingRequest,
+    AdjustedPlayerRushingRequest,
+    AdjustedTeamMetricsRequest,
+    KickerPAARRequest,
+)
+from .betting.models.pydantic.requests import BettingLinesRequest
+from .client import CFBDClient, DataFrameBackend
+from .coaches.models.pydantic.requests import (
+    CoachesRequest,
+    CoachProfileRequest,
+    CoachSeasonsRequest,
+    CoachTenuresRequest,
+)
+from .conferences.models.pydantic.requests import (
+    ConferenceAffiliationsRequest,
+    ConferenceChangesRequest,
+    ConferencesRequest,
+)
+from .conferences.models.pydantic.responses import ConferenceClassification
+from .draft.models.pydantic.requests import DraftPicksRequest
+from .drives.models.pydantic.requests import DrivesRequest
+from .enums import (
+    Classification,
+    MediaType,
+    PlayoffCompetition,
+    PlayoffRound,
+    RankingPoll,
+    RecruitClassification,
+    SeasonType,
+    TransferEligibility,
+    UserUsageApi,
+)
+from .errors import (
+    CFBDAuthenticationError,
+    CFBDAuthorizationError,
+    CFBDClientStateError,
+    CFBDConfigurationError,
+    CFBDDataFrameConversionError,
+    CFBDError,
+    CFBDHTTPError,
+    CFBDOptionalDependencyError,
+    CFBDRateLimitError,
+    CFBDRequestValidationError,
+    CFBDResponseDecodeError,
+    CFBDResponseValidationError,
+    CFBDServerError,
+    CFBDTimeoutError,
+    CFBDTLSError,
+    CFBDTransportError,
+)
+from .games.models.pydantic.requests import (
+    AdvancedBoxScoreRequest,
+    CalendarRequest,
+    GameMediaRequest,
+    GamesRequest,
+    GameWeatherRequest,
+    PlayerGameStatsRequest,
+    RecordsRequest,
+    ScoreboardRequest,
+    TeamGameStatsRequest,
+)
+from .games.models.pydantic.responses import AdvancedBoxScore
+from .info.models.pydantic.requests import InfoUsageRequest
+from .info.models.pydantic.responses import UserInfo, UserUsage
+from .metrics.models.pydantic.requests import (
+    PlayerGamePPARequest,
+    PlayerSeasonPPARequest,
+    PredictedPointsRequest,
+    PregameWinProbabilityRequest,
+    TeamGamePPARequest,
+    TeamSeasonPPARequest,
+    WinProbabilityRequest,
+)
+from .players.models.pydantic.requests import (
+    PlayerSearchRequest,
+    PlayerSeasonOverviewRequest,
+    PlayerUsageRequest,
+    ReturningProductionRequest,
+    TransferPortalRequest,
+)
+from .playoffs.models.pydantic.requests import (
+    CfpGamesRequest,
+    CfpParticipantsRequest,
+    CfpPlayoffRequest,
+)
+from .playoffs.models.pydantic.responses import CfpPlayoff
+from .plays.models.pydantic.requests import (
+    LivePlaysRequest,
+    PlaysRequest,
+    PlayStatsRequest,
+)
+from .plays.models.pydantic.responses import DownType, HomeAway, LiveGame, RushPass
+from .rankings.models.pydantic.requests import RankingsRequest
+from .ratings.models.pydantic.requests import (
+    ConferenceSPRatingsRequest,
+    CoreRatingsRequest,
+    EloRatingsRequest,
+    ExpandedSRSRatingsRequest,
+    FPIRatingsRequest,
+    SPRatingsRequest,
+    SRSRatingsRequest,
+)
+from .recruiting.models.pydantic.requests import (
+    RecruitingGroupsRequest,
+    RecruitingPlayersRequest,
+    RecruitingTeamsRequest,
+)
+from .retry import RetryPolicy
+from .stats.models.pydantic.requests import (
+    AdvancedGameStatsRequest,
+    AdvancedSeasonStatsRequest,
+    GameHavocRequest,
+    PlayerGameSuccessRequest,
+    PlayerSeasonStatsRequest,
+    PlayerSeasonSuccessRequest,
+    TeamSeasonStatsRequest,
+)
+from .teams.models.pydantic.requests import (
+    FBSTeamsRequest,
+    RosterRequest,
+    TalentRequest,
+    TeamATSRequest,
+    TeamMatchupRequest,
+    TeamsRequest,
+)
+
+__all__ = [
+    "AdjustedPlayerPassingRequest",
+    "AdjustedPlayerRushingRequest",
+    "AdjustedTeamMetricsRequest",
+    "AdvancedBoxScoreRequest",
+    "AdvancedBoxScore",
+    "AdvancedGameStatsRequest",
+    "AdvancedSeasonStatsRequest",
+    "BettingLinesRequest",
+    "CalendarRequest",
+    "CfpGamesRequest",
+    "CfpParticipantsRequest",
+    "CfpPlayoff",
+    "CfpPlayoffRequest",
+    "CFBDAuthenticationError",
+    "CFBDAuthorizationError",
+    "CFBDClient",
+    "CFBDClientStateError",
+    "CFBDConfigurationError",
+    "CFBDDataFrameConversionError",
+    "CFBDError",
+    "CFBDHTTPError",
+    "CFBDOptionalDependencyError",
+    "CFBDRateLimitError",
+    "CFBDRequestValidationError",
+    "CFBDResponseDecodeError",
+    "CFBDResponseValidationError",
+    "CFBDServerError",
+    "CFBDTimeoutError",
+    "CFBDTLSError",
+    "CFBDTransportError",
+    "Classification",
+    "CoachesRequest",
+    "CoachProfileRequest",
+    "CoachSeasonsRequest",
+    "CoachTenuresRequest",
+    "ConferenceAffiliationsRequest",
+    "ConferenceChangesRequest",
+    "ConferenceClassification",
+    "ConferencesRequest",
+    "ConferenceSPRatingsRequest",
+    "CoreRatingsRequest",
+    "DataFrameBackend",
+    "DraftPicksRequest",
+    "DrivesRequest",
+    "EloRatingsRequest",
+    "ExpandedSRSRatingsRequest",
+    "FPIRatingsRequest",
+    "GameMediaRequest",
+    "GamesRequest",
+    "GameWeatherRequest",
+    "GameHavocRequest",
+    "FBSTeamsRequest",
+    "HomeAway",
+    "InfoUsageRequest",
+    "KickerPAARRequest",
+    "LiveGame",
+    "LivePlaysRequest",
+    "MediaType",
+    "PlayerGameStatsRequest",
+    "PlayerGamePPARequest",
+    "PlayerGameSuccessRequest",
+    "PlayoffCompetition",
+    "PlayoffRound",
+    "PlaysRequest",
+    "PlayStatsRequest",
+    "PlayerSeasonStatsRequest",
+    "PlayerSearchRequest",
+    "PlayerSeasonOverviewRequest",
+    "PlayerSeasonPPARequest",
+    "PlayerSeasonSuccessRequest",
+    "PlayerUsageRequest",
+    "PredictedPointsRequest",
+    "PregameWinProbabilityRequest",
+    "RecordsRequest",
+    "RankingPoll",
+    "RankingsRequest",
+    "RecruitClassification",
+    "RecruitingGroupsRequest",
+    "RecruitingPlayersRequest",
+    "RecruitingTeamsRequest",
+    "RetryPolicy",
+    "RosterRequest",
+    "ReturningProductionRequest",
+    "RushPass",
+    "ScoreboardRequest",
+    "SeasonType",
+    "SPRatingsRequest",
+    "SRSRatingsRequest",
+    "TeamGamePPARequest",
+    "TeamGameStatsRequest",
+    "TeamSeasonStatsRequest",
+    "TeamSeasonPPARequest",
+    "TalentRequest",
+    "TeamATSRequest",
+    "TeamMatchupRequest",
+    "TeamsRequest",
+    "TransferPortalRequest",
+    "TransferEligibility",
+    "UserInfo",
+    "UserUsage",
+    "UserUsageApi",
+    "WinProbabilityRequest",
+    "DownType",
+]

cfb_data/_dataframes.py

@@ -0,0 +1,279 @@
+"""Materialize canonical Arrow tables as pandas or Polars DataFrames."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Protocol, TypeVar
+
+import pandas as pd
+import pyarrow as pa
+from pydantic import BaseModel
+
+from cfb_data._tabular import (
+    _arrow_table_from_models,
+    _assert_canonical_arrow_table,
+    _logical_records_from_arrow_table,
+    _logical_schema,
+    _LogicalType,
+)
+from cfb_data.errors import (
+    CFBDDataFrameConversionError,
+    CFBDOptionalDependencyError,
+    _sanitized_cause,
+)
+
+if TYPE_CHECKING:
+    import polars as pl
+
+_FrameT_co = TypeVar("_FrameT_co", covariant=True)
+
+
+class _DataFrameAdapter(Protocol[_FrameT_co]):
+    """Convert canonical tabular values to one eager DataFrame type."""
+
+    def from_models(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        models: Sequence[BaseModel],
+    ) -> _FrameT_co:
+        """Return a frame preserving all validated rows and columns."""
+
+    def from_table(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        table: pa.Table,
+    ) -> _FrameT_co:
+        """Return a frame materialized from a canonical Arrow table."""
+
+
+class _PandasAdapter:
+    """Create pandas DataFrames with explicit native and nullable dtypes."""
+
+    def from_models(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        models: Sequence[BaseModel],
+    ) -> pd.DataFrame:
+        """Return a pandas frame for validated model rows.
+
+        :param endpoint: Endpoint producing the rows.
+        :param row_model: Authoritative Pydantic row model.
+        :param models: Validated rows in API order.
+        :return: DataFrame with a normal :class:`pandas.RangeIndex`.
+        :raises CFBDDataFrameConversionError: If conversion loses the contract.
+        """
+        try:
+            table = _arrow_table_from_models(row_model=row_model, models=models)
+            return self.from_table(
+                endpoint=endpoint,
+                row_model=row_model,
+                table=table,
+            )
+        except CFBDDataFrameConversionError:
+            raise
+        except Exception as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDDataFrameConversionError(
+            endpoint=endpoint,
+            backend="pandas",
+        ) from safe_cause
+
+    def from_table(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        table: pa.Table,
+    ) -> pd.DataFrame:
+        """Return a pandas frame from a canonical Arrow table.
+
+        :param endpoint: Endpoint associated with the table.
+        :param row_model: Authoritative Pydantic row model.
+        :param table: Canonical Arrow table in source row order.
+        :return: DataFrame with explicit pandas dtypes and nested objects.
+        :raises CFBDDataFrameConversionError: If conversion loses the contract.
+        """
+        try:
+            schema = _logical_schema(row_model)
+            records = _logical_records_from_arrow_table(
+                row_model=row_model,
+                table=table,
+            )
+            columns = {
+                field.name: pd.Series(
+                    [record[field.name] for record in records],
+                    dtype=_pandas_dtype(field.type),
+                )
+                for field in schema.fields
+            }
+            frame = pd.DataFrame(columns)
+            _assert_frame_shape(
+                columns=list(frame.columns),
+                row_count=len(frame),
+                expected_columns=[field.name for field in schema.fields],
+                expected_rows=table.num_rows,
+            )
+            if not frame.index.equals(pd.RangeIndex(table.num_rows)):
+                raise ValueError("pandas conversion did not preserve a RangeIndex")
+            return frame
+        except CFBDDataFrameConversionError:
+            raise
+        except Exception as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDDataFrameConversionError(
+            endpoint=endpoint,
+            backend="pandas",
+        ) from safe_cause
+
+
+class _PolarsAdapter:
+    """Create strict Polars DataFrames with native nested columns."""
+
+    def from_models(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        models: Sequence[BaseModel],
+    ) -> pl.DataFrame:
+        """Return a Polars frame for validated model rows.
+
+        :param endpoint: Endpoint producing the rows.
+        :param row_model: Authoritative Pydantic row model.
+        :param models: Validated rows in API order.
+        :return: Strict eager Polars DataFrame.
+        :raises CFBDOptionalDependencyError: If Polars is not installed.
+        :raises CFBDDataFrameConversionError: If conversion loses the contract.
+        """
+        self._require_polars()
+        try:
+            table = _arrow_table_from_models(row_model=row_model, models=models)
+            return self.from_table(
+                endpoint=endpoint,
+                row_model=row_model,
+                table=table,
+            )
+        except CFBDDataFrameConversionError:
+            raise
+        except Exception as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDDataFrameConversionError(
+            endpoint=endpoint,
+            backend="polars",
+        ) from safe_cause
+
+    def from_table(
+        self,
+        *,
+        endpoint: str,
+        row_model: type[BaseModel],
+        table: pa.Table,
+    ) -> pl.DataFrame:
+        """Return a Polars frame from a canonical Arrow table.
+
+        :param endpoint: Endpoint associated with the table.
+        :param row_model: Authoritative Pydantic row model.
+        :param table: Canonical Arrow table in source row order.
+        :return: DataFrame with Arrow-native nesting and decoded mixed scalars.
+        :raises CFBDOptionalDependencyError: If Polars is not installed.
+        :raises CFBDDataFrameConversionError: If conversion loses the contract.
+        """
+        try:
+            import polars as pl
+        except ModuleNotFoundError as exc:
+            if exc.name == "polars":
+                raise CFBDOptionalDependencyError(
+                    'Polars support requires pip install "cfb-data[polars]"'
+                ) from exc
+            raise
+
+        try:
+            schema = _logical_schema(row_model)
+            _assert_canonical_arrow_table(row_model=row_model, table=table)
+            frame = pl.from_arrow(table, rechunk=True)
+            if not isinstance(frame, pl.DataFrame):
+                raise TypeError("Arrow table did not produce a Polars DataFrame")
+            scalar_fields = [
+                (index, field)
+                for index, field in enumerate(schema.fields)
+                if field.type.kind == "scalar"
+            ]
+            if scalar_fields:
+                records = _logical_records_from_arrow_table(
+                    row_model=row_model,
+                    table=table,
+                )
+                for index, field in scalar_fields:
+                    frame.replace_column(
+                        index,
+                        pl.Series(
+                            field.name,
+                            [record[field.name] for record in records],
+                            dtype=pl.Object,
+                            strict=True,
+                        ),
+                    )
+            _assert_frame_shape(
+                columns=frame.columns,
+                row_count=frame.height,
+                expected_columns=[field.name for field in schema.fields],
+                expected_rows=table.num_rows,
+            )
+            return frame
+        except CFBDOptionalDependencyError:
+            raise
+        except Exception as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDDataFrameConversionError(
+            endpoint=endpoint,
+            backend="polars",
+        ) from safe_cause
+
+    @staticmethod
+    def _require_polars() -> None:
+        """Fail with install guidance before doing backend-independent work."""
+        try:
+            import polars  # noqa: F401
+        except ModuleNotFoundError as exc:
+            if exc.name == "polars":
+                raise CFBDOptionalDependencyError(
+                    'Polars support requires pip install "cfb-data[polars]"'
+                ) from exc
+            raise
+
+
+def _pandas_dtype(logical_type: _LogicalType) -> object:
+    """Return the exact pandas dtype for a logical type."""
+    if logical_type.kind == "integer":
+        return "Int64" if logical_type.nullable else "int64"
+    if logical_type.kind == "float":
+        return "Float64" if logical_type.nullable else "float64"
+    if logical_type.kind == "boolean":
+        return "boolean" if logical_type.nullable else "bool"
+    if logical_type.kind == "string":
+        return "string"
+    if logical_type.kind == "datetime":
+        return "datetime64[ns, UTC]"
+    if logical_type.kind in {"scalar", "struct", "list"}:
+        return object
+    raise AssertionError(f"Unreachable logical kind: {logical_type.kind}")
+
+
+def _assert_frame_shape(
+    *,
+    columns: Sequence[str],
+    row_count: int,
+    expected_columns: Sequence[str],
+    expected_rows: int,
+) -> None:
+    """Reject conversions that changed column order or lost rows."""
+    if list(columns) != list(expected_columns):
+        raise ValueError("DataFrame columns do not match the logical schema")
+    if row_count != expected_rows:
+        raise ValueError("DataFrame row count does not match validated rows")

cfb_data/_executor.py

@@ -0,0 +1,129 @@
+"""Execute endpoints through request serialization and Pydantic validation."""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from cfb_data._transport import _HTTPTransport
+from cfb_data.base.types import (
+    json_list,
+    json_object,
+    json_object_list,
+    query_parameters,
+)
+from cfb_data.errors import (
+    CFBDRequestValidationError,
+    CFBDResponseValidationError,
+    _sanitized_cause,
+)
+
+_ModelT = TypeVar("_ModelT", bound=BaseModel)
+_ValueT = TypeVar("_ValueT")
+
+
+class _EndpointExecutor:
+    """Return validated models without depending on DataFrame presentation."""
+
+    def __init__(self, transport: _HTTPTransport) -> None:
+        """Bind endpoint execution to one owned transport.
+
+        :param transport: Context-managed transport used by all endpoint calls.
+        """
+        self._transport = transport
+
+    async def fetch_many(
+        self,
+        *,
+        endpoint: str,
+        request: BaseModel,
+        response_adapter: TypeAdapter[list[_ModelT]],
+    ) -> list[_ModelT]:
+        """Fetch and validate a list response in API order.
+
+        :param endpoint: Fixed endpoint path.
+        :param request: Validated endpoint request model.
+        :param response_adapter: Typed list-response validator.
+        :return: Validated models in upstream row order.
+        :raises CFBDResponseValidationError: If response shape or values fail.
+        """
+        raw = await self._transport.get_json(
+            endpoint,
+            _serialize_request(endpoint, request),
+        )
+        try:
+            payload = json_object_list(raw)
+            return response_adapter.validate_python(payload)
+        except (TypeError, ValidationError) as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+
+    async def fetch_one(
+        self,
+        *,
+        endpoint: str,
+        request: BaseModel,
+        response_adapter: TypeAdapter[_ModelT],
+    ) -> _ModelT:
+        """Fetch and validate one model response.
+
+        :param endpoint: Fixed endpoint path.
+        :param request: Validated endpoint request model.
+        :param response_adapter: Typed object-response validator.
+        :return: Validated response model.
+        :raises CFBDResponseValidationError: If response shape or values fail.
+        """
+        raw = await self._transport.get_json(
+            endpoint,
+            _serialize_request(endpoint, request),
+        )
+        try:
+            payload = json_object(raw)
+            return response_adapter.validate_python(payload)
+        except (TypeError, ValidationError) as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+
+    async def fetch_values(
+        self,
+        *,
+        endpoint: str,
+        request: BaseModel,
+        response_adapter: TypeAdapter[list[_ValueT]],
+    ) -> list[_ValueT]:
+        """Fetch and validate a JSON-array response in API order.
+
+        :param endpoint: Fixed endpoint path.
+        :param request: Validated endpoint request model.
+        :param response_adapter: Typed array-response validator.
+        :return: Validated values in upstream order.
+        :raises CFBDResponseValidationError: If response shape or values fail.
+        """
+        raw = await self._transport.get_json(
+            endpoint,
+            _serialize_request(endpoint, request),
+        )
+        try:
+            payload = json_list(raw)
+            return response_adapter.validate_python(payload)
+        except (TypeError, ValidationError) as exc:
+            safe_cause = _sanitized_cause(exc)
+        raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+
+
+def _serialize_request(
+    endpoint: str, request: BaseModel
+) -> dict[str, str | int | float | bool]:
+    """Serialize one validated request using its upstream aliases."""
+    try:
+        parameters = query_parameters(
+            request.model_dump(mode="json", by_alias=True, exclude_none=True)
+        )
+        return {
+            key: str(value).lower() if isinstance(value, bool) else value
+            for key, value in parameters.items()
+        }
+    except TypeError as exc:
+        safe_cause = _sanitized_cause(exc)
+    raise CFBDRequestValidationError(endpoint=endpoint) from safe_cause