cfb-data 0.4.1__py3-none-any.whl

cfb_data/_parquet.py

@@ -0,0 +1,197 @@
+"""Persist canonical tabular responses as versioned local Parquet files."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from contextlib import suppress
+from pathlib import Path
+from typing import Final, Literal
+
+import pyarrow as pa
+import pyarrow.parquet as pq
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from cfb_data._tabular import (
+    _arrow_table_from_models,
+    _assert_canonical_arrow_table,
+    _CanonicalTableMetadataError,
+    _CanonicalTableSchemaError,
+    _logical_records_from_arrow_table,
+    _models_from_arrow_table,
+    _ScalarEncodingError,
+    _UnsupportedTableAnnotationError,
+)
+from cfb_data.errors import CFBDError, _sanitized_cause
+
+_ParquetOperation = Literal["read", "write"]
+_ParquetErrorCategory = Literal[
+    "io",
+    "format",
+    "metadata",
+    "schema",
+    "validation",
+]
+_ParquetValidation = Literal["full", "trusted_schema"]
+
+_PARQUET_VERSION: Final = "1.0"
+_PARQUET_COMPRESSION: Final = "snappy"
+
+
+class _ParquetCodecError(CFBDError):
+    """Report a safe categorized failure in the internal Parquet codec."""
+
+    operation: _ParquetOperation
+    category: _ParquetErrorCategory
+
+    def __init__(
+        self,
+        *,
+        operation: _ParquetOperation,
+        category: _ParquetErrorCategory,
+    ) -> None:
+        """Initialize a path- and payload-free codec failure.
+
+        :param operation: File operation that failed.
+        :param category: Safe failure classification for internal policy.
+        """
+        self.operation = operation
+        self.category = category
+        super().__init__(f"Parquet {operation} failed ({category})")
+
+
+def _write_parquet(
+    path: str | os.PathLike[str],
+    *,
+    row_model: type[BaseModel],
+    table: pa.Table,
+) -> None:
+    """Atomically write a canonical Arrow table to one local Parquet file.
+
+    The destination parent must already exist. An existing destination is
+    replaced only after the complete temporary Parquet file closes successfully.
+
+    :param path: Local destination path.
+    :param row_model: Expected authoritative row model for the table.
+    :param table: Canonical Arrow table to persist.
+    :raises _ParquetCodecError: If validation, writing, or replacement fails.
+    """
+    try:
+        _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
+
+
+def _read_parquet[ModelT: BaseModel](
+    path: str | os.PathLike[str],
+    *,
+    row_model: type[ModelT],
+    response_adapter: TypeAdapter[list[ModelT]],
+    validation: _ParquetValidation = "full",
+) -> pa.Table:
+    """Read and verify one versioned cfb-data Parquet file.
+
+    ``full`` validation decodes and revalidates every row through Pydantic.
+    ``trusted_schema`` is an internal fast path only for integrity-controlled
+    library caches; it still checks all metadata, Arrow types, and tagged scalar
+    invariants.
+
+    :param path: Local source path.
+    :param row_model: Expected authoritative row model.
+    :param response_adapter: Pydantic adapter for a list of expected rows.
+    :param validation: Full domain validation or trusted schema validation.
+    :return: Verified canonical Arrow table in stored row order.
+    :raises ValueError: If ``validation`` is not a supported literal.
+    :raises _ParquetCodecError: If reading or verification fails.
+    """
+    if validation not in {"full", "trusted_schema"}:
+        raise ValueError("validation must be 'full' or 'trusted_schema'")
+    try:
+        table = _read_parquet_file(
+            Path(path),
+            row_model=row_model,
+            response_adapter=response_adapter,
+            validation=validation,
+        )
+        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
+
+
+def _write_parquet_file(
+    path: Path,
+    *,
+    row_model: type[BaseModel],
+    table: pa.Table,
+) -> None:
+    """Validate and atomically replace a local Parquet destination."""
+    _assert_canonical_arrow_table(row_model=row_model, table=table)
+    _logical_records_from_arrow_table(row_model=row_model, table=table)
+    if not path.parent.is_dir():
+        raise FileNotFoundError("Parquet destination parent does not exist")
+
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=path.parent,
+    )
+    temporary_path = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as temporary_file:
+            pq.write_table(
+                table,
+                temporary_file,
+                version=_PARQUET_VERSION,
+                compression=_PARQUET_COMPRESSION,
+                write_statistics=True,
+                use_compliant_nested_type=True,
+                store_schema=True,
+            )
+        os.replace(temporary_path, path)
+    finally:
+        with suppress(FileNotFoundError):
+            temporary_path.unlink()
+
+
+def _read_parquet_file[ModelT: BaseModel](
+    path: Path,
+    *,
+    row_model: type[ModelT],
+    response_adapter: TypeAdapter[list[ModelT]],
+    validation: _ParquetValidation,
+) -> pa.Table:
+    """Read a table and apply the selected internal validation policy."""
+    table = pq.read_table(path)
+    _assert_canonical_arrow_table(row_model=row_model, table=table)
+    if validation == "trusted_schema":
+        _logical_records_from_arrow_table(row_model=row_model, table=table)
+        return table
+
+    models = _models_from_arrow_table(
+        row_model=row_model,
+        response_adapter=response_adapter,
+        table=table,
+    )
+    return _arrow_table_from_models(row_model=row_model, models=models)
+
+
+def _codec_error_category(source: Exception) -> _ParquetErrorCategory:
+    """Classify a source exception without retaining its values or path."""
+    if isinstance(source, _CanonicalTableMetadataError):
+        return "metadata"
+    if isinstance(source, _CanonicalTableSchemaError):
+        return "schema"
+    if isinstance(source, _UnsupportedTableAnnotationError):
+        return "schema"
+    if isinstance(source, ValidationError):
+        return "validation"
+    if isinstance(source, OSError):
+        return "io"
+    if isinstance(source, _ScalarEncodingError):
+        return "format"
+    return "format"

cfb_data/_request_rules.py

@@ -0,0 +1,41 @@
+"""Provide relational validation shared by endpoint request models."""
+
+from collections.abc import Mapping, Sequence
+
+
+def _validate_year_or_game_id(
+    year: int | None,
+    game_id: int | None,
+) -> None:
+    """Require either a year or game identifier."""
+    if year is None and game_id is None:
+        raise ValueError("year is required when game_id is not specified")
+
+
+def _validate_at_least_one_of(
+    values: Mapping[str, object],
+    field_names: Sequence[str],
+    context_message: str = "At least one of the following fields is required",
+) -> None:
+    """Require a non-null value for at least one named field."""
+    if not any(values.get(field) is not None for field in field_names):
+        field_list = ", ".join(field_names)
+        raise ValueError(f"{context_message}: {field_list}")
+
+
+def _validate_game_stats_selectors(
+    year: int | None,
+    week: int | None,
+    team: str | None,
+    conference: str | None,
+    game_id: int | None,
+) -> None:
+    """Validate game-ID or grouped selectors for game-stat endpoints."""
+    if game_id is not None:
+        return
+    _validate_year_or_game_id(year, game_id)
+    if week is None and team is None and conference is None:
+        raise ValueError(
+            "At least one of week, team, or conference is required "
+            "when game_id is not specified"
+        )

cfb_data/_requests.py

@@ -0,0 +1,36 @@
+"""Build endpoint request models from the two supported call styles."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pydantic import BaseModel, ValidationError
+
+from cfb_data.errors import CFBDRequestValidationError, _sanitized_cause
+
+
+def _resolve_request[RequestT: BaseModel](
+    *,
+    endpoint: str,
+    request_type: type[RequestT],
+    request: BaseModel | None,
+    filters: Mapping[str, object],
+) -> RequestT:
+    """Return a supplied request or validate explicit keyword filters."""
+    if request is not None:
+        if filters:
+            raise TypeError(
+                "Pass either one positional request model or keyword filters, not both"
+            )
+        if not isinstance(request, request_type):
+            raise TypeError(
+                f"{endpoint} requires {request_type.__name__}, "
+                f"not {type(request).__name__}"
+            )
+        return request
+
+    try:
+        return request_type.model_validate(filters)
+    except ValidationError as exc:
+        safe_cause = _sanitized_cause(exc)
+    raise CFBDRequestValidationError(endpoint=endpoint) from safe_cause