cfb-data 0.5.1__tar.gz → 0.7.0__tar.gz

{cfb_data-0.5.1 → cfb_data-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cfb-data
-Version: 0.5.1
+Version: 0.7.0
 Summary: Async validated CollegeFootballData access for pandas and Polars
 Author: Ryan Anderson
 License-Expression: MIT
@@ -24,7 +24,7 @@ Requires-Dist: pyarrow<26,>=25
 Provides-Extra: polars
 Requires-Dist: polars<2,>=1.43.2; extra == "polars"
 Provides-Extra: redis
-Requires-Dist: redis<8,>=7.1; extra == "redis"
+Requires-Dist: redis<9,>=7.1; extra == "redis"
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.5; extra == "dev"
 Requires-Dist: furo>=2025.12.19; extra == "dev"
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 # College Football Data Python Toolkit
 
-`cfb-data` 0.5.1 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.7.0 is a pre-alpha Python toolkit for exploring the public
 [CollegeFootballData API](https://collegefootballdata.com/). Most calls return
 eager pandas DataFrames that are ready for analysis. Polars is available as an
 option, and a few naturally nested results return Pydantic models.
@@ -231,9 +231,28 @@ async with CFBDClient(cache=cache) as client:
     games = await client.games.list(year=2025)
 ```
 
+Add a bounded in-memory collector when you want to see whether calls reached
+the API or were served from cache:
+
+```python
+from cfb_data import CFBDClient, RetrievalStats, SQLiteCacheConfig
+
+stats = RetrievalStats()
+
+async with CFBDClient(cache=SQLiteCacheConfig(), observer=stats) as client:
+    await client.games.list(year=2025)
+    await client.games.list(year=2025)
+
+snapshot = stats.snapshot()
+print(snapshot.http_attempts)       # actual client-side HTTP attempts
+print(snapshot.fresh_cache_hits)    # fresh initial cache hits
+print(snapshot.fresh_hit_rate)
+```
+
 See [Cache responses and look up
 identities](docs/guides/cache-and-identities.md) for use cases, the included
-local Redis setup, cache modes, identity examples, and troubleshooting.
+local Redis setup, cache modes, observability, identity examples, and
+troubleshooting.
 
 ## Troubleshooting
 
@@ -258,6 +277,9 @@ is organized in layers:
   behavior.
 - **Project internals:** architecture decisions and contributor-facing design.
 
+The [product constitution](docs/product-constitution.md) is the concise north
+star used to evaluate product and engineering decisions.
+
 The project is pre-alpha, and the documentation describes the current version.
 
 ## Development

{cfb_data-0.5.1 → cfb_data-0.7.0}/README.md

@@ -1,6 +1,6 @@
 # College Football Data Python Toolkit
 
-`cfb-data` 0.5.1 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.7.0 is a pre-alpha Python toolkit for exploring the public
 [CollegeFootballData API](https://collegefootballdata.com/). Most calls return
 eager pandas DataFrames that are ready for analysis. Polars is available as an
 option, and a few naturally nested results return Pydantic models.
@@ -190,9 +190,28 @@ async with CFBDClient(cache=cache) as client:
     games = await client.games.list(year=2025)
 ```
 
+Add a bounded in-memory collector when you want to see whether calls reached
+the API or were served from cache:
+
+```python
+from cfb_data import CFBDClient, RetrievalStats, SQLiteCacheConfig
+
+stats = RetrievalStats()
+
+async with CFBDClient(cache=SQLiteCacheConfig(), observer=stats) as client:
+    await client.games.list(year=2025)
+    await client.games.list(year=2025)
+
+snapshot = stats.snapshot()
+print(snapshot.http_attempts)       # actual client-side HTTP attempts
+print(snapshot.fresh_cache_hits)    # fresh initial cache hits
+print(snapshot.fresh_hit_rate)
+```
+
 See [Cache responses and look up
 identities](docs/guides/cache-and-identities.md) for use cases, the included
-local Redis setup, cache modes, identity examples, and troubleshooting.
+local Redis setup, cache modes, observability, identity examples, and
+troubleshooting.
 
 ## Troubleshooting
 
@@ -217,6 +236,9 @@ is organized in layers:
   behavior.
 - **Project internals:** architecture decisions and contributor-facing design.
 
+The [product constitution](docs/product-constitution.md) is the concise north
+star used to evaluate product and engineering decisions.
+
 The project is pre-alpha, and the documentation describes the current version.
 
 ## Development

{cfb_data-0.5.1 → cfb_data-0.7.0}/cfb_data/cfb_data/__init__.py

@@ -94,6 +94,13 @@ from .metrics.models.pydantic.requests import (
     TeamSeasonPPARequest,
     WinProbabilityRequest,
 )
+from .observability import (
+    EndpointRetrievalStats,
+    RetrievalEvent,
+    RetrievalObserver,
+    RetrievalStats,
+    RetrievalStatsSnapshot,
+)
 from .players.models.pydantic.identity import AthleteIdentity
 from .players.models.pydantic.requests import (
     PlayerSearchRequest,
@@ -210,6 +217,7 @@ __all__ = [
     "DraftPicksRequest",
     "DrivesRequest",
     "EloRatingsRequest",
+    "EndpointRetrievalStats",
     "ExpandedSRSRatingsRequest",
     "FPIRatingsRequest",
     "FreshnessMode",
@@ -249,6 +257,10 @@ __all__ = [
     "RecruitingPlayersRequest",
     "RecruitingTeamsRequest",
     "RedisCacheConfig",
+    "RetrievalEvent",
+    "RetrievalObserver",
+    "RetrievalStats",
+    "RetrievalStatsSnapshot",
     "RetryPolicy",
     "RosterRequest",
     "ReturningProductionRequest",

{cfb_data-0.5.1 → cfb_data-0.7.0}/cfb_data/cfb_data/_executor.py

@@ -2,12 +2,19 @@
 
 from __future__ import annotations
 
+import asyncio
 import hashlib
 import json
+from collections.abc import Callable
 from typing import TypeVar
 
 from pydantic import BaseModel, TypeAdapter, ValidationError
 
+from cfb_data._observability import (
+    _EventDispatcher,
+    _failure_category,
+    _OperationContext,
+)
 from cfb_data._transport import _HTTPTransport
 from cfb_data.base.types import (
     json_list,
@@ -21,6 +28,11 @@ from cfb_data.errors import (
     CFBDResponseValidationError,
     _sanitized_cause,
 )
+from cfb_data.observability import (
+    RetrievalFinished,
+    RetrievalOutcome,
+    RetrievalStarted,
+)
 
 _ModelT = TypeVar("_ModelT", bound=BaseModel)
 _ValueT = TypeVar("_ValueT")
@@ -30,14 +42,21 @@ class _EndpointExecutor:
     """Return validated models without depending on DataFrame presentation."""
 
     def __init__(
-        self, transport: _HTTPTransport, cache_coordinator: CacheCoordinator
+        self,
+        transport: _HTTPTransport,
+        cache_coordinator: CacheCoordinator,
+        *,
+        event_dispatcher: _EventDispatcher,
     ) -> None:
         """Bind endpoint execution to one owned transport.
 
         :param transport: Context-managed transport used by all endpoint calls.
+        :param cache_coordinator: Cache policy and refresh coordinator.
+        :param event_dispatcher: Optional-observer event dispatcher.
         """
         self._transport = transport
         self._cache_coordinator = cache_coordinator
+        self._event_dispatcher = event_dispatcher
 
     async def fetch_many(
         self,
@@ -54,9 +73,9 @@ class _EndpointExecutor:
         :return: Validated models in upstream row order.
         :raises CFBDResponseValidationError: If response shape or values fail.
         """
-        return await self._cache_coordinator.execute(
+        return await self._execute(
             endpoint=endpoint,
-            parameters=_serialize_request(endpoint, request),
+            request=request,
             response_contract=_response_contract(response_adapter),
             validate=lambda raw: _validate_many(endpoint, raw, response_adapter),
         )
@@ -76,9 +95,9 @@ class _EndpointExecutor:
         :return: Validated response model.
         :raises CFBDResponseValidationError: If response shape or values fail.
         """
-        return await self._cache_coordinator.execute(
+        return await self._execute(
             endpoint=endpoint,
-            parameters=_serialize_request(endpoint, request),
+            request=request,
             response_contract=_response_contract(response_adapter),
             validate=lambda raw: _validate_one(endpoint, raw, response_adapter),
         )
@@ -98,13 +117,88 @@ class _EndpointExecutor:
         :return: Validated values in upstream order.
         :raises CFBDResponseValidationError: If response shape or values fail.
         """
-        return await self._cache_coordinator.execute(
+        return await self._execute(
             endpoint=endpoint,
-            parameters=_serialize_request(endpoint, request),
+            request=request,
             response_contract=_response_contract(response_adapter),
             validate=lambda raw: _validate_values(endpoint, raw, response_adapter),
         )
 
+    async def _execute[ValueT](
+        self,
+        *,
+        endpoint: str,
+        request: BaseModel,
+        response_contract: str,
+        validate: Callable[[object], ValueT],
+    ) -> ValueT:
+        """Execute and observe one serialized, validated endpoint retrieval.
+
+        :param endpoint: Fixed endpoint path.
+        :param request: Validated endpoint request model.
+        :param response_contract: Stable response-schema fingerprint.
+        :param validate: Callable that validates the decoded response.
+        :return: Validated response value.
+        """
+        parameters = _serialize_request(endpoint, request)
+        context = self._event_dispatcher.new_operation(endpoint)
+        if context is not None:
+            self._event_dispatcher.emit(
+                RetrievalStarted(
+                    client_id=context.client_id,
+                    operation_id=context.operation_id,
+                    endpoint=endpoint,
+                    parameter_names=tuple(sorted(parameters)),
+                    cache_mode=self._cache_coordinator.current_mode,
+                )
+            )
+        try:
+            value = await self._cache_coordinator.execute(
+                endpoint=endpoint,
+                parameters=parameters,
+                response_contract=response_contract,
+                validate=validate,
+                context=context,
+            )
+        except asyncio.CancelledError as exc:
+            self._emit_finished(context, RetrievalOutcome.cancelled, None, exc)
+            raise
+        except Exception as exc:
+            self._emit_finished(context, RetrievalOutcome.error, None, exc)
+            raise
+        self._emit_finished(context, RetrievalOutcome.success, _row_count(value), None)
+        return value
+
+    def _emit_finished(
+        self,
+        context: _OperationContext | None,
+        outcome: RetrievalOutcome,
+        row_count: int | None,
+        error: BaseException | None,
+    ) -> None:
+        """Emit one terminal retrieval event when observation is enabled."""
+        if context is None or not self._event_dispatcher.enabled:
+            return
+        self._event_dispatcher.emit(
+            RetrievalFinished(
+                client_id=context.client_id,
+                operation_id=context.operation_id,
+                endpoint=context.endpoint,
+                outcome=outcome,
+                source=context.source,
+                row_count=row_count,
+                duration_seconds=self._event_dispatcher.elapsed(context.started_at),
+                failure_category=(
+                    _failure_category(error) if error is not None else None
+                ),
+            )
+        )
+
+
+def _row_count(value: object) -> int:
+    """Return the validated logical row count for one endpoint result."""
+    return len(value) if isinstance(value, list) else 1
+
 
 def _serialize_request(
     endpoint: str, request: BaseModel

cfb_data-0.7.0/cfb_data/cfb_data/_observability.py

@@ -0,0 +1,111 @@
+"""Dispatch public observability events without affecting retrieval behavior."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cfb_data.observability import (
+    RetrievalEvent,
+    RetrievalObserver,
+    RetrievalSource,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class _OperationContext:
+    """Carry safe correlation state across cache and transport boundaries."""
+
+    client_id: str
+    operation_id: str
+    endpoint: str
+    started_at: float
+    source: RetrievalSource = RetrievalSource.unknown
+    refresh_id: str | None = None
+
+
+class _EventDispatcher:
+    """Deliver ordered events and isolate failures in an optional observer."""
+
+    def __init__(
+        self,
+        observer: RetrievalObserver | None,
+        *,
+        monotonic: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Initialize one client-scoped dispatcher.
+
+        :param observer: Optional synchronous event observer.
+        :param monotonic: Monotonic clock used for bounded durations.
+        """
+        self._observer = observer
+        self._monotonic = monotonic
+        self._client_id = uuid.uuid4().hex
+
+    @property
+    def enabled(self) -> bool:
+        """Return whether a healthy observer is currently configured."""
+        return self._observer is not None
+
+    @property
+    def client_id(self) -> str:
+        """Return this dispatcher's non-secret client correlation identifier."""
+        return self._client_id
+
+    def new_operation(self, endpoint: str) -> _OperationContext | None:
+        """Return a new safe operation context when observation is enabled."""
+        if self._observer is None:
+            return None
+        return _OperationContext(
+            client_id=self._client_id,
+            operation_id=uuid.uuid4().hex,
+            endpoint=endpoint,
+            started_at=self._monotonic(),
+        )
+
+    def new_refresh_id(self) -> str:
+        """Return a non-secret identifier for one shared refresh."""
+        return uuid.uuid4().hex
+
+    def now(self) -> float:
+        """Return the current monotonic clock value."""
+        return self._monotonic()
+
+    def elapsed(self, started_at: float) -> float:
+        """Return a finite non-negative elapsed duration."""
+        return max(0.0, self._monotonic() - started_at)
+
+    def emit(self, event: RetrievalEvent) -> None:
+        """Deliver one event or disable a failing observer without propagating."""
+        observer = self._observer
+        if observer is None:
+            return
+        try:
+            observer(event)
+        except (Exception, asyncio.CancelledError) as exc:
+            self._observer = None
+            _LOGGER.warning(
+                "CFBD retrieval observer disabled event=%s category=%s",
+                type(event).__name__,
+                type(exc).__name__,
+            )
+
+
+def _failure_category(error: BaseException) -> str:
+    """Return a bounded safe category without retaining an exception object."""
+    category = getattr(error, "category", None)
+    if isinstance(category, str) and category:
+        return category[:64]
+    status = getattr(error, "status", None)
+    if isinstance(status, int):
+        return f"http_{status}"
+    return type(error).__name__[:64]
+
+
+__all__ = ["_EventDispatcher", "_OperationContext", "_failure_category"]

{cfb_data-0.5.1 → cfb_data-0.7.0}/cfb_data/cfb_data/_transport.py

@@ -17,6 +17,11 @@ from urllib.parse import urlsplit
 
 import aiohttp
 
+from cfb_data._observability import (
+    _EventDispatcher,
+    _failure_category,
+    _OperationContext,
+)
 from cfb_data.base.types import QueryParameters
 from cfb_data.cache._models import MAX_RESPONSE_BODY_BYTES
 from cfb_data.errors import (
@@ -35,6 +40,11 @@ from cfb_data.errors import (
     _sanitized_cause,
     _SanitizedCause,
 )
+from cfb_data.observability import (
+    HTTPAttemptFinished,
+    HTTPAttemptOutcome,
+    HTTPAttemptStarted,
+)
 from cfb_data.retry import RetryPolicy
 
 _LOGGER = logging.getLogger(__name__)
@@ -91,6 +101,7 @@ class _HTTPTransport:
         base_url: str,
         timeout_seconds: float,
         retry_policy: RetryPolicy,
+        event_dispatcher: _EventDispatcher,
         sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
         random_source: Callable[[], float] = random.random,
         utc_now: Callable[[], datetime] | None = None,
@@ -101,6 +112,7 @@ class _HTTPTransport:
         :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 event_dispatcher: Client-scoped retrieval event dispatcher.
         :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.
@@ -110,6 +122,7 @@ class _HTTPTransport:
         self._timeout_seconds = timeout_seconds
         self._timeout = aiohttp.ClientTimeout(total=timeout_seconds)
         self._retry_policy = retry_policy
+        self._event_dispatcher = event_dispatcher
         self._sleep = sleep
         self._random_source = random_source
         self._utc_now = utc_now or (lambda: datetime.now(UTC))
@@ -181,12 +194,16 @@ class _HTTPTransport:
         params: QueryParameters,
         *,
         conditional_headers: Mapping[str, str] | None = None,
+        context: _OperationContext | None = None,
+        refresh_id: str | None = None,
     ) -> _ResponseEnvelope:
         """Return one bounded response envelope using safe-GET retries.
 
         :param endpoint: Fixed endpoint path without query parameters.
         :param params: Validated scalar query parameters.
         :param conditional_headers: Safe validators for retained records.
+        :param context: Optional safe endpoint-operation correlation context.
+        :param refresh_id: Optional shared-refresh correlation identifier.
         :return: Decoded response and cache-relevant metadata.
         :raises CFBDClientStateError: If used outside its active context.
         :raises CFBDHTTPError: If the API returns an unsuccessful status.
@@ -197,6 +214,12 @@ class _HTTPTransport:
         url = f"{self._base_url}{endpoint}"
 
         for attempt in range(1, self._retry_policy.max_attempts + 1):
+            attempt_started_at = self._start_attempt(
+                context=context,
+                refresh_id=refresh_id,
+                endpoint=endpoint,
+                attempt=attempt,
+            )
             failure: _TransportFailure | None = None
             try:
                 result = await self._request_once(
@@ -208,6 +231,42 @@ class _HTTPTransport:
                     conditional_headers=conditional_headers,
                 )
             except asyncio.CancelledError:
+                self._finish_attempt(
+                    context=context,
+                    refresh_id=refresh_id,
+                    endpoint=endpoint,
+                    attempt=attempt,
+                    started_at=attempt_started_at,
+                    outcome=HTTPAttemptOutcome.cancelled,
+                    terminal=True,
+                    failure_category="cancelled",
+                )
+                raise
+            except CFBDHTTPError as exc:
+                self._finish_attempt(
+                    context=context,
+                    refresh_id=refresh_id,
+                    endpoint=endpoint,
+                    attempt=attempt,
+                    started_at=attempt_started_at,
+                    outcome=HTTPAttemptOutcome.http_error,
+                    terminal=True,
+                    status_class=exc.status // 100,
+                    failure_category=f"http_{exc.status}",
+                )
+                raise
+            except (CFBDNoContentError, CFBDResponseDecodeError) as exc:
+                self._finish_attempt(
+                    context=context,
+                    refresh_id=refresh_id,
+                    endpoint=endpoint,
+                    attempt=attempt,
+                    started_at=attempt_started_at,
+                    outcome=HTTPAttemptOutcome.response_error,
+                    terminal=True,
+                    status_class=(2 if isinstance(exc, CFBDNoContentError) else None),
+                    failure_category=_failure_category(exc),
+                )
                 raise
             except aiohttp.InvalidURL as exc:
                 failure = _TransportFailure(
@@ -270,17 +329,66 @@ class _HTTPTransport:
 
             if failure is not None:
                 if failure.retryable and attempt < self._retry_policy.max_attempts:
-                    await self._retry_after_failure(
+                    delay = self._backoff_delay(attempt)
+                    self._finish_attempt(
+                        context=context,
+                        refresh_id=refresh_id,
                         endpoint=endpoint,
                         attempt=attempt,
-                        category=failure.category,
+                        started_at=attempt_started_at,
+                        outcome=HTTPAttemptOutcome.retry,
+                        terminal=False,
+                        retry_delay_seconds=delay,
+                        failure_category=failure.category,
+                    )
+                    _LOGGER.debug(
+                        "Retrying CFBD GET endpoint=%s category=%s "
+                        "attempt=%d delay=%.3f",
+                        endpoint,
+                        failure.category,
+                        attempt,
+                        delay,
                     )
+                    await self._sleep(delay)
                     continue
+                self._finish_attempt(
+                    context=context,
+                    refresh_id=refresh_id,
+                    endpoint=endpoint,
+                    attempt=attempt,
+                    started_at=attempt_started_at,
+                    outcome=HTTPAttemptOutcome.transport_error,
+                    terminal=True,
+                    failure_category=failure.category,
+                )
                 raise failure.error from failure.cause
 
             if not isinstance(result, _RetryDecision):
+                self._finish_attempt(
+                    context=context,
+                    refresh_id=refresh_id,
+                    endpoint=endpoint,
+                    attempt=attempt,
+                    started_at=attempt_started_at,
+                    outcome=HTTPAttemptOutcome.success,
+                    terminal=True,
+                    status_class=result.status // 100,
+                    response_bytes=len(result.raw_body),
+                )
                 return result
 
+            self._finish_attempt(
+                context=context,
+                refresh_id=refresh_id,
+                endpoint=endpoint,
+                attempt=attempt,
+                started_at=attempt_started_at,
+                outcome=HTTPAttemptOutcome.retry,
+                terminal=False,
+                status_class=result.error.status // 100,
+                retry_delay_seconds=result.delay_seconds,
+                failure_category=result.category,
+            )
             _LOGGER.debug(
                 "Retrying CFBD GET endpoint=%s category=%s attempt=%d delay=%.3f",
                 endpoint,
@@ -382,23 +490,68 @@ class _HTTPTransport:
                 attempts=attempt,
             ) from safe_cause
 
-    async def _retry_after_failure(
+    def _start_attempt(
         self,
         *,
+        context: _OperationContext | None,
+        refresh_id: str | None,
         endpoint: str,
         attempt: int,
-        category: str,
+    ) -> float | None:
+        """Emit one attempt start and return its monotonic start time."""
+        if context is None or refresh_id is None or not self._event_dispatcher.enabled:
+            return None
+        started_at = self._event_dispatcher.now()
+        self._event_dispatcher.emit(
+            HTTPAttemptStarted(
+                client_id=context.client_id,
+                operation_id=context.operation_id,
+                refresh_id=refresh_id,
+                endpoint=endpoint,
+                attempt_number=attempt,
+            )
+        )
+        return started_at
+
+    def _finish_attempt(
+        self,
+        *,
+        context: _OperationContext | None,
+        refresh_id: str | None,
+        endpoint: str,
+        attempt: int,
+        started_at: float | None,
+        outcome: HTTPAttemptOutcome,
+        terminal: bool,
+        status_class: int | None = None,
+        response_bytes: int = 0,
+        retry_delay_seconds: float | None = None,
+        failure_category: str | None = None,
     ) -> 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,
+        """Emit one bounded terminal event for a started HTTP attempt."""
+        if (
+            context is None
+            or refresh_id is None
+            or started_at is None
+            or not self._event_dispatcher.enabled
+        ):
+            return
+        self._event_dispatcher.emit(
+            HTTPAttemptFinished(
+                client_id=context.client_id,
+                operation_id=context.operation_id,
+                refresh_id=refresh_id,
+                endpoint=endpoint,
+                attempt_number=attempt,
+                outcome=outcome,
+                terminal=terminal,
+                status_class=status_class,
+                duration_seconds=self._event_dispatcher.elapsed(started_at),
+                response_bytes=response_bytes,
+                retry_delay_seconds=retry_delay_seconds,
+                failure_category=failure_category,
+            )
         )
-        await self._sleep(delay)
 
     def _backoff_delay(self, attempt: int) -> float:
         """Return capped exponential full-jitter backoff after an attempt."""