fastbreak

Async Python client for the NBA Stats API, fully typed with Pydantic. Pandas and polars exports are optional.

Installation

Requires Python 3.12+.

pip install fastbreak

With DataFrame support:

pip install fastbreak pandas   # or polars

Quick Start

import asyncio
from fastbreak.clients import NBAClient
from fastbreak.endpoints import LeagueStandings

async def main():
    async with NBAClient() as client:
        standings = await client.get(LeagueStandings(season="2025-26"))

        for team in standings.standings[:5]:
            print(f"{team.team_name}: {team.wins}-{team.losses}")

asyncio.run(main())

Convert to DataFrame

from fastbreak.models import TeamStanding

# To pandas
df = TeamStanding.to_pandas(standings.standings)

# To polars
df = TeamStanding.to_polars(standings.standings)

Batch Requests

Fetch multiple endpoints concurrently with get_many():

from fastbreak.clients import NBAClient
from fastbreak.endpoints import BoxScoreTraditional

game_ids = ["0022500001", "0022500002", "0022500003"]

async with NBAClient() as client:
    results = await client.get_many(
        [BoxScoreTraditional(game_id=gid) for gid in game_ids],
        max_concurrency=5,
    )

Results come back in the same order as the input. If any request fails, all in-flight requests are cancelled and an ExceptionGroup is raised.

Caching

Pass cache_ttl to avoid hitting the API twice for the same response:

from fastbreak.clients import NBAClient
from fastbreak.endpoints import LeagueStandings

async with NBAClient(cache_ttl=300, cache_maxsize=256) as client:
    result = await client.get(LeagueStandings(season="2025-26"))  # cached for 5 min
    print(client.cache_info)  # {'size': 1, 'maxsize': 256, 'ttl': 300}
    await client.clear_cache()

Features

• Async I/O via aiohttp (asyncio only)
• Strict mypy typing
• Pydantic models for all responses, with pandas/polars export
• Retries and rate-limit handling built in
• get_many() for concurrent batch requests
• Optional TTL response caching
• Pure-computation analytics: BPM, VORP, PER, true shooting, win shares, Pythagorean wins

Utility Modules

Skip the endpoint boilerplate for common operations. Import directly and pass client as the first argument.

Data Access

Shooting & Defense

Matchups, Lineups & Rotations

Analytics & Comparison

from fastbreak.players import search_players, get_player_game_log
from fastbreak.games import get_todays_games

async with NBAClient() as client:
    players = await search_players(client, "Jokić")
    log     = await get_player_game_log(client, player_id=players[0].person_id)
    games   = await get_todays_games(client)

Available Endpoints

Over 115 endpoints covering:

See fastbreak.endpoints for the full list.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.

Stargazers