cfb-data 0.4.1__py3-none-any.whl

cfb_data/enums.py

@@ -0,0 +1,93 @@
+"""Define values shared by CFBD requests and responses."""
+
+from enum import StrEnum
+
+
+class SeasonType(StrEnum):
+    """Identify the phase of a college football season."""
+
+    regular = "regular"
+    postseason = "postseason"
+    both = "both"
+    allstar = "allstar"
+    spring_regular = "spring_regular"
+    spring_postseason = "spring_postseason"
+
+
+class Classification(StrEnum):
+    """Identify a college football division classification."""
+
+    fbs = "fbs"
+    fcs = "fcs"
+    ii = "ii"
+    iii = "iii"
+
+
+class RankingPoll(StrEnum):
+    """Identify a supported rankings poll selector."""
+
+    cfp = "cfp"
+
+
+class RecruitClassification(StrEnum):
+    """Identify the source classification of a recruit."""
+
+    juco = "JUCO"
+    prep_school = "PrepSchool"
+    high_school = "HighSchool"
+
+
+class MediaType(StrEnum):
+    """Identify a game broadcast medium."""
+
+    tv = "tv"
+    radio = "radio"
+    web = "web"
+    ppv = "ppv"
+    mobile = "mobile"
+
+
+class PlayoffCompetition(StrEnum):
+    """Identify an accepted playoff competition filter."""
+
+    cfp = "cfp"
+
+
+class PlayoffRound(StrEnum):
+    """Identify an accepted College Football Playoff round filter."""
+
+    first_round = "first_round"
+    quarterfinal = "quarterfinal"
+    semifinal = "semifinal"
+    championship = "championship"
+
+
+class UserUsageApi(StrEnum):
+    """Identify which product contributes to an account usage summary."""
+
+    all = "all"
+    cfb = "cfb"
+    cbb = "cbb"
+
+
+class TransferEligibility(StrEnum):
+    """Identify a transfer player's recorded eligibility status."""
+
+    withdrawn = "Withdrawn"
+    tbd = "TBD"
+    pending_appeal = "PendingAppeal"
+    sitting_one = "SittingOne"
+    immediate = "Immediate"
+
+
+__all__ = [
+    "Classification",
+    "MediaType",
+    "PlayoffCompetition",
+    "PlayoffRound",
+    "RankingPoll",
+    "RecruitClassification",
+    "SeasonType",
+    "TransferEligibility",
+    "UserUsageApi",
+]

cfb_data/errors.py

@@ -0,0 +1,234 @@
+"""Define safe, actionable exceptions raised by :mod:`cfb_data`."""
+
+from __future__ import annotations
+
+
+class CFBDError(Exception):
+    """Provide the root exception for all library-owned failures."""
+
+
+class _SanitizedCause(Exception):
+    """Retain an exception category without retaining unsafe source data."""
+
+    category: str
+
+    def __init__(self, *, category: str) -> None:
+        """Initialize a safe diagnostic cause.
+
+        :param category: Source exception type name without its values or state.
+        """
+        self.category = category
+        super().__init__(category)
+
+
+def _sanitized_cause(source: BaseException) -> _SanitizedCause:
+    """Return a diagnostic cause detached from a potentially unsafe exception.
+
+    :param source: Exception whose type identifies the failure category.
+    :return: New exception retaining only the source type name.
+    """
+    return _SanitizedCause(category=type(source).__name__)
+
+
+class CFBDConfigurationError(CFBDError):
+    """Report invalid or missing client configuration."""
+
+
+class CFBDOptionalDependencyError(CFBDError, ImportError):
+    """Report that a selected optional feature is not installed."""
+
+
+class CFBDClientStateError(CFBDError, RuntimeError):
+    """Report an operation that violates the one-shot client lifecycle."""
+
+
+class _EndpointError(CFBDError):
+    """Attach a safe endpoint identifier to an operation failure."""
+
+    endpoint: str
+
+    def __init__(self, message: str, *, endpoint: str) -> None:
+        """Initialize an endpoint-scoped error.
+
+        :param message: Safe human-readable failure description.
+        :param endpoint: Fixed endpoint path without query parameters.
+        """
+        self.endpoint = endpoint
+        super().__init__(f"{message} for endpoint {endpoint}")
+
+
+class CFBDRequestValidationError(_EndpointError):
+    """Report invalid endpoint request parameters."""
+
+    def __init__(self, *, endpoint: str) -> None:
+        """Initialize a request-validation error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        """
+        super().__init__("Request validation failed", endpoint=endpoint)
+
+
+class CFBDTransportError(_EndpointError):
+    """Report a non-timeout failure while communicating with the API."""
+
+    attempts: int
+    category: str
+
+    def __init__(self, *, endpoint: str, attempts: int, category: str) -> None:
+        """Initialize a transport error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param attempts: Total attempts made.
+        :param category: Safe transport failure category.
+        """
+        self.attempts = attempts
+        self.category = category
+        super().__init__(
+            f"Transport failed after {attempts} attempt(s) ({category})",
+            endpoint=endpoint,
+        )
+
+
+class CFBDTimeoutError(CFBDTransportError, TimeoutError):
+    """Report that every permitted request attempt timed out."""
+
+    def __init__(self, *, endpoint: str, attempts: int) -> None:
+        """Initialize a timeout error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param attempts: Total attempts made.
+        """
+        super().__init__(
+            endpoint=endpoint,
+            attempts=attempts,
+            category="timeout",
+        )
+
+
+class CFBDTLSError(CFBDTransportError):
+    """Report a non-retryable TLS or certificate failure."""
+
+    def __init__(self, *, endpoint: str, attempts: int) -> None:
+        """Initialize a TLS error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param attempts: Total attempts made.
+        """
+        super().__init__(endpoint=endpoint, attempts=attempts, category="tls")
+
+
+class CFBDHTTPError(_EndpointError):
+    """Report an unsuccessful HTTP response without exposing its body."""
+
+    status: int
+    attempts: int
+    retry_after_seconds: float | None
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        status: int,
+        attempts: int,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        """Initialize an HTTP error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param status: HTTP response status.
+        :param attempts: Total attempts made.
+        :param retry_after_seconds: Parsed server-requested delay, if valid.
+        """
+        self.status = status
+        self.attempts = attempts
+        self.retry_after_seconds = retry_after_seconds
+        retry_detail = ""
+        if retry_after_seconds is not None:
+            retry_detail = f", Retry-After={retry_after_seconds:g}s"
+        super().__init__(
+            f"HTTP {status} after {attempts} attempt(s){retry_detail}",
+            endpoint=endpoint,
+        )
+
+
+class CFBDAuthenticationError(CFBDHTTPError):
+    """Report rejected API authentication."""
+
+
+class CFBDAuthorizationError(CFBDHTTPError):
+    """Report insufficient authorization for an endpoint."""
+
+
+class CFBDRateLimitError(CFBDHTTPError):
+    """Report an API rate-limit response."""
+
+
+class CFBDServerError(CFBDHTTPError):
+    """Report an unsuccessful server response."""
+
+
+class CFBDResponseDecodeError(_EndpointError):
+    """Report a response body that cannot be decoded as JSON."""
+
+    attempts: int
+
+    def __init__(self, *, endpoint: str, attempts: int) -> None:
+        """Initialize a response-decode error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param attempts: Total attempts made.
+        """
+        self.attempts = attempts
+        super().__init__(
+            f"Response JSON decoding failed after {attempts} attempt(s)",
+            endpoint=endpoint,
+        )
+
+
+class CFBDResponseValidationError(_EndpointError):
+    """Report a decoded response that violates its Pydantic contract."""
+
+    def __init__(self, *, endpoint: str) -> None:
+        """Initialize a response-validation error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        """
+        super().__init__("Response validation failed", endpoint=endpoint)
+
+
+class CFBDDataFrameConversionError(_EndpointError):
+    """Report failure to preserve validated rows in a selected DataFrame."""
+
+    backend: str
+
+    def __init__(self, *, endpoint: str, backend: str) -> None:
+        """Initialize a DataFrame-conversion error.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param backend: Selected DataFrame backend name.
+        """
+        self.backend = backend
+        super().__init__(
+            f"{backend} DataFrame conversion failed",
+            endpoint=endpoint,
+        )
+
+
+__all__ = [
+    "CFBDAuthenticationError",
+    "CFBDAuthorizationError",
+    "CFBDClientStateError",
+    "CFBDConfigurationError",
+    "CFBDDataFrameConversionError",
+    "CFBDError",
+    "CFBDHTTPError",
+    "CFBDOptionalDependencyError",
+    "CFBDRateLimitError",
+    "CFBDRequestValidationError",
+    "CFBDResponseDecodeError",
+    "CFBDResponseValidationError",
+    "CFBDServerError",
+    "CFBDTimeoutError",
+    "CFBDTLSError",
+    "CFBDTransportError",
+]

cfb_data/games/__init__.py

@@ -0,0 +1,42 @@
+"""Export the supported Games namespace and request contracts."""
+
+from cfb_data.enums import (
+    Classification,
+    MediaType,
+    PlayoffCompetition,
+    PlayoffRound,
+    SeasonType,
+)
+
+from .models.pydantic.requests import (
+    AdvancedBoxScoreRequest,
+    CalendarRequest,
+    GameMediaRequest,
+    GamesRequest,
+    GameWeatherRequest,
+    PlayerGameStatsRequest,
+    RecordsRequest,
+    ScoreboardRequest,
+    TeamGameStatsRequest,
+)
+from .models.pydantic.responses import AdvancedBoxScore
+from .resource import GamesResource
+
+__all__ = [
+    "AdvancedBoxScoreRequest",
+    "AdvancedBoxScore",
+    "CalendarRequest",
+    "Classification",
+    "GameMediaRequest",
+    "GamesRequest",
+    "GamesResource",
+    "GameWeatherRequest",
+    "MediaType",
+    "PlayerGameStatsRequest",
+    "PlayoffCompetition",
+    "PlayoffRound",
+    "RecordsRequest",
+    "ScoreboardRequest",
+    "SeasonType",
+    "TeamGameStatsRequest",
+]

cfb_data/games/models/__init__.py

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

cfb_data/games/models/pydantic/__init__.py

@@ -0,0 +1,106 @@
+"""Pydantic models for game endpoints."""
+
+from cfb_data.enums import Classification, MediaType, SeasonType
+
+from .requests import (
+    AdvancedBoxScoreRequest,
+    CalendarRequest,
+    GameMediaRequest,
+    GamesRequest,
+    GameWeatherRequest,
+    PlayerGameStatsRequest,
+    RecordsRequest,
+    ScoreboardRequest,
+    TeamGameStatsRequest,
+)
+from .responses import (
+    AdvancedBoxScore,
+    AdvancedGameInfo,
+    AdvancedPlayerStats,
+    AdvancedTeamStats,
+    CalendarWeek,
+    Game,
+    GameMedia,
+    GamePlayoff,
+    GameStatus,
+    GameWeather,
+    PlayerGameStatCategory,
+    PlayerGameStatPlayer,
+    PlayerGameStats,
+    PlayerGameStatsTeam,
+    PlayerGameStatType,
+    PlayerGameUsage,
+    PlayerPPA,
+    PlayerStatsByQuarter,
+    ScoreboardBetting,
+    ScoreboardGame,
+    ScoreboardTeam,
+    ScoreboardVenue,
+    ScoreboardWeather,
+    StatsByQuarter,
+    TeamExplosiveness,
+    TeamFieldPosition,
+    TeamGameStat,
+    TeamGameStats,
+    TeamGameStatsTeam,
+    TeamHavoc,
+    TeamPPA,
+    TeamRecord,
+    TeamRecords,
+    TeamRushingStats,
+    TeamScoringOpportunities,
+    TeamSuccessRates,
+)
+
+__all__ = [
+    # Request models
+    "GamesRequest",
+    "CalendarRequest",
+    "RecordsRequest",
+    "ScoreboardRequest",
+    "GameMediaRequest",
+    "GameWeatherRequest",
+    "PlayerGameStatsRequest",
+    "TeamGameStatsRequest",
+    "AdvancedBoxScoreRequest",
+    # Response models
+    "SeasonType",
+    "Classification",
+    "MediaType",
+    "GameStatus",
+    "GamePlayoff",
+    "Game",
+    "CalendarWeek",
+    "GameMedia",
+    "GameWeather",
+    "TeamRecord",
+    "TeamRecords",
+    "ScoreboardVenue",
+    "ScoreboardTeam",
+    "ScoreboardWeather",
+    "ScoreboardBetting",
+    "ScoreboardGame",
+    "PlayerGameStatPlayer",
+    "PlayerGameStatType",
+    "PlayerGameStatCategory",
+    "PlayerGameStatsTeam",
+    "PlayerGameStats",
+    "TeamGameStat",
+    "TeamGameStatsTeam",
+    "TeamGameStats",
+    "StatsByQuarter",
+    "TeamPPA",
+    "TeamSuccessRates",
+    "TeamExplosiveness",
+    "TeamRushingStats",
+    "TeamHavoc",
+    "TeamScoringOpportunities",
+    "TeamFieldPosition",
+    "PlayerStatsByQuarter",
+    "PlayerGameUsage",
+    "PlayerPPA",
+    "AdvancedGameInfo",
+    "AdvancedTeamStats",
+    "AdvancedPlayerStats",
+    "AdvancedBoxScore",
+]