Sdk

griddy / nfl / sdk**

sdk

NFL SDK client for accessing NFL data from multiple API endpoints.

This module provides the GriddyNFL class, the main entry point for accessing NFL data including games, stats, rosters, and Next Gen Stats.

Example

from griddy.nfl import GriddyNFL nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"}) games = nfl.games.get_games(season=2024, week=1) stats = nfl.stats.passing.get_passing_stats(season=2024)

Classes

GriddyNFL

GriddyNFL(
    nfl_auth: Optional[Dict[str, Any]] = None,
    login_email: Optional[str] = None,
    login_password: Optional[str] = None,
    headless_login: Optional[bool] = False,
    server_idx: Optional[int] = None,
    server_url: Optional[str] = None,
    url_params: Optional[Dict[str, str]] = None,
    client: Optional[HttpClient] = None,
    async_client: Optional[AsyncHttpClient] = None,
    retry_config: OptionalNullable[RetryConfig] = UNSET,
    timeout_ms: Optional[int] = None,
    debug_logger: Optional[Logger] = None,
)

Bases: BaseSDK

              flowchart TD
              griddy.nfl.sdk.GriddyNFL[GriddyNFL]
              griddy.nfl.basesdk.BaseSDK[BaseSDK]

                              griddy.nfl.basesdk.BaseSDK --> griddy.nfl.sdk.GriddyNFL
                


              click griddy.nfl.sdk.GriddyNFL href "" "griddy.nfl.sdk.GriddyNFL"
              click griddy.nfl.basesdk.BaseSDK href "" "griddy.nfl.basesdk.BaseSDK"
            

Main client for accessing NFL data from multiple API endpoints.

GriddyNFL provides unified access to NFL data through three API categories:

• Regular API: Public NFL.com endpoints for games, rosters, standings
• Pro API: Advanced statistics, betting odds, player projections
• Next Gen Stats: Player tracking data and advanced analytics

Sub-SDKs are loaded lazily on first access to minimize startup time.

ATTRIBUTE	DESCRIPTION
authentication	Token generation and refresh operations. TYPE: Authentication
combine	NFL Combine workout data and results. TYPE: Combine
draft	NFL Draft picks and information. TYPE: Draft
games	Game schedules, scores, and details. TYPE: Games
rosters	Team rosters and player assignments. TYPE: Rosters
standings	Division and conference standings. TYPE: Standings
football_teams	Team information and details. TYPE: Teams
venues	Stadium information. TYPE: Venues
weeks	Season week information. TYPE: Weeks
stats	Aggregated player/team statistics (passing, rushing, etc.). TYPE: StatsSDK
betting	Betting odds and lines. TYPE: Betting
content	Game previews and film cards. TYPE: Content
players	Player information and projections. TYPE: Players
pro_games	Advanced game data. TYPE: ProGames
schedules	Matchup rankings and injury reports. TYPE: Schedules
transactions	Player transactions. TYPE: Transactions
teams	Pro team information. TYPE: Teams
ngs	Next Gen Stats (tracking data, leaderboards, charts). TYPE: NextGenStats

Example

from griddy.nfl import GriddyNFL

Initialize with auth token

nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"})

Get games

games = nfl.games.get_games(season=2024, week=1)

Get Next Gen Stats

passing = nfl.ngs.stats.get_passing_stats(season=2024)

Use as context manager

with GriddyNFL(nfl_auth=auth) as nfl: ... games = nfl.games.get_games(season=2024)

Initialize the GriddyNFL client.

You must provide authentication either via a pre-obtained auth token (nfl_auth) or via email/password for browser-based authentication.

PARAMETER	DESCRIPTION
nfl_auth	Dictionary containing authentication information, must include 'accessToken' key. Example: TYPE: Optional[Dict[str, Any]] DEFAULT: None
login_email	Email address for NFL.com account. Used with login_password for browser-based authentication. TYPE: Optional[str] DEFAULT: None
login_password	Password for NFL.com account. TYPE: Optional[str] DEFAULT: None
headless_login	If True, run browser in headless mode during authentication. Defaults to False. TYPE: Optional[bool] DEFAULT: False
server_idx	Index of the server to use from the server list. TYPE: Optional[int] DEFAULT: None
server_url	Override the default server URL. TYPE: Optional[str] DEFAULT: None
url_params	Parameters to template into the server URL. TYPE: Optional[Dict[str, str]] DEFAULT: None
client	Custom synchronous HTTP client (must implement HttpClient). TYPE: Optional[HttpClient] DEFAULT: None
async_client	Custom async HTTP client (must implement AsyncHttpClient). TYPE: Optional[AsyncHttpClient] DEFAULT: None
retry_config	Configuration for automatic request retries. TYPE: OptionalNullable[RetryConfig] DEFAULT: UNSET
timeout_ms	Request timeout in milliseconds. TYPE: Optional[int] DEFAULT: None
debug_logger	Custom logger for debug output. TYPE: Optional[Logger] DEFAULT: None

RAISES	DESCRIPTION
ValueError	If neither nfl_auth nor email/password is provided, or if both are provided.

Example

With pre-obtained token

nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"})

With email/password

nfl = GriddyNFL( ... login_email="user@example.com", ... login_password="password", ... headless_login=True, ... )

Source code in griddy/nfl/sdk.py

def __init__(
    self,
    nfl_auth: Optional[Dict[str, Any]] = None,
    login_email: Optional[str] = None,
    login_password: Optional[str] = None,
    headless_login: Optional[bool] = False,
    server_idx: Optional[int] = None,
    server_url: Optional[str] = None,
    url_params: Optional[Dict[str, str]] = None,
    client: Optional[HttpClient] = None,
    async_client: Optional[AsyncHttpClient] = None,
    retry_config: OptionalNullable[RetryConfig] = UNSET,
    timeout_ms: Optional[int] = None,
    debug_logger: Optional[Logger] = None,
) -> None:
    """Initialize the GriddyNFL client.

    You must provide authentication either via a pre-obtained auth token
    (nfl_auth) or via email/password for browser-based authentication.

    Args:
        nfl_auth: Dictionary containing authentication information,
            must include 'accessToken' key. Example:
            {"accessToken": "your_nfl_access_token"}
        login_email: Email address for NFL.com account. Used with
            login_password for browser-based authentication.
        login_password: Password for NFL.com account.
        headless_login: If True, run browser in headless mode during
            authentication. Defaults to False.
        server_idx: Index of the server to use from the server list.
        server_url: Override the default server URL.
        url_params: Parameters to template into the server URL.
        client: Custom synchronous HTTP client (must implement HttpClient).
        async_client: Custom async HTTP client (must implement AsyncHttpClient).
        retry_config: Configuration for automatic request retries.
        timeout_ms: Request timeout in milliseconds.
        debug_logger: Custom logger for debug output.

    Raises:
        ValueError: If neither nfl_auth nor email/password is provided,
            or if both are provided.

    Example:
        >>> # With pre-obtained token
        >>> nfl = GriddyNFL(nfl_auth={"accessToken": "your_token"})
        >>> # With email/password
        >>> nfl = GriddyNFL(
        ...     login_email="user@example.com",
        ...     login_password="password",
        ...     headless_login=True,
        ... )
    """
    client_supplied = True
    if client is None:
        client = httpx.Client(follow_redirects=True)
        client_supplied = False

    assert issubclass(
        type(client), HttpClient
    ), "The provided client must implement the HttpClient protocol."

    async_client_supplied = True
    if async_client is None:
        async_client = httpx.AsyncClient(follow_redirects=True)
        async_client_supplied = False

    if debug_logger is None:
        debug_logger = get_default_logger()

    assert issubclass(
        type(async_client), AsyncHttpClient
    ), "The provided async_client must implement the AsyncHttpClient protocol."

    auth_params_error = (
        "You must provide either nfl_auth, OR email/password combination."
    )
    if all([nfl_auth, login_email, login_password]):
        raise ValueError(auth_params_error)
    elif not any([nfl_auth, login_email, login_password]):
        raise ValueError(auth_params_error)

    if not nfl_auth:
        nfl_auth = do_browser_auth(
            email=login_email, password=login_password, headless=headless_login
        )

        print("Writing auth creds to file")
        with open("creds.json", "w") as outfile:
            json.dump(nfl_auth, outfile, indent=4)

    security = models.Security(nfl_auth=nfl_auth["accessToken"])

    if server_url is not None:
        if url_params is not None:
            server_url = utils.template_url(server_url, url_params)

    BaseSDK.__init__(
        self,
        SDKConfiguration(
            client=client,
            client_supplied=client_supplied,
            async_client=async_client,
            async_client_supplied=async_client_supplied,
            security=security,
            server_url=server_url,
            server_idx=server_idx,
            retry_config=retry_config,
            timeout_ms=timeout_ms,
            debug_logger=debug_logger,
            custom_auth_info=nfl_auth,
        ),
        parent_ref=self,
    )

    hooks = SDKHooks()

    # pylint: disable=protected-access
    self.sdk_configuration.__dict__["_hooks"] = hooks

    self.sdk_configuration = hooks.sdk_init(self.sdk_configuration)

    weakref.finalize(
        self,
        close_clients,
        cast(ClientOwner, self.sdk_configuration),
        self.sdk_configuration.client,
        self.sdk_configuration.client_supplied,
        self.sdk_configuration.async_client,
        self.sdk_configuration.async_client_supplied,
    )

Attributes

authentication instance-attribute

authentication: Authentication

Token generation and refresh operations for NFL API access.

combine instance-attribute

combine: Combine

NFL Combine workout data and results.

draft instance-attribute

draft: Draft

NFL Draft picks and information.

games instance-attribute

games: Games

Game schedules, scores, and details from the regular API.

rosters instance-attribute

rosters: Rosters

Team rosters and player assignments.

standings instance-attribute

standings: Standings

Division and conference standings.

football_teams instance-attribute

football_teams: Teams

Team information and details.

venues instance-attribute

venues: Venues

Stadium and venue information.

weeks instance-attribute

weeks: Weeks

Season week information.

stats instance-attribute

stats: StatsSDK

Aggregated player and team statistics (stats.passing, stats.rushing, etc.).

betting instance-attribute

betting: Betting

Betting odds and lines.

content instance-attribute

content: Content

Game previews, film cards, and insights.

players instance-attribute

players: Players

Player information, statistics, and projections.

pro_games instance-attribute

pro_games: ProGames

Advanced game data and statistics.

schedules instance-attribute

schedules: Schedules

Matchup rankings and injury reports.

transactions instance-attribute

transactions: Transactions

Player transactions and roster moves.

fantasy_statistics instance-attribute

fantasy_statistics: FantasyStatistics

Fantasy football statistics and scoring metrics.

teams instance-attribute

teams: Teams

Pro team information, rosters, and schedules.

ngs instance-attribute

ngs: NextGenStats

Next Gen Stats data (tracking statistics, leaderboards, charts, highlights).

Functions

Functions