cfb-data 0.7.1__tar.gz → 0.9.0__tar.gz

{cfb_data-0.7.1 → cfb_data-0.9.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: cfb-data
-Version: 0.7.1
-Summary: Async validated CollegeFootballData access for pandas and Polars
+Version: 0.9.0
+Summary: Async validated CollegeFootballData access for pandas and Polars, with native Dask analytics
 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
@@ -17,14 +17,22 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp<4,>=3.13
 Requires-Dist: aiosqlite<1,>=0.22
+Requires-Dist: dask[dataframe]<2027,>=2026.7.1
 Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: narwhals<3,>=2.24
+Requires-Dist: numpy<3,>=2
 Requires-Dist: pandas<4,>=3.0
+Requires-Dist: platformdirs<5,>=4.11
 Requires-Dist: pydantic<3,>=2.12
 Requires-Dist: pyarrow<26,>=25
 Provides-Extra: polars
 Requires-Dist: polars<2,>=1.43.2; extra == "polars"
 Provides-Extra: redis
 Requires-Dist: redis<9,>=7.1; extra == "redis"
+Provides-Extra: dask
+Requires-Dist: distributed<2027,>=2026.7.1; extra == "dask"
+Provides-Extra: yaml
+Requires-Dist: PyYAML<7,>=6.0.3; extra == "yaml"
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.5; extra == "dev"
 Requires-Dist: furo>=2025.12.19; extra == "dev"
@@ -34,14 +42,19 @@ Requires-Dist: pre-commit<5,>=4.5; extra == "dev"
 Requires-Dist: pyarrow-stubs<21,>=20.0.0.20260625; extra == "dev"
 Requires-Dist: pytest<10,>=9; extra == "dev"
 Requires-Dist: pytest-asyncio<2,>=1.3; extra == "dev"
+Requires-Dist: pytest-split<1,>=0.11; extra == "dev"
+Requires-Dist: pytest-xdist<4,>=3.8; extra == "dev"
 Requires-Dist: ruff<0.17,>=0.15.22; extra == "dev"
+Requires-Dist: setuptools<85,>=80; extra == "dev"
 Requires-Dist: sphinx<10,>=9.1; extra == "dev"
 Requires-Dist: twine<8,>=7; extra == "dev"
+Requires-Dist: types-PyYAML<6.1,>=6.0.12.20260815; extra == "dev"
+Requires-Dist: wheel<1,>=0.46; extra == "dev"
 Dynamic: license-file
 
 # College Football Data Python Toolkit
 
-`cfb-data` 0.7.1 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.9.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.
@@ -55,7 +68,7 @@ HTTP client or cleaning up inconsistent response shapes.
 - Pull games, plays, drives, ratings, rosters, recruiting, betting, draft, and
   other CFBD data into Python.
 - Explore one team or season in a notebook.
-- Build repeatable pandas or Polars analyses across several endpoints.
+- Run or author durable pandas or Polars recipes across several endpoints.
 - Cache responses locally so rerunning an analysis does not repeat every API
   call.
 - Resolve team, venue, game, and athlete names and IDs when joining data.
@@ -66,7 +79,7 @@ Arrow, HTTP retry logic, or the cache implementation.
 
 ## Install
 
-Python 3.12 and 3.13 are supported. pandas and PyArrow are included:
+Python 3.12 and 3.13 are supported. pandas, PyArrow, and native Dask DataFrame processing are included:
 
 ```shell
 python -m pip install cfb-data
@@ -86,6 +99,12 @@ python -m pip install "cfb-data[redis]"
 
 SQLite caching is included in the normal installation.
 
+For parallel Dask workers or safe declarative YAML recipes:
+
+```shell
+python -m pip install "cfb-data[dask,yaml]"
+```
+
 ## Make a first request
 
 Get an API key from [CollegeFootballData](https://collegefootballdata.com/) and
@@ -124,6 +143,32 @@ The `async with` block lets related calls share one HTTP session and closes it
 when the block ends. Async is limited to gathering and validating data; the
 pandas calculation starts synchronously after the completed frame is returned.
 
+## Run a modular analytics recipe
+
+First-party datasets and workflows are ordinary independently importable
+recipe modules. They use the same authoring and execution surface available to
+your own package:
+
+```python
+from cfb_data_recipes.team_seasons import team_seasons
+
+async with CFBDClient() as client:
+    season = await team_seasons(
+        client,
+        season=2024,
+        team="Penn State",
+    )
+
+print(season[["team", "season", "expected_wins", "total"]])
+```
+
+Use ``.plan()`` for a pure no-I/O execution plan and ``.run()`` for durable
+artifacts, lineage, source coverage, quality results, and recovery evidence.
+Workflows return explicit named outputs rather than choosing a hidden primary
+table. See [Build durable analyses with modular
+recipes](docs/guides/modular-analytics.md) for the thirteen included datasets,
+three workflows, Dask execution, safe YAML, recovery, and user authoring.
+
 ## Find the data you need
 
 Methods are grouped by subject:
@@ -244,8 +289,8 @@ async with CFBDClient(cache=SQLiteCacheConfig(), observer=stats) as client:
     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.http_attempts)  # actual client-side HTTP attempts
+print(snapshot.fresh_cache_hits)  # fresh initial cache hits
 print(snapshot.fresh_hit_rate)
 ```
 
@@ -271,8 +316,9 @@ The [complete documentation](https://ryanpaulanderson.github.io/cfb-data/)
 is organized in layers:
 
 - **Start and use:** installation, examples, requests, results, caching, and
-  troubleshooting, including [common notebook
-  recipes](docs/guides/common-recipes.md).
+  troubleshooting, including [modular analytics
+  recipes](docs/guides/modular-analytics.md) and [common notebook
+  patterns](docs/guides/common-recipes.md).
 - **Advanced details:** exact enum values, dtypes, TTLs, retries, and storage
   behavior.
 - **Project internals:** architecture decisions and contributor-facing design.
@@ -280,7 +326,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.1 → cfb_data-0.9.0}/README.md

@@ -1,6 +1,6 @@
 # College Football Data Python Toolkit
 
-`cfb-data` 0.7.1 is a pre-alpha Python toolkit for exploring the public
+`cfb-data` 0.9.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.
@@ -14,7 +14,7 @@ HTTP client or cleaning up inconsistent response shapes.
 - Pull games, plays, drives, ratings, rosters, recruiting, betting, draft, and
   other CFBD data into Python.
 - Explore one team or season in a notebook.
-- Build repeatable pandas or Polars analyses across several endpoints.
+- Run or author durable pandas or Polars recipes across several endpoints.
 - Cache responses locally so rerunning an analysis does not repeat every API
   call.
 - Resolve team, venue, game, and athlete names and IDs when joining data.
@@ -25,7 +25,7 @@ Arrow, HTTP retry logic, or the cache implementation.
 
 ## Install
 
-Python 3.12 and 3.13 are supported. pandas and PyArrow are included:
+Python 3.12 and 3.13 are supported. pandas, PyArrow, and native Dask DataFrame processing are included:
 
 ```shell
 python -m pip install cfb-data
@@ -45,6 +45,12 @@ python -m pip install "cfb-data[redis]"
 
 SQLite caching is included in the normal installation.
 
+For parallel Dask workers or safe declarative YAML recipes:
+
+```shell
+python -m pip install "cfb-data[dask,yaml]"
+```
+
 ## Make a first request
 
 Get an API key from [CollegeFootballData](https://collegefootballdata.com/) and
@@ -83,6 +89,32 @@ The `async with` block lets related calls share one HTTP session and closes it
 when the block ends. Async is limited to gathering and validating data; the
 pandas calculation starts synchronously after the completed frame is returned.
 
+## Run a modular analytics recipe
+
+First-party datasets and workflows are ordinary independently importable
+recipe modules. They use the same authoring and execution surface available to
+your own package:
+
+```python
+from cfb_data_recipes.team_seasons import team_seasons
+
+async with CFBDClient() as client:
+    season = await team_seasons(
+        client,
+        season=2024,
+        team="Penn State",
+    )
+
+print(season[["team", "season", "expected_wins", "total"]])
+```
+
+Use ``.plan()`` for a pure no-I/O execution plan and ``.run()`` for durable
+artifacts, lineage, source coverage, quality results, and recovery evidence.
+Workflows return explicit named outputs rather than choosing a hidden primary
+table. See [Build durable analyses with modular
+recipes](docs/guides/modular-analytics.md) for the thirteen included datasets,
+three workflows, Dask execution, safe YAML, recovery, and user authoring.
+
 ## Find the data you need
 
 Methods are grouped by subject:
@@ -203,8 +235,8 @@ async with CFBDClient(cache=SQLiteCacheConfig(), observer=stats) as client:
     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.http_attempts)  # actual client-side HTTP attempts
+print(snapshot.fresh_cache_hits)  # fresh initial cache hits
 print(snapshot.fresh_hit_rate)
 ```
 
@@ -230,8 +262,9 @@ The [complete documentation](https://ryanpaulanderson.github.io/cfb-data/)
 is organized in layers:
 
 - **Start and use:** installation, examples, requests, results, caching, and
-  troubleshooting, including [common notebook
-  recipes](docs/guides/common-recipes.md).
+  troubleshooting, including [modular analytics
+  recipes](docs/guides/modular-analytics.md) and [common notebook
+  patterns](docs/guides/common-recipes.md).
 - **Advanced details:** exact enum values, dtypes, TTLs, retries, and storage
   behavior.
 - **Project internals:** architecture decisions and contributor-facing design.
@@ -239,7 +272,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.1 → cfb_data-0.9.0}/cfb_data/cfb_data/_executor.py

@@ -149,6 +149,8 @@ class _EndpointExecutor:
                     endpoint=endpoint,
                     parameter_names=tuple(sorted(parameters)),
                     cache_mode=self._cache_coordinator.current_mode,
+                    analytics_run_id=context.analytics_run_id,
+                    analytics_node_id=context.analytics_node_id,
                 )
             )
         try:
@@ -190,6 +192,8 @@ class _EndpointExecutor:
                 failure_category=(
                     _failure_category(error) if error is not None else None
                 ),
+                analytics_run_id=context.analytics_run_id,
+                analytics_node_id=context.analytics_node_id,
             )
         )
 

{cfb_data-0.7.1 → cfb_data-0.9.0}/cfb_data/cfb_data/_observability.py

@@ -6,7 +6,9 @@ import asyncio
 import logging
 import time
 import uuid
-from collections.abc import Callable
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from dataclasses import dataclass
 
 from cfb_data.observability import (
@@ -16,6 +18,9 @@ from cfb_data.observability import (
 )
 
 _LOGGER = logging.getLogger(__name__)
+_ANALYTICS_CORRELATION: ContextVar[tuple[str, str] | None] = ContextVar(
+    "cfb_data_analytics_retrieval_correlation", default=None
+)
 
 
 @dataclass(slots=True)
@@ -28,6 +33,8 @@ class _OperationContext:
     started_at: float
     source: RetrievalSource = RetrievalSource.unknown
     refresh_id: str | None = None
+    analytics_run_id: str | None = None
+    analytics_node_id: str | None = None
 
 
 class _EventDispatcher:
@@ -62,11 +69,14 @@ class _EventDispatcher:
         """Return a new safe operation context when observation is enabled."""
         if self._observer is None:
             return None
+        correlation = _ANALYTICS_CORRELATION.get()
         return _OperationContext(
             client_id=self._client_id,
             operation_id=uuid.uuid4().hex,
             endpoint=endpoint,
             started_at=self._monotonic(),
+            analytics_run_id=(correlation[0] if correlation is not None else None),
+            analytics_node_id=(correlation[1] if correlation is not None else None),
         )
 
     def new_refresh_id(self) -> str:
@@ -108,4 +118,19 @@ def _failure_category(error: BaseException) -> str:
     return type(error).__name__[:64]
 
 
-__all__ = ["_EventDispatcher", "_OperationContext", "_failure_category"]
+@contextmanager
+def _analytics_retrieval_context(run_id: str, node_id: str) -> Iterator[None]:
+    """Correlate task-local endpoint retrieval events with one analytics node."""
+    token = _ANALYTICS_CORRELATION.set((run_id, node_id))
+    try:
+        yield
+    finally:
+        _ANALYTICS_CORRELATION.reset(token)
+
+
+__all__ = [
+    "_EventDispatcher",
+    "_OperationContext",
+    "_analytics_retrieval_context",
+    "_failure_category",
+]

cfb_data-0.9.0/cfb_data/cfb_data/_operation.py

@@ -0,0 +1,167 @@
+"""Define generic endpoint-operation ownership shared by resources and recipes."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from types import GenericAlias
+from typing import Literal
+
+from pydantic import BaseModel, TypeAdapter
+
+from cfb_data._dataframes import _DataFrameAdapter
+from cfb_data._executor import _EndpointExecutor, _response_contract, _serialize_request
+from cfb_data._requests import _resolve_request
+
+
+class _EndpointOperation[RequestT: BaseModel, RowT: BaseModel](ABC):
+    """Own the common contract for one validated endpoint operation."""
+
+    id: str
+    revision: int
+    endpoint: str
+    request_type: type[RequestT]
+    row_model: type[RowT]
+    access_tier: Literal["free", "tier_1", "tier_2"]
+    documented_limit: int | None
+    cost: int
+
+    def resolve(
+        self,
+        request: RequestT | None,
+        filters: dict[str, object],
+    ) -> RequestT:
+        """Return the one authoritative validated request model."""
+        return _resolve_request(
+            endpoint=self.endpoint,
+            request_type=self.request_type,
+            request=request,
+            filters=filters,
+        )
+
+    @abstractmethod
+    async def fetch(
+        self,
+        executor: _EndpointExecutor,
+        request: RequestT,
+    ) -> list[RowT]:
+        """Return one normalized row list through the shared executor."""
+
+    @property
+    @abstractmethod
+    def rows_adapter(self) -> TypeAdapter[list[RowT]]:
+        """Return the adapter for the normalized analytical row list."""
+
+    @property
+    @abstractmethod
+    def response_contract(self) -> str:
+        """Return the actual HTTP response schema fingerprint."""
+
+    def serialized_parameters(
+        self, request: RequestT
+    ) -> dict[str, str | int | float | bool]:
+        """Return the exact typed upstream request parameters."""
+        return _serialize_request(self.endpoint, request)
+
+
+@dataclass(frozen=True, slots=True)
+class _ManyEndpointOperation[RequestT: BaseModel, RowT: BaseModel](
+    _EndpointOperation[RequestT, RowT]
+):
+    """Own one endpoint whose HTTP response is a model list."""
+
+    id: str
+    revision: int
+    endpoint: str
+    request_type: type[RequestT]
+    response_adapter: TypeAdapter[list[RowT]]
+    row_model: type[RowT]
+    access_tier: Literal["free", "tier_1", "tier_2"]
+    documented_limit: int | None = None
+    cost: int = 1
+
+    async def fetch(
+        self,
+        executor: _EndpointExecutor,
+        request: RequestT,
+    ) -> list[RowT]:
+        """Return validated rows through the shared endpoint executor."""
+        return await executor.fetch_many(
+            endpoint=self.endpoint,
+            request=request,
+            response_adapter=self.response_adapter,
+        )
+
+    @property
+    def rows_adapter(self) -> TypeAdapter[list[RowT]]:
+        """Return the HTTP list adapter as the analytical row adapter."""
+        return self.response_adapter
+
+    async def fetch_frame[FrameT](
+        self,
+        executor: _EndpointExecutor,
+        dataframe_adapter: _DataFrameAdapter[FrameT],
+        request: RequestT | None,
+        filters: dict[str, object],
+    ) -> FrameT:
+        """Validate, retrieve, and present rows for a public resource method."""
+        validated = self.resolve(request, filters)
+        rows = await self.fetch(executor, validated)
+        return dataframe_adapter.from_models(
+            endpoint=self.endpoint,
+            row_model=self.row_model,
+            models=rows,
+        )
+
+    @property
+    def response_contract(self) -> str:
+        """Return the stable response schema fingerprint used by the cache."""
+        return _response_contract(self.response_adapter)
+
+
+@dataclass(frozen=True, slots=True)
+class _OneEndpointOperation[RequestT: BaseModel, RowT: BaseModel](
+    _EndpointOperation[RequestT, RowT]
+):
+    """Own one endpoint whose HTTP response is one validated model."""
+
+    id: str
+    revision: int
+    endpoint: str
+    request_type: type[RequestT]
+    response_adapter: TypeAdapter[RowT]
+    row_model: type[RowT]
+    access_tier: Literal["free", "tier_1", "tier_2"]
+    documented_limit: int | None = None
+    cost: int = 1
+
+    async def fetch(
+        self,
+        executor: _EndpointExecutor,
+        request: RequestT,
+    ) -> list[RowT]:
+        """Wrap the validated HTTP object in the analytical row list."""
+        return [await self.fetch_one(executor, request)]
+
+    async def fetch_one(
+        self,
+        executor: _EndpointExecutor,
+        request: RequestT,
+    ) -> RowT:
+        """Return the validated object through the shared endpoint executor."""
+        return await executor.fetch_one(
+            endpoint=self.endpoint,
+            request=request,
+            response_adapter=self.response_adapter,
+        )
+
+    @property
+    def rows_adapter(self) -> TypeAdapter[list[RowT]]:
+        """Return the normalized analytical row-list adapter."""
+        annotation = GenericAlias(list, self.row_model)
+        return TypeAdapter(annotation)
+
+    @property
+    def response_contract(self) -> str:
+        """Return the stable single-object response schema fingerprint."""
+        return _response_contract(self.response_adapter)

{cfb_data-0.7.1/cfb_data/cfb_data/cache → cfb_data-0.9.0/cfb_data/cfb_data}/_sqlite_sql.py

@@ -1,16 +1,10 @@
-"""Render packaged SQLite templates through one strict SQL handler."""
+"""Render packaged SQLite templates through one strict shared handler."""
 
 from __future__ import annotations
 
 from pathlib import PurePosixPath
 
-from jinja2 import (
-    BaseLoader,
-    Environment,
-    PackageLoader,
-    StrictUndefined,
-    TemplateError,
-)
+from jinja2 import BaseLoader, Environment, StrictUndefined, TemplateError
 
 
 class SQLTemplateHandler:
@@ -60,9 +54,4 @@ class SQLTemplateHandler:
         return rendered
 
 
-class SQLiteSQL(SQLTemplateHandler):
-    """Load installed SQLite templates from the cache package."""
-
-    def __init__(self) -> None:
-        """Bind the strict handler to packaged cache SQL resources."""
-        super().__init__(PackageLoader("cfb_data.cache", "sql"))
+__all__ = ["SQLTemplateHandler"]