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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: cfb-data
-Version: 0.7.0
+Version: 0.8.0
 Summary: Async validated CollegeFootballData access for pandas and Polars
 Author: Ryan Anderson
 License-Expression: MIT
 Project-URL: Documentation, https://ryanpaulanderson.github.io/cfb-data/
 Project-URL: Repository, https://github.com/ryanpaulanderson/cfb-data
 Project-URL: Issues, https://github.com/ryanpaulanderson/cfb-data/issues
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
@@ -41,7 +41,7 @@ Dynamic: license-file
 
 # College Football Data Python Toolkit
 
-`cfb-data` 0.7.0 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.8.0 is a beta 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.
@@ -280,7 +280,10 @@ is organized in layers:
 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.
+The project is in beta: its core retrieval, validation, DataFrame, caching, and
+identity workflows are usable and carefully tested. Public APIs and local cache
+formats may still change before 1.0, and the documentation describes the
+current version.
 
 ## Development
 

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

@@ -1,6 +1,6 @@
 # College Football Data Python Toolkit
 
-`cfb-data` 0.7.0 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.8.0 is a beta 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.
@@ -239,7 +239,10 @@ is organized in layers:
 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.
+The project is in beta: its core retrieval, validation, DataFrame, caching, and
+identity workflows are usable and carefully tested. Public APIs and local cache
+formats may still change before 1.0, and the documentation describes the
+current version.
 
 ## Development
 

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/_dataframes.py

@@ -19,7 +19,6 @@ from cfb_data._tabular import (
 from cfb_data.errors import (
     CFBDDataFrameConversionError,
     CFBDOptionalDependencyError,
-    _sanitized_cause,
 )
 
 if TYPE_CHECKING:
@@ -78,11 +77,10 @@ class _PandasAdapter:
         except CFBDDataFrameConversionError:
             raise
         except Exception as exc:
-            safe_cause = _sanitized_cause(exc)
-        raise CFBDDataFrameConversionError(
-            endpoint=endpoint,
-            backend="pandas",
-        ) from safe_cause
+            raise CFBDDataFrameConversionError(
+                endpoint=endpoint,
+                backend="pandas",
+            ) from exc
 
     def from_table(
         self,
@@ -125,11 +123,10 @@ class _PandasAdapter:
         except CFBDDataFrameConversionError:
             raise
         except Exception as exc:
-            safe_cause = _sanitized_cause(exc)
-        raise CFBDDataFrameConversionError(
-            endpoint=endpoint,
-            backend="pandas",
-        ) from safe_cause
+            raise CFBDDataFrameConversionError(
+                endpoint=endpoint,
+                backend="pandas",
+            ) from exc
 
 
 class _PolarsAdapter:
@@ -162,11 +159,10 @@ class _PolarsAdapter:
         except CFBDDataFrameConversionError:
             raise
         except Exception as exc:
-            safe_cause = _sanitized_cause(exc)
-        raise CFBDDataFrameConversionError(
-            endpoint=endpoint,
-            backend="polars",
-        ) from safe_cause
+            raise CFBDDataFrameConversionError(
+                endpoint=endpoint,
+                backend="polars",
+            ) from exc
 
     def from_table(
         self,
@@ -229,11 +225,10 @@ class _PolarsAdapter:
         except CFBDOptionalDependencyError:
             raise
         except Exception as exc:
-            safe_cause = _sanitized_cause(exc)
-        raise CFBDDataFrameConversionError(
-            endpoint=endpoint,
-            backend="polars",
-        ) from safe_cause
+            raise CFBDDataFrameConversionError(
+                endpoint=endpoint,
+                backend="polars",
+            ) from exc
 
     @staticmethod
     def _require_polars() -> None:

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

@@ -26,7 +26,6 @@ from cfb_data.cache._coordinator import CacheCoordinator
 from cfb_data.errors import (
     CFBDRequestValidationError,
     CFBDResponseValidationError,
-    _sanitized_cause,
 )
 from cfb_data.observability import (
     RetrievalFinished,
@@ -210,8 +209,7 @@ def _serialize_request(
         )
         return parameters
     except TypeError as exc:
-        safe_cause = _sanitized_cause(exc)
-    raise CFBDRequestValidationError(endpoint=endpoint) from safe_cause
+        raise CFBDRequestValidationError(endpoint=endpoint) from exc
 
 
 def _response_contract[ValueT](response_adapter: TypeAdapter[ValueT]) -> str:
@@ -227,12 +225,11 @@ def _validate_many[ModelT: BaseModel](
     raw: object,
     response_adapter: TypeAdapter[list[ModelT]],
 ) -> list[ModelT]:
-    """Validate one decoded model-list response with a sanitized cause."""
+    """Validate one decoded model-list response with its diagnostic cause."""
     try:
         return response_adapter.validate_python(json_object_list(raw))
     except (TypeError, ValidationError) as exc:
-        safe_cause = _sanitized_cause(exc)
-    raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+        raise CFBDResponseValidationError(endpoint=endpoint) from exc
 
 
 def _validate_one[ModelT: BaseModel](
@@ -240,12 +237,11 @@ def _validate_one[ModelT: BaseModel](
     raw: object,
     response_adapter: TypeAdapter[ModelT],
 ) -> ModelT:
-    """Validate one decoded model response with a sanitized cause."""
+    """Validate one decoded model response with its diagnostic cause."""
     try:
         return response_adapter.validate_python(json_object(raw))
     except (TypeError, ValidationError) as exc:
-        safe_cause = _sanitized_cause(exc)
-    raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+        raise CFBDResponseValidationError(endpoint=endpoint) from exc
 
 
 def _validate_values[ValueT](
@@ -253,9 +249,8 @@ def _validate_values[ValueT](
     raw: object,
     response_adapter: TypeAdapter[list[ValueT]],
 ) -> list[ValueT]:
-    """Validate one decoded scalar-list response with a sanitized cause."""
+    """Validate one decoded scalar-list response with its diagnostic cause."""
     try:
         return response_adapter.validate_python(json_list(raw))
     except (TypeError, ValidationError) as exc:
-        safe_cause = _sanitized_cause(exc)
-    raise CFBDResponseValidationError(endpoint=endpoint) from safe_cause
+        raise CFBDResponseValidationError(endpoint=endpoint) from exc

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/_parquet.py

@@ -22,7 +22,7 @@ from cfb_data._tabular import (
     _ScalarEncodingError,
     _UnsupportedTableAnnotationError,
 )
-from cfb_data.errors import CFBDError, _sanitized_cause
+from cfb_data.errors import CFBDError
 
 _ParquetOperation = Literal["read", "write"]
 _ParquetErrorCategory = Literal[
@@ -39,7 +39,7 @@ _PARQUET_COMPRESSION: Final = "snappy"
 
 
 class _ParquetCodecError(CFBDError):
-    """Report a safe categorized failure in the internal Parquet codec."""
+    """Report a categorized failure in the internal Parquet codec."""
 
     operation: _ParquetOperation
     category: _ParquetErrorCategory
@@ -50,10 +50,10 @@ class _ParquetCodecError(CFBDError):
         operation: _ParquetOperation,
         category: _ParquetErrorCategory,
     ) -> None:
-        """Initialize a path- and payload-free codec failure.
+        """Initialize a categorized codec failure.
 
         :param operation: File operation that failed.
-        :param category: Safe failure classification for internal policy.
+        :param category: Failure classification for internal policy.
         """
         self.operation = operation
         self.category = category
@@ -80,9 +80,10 @@ def _write_parquet(
         _write_parquet_file(Path(path), row_model=row_model, table=table)
         return
     except Exception as exc:
-        category = _codec_error_category(exc)
-        safe_cause = _sanitized_cause(exc)
-    raise _ParquetCodecError(operation="write", category=category) from safe_cause
+        raise _ParquetCodecError(
+            operation="write",
+            category=_codec_error_category(exc),
+        ) from exc
 
 
 def _read_parquet[ModelT: BaseModel](
@@ -118,9 +119,10 @@ def _read_parquet[ModelT: BaseModel](
         )
         return table
     except Exception as exc:
-        category = _codec_error_category(exc)
-        safe_cause = _sanitized_cause(exc)
-    raise _ParquetCodecError(operation="read", category=category) from safe_cause
+        raise _ParquetCodecError(
+            operation="read",
+            category=_codec_error_category(exc),
+        ) from exc
 
 
 def _write_parquet_file(
@@ -181,7 +183,7 @@ def _read_parquet_file[ModelT: BaseModel](
 
 
 def _codec_error_category(source: Exception) -> _ParquetErrorCategory:
-    """Classify a source exception without retaining its values or path."""
+    """Classify a source exception for internal recovery policy."""
     if isinstance(source, _CanonicalTableMetadataError):
         return "metadata"
     if isinstance(source, _CanonicalTableSchemaError):

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/_requests.py

@@ -6,7 +6,7 @@ from collections.abc import Mapping
 
 from pydantic import BaseModel, ValidationError
 
-from cfb_data.errors import CFBDRequestValidationError, _sanitized_cause
+from cfb_data.errors import CFBDRequestValidationError
 
 
 def _resolve_request[RequestT: BaseModel](
@@ -32,5 +32,4 @@ def _resolve_request[RequestT: BaseModel](
     try:
         return request_type.model_validate(filters)
     except ValidationError as exc:
-        safe_cause = _sanitized_cause(exc)
-    raise CFBDRequestValidationError(endpoint=endpoint) from safe_cause
+        raise CFBDRequestValidationError(endpoint=endpoint) from exc

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

@@ -37,8 +37,6 @@ from cfb_data.errors import (
     CFBDTimeoutError,
     CFBDTLSError,
     CFBDTransportError,
-    _sanitized_cause,
-    _SanitizedCause,
 )
 from cfb_data.observability import (
     HTTPAttemptFinished,
@@ -51,6 +49,29 @@ _LOGGER = logging.getLogger(__name__)
 _RETRYABLE_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
 
 
+class _DetachedTransportCause(Exception):
+    """Retain a transport category without request metadata or credentials."""
+
+    category: str
+
+    def __init__(self, *, category: str) -> None:
+        """Initialize a credential-safe transport cause.
+
+        :param category: Source exception type name without its retained state.
+        """
+        self.category = category
+        super().__init__(category)
+
+
+def _detached_transport_cause(source: BaseException) -> _DetachedTransportCause:
+    """Detach an exception that may retain authenticated request metadata.
+
+    :param source: Transport exception whose type identifies the failure.
+    :return: New exception retaining only the source type name.
+    """
+    return _DetachedTransportCause(category=type(source).__name__)
+
+
 class _TransportState(Enum):
     """Track the one-shot session lifecycle."""
 
@@ -73,7 +94,7 @@ class _TransportFailure:
     """Carry a safely detached transport failure outside its exception handler."""
 
     error: CFBDTransportError
-    cause: _SanitizedCause
+    cause: _DetachedTransportCause
     category: str
     retryable: bool
 
@@ -275,21 +296,21 @@ class _HTTPTransport:
                         attempts=attempt,
                         category="invalid_url",
                     ),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="invalid_url",
                     retryable=False,
                 )
             except aiohttp.ClientSSLError as exc:
                 failure = _TransportFailure(
                     error=CFBDTLSError(endpoint=endpoint, attempts=attempt),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="tls",
                     retryable=False,
                 )
             except TimeoutError as exc:
                 failure = _TransportFailure(
                     error=CFBDTimeoutError(endpoint=endpoint, attempts=attempt),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="timeout",
                     retryable=True,
                 )
@@ -300,7 +321,7 @@ class _HTTPTransport:
                         attempts=attempt,
                         category="truncated_payload",
                     ),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="truncated_payload",
                     retryable=True,
                 )
@@ -311,7 +332,7 @@ class _HTTPTransport:
                         attempts=attempt,
                         category="connection",
                     ),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="connection",
                     retryable=True,
                 )
@@ -322,7 +343,7 @@ class _HTTPTransport:
                         attempts=attempt,
                         category="client",
                     ),
-                    cause=_sanitized_cause(exc),
+                    cause=_detached_transport_cause(exc),
                     category="client",
                     retryable=False,
                 )
@@ -477,18 +498,19 @@ class _HTTPTransport:
                         headers=response.headers,
                     )
                 decoded: object = json.loads(raw_body)
-            except (
-                aiohttp.ContentTypeError,
-                json.JSONDecodeError,
-                UnicodeDecodeError,
-            ) as exc:
-                safe_cause = _sanitized_cause(exc)
+            except aiohttp.ContentTypeError as exc:
+                detached_cause = _detached_transport_cause(exc)
+            except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+                raise CFBDResponseDecodeError(
+                    endpoint=endpoint,
+                    attempts=attempt,
+                ) from exc
             else:
                 return _response_envelope(response, body=decoded, raw_body=raw_body)
             raise CFBDResponseDecodeError(
                 endpoint=endpoint,
                 attempts=attempt,
-            ) from safe_cause
+            ) from detached_cause
 
     def _start_attempt(
         self,

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/cache/_backend.py

@@ -60,6 +60,16 @@ class CatalogWriter(Protocol):
         ...
 
 
+class ProjectionStateStore(Protocol):
+    """Report whether durable coverage uses the current projection contract."""
+
+    async def has_current_projection(
+        self, *, endpoint: str, canonical_filters: str
+    ) -> bool:
+        """Return whether one partition was projected by the current contract."""
+        ...
+
+
 class CoverageStore(Protocol):
     """Read and record capability-aware catalog coverage."""
 
@@ -150,6 +160,7 @@ class CacheBackend(
     BackendLifecycle,
     ResponseStore,
     CatalogWriter,
+    ProjectionStateStore,
     CoverageStore,
     LeaseStore,
     IdentityReader,

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/cache/_coordinator.py

@@ -24,7 +24,7 @@ from cfb_data._observability import (
 from cfb_data._transport import _HTTPTransport
 from cfb_data.base.types import QueryParameters
 from cfb_data.cache._backend import CacheBackend
-from cfb_data.cache._catalog import project_catalog
+from cfb_data.cache._catalog import canonical_filters, project_catalog
 from cfb_data.cache._key import response_cache_key
 from cfb_data.cache._models import MAX_RESPONSE_BODY_BYTES, ResponseRecord
 from cfb_data.cache._null import NullCacheBackend
@@ -154,6 +154,7 @@ class CacheCoordinator:
         )
         self._flights: dict[str, _FlightState] = {}
         self._flights_lock = asyncio.Lock()
+        self._catalog_write_lock = asyncio.Lock()
         self._backend_available = False
         self._transient_available = False
 
@@ -1184,8 +1185,74 @@ class CacheCoordinator:
             fresh_until=record.fresh_until,
             retained_until=record.retained_until,
         )
-        await self._commit_catalog_response(
-            "reproject", record, projection, context=context
+        filters = canonical_filters(parameters)
+        answered, current = await self._projection_is_current(
+            endpoint=endpoint,
+            canonical_filters=filters,
+            context=context,
+        )
+        if not answered:
+            await self._transient.commit_response(record, projection)
+            return
+        if current:
+            await self._mirror_catalog_projection(record, projection, context=context)
+            return
+
+        async with self._catalog_write_lock:
+            answered, current = await self._projection_is_current(
+                endpoint=endpoint,
+                canonical_filters=filters,
+                context=context,
+            )
+            if not answered:
+                await self._transient.commit_response(record, projection)
+                return
+            if current:
+                await self._mirror_catalog_projection(
+                    record, projection, context=context
+                )
+                return
+            await self._commit_catalog_response_locked(
+                "reproject",
+                record,
+                projection,
+                timeout_seconds=_MAX_CATALOG_COMMIT_TIMEOUT_SECONDS,
+                context=context,
+            )
+
+    async def _projection_is_current(
+        self,
+        *,
+        endpoint: str,
+        canonical_filters: str,
+        context: _OperationContext | None,
+    ) -> tuple[bool, bool]:
+        """Return whether durable projection metadata answered and is current."""
+        answered, current = await self._catalog_call(
+            "reproject_status",
+            self._backend.has_current_projection(
+                endpoint=endpoint,
+                canonical_filters=canonical_filters,
+            ),
+            context=context,
+        )
+        return answered, bool(current)
+
+    async def _mirror_catalog_projection(
+        self,
+        record: ResponseRecord,
+        projection: CatalogProjection,
+        *,
+        context: _OperationContext | None,
+    ) -> None:
+        """Mirror one read-only canonical merge into the transient catalog."""
+        answered, merged = await self._catalog_call(
+            "reproject_merge_read",
+            self._backend.merge_catalog_projection(record, projection),
+            context=context,
+        )
+        await self._transient.commit_response(
+            record, merged if answered and merged is not None else projection
         )
 
     async def _commit_catalog_response(
@@ -1197,10 +1264,33 @@ class CacheCoordinator:
         context: _OperationContext | None,
     ) -> None:
         """Commit durably and mirror the canonical merged state in memory."""
+        async with self._catalog_write_lock:
+            await self._commit_catalog_response_locked(
+                operation,
+                record,
+                projection,
+                timeout_seconds=None,
+                context=context,
+            )
+
+    async def _commit_catalog_response_locked(
+        self,
+        operation: str,
+        record: ResponseRecord,
+        projection: CatalogProjection,
+        *,
+        timeout_seconds: float | None,
+        context: _OperationContext | None,
+    ) -> None:
+        """Commit while the process-local catalog-write lock is held."""
         answered, merged = await self._catalog_call(
             operation,
             self._backend.commit_response(record, projection),
-            timeout_seconds=self._catalog_commit_timeout(projection),
+            timeout_seconds=(
+                timeout_seconds
+                if timeout_seconds is not None
+                else self._catalog_commit_timeout(projection)
+            ),
             context=context,
         )
         write_answered = answered

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/cache/_null.py

@@ -142,6 +142,16 @@ class NullCacheBackend:
         )
         return projection_from_observations(merged, original=projection)
 
+    async def has_current_projection(
+        self, *, endpoint: str, canonical_filters: str
+    ) -> bool:
+        """Return whether transient coverage uses the current contract."""
+        coverage = self._coverage.get((endpoint, canonical_filters))
+        return bool(
+            coverage is not None
+            and coverage.projection_contract == projection_contract(endpoint)
+        )
+
     async def delete_response(self, key: str) -> None:
         """Delete no response because response bytes are never retained."""
 

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/cache/_redis.py

@@ -169,7 +169,7 @@ class RedisCacheBackend:
         lock = client.lock(
             self._key("lock", "catalog-commit"),
             timeout=_MAX_CATALOG_COMMIT_TIMEOUT_SECONDS,
-            blocking_timeout=self._config.io_timeout_seconds,
+            blocking_timeout=None,
         )
         try:
             async with lock:
@@ -253,6 +253,19 @@ class RedisCacheBackend:
         )
         return merged
 
+    async def has_current_projection(
+        self, *, endpoint: str, canonical_filters: str
+    ) -> bool:
+        """Return whether durable coverage uses the current contract."""
+        identity = _digest(f"{endpoint}:{canonical_filters}")
+        raw = await self._active_client().get(self._key("coverage", identity))
+        if raw is None:
+            return False
+        record = json_object(json.loads(_bytes(raw)))
+        return _json_required_text(
+            record, "projection_contract"
+        ) == projection_contract(endpoint)
+
     async def delete_response(self, key: str) -> None:
         """Delete one invalid response record without catalog pruning."""
         await self._active_client().delete(self._response_key(key))

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/cache/_sqlite.py

@@ -225,6 +225,21 @@ class SQLiteCacheBackend:
                 persist=False,
             )
 
+    async def has_current_projection(
+        self, *, endpoint: str, canonical_filters: str
+    ) -> bool:
+        """Return whether durable coverage uses the current contract."""
+        async with self._operation_lock:
+            cursor = await self._active_connection().execute(
+                self._sql.render("select_projection_contract.sql"),
+                (endpoint, canonical_filters),
+            )
+            row = await cursor.fetchone()
+            await cursor.close()
+            return bool(
+                row is not None and _row_str(row, 0) == projection_contract(endpoint)
+            )
+
     async def delete_response(self, key: str) -> None:
         """Delete one invalid or expired response record."""
         async with self._operation_lock:

cfb_data-0.8.0/cfb_data/cfb_data/cache/sql/select_projection_contract.sql

@@ -0,0 +1,3 @@
+SELECT projection_contract
+FROM coverage
+WHERE endpoint = ? AND canonical_filters = ?;

{cfb_data-0.7.0 → cfb_data-0.8.0}/cfb_data/cfb_data/errors.py

@@ -1,4 +1,4 @@
-"""Define safe, actionable exceptions raised by :mod:`cfb_data`."""
+"""Define actionable exceptions raised by :mod:`cfb_data`."""
 
 from __future__ import annotations
 
@@ -7,29 +7,6 @@ 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."""