ncaa_eval.ingest.connectors.base module

Abstract base class for data source connectors and shared exception hierarchy.

All concrete connectors (Kaggle, ESPN, etc.) inherit from Connector and implement the fetch_* methods relevant to their data source. The exception hierarchy provides a uniform error contract across connectors so that callers can handle failures without coupling to a specific source.

exception ncaa_eval.ingest.connectors.base.AuthenticationError

Bases: ConnectorError

Credentials missing, invalid, or expired.

class ncaa_eval.ingest.connectors.base.Connector

Bases: ABC

Abstract base class for NCAA data source connectors.

All connectors must implement fetch_games(), which is the universal capability. fetch_teams() and fetch_seasons() are optional capabilities — subclasses that do not support them inherit the default implementation, which raises NotImplementedError. Callers should use isinstance() checks or try/except NotImplementedError to probe optional capabilities before calling them.

abstractmethod fetch_games(season: int) → list[Game]

Fetch game results for a given season year.

fetch_seasons() → list[Season]

Fetch available seasons from the source.

Optional capability — not all connectors provide season master data.

Raises:

NotImplementedError – If this connector does not support fetching seasons.

fetch_teams() → list[Team]

Fetch team data from the source.

Optional capability — not all connectors provide team master data.

Raises:

NotImplementedError – If this connector does not support fetching teams.

exception ncaa_eval.ingest.connectors.base.ConnectorError

Bases: Exception

Base exception for all connector errors.

exception ncaa_eval.ingest.connectors.base.DataFormatError

Bases: ConnectorError

Raw data (CSV / API response) does not match the expected schema.

exception ncaa_eval.ingest.connectors.base.NetworkError

Bases: ConnectorError

Connection failure, timeout, or HTTP error.