Metadata-Version: 2.4
Name: fastbreak
Version: 0.0.3
Summary: Async NBA statistics API client
Project-URL: Homepage, https://github.com/reidhoch/fastbreak
Project-URL: Repository, https://github.com/reidhoch/fastbreak
Project-URL: Issues, https://github.com/reidhoch/fastbreak/issues
Project-URL: Changelog, https://github.com/reidhoch/fastbreak/blob/main/CHANGELOG.md
Author-email: Reid Hochstedler <reidhoch@gmail.com>
Maintainer-email: Reid Hochstedler <reidhoch@gmail.com>
License-File: LICENSE
Keywords: analytics,api,basketball,nba,sports,statistics,stats
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiodns>=4.0
Requires-Dist: aiohttp>=3.13
Requires-Dist: anyio>=4.12.1
Requires-Dist: cachetools>=5.5
Requires-Dist: certifi>=2026
Requires-Dist: pydantic>=2.12
Requires-Dist: structlog>=25.0
Requires-Dist: tenacity>=8.0
Description-Content-Type: text/markdown

# fastbreak

[![PyPI](https://img.shields.io/pypi/v/fastbreak)](https://pypi.org/project/fastbreak/)
[![Python](https://img.shields.io/pypi/pyversions/fastbreak)](https://pypi.org/project/fastbreak/)
[![License](https://img.shields.io/github/license/reidhoch/fastbreak)](https://github.com/reidhoch/fastbreak/blob/main/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/reidhoch/fastbreak/ci.yaml?label=CI)](https://github.com/reidhoch/fastbreak/actions)

Async Python client for the NBA Stats API. Fully typed, with Pydantic models and optional DataFrame conversion.

## Installation

```bash
pip install fastbreak
```

With DataFrame support:

```bash
pip install fastbreak pandas   # or polars
```

## Quick Start

```python
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

```python
from fastbreak.models import TeamStanding

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

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

## Features

- **Async-first** - Built on aiohttp for high-performance concurrent requests
- **Fully typed** - Complete type hints with strict mypy compliance
- **Pydantic models** - Validated response parsing with IDE autocomplete
- **DataFrame support** - Optional conversion to pandas or polars
- **Automatic retries** - Handles rate limiting and transient errors

## Available Endpoints

100+ endpoints covering:

| Category | Examples |
|----------|----------|
| **Box Scores** | `BoxScoreTraditional`, `BoxScoreAdvanced`, `BoxScorePlayerTrack` |
| **Players** | `PlayerCareerStats`, `PlayerGameLogs`, `PlayerDashboardByClutch` |
| **Teams** | `TeamDetails`, `TeamGameLog`, `TeamPlayerDashboard` |
| **League** | `LeagueStandings`, `LeagueLeaders`, `LeagueGameLog` |
| **Play-by-Play** | `PlayByPlay`, `GameRotation` |
| **Shooting** | `ShotChartDetail`, `ShotChartLeaguewide` |
| **Draft** | `DraftHistory`, `DraftCombineStats` |

See [`fastbreak.endpoints`](https://github.com/reidhoch/fastbreak/tree/main/src/fastbreak/endpoints) for the full list.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Stargazers

[![Stargazers](https://api.star-history.com/svg?repos=reidhoch/fastbreak&type=date&legend=top-left)](https://www.star-history.com/#reidhoch/fastbreak&type=date&legend=top-left)
