cfb-data 0.4.1__tar.gz → 0.5.0__tar.gz

{cfb_data-0.4.1 → cfb_data-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cfb-data
-Version: 0.4.1
+Version: 0.5.0
 Summary: Async validated CollegeFootballData access for pandas and Polars
 Author: Ryan Anderson
 License-Expression: MIT
@@ -16,11 +16,15 @@ Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp<4,>=3.13
+Requires-Dist: aiosqlite<1,>=0.22
+Requires-Dist: jinja2<4,>=3.1
 Requires-Dist: pandas<4,>=3.0
 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<8,>=7.1; extra == "redis"
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.5; extra == "dev"
 Requires-Dist: furo>=2025.12.19; extra == "dev"
@@ -37,7 +41,7 @@ Dynamic: license-file
 
 # College Football Data Python Toolkit
 
-`cfb-data` 0.4.1 is an asynchronous, validated client for the public
+`cfb-data` 0.5.0 is an asynchronous, validated client for the public
 [CollegeFootballData API](https://collegefootballdata.com/) REST endpoint
 groups. It returns eager pandas DataFrames by default and can return the same
 logical tables as Polars DataFrames. Irreducibly nested analytical responses
@@ -72,8 +76,15 @@ Install the optional Polars backend with:
 python -m pip install "cfb-data[polars]"
 ```
 
+SQLite caching and identity lookup are available in the base installation.
+Install the optional shared Redis backend with:
+
+```sh
+python -m pip install "cfb-data[redis]"
+```
+
 Python 3.12 and 3.13 are supported. DataFrames are eager; Polars
-`LazyFrame` results are not part of the 0.4.1 contract.
+`LazyFrame` results are not part of the 0.5.0 contract.
 
 ## Authentication and lifecycle
 
@@ -143,6 +154,56 @@ async with CFBDClient(dataframe_backend="polars") as client:
 Type checkers infer `pandas.DataFrame` for the default client and
 `polars.DataFrame` when the literal backend is `"polars"`.
 
+## Response caching and identities
+
+Caching is opt-in. `SQLiteCacheConfig()` provides a private per-user local
+response cache and durable identity catalog without another service:
+
+```python
+from cfb_data import CFBDClient, FreshnessMode, SQLiteCacheConfig
+
+async with CFBDClient(cache=SQLiteCacheConfig()) as client:
+    games = await client.games.list(year=2025)
+    repeated = await client.games.list(year=2025)  # validated exact cache hit
+
+    team = await client.identities.teams.resolve("MICH")
+    game = await client.identities.games.resolve(game_id=401628347)
+
+    with client.cache_mode("local_only"):
+        offline = await client.games.list(year=2025)
+
+    retained = await client.identities.teams.resolve(
+        "Michigan",
+        freshness=FreshnessMode.allow_stale,
+    )
+```
+
+Use `RedisCacheConfig(url=...)` for multiple workers or hosts. Validated
+response records expire according to college-football-specific TTL profiles;
+normalized identity facts and their coverage ledger remain until explicitly
+pruned or rebuilt. Operational account and usage routes are never cached.
+Cache hits are decoded and revalidated through the current Pydantic response
+contract, and cache/backend failures fail open for ordinary API calls without
+silently changing backend types.
+
+Source-domain Pydantic models own the upstream fields and typed declarations
+that produce catalog facts. The catalog owns only normalized merge, coverage,
+provenance, persistence, and query semantics. The SQLite schema and queries
+live in packaged `.sql` resources rendered through a strict Jinja handler;
+runtime data continues to use bound SQLite parameters. With persistence
+disabled, the same projection path writes a client-local transient catalog;
+there is no separate response-to-identity fallback. Compact identity result
+types live in their team, conference, venue, game, and player domains, while
+`client.identities` remains the query and hydration facade.
+
+Per-operation modes are `default`, `refresh`, `bypass`, and `local_only`.
+`client.identities.hydrate(...)` supports dry-run, bounded-concurrency,
+resumable canonical hydration at `4 + 2S` calls for `S` seasons, or `7 + 2S`
+with vocabularies, with an optional division-classification scope. See the complete
+[response caching and identity guide](docs/guides/cache-and-identities.md) for
+TTL defaults, ambiguity behavior, maintenance, Redis Docker/Compose setup, and
+hosted-service security requirements.
+
 ## Endpoints
 
 Each method accepts either one positional request model or explicit snake-case
@@ -298,10 +359,12 @@ original string, integer, or float value for DataFrames.
 Direct pandas and Polars Parquet methods are not the cfb-data persistence
 compatibility contract: pandas object inference and Polars `Object` columns do
 not provide identical empty- and mixed-value behavior. Version 0.2.0 keeps the
-codec internal so future caching can use it without prematurely committing to
-a public save/load API. See
+codec internal so future workflow checkpoints and tabular artifacts can use it
+without prematurely committing to a public save/load API. See
 [`ADR 0003`](docs/architecture/0003-canonical-arrow-parquet.md) for the format,
-validation, and compatibility decisions.
+validation, and compatibility decisions. API response caching and its durable
+identity catalog are a separate accepted architecture in
+[`ADR 0004`](docs/architecture/0004-api-cache-identity-catalog.md).
 
 ## Retries and errors
 
@@ -371,7 +434,7 @@ Use the typed namespace method and either its request model or keyword filters.
 
 ## Datasets and workflows
 
-Version 0.4.1 does not expose `client.datasets` or `client.workflows`. The
+Version 0.5.0 does not expose `client.datasets` or `client.workflows`. The
 accepted architecture reserves two higher layers:
 
 - datasets compose validated endpoint results and validated subdatasets
@@ -396,8 +459,13 @@ make docs
 make check
 ```
 
-`make install` creates `.venv` and installs `.[dev,polars]`, giving
-contributors the complete Arrow/Parquet and two-backend test contract.
+`make install` creates `.venv` and installs `.[dev,polars,redis]`, giving
+contributors the complete Arrow/Parquet, DataFrame, and Redis-client test
+contract. `make redis-up` and `make test-redis` exercise the local shared
+backend; `make test-live` is an explicit credentialed check using untracked
+`.env` configuration. `make test-live-all` is the separately opted-in,
+quota-ledgered 74-route SQLite/Redis matrix and keeps the transport's normal
+bounded retries enabled.
 `make check` runs Ruff, strict mypy, a warning-free Sphinx build, and pytest
 under the same contract as CI. `make docs` writes the local HTML site to
 `docs/_build/html`. Package metadata and all dependency groups live only in

{cfb_data-0.4.1 → cfb_data-0.5.0}/README.md

@@ -1,6 +1,6 @@
 # College Football Data Python Toolkit
 
-`cfb-data` 0.4.1 is an asynchronous, validated client for the public
+`cfb-data` 0.5.0 is an asynchronous, validated client for the public
 [CollegeFootballData API](https://collegefootballdata.com/) REST endpoint
 groups. It returns eager pandas DataFrames by default and can return the same
 logical tables as Polars DataFrames. Irreducibly nested analytical responses
@@ -35,8 +35,15 @@ Install the optional Polars backend with:
 python -m pip install "cfb-data[polars]"
 ```
 
+SQLite caching and identity lookup are available in the base installation.
+Install the optional shared Redis backend with:
+
+```sh
+python -m pip install "cfb-data[redis]"
+```
+
 Python 3.12 and 3.13 are supported. DataFrames are eager; Polars
-`LazyFrame` results are not part of the 0.4.1 contract.
+`LazyFrame` results are not part of the 0.5.0 contract.
 
 ## Authentication and lifecycle
 
@@ -106,6 +113,56 @@ async with CFBDClient(dataframe_backend="polars") as client:
 Type checkers infer `pandas.DataFrame` for the default client and
 `polars.DataFrame` when the literal backend is `"polars"`.
 
+## Response caching and identities
+
+Caching is opt-in. `SQLiteCacheConfig()` provides a private per-user local
+response cache and durable identity catalog without another service:
+
+```python
+from cfb_data import CFBDClient, FreshnessMode, SQLiteCacheConfig
+
+async with CFBDClient(cache=SQLiteCacheConfig()) as client:
+    games = await client.games.list(year=2025)
+    repeated = await client.games.list(year=2025)  # validated exact cache hit
+
+    team = await client.identities.teams.resolve("MICH")
+    game = await client.identities.games.resolve(game_id=401628347)
+
+    with client.cache_mode("local_only"):
+        offline = await client.games.list(year=2025)
+
+    retained = await client.identities.teams.resolve(
+        "Michigan",
+        freshness=FreshnessMode.allow_stale,
+    )
+```
+
+Use `RedisCacheConfig(url=...)` for multiple workers or hosts. Validated
+response records expire according to college-football-specific TTL profiles;
+normalized identity facts and their coverage ledger remain until explicitly
+pruned or rebuilt. Operational account and usage routes are never cached.
+Cache hits are decoded and revalidated through the current Pydantic response
+contract, and cache/backend failures fail open for ordinary API calls without
+silently changing backend types.
+
+Source-domain Pydantic models own the upstream fields and typed declarations
+that produce catalog facts. The catalog owns only normalized merge, coverage,
+provenance, persistence, and query semantics. The SQLite schema and queries
+live in packaged `.sql` resources rendered through a strict Jinja handler;
+runtime data continues to use bound SQLite parameters. With persistence
+disabled, the same projection path writes a client-local transient catalog;
+there is no separate response-to-identity fallback. Compact identity result
+types live in their team, conference, venue, game, and player domains, while
+`client.identities` remains the query and hydration facade.
+
+Per-operation modes are `default`, `refresh`, `bypass`, and `local_only`.
+`client.identities.hydrate(...)` supports dry-run, bounded-concurrency,
+resumable canonical hydration at `4 + 2S` calls for `S` seasons, or `7 + 2S`
+with vocabularies, with an optional division-classification scope. See the complete
+[response caching and identity guide](docs/guides/cache-and-identities.md) for
+TTL defaults, ambiguity behavior, maintenance, Redis Docker/Compose setup, and
+hosted-service security requirements.
+
 ## Endpoints
 
 Each method accepts either one positional request model or explicit snake-case
@@ -261,10 +318,12 @@ original string, integer, or float value for DataFrames.
 Direct pandas and Polars Parquet methods are not the cfb-data persistence
 compatibility contract: pandas object inference and Polars `Object` columns do
 not provide identical empty- and mixed-value behavior. Version 0.2.0 keeps the
-codec internal so future caching can use it without prematurely committing to
-a public save/load API. See
+codec internal so future workflow checkpoints and tabular artifacts can use it
+without prematurely committing to a public save/load API. See
 [`ADR 0003`](docs/architecture/0003-canonical-arrow-parquet.md) for the format,
-validation, and compatibility decisions.
+validation, and compatibility decisions. API response caching and its durable
+identity catalog are a separate accepted architecture in
+[`ADR 0004`](docs/architecture/0004-api-cache-identity-catalog.md).
 
 ## Retries and errors
 
@@ -334,7 +393,7 @@ Use the typed namespace method and either its request model or keyword filters.
 
 ## Datasets and workflows
 
-Version 0.4.1 does not expose `client.datasets` or `client.workflows`. The
+Version 0.5.0 does not expose `client.datasets` or `client.workflows`. The
 accepted architecture reserves two higher layers:
 
 - datasets compose validated endpoint results and validated subdatasets
@@ -359,8 +418,13 @@ make docs
 make check
 ```
 
-`make install` creates `.venv` and installs `.[dev,polars]`, giving
-contributors the complete Arrow/Parquet and two-backend test contract.
+`make install` creates `.venv` and installs `.[dev,polars,redis]`, giving
+contributors the complete Arrow/Parquet, DataFrame, and Redis-client test
+contract. `make redis-up` and `make test-redis` exercise the local shared
+backend; `make test-live` is an explicit credentialed check using untracked
+`.env` configuration. `make test-live-all` is the separately opted-in,
+quota-ledgered 74-route SQLite/Redis matrix and keeps the transport's normal
+bounded retries enabled.
 `make check` runs Ruff, strict mypy, a warning-free Sphinx build, and pytest
 under the same contract as CI. `make docs` writes the local HTML site to
 `docs/_build/html`. Package metadata and all dependency groups live only in

{cfb_data-0.4.1 → cfb_data-0.5.0}/cfb_data/cfb_data/__init__.py

@@ -7,6 +7,15 @@ from .adjusted_metrics.models.pydantic.requests import (
     KickerPAARRequest,
 )
 from .betting.models.pydantic.requests import BettingLinesRequest
+from .cache import (
+    CacheConfig,
+    CacheMode,
+    CachePolicyConfig,
+    CacheProfile,
+    CacheTTL,
+    RedisCacheConfig,
+    SQLiteCacheConfig,
+)
 from .client import CFBDClient, DataFrameBackend
 from .coaches.models.pydantic.requests import (
     CoachesRequest,
@@ -14,6 +23,7 @@ from .coaches.models.pydantic.requests import (
     CoachSeasonsRequest,
     CoachTenuresRequest,
 )
+from .conferences.models.pydantic.identity import ConferenceIdentity
 from .conferences.models.pydantic.requests import (
     ConferenceAffiliationsRequest,
     ConferenceChangesRequest,
@@ -36,11 +46,17 @@ from .enums import (
 from .errors import (
     CFBDAuthenticationError,
     CFBDAuthorizationError,
+    CFBDCacheBackendError,
+    CFBDCacheError,
+    CFBDCacheMissError,
     CFBDClientStateError,
     CFBDConfigurationError,
     CFBDDataFrameConversionError,
     CFBDError,
     CFBDHTTPError,
+    CFBDIdentityAmbiguityError,
+    CFBDIdentityNotFoundError,
+    CFBDNoContentError,
     CFBDOptionalDependencyError,
     CFBDRateLimitError,
     CFBDRequestValidationError,
@@ -51,6 +67,7 @@ from .errors import (
     CFBDTLSError,
     CFBDTransportError,
 )
+from .games.models.pydantic.identity import GameIdentity
 from .games.models.pydantic.requests import (
     AdvancedBoxScoreRequest,
     CalendarRequest,
@@ -63,6 +80,7 @@ from .games.models.pydantic.requests import (
     TeamGameStatsRequest,
 )
 from .games.models.pydantic.responses import AdvancedBoxScore
+from .identities import FreshnessMode, HydrationPlan
 from .info.models.pydantic.requests import InfoUsageRequest
 from .info.models.pydantic.responses import UserInfo, UserUsage
 from .metrics.models.pydantic.requests import (
@@ -74,6 +92,7 @@ from .metrics.models.pydantic.requests import (
     TeamSeasonPPARequest,
     WinProbabilityRequest,
 )
+from .players.models.pydantic.identity import AthleteIdentity
 from .players.models.pydantic.requests import (
     PlayerSearchRequest,
     PlayerSeasonOverviewRequest,
@@ -118,6 +137,7 @@ from .stats.models.pydantic.requests import (
     PlayerSeasonSuccessRequest,
     TeamSeasonStatsRequest,
 )
+from .teams.models.pydantic.identity import TeamIdentity
 from .teams.models.pydantic.requests import (
     FBSTeamsRequest,
     RosterRequest,
@@ -126,29 +146,42 @@ from .teams.models.pydantic.requests import (
     TeamMatchupRequest,
     TeamsRequest,
 )
+from .venues.models.pydantic.identity import VenueIdentity
 
 __all__ = [
     "AdjustedPlayerPassingRequest",
     "AdjustedPlayerRushingRequest",
     "AdjustedTeamMetricsRequest",
+    "AthleteIdentity",
     "AdvancedBoxScoreRequest",
     "AdvancedBoxScore",
     "AdvancedGameStatsRequest",
     "AdvancedSeasonStatsRequest",
     "BettingLinesRequest",
     "CalendarRequest",
+    "CacheConfig",
+    "CacheMode",
+    "CachePolicyConfig",
+    "CacheProfile",
+    "CacheTTL",
     "CfpGamesRequest",
     "CfpParticipantsRequest",
     "CfpPlayoff",
     "CfpPlayoffRequest",
     "CFBDAuthenticationError",
     "CFBDAuthorizationError",
+    "CFBDCacheBackendError",
+    "CFBDCacheError",
+    "CFBDCacheMissError",
     "CFBDClient",
     "CFBDClientStateError",
     "CFBDConfigurationError",
     "CFBDDataFrameConversionError",
     "CFBDError",
     "CFBDHTTPError",
+    "CFBDIdentityAmbiguityError",
+    "CFBDIdentityNotFoundError",
+    "CFBDNoContentError",
     "CFBDOptionalDependencyError",
     "CFBDRateLimitError",
     "CFBDRequestValidationError",
@@ -166,6 +199,7 @@ __all__ = [
     "ConferenceAffiliationsRequest",
     "ConferenceChangesRequest",
     "ConferenceClassification",
+    "ConferenceIdentity",
     "ConferencesRequest",
     "ConferenceSPRatingsRequest",
     "CoreRatingsRequest",
@@ -175,12 +209,15 @@ __all__ = [
     "EloRatingsRequest",
     "ExpandedSRSRatingsRequest",
     "FPIRatingsRequest",
+    "FreshnessMode",
     "GameMediaRequest",
+    "GameIdentity",
     "GamesRequest",
     "GameWeatherRequest",
     "GameHavocRequest",
     "FBSTeamsRequest",
     "HomeAway",
+    "HydrationPlan",
     "InfoUsageRequest",
     "KickerPAARRequest",
     "LiveGame",
@@ -208,6 +245,7 @@ __all__ = [
     "RecruitingGroupsRequest",
     "RecruitingPlayersRequest",
     "RecruitingTeamsRequest",
+    "RedisCacheConfig",
     "RetryPolicy",
     "RosterRequest",
     "ReturningProductionRequest",
@@ -216,7 +254,9 @@ __all__ = [
     "SeasonType",
     "SPRatingsRequest",
     "SRSRatingsRequest",
+    "SQLiteCacheConfig",
     "TeamGamePPARequest",
+    "TeamIdentity",
     "TeamGameStatsRequest",
     "TeamSeasonStatsRequest",
     "TeamSeasonPPARequest",
@@ -229,6 +269,7 @@ __all__ = [
     "UserInfo",
     "UserUsage",
     "UserUsageApi",
+    "VenueIdentity",
     "WinProbabilityRequest",
     "DownType",
 ]

cfb_data-0.5.0/cfb_data/cfb_data/_catalog/__init__.py

@@ -0,0 +1 @@
+"""Provide internal normalized catalog contracts."""

cfb_data-0.5.0/cfb_data/cfb_data/_catalog/merge.py

@@ -0,0 +1,104 @@
+"""Merge canonical observations independently of storage backends."""
+
+from __future__ import annotations
+
+from dataclasses import fields, replace
+from datetime import datetime
+from typing import Protocol, cast
+
+from cfb_data._catalog.models import (
+    CatalogFact,
+    CatalogObservation,
+    FieldObservation,
+    ObservationState,
+)
+from cfb_data._catalog.projection import catalog_fact_key
+
+
+class _FactConstructor(Protocol):
+    """Construct a canonical fact from merge-validated field values."""
+
+    def __call__(self, **values: object) -> CatalogFact:
+        """Return one canonical fact."""
+        ...
+
+
+def merge_catalog_observations(
+    current: CatalogObservation | None,
+    candidate: CatalogObservation,
+) -> CatalogObservation:
+    """Merge observations using authority, time, and stable source precedence.
+
+    :param current: Previously selected field observations, if any.
+    :param candidate: Newly encountered field observations for the same grain.
+    :return: A deterministic merged observation.
+    :raises ValueError: If the observations describe different fact grains.
+    """
+    if current is None:
+        return (
+            candidate
+            if candidate.first_observed_at is not None
+            else replace(candidate, first_observed_at=_earliest_evidence(candidate))
+        )
+    if type(current.fact) is not type(candidate.fact) or catalog_fact_key(
+        current.fact
+    ) != catalog_fact_key(candidate.fact):
+        raise ValueError("Catalog observations must share a type and grain")
+
+    current_fields = {field.field: field for field in current.fields}
+    candidate_fields = {field.field: field for field in candidate.fields}
+    merged_fields: list[FieldObservation] = []
+    values: dict[str, object] = {}
+    for fact_field in fields(current.fact):
+        existing = current_fields[fact_field.name]
+        incoming = candidate_fields[fact_field.name]
+        selected = _select_field(existing, incoming)
+        merged_fields.append(selected)
+        if selected.value.state is ObservationState.value:
+            values[fact_field.name] = selected.value.value
+        elif selected.value.state is ObservationState.null:
+            values[fact_field.name] = None
+        else:
+            values[fact_field.name] = getattr(current.fact, fact_field.name)
+    constructor = cast(_FactConstructor, type(current.fact))
+    return CatalogObservation(
+        constructor(**values),
+        tuple(merged_fields),
+        min(_first_observed_at(current), _first_observed_at(candidate)),
+    )
+
+
+def _first_observed_at(observation: CatalogObservation) -> datetime:
+    """Return explicit or field-derived first observation time."""
+    return observation.first_observed_at or _earliest_evidence(observation)
+
+
+def _earliest_evidence(observation: CatalogObservation) -> datetime:
+    """Return the earliest timestamp carried by one observation's fields."""
+    observed = [
+        field.observed_at for field in observation.fields if field.authority > 0
+    ]
+    if not observed:
+        observed = [field.observed_at for field in observation.fields]
+    return min(observed)
+
+
+def _select_field(
+    current: FieldObservation, candidate: FieldObservation
+) -> FieldObservation:
+    """Return the field observation that wins deterministic precedence."""
+    if candidate.value.state is ObservationState.unobserved:
+        return current
+    if current.value.state is ObservationState.unobserved:
+        return candidate
+    current_precedence = (
+        current.authority,
+        current.observed_at,
+        current.source,
+    )
+    candidate_precedence = (
+        candidate.authority,
+        candidate.observed_at,
+        candidate.source,
+    )
+    return candidate if candidate_precedence >= current_precedence else current