cfb-data 0.4.1__py3-none-any.whl

cfb_data/_transport.py

@@ -0,0 +1,452 @@
+"""Own HTTP resources and retry policy for the public client."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import math
+import os
+import random
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from enum import Enum, auto
+from urllib.parse import urlsplit
+
+import aiohttp
+
+from cfb_data.base.types import QueryParameters
+from cfb_data.errors import (
+    CFBDAuthenticationError,
+    CFBDAuthorizationError,
+    CFBDClientStateError,
+    CFBDConfigurationError,
+    CFBDHTTPError,
+    CFBDRateLimitError,
+    CFBDResponseDecodeError,
+    CFBDServerError,
+    CFBDTimeoutError,
+    CFBDTLSError,
+    CFBDTransportError,
+    _sanitized_cause,
+    _SanitizedCause,
+)
+from cfb_data.retry import RetryPolicy
+
+_LOGGER = logging.getLogger(__name__)
+_RETRYABLE_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+
+
+class _TransportState(Enum):
+    """Track the one-shot session lifecycle."""
+
+    new = auto()
+    active = auto()
+    closed = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class _RetryDecision:
+    """Carry a retry outside the response context so its connection is released."""
+
+    error: CFBDHTTPError
+    delay_seconds: float
+    category: str
+
+
+@dataclass(frozen=True, slots=True)
+class _TransportFailure:
+    """Carry a safely detached transport failure outside its exception handler."""
+
+    error: CFBDTransportError
+    cause: _SanitizedCause
+    category: str
+    retryable: bool
+
+
+class _HTTPTransport:
+    """Own one reusable :class:`aiohttp.ClientSession` and its connection pool."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout_seconds: float,
+        retry_policy: RetryPolicy,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        random_source: Callable[[], float] = random.random,
+        utc_now: Callable[[], datetime] | None = None,
+    ) -> None:
+        """Initialize transport configuration without opening resources.
+
+        :param api_key: Non-empty CFBD bearer token.
+        :param base_url: Validated API origin and optional base path.
+        :param timeout_seconds: Finite timeout applied to each attempt.
+        :param retry_policy: Bounded GET retry configuration.
+        :param sleep: Awaitable delay function used by retries.
+        :param random_source: Uniform random source in the inclusive range 0..1.
+        :param utc_now: Clock used to interpret HTTP-date ``Retry-After`` values.
+        """
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = aiohttp.ClientTimeout(total=timeout_seconds)
+        self._retry_policy = retry_policy
+        self._sleep = sleep
+        self._random_source = random_source
+        self._utc_now = utc_now or (lambda: datetime.now(UTC))
+        self._state = _TransportState.new
+        self._session: aiohttp.ClientSession | None = None
+
+    async def open(self) -> None:
+        """Create the one session owned by this transport.
+
+        :raises CFBDClientStateError: If the one-shot transport is not new.
+        """
+        if self._state is not _TransportState.new:
+            raise CFBDClientStateError(
+                "CFBDClient can be entered exactly once and cannot be nested"
+            )
+
+        try:
+            session = aiohttp.ClientSession(
+                headers={
+                    "Accept": "application/json",
+                    "Authorization": f"Bearer {self._api_key}",
+                },
+                timeout=self._timeout,
+                trust_env=False,
+            )
+        except Exception:
+            self._state = _TransportState.closed
+            raise
+
+        self._session = session
+        self._state = _TransportState.active
+
+    async def close(self) -> None:
+        """Close the owned session and permanently retire this transport.
+
+        :raises CFBDClientStateError: If no active context owns a session.
+        """
+        if self._state is not _TransportState.active or self._session is None:
+            raise CFBDClientStateError("CFBDClient has no active session to close")
+
+        session = self._session
+        self._session = None
+        self._state = _TransportState.closed
+        await session.close()
+
+    async def get_json(
+        self,
+        endpoint: str,
+        params: QueryParameters,
+    ) -> object:
+        """Return one decoded JSON response using bounded safe-GET retries.
+
+        :param endpoint: Fixed endpoint path without query parameters.
+        :param params: Validated scalar query parameters.
+        :return: Value produced by the response JSON decoder.
+        :raises CFBDClientStateError: If used outside its active context.
+        :raises CFBDHTTPError: If the API returns an unsuccessful status.
+        :raises CFBDTransportError: If transport attempts are exhausted.
+        :raises CFBDResponseDecodeError: If a response is not valid JSON.
+        """
+        session = self._active_session()
+        url = f"{self._base_url}{endpoint}"
+
+        for attempt in range(1, self._retry_policy.max_attempts + 1):
+            failure: _TransportFailure | None = None
+            try:
+                result = await self._request_once(
+                    session=session,
+                    url=url,
+                    endpoint=endpoint,
+                    params=params,
+                    attempt=attempt,
+                )
+            except asyncio.CancelledError:
+                raise
+            except aiohttp.InvalidURL as exc:
+                failure = _TransportFailure(
+                    error=CFBDTransportError(
+                        endpoint=endpoint,
+                        attempts=attempt,
+                        category="invalid_url",
+                    ),
+                    cause=_sanitized_cause(exc),
+                    category="invalid_url",
+                    retryable=False,
+                )
+            except aiohttp.ClientSSLError as exc:
+                failure = _TransportFailure(
+                    error=CFBDTLSError(endpoint=endpoint, attempts=attempt),
+                    cause=_sanitized_cause(exc),
+                    category="tls",
+                    retryable=False,
+                )
+            except TimeoutError as exc:
+                failure = _TransportFailure(
+                    error=CFBDTimeoutError(endpoint=endpoint, attempts=attempt),
+                    cause=_sanitized_cause(exc),
+                    category="timeout",
+                    retryable=True,
+                )
+            except aiohttp.ClientPayloadError as exc:
+                failure = _TransportFailure(
+                    error=CFBDTransportError(
+                        endpoint=endpoint,
+                        attempts=attempt,
+                        category="truncated_payload",
+                    ),
+                    cause=_sanitized_cause(exc),
+                    category="truncated_payload",
+                    retryable=True,
+                )
+            except aiohttp.ClientConnectionError as exc:
+                failure = _TransportFailure(
+                    error=CFBDTransportError(
+                        endpoint=endpoint,
+                        attempts=attempt,
+                        category="connection",
+                    ),
+                    cause=_sanitized_cause(exc),
+                    category="connection",
+                    retryable=True,
+                )
+            except aiohttp.ClientError as exc:
+                failure = _TransportFailure(
+                    error=CFBDTransportError(
+                        endpoint=endpoint,
+                        attempts=attempt,
+                        category="client",
+                    ),
+                    cause=_sanitized_cause(exc),
+                    category="client",
+                    retryable=False,
+                )
+
+            if failure is not None:
+                if failure.retryable and attempt < self._retry_policy.max_attempts:
+                    await self._retry_after_failure(
+                        endpoint=endpoint,
+                        attempt=attempt,
+                        category=failure.category,
+                    )
+                    continue
+                raise failure.error from failure.cause
+
+            if not isinstance(result, _RetryDecision):
+                return result
+
+            _LOGGER.debug(
+                "Retrying CFBD GET endpoint=%s category=%s attempt=%d delay=%.3f",
+                endpoint,
+                result.category,
+                attempt,
+                result.delay_seconds,
+            )
+            await self._sleep(result.delay_seconds)
+
+        raise AssertionError("retry loop exhausted without returning or raising")
+
+    async def _request_once(
+        self,
+        *,
+        session: aiohttp.ClientSession,
+        url: str,
+        endpoint: str,
+        params: QueryParameters,
+        attempt: int,
+    ) -> object | _RetryDecision:
+        """Perform one attempt and release its response before any retry delay."""
+        async with session.get(
+            url,
+            params=params,
+            allow_redirects=False,
+        ) as response:
+            if response.status >= 300:
+                retry_after = self._parse_retry_after(
+                    response.headers.get("Retry-After")
+                )
+                error = _http_error(
+                    endpoint=endpoint,
+                    status=response.status,
+                    attempts=attempt,
+                    retry_after_seconds=retry_after,
+                )
+                if (
+                    response.status in _RETRYABLE_STATUSES
+                    and retry_after is not None
+                    and retry_after > self._retry_policy.max_retry_after_seconds
+                ):
+                    raise error
+                if (
+                    response.status in _RETRYABLE_STATUSES
+                    and attempt < self._retry_policy.max_attempts
+                ):
+                    delay = retry_after
+                    if delay is None:
+                        delay = self._backoff_delay(attempt)
+                    return _RetryDecision(
+                        error=error,
+                        delay_seconds=delay,
+                        category=f"http_{response.status}",
+                    )
+                raise error
+
+            try:
+                decoded: object = await response.json()
+            except (
+                aiohttp.ContentTypeError,
+                json.JSONDecodeError,
+                UnicodeDecodeError,
+            ) as exc:
+                safe_cause = _sanitized_cause(exc)
+            else:
+                return decoded
+            raise CFBDResponseDecodeError(
+                endpoint=endpoint,
+                attempts=attempt,
+            ) from safe_cause
+
+    async def _retry_after_failure(
+        self,
+        *,
+        endpoint: str,
+        attempt: int,
+        category: str,
+    ) -> None:
+        """Log and apply one client-selected full-jitter delay."""
+        delay = self._backoff_delay(attempt)
+        _LOGGER.debug(
+            "Retrying CFBD GET endpoint=%s category=%s attempt=%d delay=%.3f",
+            endpoint,
+            category,
+            attempt,
+            delay,
+        )
+        await self._sleep(delay)
+
+    def _backoff_delay(self, attempt: int) -> float:
+        """Return capped exponential full-jitter backoff after an attempt."""
+        backoff_multiplier: float = 2.0 ** (attempt - 1)
+        ceiling: float = min(
+            self._retry_policy.max_backoff_seconds,
+            self._retry_policy.base_delay_seconds * backoff_multiplier,
+        )
+        random_fraction: float = self._random_source()
+        if not 0 <= random_fraction <= 1:
+            raise ValueError("random_source must return a value from 0 through 1")
+        return random_fraction * ceiling
+
+    def _parse_retry_after(self, value: str | None) -> float | None:
+        """Parse a numeric or HTTP-date ``Retry-After`` value."""
+        if value is None:
+            return None
+
+        numeric = True
+        try:
+            seconds = float(value)
+        except ValueError:
+            numeric = False
+            try:
+                retry_at = parsedate_to_datetime(value)
+            except (TypeError, ValueError, OverflowError):
+                return None
+            if retry_at.tzinfo is None or retry_at.utcoffset() is None:
+                retry_at = retry_at.replace(tzinfo=UTC)
+            seconds = max(
+                0.0,
+                (retry_at.astimezone(UTC) - self._utc_now()).total_seconds(),
+            )
+
+        if not math.isfinite(seconds) or (numeric and seconds < 0):
+            return None
+        return seconds
+
+    def _active_session(self) -> aiohttp.ClientSession:
+        """Return the active session or reject calls outside the context."""
+        if self._state is not _TransportState.active or self._session is None:
+            raise CFBDClientStateError(
+                "Endpoint calls require an active 'async with CFBDClient(...)' context"
+            )
+        return self._session
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    """Resolve and validate explicit or environment authentication.
+
+    :param api_key: Explicit key, or ``None`` to consult ``CFBD_API_KEY``.
+    :return: Non-empty bearer token.
+    :raises CFBDConfigurationError: If the selected credential is empty or absent.
+    """
+    if api_key is not None:
+        if not api_key.strip():
+            raise CFBDConfigurationError("Explicit api_key cannot be empty")
+        return api_key
+
+    environment_key = os.getenv("CFBD_API_KEY")
+    if environment_key is None or not environment_key.strip():
+        raise CFBDConfigurationError(
+            "Provide api_key or set a non-empty CFBD_API_KEY environment variable"
+        )
+    return environment_key
+
+
+def _validate_base_url(base_url: str) -> str:
+    """Return a normalized HTTP(S) base URL without unsafe components.
+
+    :param base_url: API origin and optional base path.
+    :return: Base URL without trailing slashes.
+    :raises CFBDConfigurationError: If the URL cannot safely identify an origin.
+    """
+    parsed = urlsplit(base_url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise CFBDConfigurationError("base_url must be an absolute HTTP(S) URL")
+    if parsed.username is not None or parsed.password is not None:
+        raise CFBDConfigurationError("base_url must not contain credentials")
+    if parsed.query or parsed.fragment:
+        raise CFBDConfigurationError("base_url must not contain a query or fragment")
+    return base_url.rstrip("/")
+
+
+def _validate_timeout(timeout_seconds: float) -> float:
+    """Return a finite positive per-attempt timeout.
+
+    :param timeout_seconds: Configured timeout in seconds.
+    :return: Validated timeout.
+    :raises CFBDConfigurationError: If the timeout is not finite and positive.
+    """
+    if not math.isfinite(timeout_seconds) or timeout_seconds <= 0:
+        raise CFBDConfigurationError("timeout_seconds must be finite and positive")
+    return timeout_seconds
+
+
+def _http_error(
+    *,
+    endpoint: str,
+    status: int,
+    attempts: int,
+    retry_after_seconds: float | None,
+) -> CFBDHTTPError:
+    """Create the most specific safe HTTP exception for a response status."""
+    error_type: type[CFBDHTTPError]
+    if status == 401:
+        error_type = CFBDAuthenticationError
+    elif status == 403:
+        error_type = CFBDAuthorizationError
+    elif status == 429:
+        error_type = CFBDRateLimitError
+    elif status >= 500:
+        error_type = CFBDServerError
+    else:
+        error_type = CFBDHTTPError
+    return error_type(
+        endpoint=endpoint,
+        status=status,
+        attempts=attempts,
+        retry_after_seconds=retry_after_seconds,
+    )

cfb_data/adjusted_metrics/__init__.py

@@ -0,0 +1,29 @@
+"""Export the supported Adjusted Metrics namespace and public contracts."""
+
+from .models.pydantic import (
+    AdjustedPlayerPassingRequest,
+    AdjustedPlayerRushingRequest,
+    AdjustedTeamMetrics,
+    AdjustedTeamMetricsEPA,
+    AdjustedTeamMetricsRequest,
+    AdjustedTeamMetricsRushing,
+    AdjustedTeamMetricsSuccessRate,
+    KickerPAAR,
+    KickerPAARRequest,
+    PlayerWeightedEPA,
+)
+from .resource import AdjustedMetricsResource
+
+__all__ = [
+    "AdjustedMetricsResource",
+    "AdjustedPlayerPassingRequest",
+    "AdjustedPlayerRushingRequest",
+    "AdjustedTeamMetrics",
+    "AdjustedTeamMetricsEPA",
+    "AdjustedTeamMetricsRequest",
+    "AdjustedTeamMetricsRushing",
+    "AdjustedTeamMetricsSuccessRate",
+    "KickerPAAR",
+    "KickerPAARRequest",
+    "PlayerWeightedEPA",
+]

cfb_data/adjusted_metrics/models/__init__.py

@@ -0,0 +1 @@
+"""Export Adjusted Metrics model families."""

cfb_data/adjusted_metrics/models/pydantic/__init__.py

@@ -0,0 +1,29 @@
+"""Export validated Adjusted Metrics request and response models."""
+
+from .requests import (
+    AdjustedPlayerPassingRequest,
+    AdjustedPlayerRushingRequest,
+    AdjustedTeamMetricsRequest,
+    KickerPAARRequest,
+)
+from .responses import (
+    AdjustedTeamMetrics,
+    AdjustedTeamMetricsEPA,
+    AdjustedTeamMetricsRushing,
+    AdjustedTeamMetricsSuccessRate,
+    KickerPAAR,
+    PlayerWeightedEPA,
+)
+
+__all__ = [
+    "AdjustedPlayerPassingRequest",
+    "AdjustedPlayerRushingRequest",
+    "AdjustedTeamMetrics",
+    "AdjustedTeamMetricsEPA",
+    "AdjustedTeamMetricsRequest",
+    "AdjustedTeamMetricsRushing",
+    "AdjustedTeamMetricsSuccessRate",
+    "KickerPAAR",
+    "KickerPAARRequest",
+    "PlayerWeightedEPA",
+]

cfb_data/adjusted_metrics/models/pydantic/requests.py

@@ -0,0 +1,45 @@
+"""Validate request parameters for implemented Adjusted Metrics endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _AdjustedMetricsRequest(BaseModel):
+    """Apply the closed-object contract shared by Adjusted Metrics requests."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class _TeamFilters(_AdjustedMetricsRequest):
+    """Define team and season filters shared by adjusted metric routes."""
+
+    year: int | None = Field(default=None, ge=1869)
+    team: str | None = Field(default=None, min_length=1)
+    conference: str | None = Field(default=None, min_length=1)
+
+
+class AdjustedTeamMetricsRequest(_TeamFilters):
+    """Validate filters accepted by ``GET /wepa/team/season``."""
+
+
+class AdjustedPlayerPassingRequest(_TeamFilters):
+    """Validate filters accepted by ``GET /wepa/players/passing``."""
+
+    position: str | None = Field(default=None, min_length=1)
+
+
+class AdjustedPlayerRushingRequest(_TeamFilters):
+    """Validate filters accepted by ``GET /wepa/players/rushing``."""
+
+    position: str | None = Field(default=None, min_length=1)
+
+
+class KickerPAARRequest(_TeamFilters):
+    """Validate filters accepted by ``GET /wepa/players/kicking``."""
+
+
+__all__ = [
+    "AdjustedPlayerPassingRequest",
+    "AdjustedPlayerRushingRequest",
+    "AdjustedTeamMetricsRequest",
+    "KickerPAARRequest",
+]

cfb_data/adjusted_metrics/models/pydantic/responses.py

@@ -0,0 +1,88 @@
+"""Validate responses from implemented CFBD Adjusted Metrics endpoints."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _ResponseModel(BaseModel):
+    """Apply the upstream closed-object contract to adjusted metric responses."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class AdjustedTeamMetricsEPA(_ResponseModel):
+    """Represent opponent-adjusted EPA by play type."""
+
+    total: float
+    passing: float
+    rushing: float
+
+
+class AdjustedTeamMetricsSuccessRate(_ResponseModel):
+    """Represent opponent-adjusted success rate by down context."""
+
+    total: float = Field(ge=0, le=1)
+    standard_downs: float = Field(alias="standardDowns", ge=0, le=1)
+    passing_downs: float = Field(alias="passingDowns", ge=0, le=1)
+
+
+class AdjustedTeamMetricsRushing(_ResponseModel):
+    """Represent opponent-adjusted rushing yard components."""
+
+    line_yards: float = Field(alias="lineYards")
+    second_level_yards: float = Field(alias="secondLevelYards")
+    open_field_yards: float = Field(alias="openFieldYards")
+    highlight_yards: float = Field(alias="highlightYards")
+
+
+class AdjustedTeamMetrics(_ResponseModel):
+    """Represent opponent-adjusted team metrics for one season."""
+
+    year: int = Field(ge=1869)
+    team_id: int = Field(alias="teamId", gt=0)
+    team: str
+    conference: str
+    epa: AdjustedTeamMetricsEPA
+    epa_allowed: AdjustedTeamMetricsEPA = Field(alias="epaAllowed")
+    success_rate: AdjustedTeamMetricsSuccessRate = Field(alias="successRate")
+    success_rate_allowed: AdjustedTeamMetricsSuccessRate = Field(
+        alias="successRateAllowed"
+    )
+    rushing: AdjustedTeamMetricsRushing
+    rushing_allowed: AdjustedTeamMetricsRushing = Field(alias="rushingAllowed")
+    explosiveness: float
+    explosiveness_allowed: float = Field(alias="explosivenessAllowed")
+
+
+class PlayerWeightedEPA(_ResponseModel):
+    """Represent opponent-adjusted player EPA for one season."""
+
+    year: int = Field(ge=1869)
+    athlete_id: str = Field(alias="athleteId", min_length=1)
+    athlete_name: str = Field(alias="athleteName")
+    position: str
+    team: str
+    conference: str
+    wepa: float
+    plays: int = Field(ge=0)
+
+
+class KickerPAAR(_ResponseModel):
+    """Represent a kicker's Points Added Above Replacement rating."""
+
+    year: int = Field(ge=1869)
+    athlete_id: str = Field(alias="athleteId", min_length=1)
+    athlete_name: str = Field(alias="athleteName")
+    team: str
+    conference: str
+    paar: float
+    attempts: int = Field(ge=0)
+
+
+__all__ = [
+    "AdjustedTeamMetrics",
+    "AdjustedTeamMetricsEPA",
+    "AdjustedTeamMetricsRushing",
+    "AdjustedTeamMetricsSuccessRate",
+    "KickerPAAR",
+    "PlayerWeightedEPA",
+]