pbpstats

https://pbpstats.readthedocs.io/
Admin
A package to scrape and parse NBA, WNBA and G-League play-by-play data with features including...
Tokens:99,208
Snippets:466
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Get All Final Games for a Day (Python)

Source: https://pbpstats.readthedocs.io/en/latest/quickstart

Illustrates how to fetch all final games for a specific day using the pbpstats client. This example configures the 'Games' resource to use the 'web' source and importantly, the 'stats_nba' data provider, as required for day-specific lookups. It then iterates through and prints the final games for the specified date.

```python
from pbpstats.client import Client

settings = {
    "Games": {"source": "web", "data_provider": "stats_nba"},
}
client = Client(settings)
day = client.Day("12/05/2019", "nba")

for final_game in day.games.final_games:
    print(final_game)
```

--------------------------------

### Filter Possessions by Start Type (Python)

Source: https://pbpstats.readthedocs.io/en/latest/quickstart

This code snippet filters possessions to include only those that started with an 'OffAtRimMiss' type. It assumes a 'game' object with a 'possessions' attribute, where each possession has a 'possession_start_type' attribute.

```python
off_rim_miss = [possession for possession in game.possessions.items if possession.possession_start_type == "OffAtRimMiss"]
```

--------------------------------

### Install pbpstats using pip

Source: https://pbpstats.readthedocs.io/en/latest/quickstart

Install the pbpstats library using the pip package manager. This command downloads and installs the latest version of the library and its dependencies.

```bash
pip install pbpstats
```

--------------------------------

### StatsStartOfPeriod Class for NBA Period Starters

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.resources.enhanced_pbp.stats_nba

Represents the start of a period event in NBA play-by-play data. It inherits from StartOfPeriod and StatsEnhancedPbpItem. Includes a method to retrieve the starting players for each team, with an option to use an override file if parsing fails.

```python
from pbpstats.resources.enhanced_pbp.stats_nba.start_of_period import StatsStartOfPeriod

# Example usage (assuming you have a start of period event object)
# sop_event = StatsStartOfPeriod(...)
# starters = sop_event.get_period_starters()
# print(starters)
```

--------------------------------

### DataStartOfPeriod Class Definition and Starter Retrieval (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/data_nba/start_of_period

Defines the DataStartOfPeriod class for handling start of period events. It includes a method to retrieve starting players for each team, attempting to parse play-by-play events first and falling back to boxscore API requests if necessary. It raises an exception if the correct number of starters cannot be determined.

```python
from pbpstats.resources.enhanced_pbp import (
    InvalidNumberOfStartersException,
    StartOfPeriod,
)
from pbpstats.resources.enhanced_pbp.data_nba.enhanced_pbp_item import (
    DataEnhancedPbpItem,
)



[docs]class DataStartOfPeriod(StartOfPeriod, DataEnhancedPbpItem):
    """
    Class for start of period events
    """

    event_type = 12

    def __init__(self, *args):
        super().__init__(*args)


[docs]    def get_period_starters(self, file_directory=None):
        """
        Gets player ids of players who started the period for each team
        If players can't be determined from parsing pbp, will try to
        find them by making API request to stats.nba.com boxscore filtered by time.

        :param str file_directory: directory in which overrides subdirectory exists
            containing period starter overrides when period starters can't be determined
            from parsing pbp events
        :returns: dict with list of player ids for each team
            with players on the floor at start of period
        :raises: :obj:`~pbpstats.resources.enhanced_pbp.start_of_period.InvalidNumberOfStartersException`:
            If all 5 players that start the period for a team can't be determined.
        """
        try:
            return self._get_period_starters_from_period_events(file_directory)
        except InvalidNumberOfStartersException:
            # get starters from stats.nba.com boxcore data by time range
            return self._get_starters_from_boxscore_request()

```

--------------------------------

### Python Class for Live Start of Period Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/live/start_of_period

Defines the LiveStartOfPeriod class, inheriting from StartOfPeriod and LiveEnhancedPbpItem. It sets specific action and sub-types for period start events and provides a method to retrieve starting players for each team, with options for handling missing data and file overrides. This class is crucial for analyzing player lineups at the beginning of game periods.

```python
from pbpstats.resources.enhanced_pbp import StartOfPeriod
from pbpstats.resources.enhanced_pbp.live.enhanced_pbp_item import LiveEnhancedPbpItem


[docs]class LiveStartOfPeriod(StartOfPeriod, LiveEnhancedPbpItem):
    """
    Class for start of period events
    """

    action_type = "period"
    sub_type = "start"

    def __init__(self, *args):
        super().__init__(*args)


[docs]    def get_period_starters(self, file_directory=None, ignore_missing_starters=False):
        """
        Gets player ids of players who started the period for each team

        :param str file_directory: directory in which overrides subdirectory exists
            containing period starter overrides when period starters can't be determined
            from parsing pbp events
        :param bool ignore_missing_starters: when True won't reaise missing starters exception
        :returns: dict with list of player ids for each team
            with players on the floor at start of period
        :raises: :obj:`~pbpstats.resources.enhanced_pbp.start_of_period.InvalidNumberOfStartersException`:
            If all 5 players that start the period for a team can't be determined.
        """
        return self._get_period_starters_from_period_events(
            file_directory, ignore_missing_starters=ignore_missing_starters
        )

```

--------------------------------

### Get All Final Games for a Season (Python)

Source: https://pbpstats.readthedocs.io/en/latest/quickstart

Shows how to initialize the pbpstats client to retrieve all final games for a given NBA season. It configures the 'Games' resource to use the 'web' source and the 'data_nba' data provider. The code then iterates through the retrieved final games and prints each one.

```python
from pbpstats.client import Client

settings = {
    "Games": {"source": "web", "data_provider": "data_nba"},
}
client = Client(settings)
season = client.Season("nba", "2019-20", "Regular Season")

for final_game in season.games.final_games:
    print(final_game)
```

--------------------------------

### Set Period Start Data (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/data_loader/nba_enhanced_pbp_loader

This method sets the `team_starting_with_ball` and `period_starters` attributes for events that mark the beginning of a period. It utilizes the `start_period_indices` calculated in `_add_extra_attrs_to_all_events` and calls `get_team_starting_with_ball` and `get_period_starters` methods on the `StartOfPeriod` event objects.

```python
    def _set_period_start_items(self):
        """
        sets team starting period with the ball and period starters for each team
        """
        for i in self.start_period_indices:
            team_id = self.items[i].get_team_starting_with_ball()
            self.items[i].team_starting_with_ball = team_id
            period_starters = self.items[i].get_period_starters(
                file_directory=self.file_directory
            )
            self.items[i].period_starters = period_starters

```

--------------------------------

### Instantiate Client and Get Game Data (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/objects/day

This code snippet demonstrates how to instantiate the pbpstats client with custom settings and retrieve game data for a specific date. It iterates through the games and prints the data for each game. Dependencies include the pbpstats.client module.

```python
from pbpstats.client import Client

settings = {
    "dir": "/response_data",
    "Games": {"source": "web", "data_provider": "stats_nba"}
}
client = Client(settings)
day = client.Day("02/03/2020", "nba")
for game in day.games.items:
    print(game.data)
```

--------------------------------

### Get Period Starters with Team Map

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/start_of_period

This function retrieves the starters for a given period and creates a map of players to their teams. It then validates that both teams have exactly 5 starters, unless the `ignore_missing_starters` flag is set to True. It returns a dictionary mapping teams to their starters.

```python
def _get_period_starters_from_period_events(
        self, file_directory, ignore_missing_starters=False
    ):
        starters, player_team_map = self._get_players_who_started_period_with_team_map()

        starters_by_team = self._split_up_starters_by_team(starters, player_team_map)
        if not ignore_missing_starters:
            self._check_both_teams_have_5_starters(starters_by_team, file_directory)

        return starters_by_team
```

--------------------------------

### Detailed Possession Data Analysis (Python)

Source: https://pbpstats.readthedocs.io/index

Illustrates how to work with detailed possession data, including its start and end times, score margin, and preceding possession outcome. This requires loading enhanced PBP data.

```python
import pbpstats.data_loader.data_nba_com.data_loader_factory

# Assuming you have loaded a game's enhanced PBP data
game_id = '0022100001' # Example Game ID
loader = pbpstats.data_loader.data_nba_com.data_loader_factory.get_game(game_id=game_id)

# Access possession data (example: first possession)
if loader.possessions:
    first_possession = loader.possessions[0]
    print(f"Possession start: {first_possession.start_time}")
    print(f"Possession end: {first_possession.end_time}")
    print(f"Score margin at start: {first_possession.score_margin}")
    print(f"Previous possession ended with: {first_possession.previous_possession_ended_with}")
else:
    print("No possession data found for this game.")
```

--------------------------------

### Abstract Base Class for StartOfPeriod Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/start_of_period

Defines an abstract base class `StartOfPeriod` for handling the start of period events. It includes abstract methods and properties for retrieving period starters and determining the league based on the game ID.

```python
class StartOfPeriod(metaclass=abc.ABCMeta):
    """
    Class for start of period events
    """


    @abc.abstractclassmethod
    def get_period_starters(self, file_directory):
        """
        Gets player ids of players who started the period for each team

        :param str file_directory: directory in which overrides subdirectory exists
            containing period starter overrides when period starters can't be determined
            from parsing pbp events
        :returns: dict with list of player ids for each team
            with players on the floor at start of period
        :raises: :obj:`~pbpstats.resources.enhanced_pbp.start_of_period.InvalidNumberOfStartersException`:
            If all 5 players that start the period for a team can't be determined.
        """
        pass


    @property
    def current_players(self):
        """
        returns period starters
        """
        return self.period_starters

    @property
    def league(self):
        """
        Returns League for game id.

        First 2 in game id represent league - 00 for nba, 10 for wnba, 20 for g-league
        """
        if self.game_id[0:2] == NBA_GAME_ID_PREFIX:
            return NBA_STRING
        elif self.game_id[0:2] == G_LEAGUE_GAME_ID_PREFIX:
            return G_LEAGUE_STRING
        elif self.game_id[0:2] == WNBA_GAME_ID_PREFIX:
            return WNBA_STRING

    @property
    def league_url_part(self):
        if self.game_id[0:2] == NBA_GAME_ID_PREFIX:
            return NBA_STRING
        elif self.game_id[0:2] == G_LEAGUE_GAME_ID_PREFIX:
            return f"{G_LEAGUE_STRING}.{NBA_STRING}"
        elif self.game_id[0:2] == WNBA_GAME_ID_PREFIX:
            return WNBA_STRING

    def _get_starters_from_boxscore_request(self):
        """
        makes request to boxscore url for time from period start to first event to get period starters
        """
        base_url = (
            f"https://stats.{self.league_url_part}.com/stats/boxscoretraditionalv2"
        )
        event = self
        while event is not None and event.seconds_remaining == self.seconds_remaining:
            event = event.next_event
        seconds_to_first_event = self.seconds_remaining - event.seconds_remaining

        if self.league == WNBA_STRING:
            seconds_in_period = 6000
        else:
            seconds_in_period = 7200

        if self.period == 1:
            start_range = 0
        elif self.period <= 4:
            start_range = int(seconds_in_period * (self.period - 1))
        else:
            start_range = int(4 * seconds_in_period + 3000 * (self.period - 5))
        end_range = int(start_range + seconds_to_first_event * 10)
        params = {
            "GameId": self.game_id,
            "StartPeriod": 0,
            "EndPeriod": 0,
            "RangeType": 2,
            "StartRange": start_range,
            "EndRange": end_range,
        }
        starters_by_team = {}
        response = requests.get(
            base_url, params, headers=HEADERS, timeout=REQUEST_TIMEOUT
        )
        if response.status_code == 200:
            response_json = response.json()
        else:
            response.raise_for_status()

        headers = response_json["resultSets"][0]["headers"]
        rows = response_json["resultSets"][0]["rowSet"]
        players = [dict(zip(headers, row)) for row in rows]
        starters = sorted(
            players, key=lambda k: int(k["MIN"].split(":")[1]), reverse=True
        )

        if len(starters) < 10:
            raise InvalidNumberOfStartersException(
                f"GameId: {self.game_id}, Period: {self.period}, Starters: {starters}"
            )

        for starter in starters[0:10]:
            team_id = starter["TEAM_ID"]
            player_id = starter["PLAYER_ID"]
            if team_id not in starters_by_team.keys():
                starters_by_team[team_id] = []
            starters_by_team[team_id].append(player_id)

        for team_id, starters in starters_by_team.items():
            if len(starters) != 5:
                raise InvalidNumberOfStartersException(

```

--------------------------------

### Create Stats NBA Enhanced PBP DataLoader | Python

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/data_loader/factory

This example demonstrates how to use the DataLoaderFactory to create a data loader object specifically for enhanced PBP data from stats.nba.com. It initializes the factory and then retrieves the appropriate loader.

```python
from pbpstats.data_loader.factory import DataLoaderFactory

data_loader = DataLoaderFactory()
stats_enhanced_pbp_data_loader = data_loader.get_data_loader("stats_nba", "EnhancedPbp")
print(stats_enhanced_pbp_data_loader[0])
# prints "<class 'pbpstats.data_loader.stats_nba.enhanced_pbp_loader.StatsNbaEnhancedPbpLoader'>"
```

--------------------------------

### Instantiate and Get Game Possessions - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.objects

Instantiates a Game object to load possession data for a specific game ID. It configures the client to read possession data from files in a specified directory. The code then iterates through the game's possessions and prints each one.

```Python
from pbpstats.client import Client

settings = {
    "dir": "/response_data",
    "Possessions": {"source": "file", "data_provider": "stats_nba"}
}
client = Client(settings)
game = client.Game('0021900001')
for possession in game.possessions.items:
    print(possession)

```

--------------------------------

### Initialize pbpstats Client with Game Data Settings (Python)

Source: https://pbpstats.readthedocs.io/en/latest/quickstart

Demonstrates how to initialize the pbpstats client with custom settings, specifying a data directory for saving responses and configuring the 'Boxscore' and 'Possessions' resources to use file source with 'stats_nba' data provider. It then instantiates a Game object for a specific game ID.

```python
from pbpstats.client import Client

settings = {
    "dir": "/response_data",
    "Boxscore": {"source": "file", "data_provider": "stats_nba"},
    "Possessions": {"source": "file", "data_provider": "stats_nba"},
}
client = Client(settings)
game = client.Game("0021900001")
```

--------------------------------

### Load Live PBP Data from File using Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.live.pbp

This snippet demonstrates how to load live Play-by-Play (PBP) data for a specific NBA game from a local file using the `LivePbpFileLoader` and `LivePbpLoader` from the pbpstats library. It initializes the loaders, retrieves the game data, and prints the first event's data.

```python
from pbpstats.data_loader import LivePbpFileLoader, LivePbpLoader

source_loader = LivePbpFileLoader("/data")
pbp_loader = LivePbpLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game
```

--------------------------------

### Get Offensive Team ID at Period Start

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/start_of_period

Returns the team ID of the team that is on offense at the start of a period. This method simply calls `get_team_starting_with_ball` to determine the offensive team.

```python
def get_offense_team_id(self):
        """
        returns team id for team on starting period on offense
        """
        return self.team_starting_with_ball
```

--------------------------------

### Client Class Initialization (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/client

The Client class constructor initializes the client by loading data loader objects based on provided settings. It dynamically sets attributes for data loaders and data sources for each specified resource.

```python
import re

import pbpstats.objects as objects
import pbpstats.resources as resources
from pbpstats.data_loader.factory import DataLoaderFactory

DATA_LOADER_SUFFIX = "DataLoaderClass"
DATA_SOURCE_SUFFIX = "DataSource"
PATTERN = re.compile(r"(?<!^)(?=[A-Z])")  # for converting camel case to snake case



class Client(object):
    """
    :param dict settings: Dict with data that specifies which data loaders should be used.
        ``dir`` key is optional, but recommended and should point to the directory you have set up
        that either already contains response data or where you want to store the response data.
        Other keys in the settings dict should be resources from the :py:mod:`~pbpstats.resources` module
        and their values should be a dict with ``source`` ('file' or 'web') and ``data_provider`` ('stats_nba' or 'data_nba' or 'live')
    """

    def __init__(self, settings):
        data_loader = DataLoaderFactory()
        self.settings = settings
        self.data_directory = settings.get("dir")
        self._load_objects()
        self._load_resources()
        for resource, value in settings.items():
            if resource in data_loader.loaders.keys():
                resource_data_loaders = data_loader.get_data_loader(
                    value["data_provider"], resource
                )
                for resource_data_loader in resource_data_loaders:
                    parent_cls_name = resource_data_loader["loader"].parent_object
                    setattr(
                        getattr(self, parent_cls_name),
                        f"{resource}{DATA_LOADER_SUFFIX}",
                        resource_data_loader["loader"],
                    )
                    setattr(
                        getattr(self, parent_cls_name),
                        f"{resource}{DATA_SOURCE_SUFFIX}",
                        resource_data_loader[f'{{value["source"]}}_source'],
                    )
                    setattr(
                        getattr(self, parent_cls_name),
                        resource,
                        self.resource_dict[resource],
                    )
```

--------------------------------

### Get Team Starting With Ball in Period

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/start_of_period

Retrieves the team ID of the team that starts a given period with possession. It handles cases for jump balls at the start of periods and determines possession based on the first scoring play, turnover, or free throw.

```python
def get_team_starting_with_ball(self):
        """
        returns team id for team on starting period with the ball
        """
        if (self.period == 1 or self.period >= 5) and isinstance(
            self.next_event, JumpBall
        ):
            # period starts with jump ball - team that wins starts with the ball
            return self.next_event.team_id
        else:
            # find team id on first shot, non technical ft or turnover
            next_event = self.next_event
            while not (
                isinstance(next_event, (FieldGoal, Turnover))
                or (
                    isinstance(next_event, FreeThrow) and not next_event.is_technical_ft
                )
            ):
                next_event = next_event.next_event
            return next_event.team_id
```

--------------------------------

### Load Live PBP Data from Web using Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.live.pbp

This snippet shows how to load live Play-by-Play (PBP) data directly from the NBA Stats API using `LivePbpWebLoader` and `LivePbpLoader`. It initializes the web loader, passing it to the `LivePbpLoader` to fetch data for a given game ID. Optionally, the `file_directory` parameter can be used to save the response data locally.

```python
from pbpstats.data_loader import LivePbpWebLoader, LivePbpLoader

source_loader = LivePbpWebLoader()
pbp_loader = LivePbpLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game
```

--------------------------------

### Get Period Starters for NBA Enhanced PBP Data

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/stats_nba/start_of_period

Retrieves the player IDs of players who started a period for each team. It first attempts to parse this information from play-by-play events. If that fails, it makes an API request to stats.nba.com's boxscore endpoint filtered by time. This method requires the pbpstats library and may raise an InvalidNumberOfStartersException if the 5 starting players cannot be determined.

```python
from pbpstats.resources.enhanced_pbp import (
    InvalidNumberOfStartersException,
    StartOfPeriod,
)
from pbpstats.resources.enhanced_pbp.stats_nba.enhanced_pbp_item import (
    StatsEnhancedPbpItem,
)



[docs]
class StatsStartOfPeriod(StartOfPeriod, StatsEnhancedPbpItem):
    """
    Class for start of period events
    """

    event_type = 12

    def __init__(self, *args):
        super().__init__(*args)


[docs]
    def get_period_starters(self, file_directory=None):
        """
        Gets player ids of players who started the period for each team.
        If players can't be determined from parsing pbp, will try to
        find them by making API request to stats.nba.com boxscore filtered by time.

        :param str file_directory: directory in which overrides subdirectory exists
            containing period starter overrides when period starters can't be determined
            from parsing pbp events
        :returns: dict with list of player ids for each team
            with players on the floor at start of period
        :raises: :obj:`~pbpstats.resources.enhanced_pbp.start_of_period.InvalidNumberOfStartersException`:
            If all 5 players that start the period for a team can't be determined.
        """
        try:
            return self._get_period_starters_from_period_events(file_directory)
        except InvalidNumberOfStartersException:
            return self._get_starters_from_boxscore_request()

```

--------------------------------

### Get Period Starters and Player-Team Map

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/start_of_period

Identifies players who started a given period and maps them to their respective teams. It iterates through game events, tracking team assignments for players, and distinguishes between regular starters and players substituted in. Excludes players involved in technical fouls or ejections.

```python
def _get_players_who_started_period_with_team_map(self):
        starters = []
        subbed_in_players = []
        player_team_map = {}  # only player1 has team id in event, this is to track team
        event = self
        while event is not None and not isinstance(event, EndOfPeriod):
            if (
                not isinstance(event, Timeout)
                and event.player1_id != 0
                and hasattr(event, "team_id")
            ):
                player_id = event.player1_id
                if not isinstance(event, JumpBall):
                    # on jump balls team id is winning team, not guaranteed to be player1 team
                    player_team_map[player_id] = event.team_id
                if (
                    isinstance(event, Substitution)
                    and event.incoming_player_id is not None
                ):
                    player_team_map[event.incoming_player_id] = event.team_id
                    if (
                        event.incoming_player_id not in starters
                        and event.incoming_player_id not in subbed_in_players
                    ):
                        subbed_in_players.append(event.incoming_player_id)
                    if player_id not in starters and player_id not in subbed_in_players:
                        starters.append(player_id)

                is_technical_foul = isinstance(event, Foul) and (
                    event.is_technical or event.is_double_technical
                )
                if player_id not in starters and player_id not in subbed_in_players:
                    tech_ft_at_period_start = (
                        isinstance(event, FreeThrow) and event.clock == "12:00"
                    )
                    if not (
                        is_technical_foul
                        or isinstance(event, Ejection)
                        or tech_ft_at_period_start
                    ):
                        # ignore all techs because a player could get a technical foul when they aren't in the game
                        starters.append(player_id)
                # need player2_id and player3_id for players who play full period and never appear in an event as player_id - ex assists, blocks, steals, foul drawn
                if not isinstance(event, Substitution) and not (
                    is_technical_foul or isinstance(event, Ejection)
                ):
                    # ignore all techs because a player could get a technical foul when they aren't in the game
                    if (
                        hasattr(event, "player2_id")
                        and event.player2_id not in starters
                        and event.player2_id not in subbed_in_players
                    ):
                        starters.append(event.player2_id)
                    if (
                        hasattr(event, "player3_id")
                        and event.player3_id not in starters
                        and event.player3_id not in subbed_in_players
                    ):
                        starters.append(event.player3_id)
            event = event.next_event
        return starters, player_team_map
```

--------------------------------

### Initialize DataNbaEnhancedPbpLoader - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.data_nba.enhanced_pbp

This section describes the initialization of the DataNbaEnhancedPbpLoader class, used for loading enhanced play-by-play data from data.nba.com. It requires a game ID and a source loader object (either DataNbaEnhancedPbpFileLoader or DataNbaEnhancedPbpWebLoader). The loader stores events as EnhancedPbpItem objects.

```Python
class DataNbaEnhancedPbpLoader(game_id , source_loader):
    # ... implementation details ...
    pass

```

--------------------------------

### Instantiate Game Object and Load Possessions

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/objects/game

Demonstrates how to instantiate the Client, configure it to load possession data from files, and then retrieve possession data for a specific game ID. This requires the 'pbpstats' library and a 'settings' dictionary specifying the data directory and possession data provider.

```python
from pbpstats.client import Client

settings = {
    "dir": "/response_data",
    "Possessions": {"source": "file", "data_provider": "stats_nba"}
}
client = Client(settings)
game = client.Game('0021900001')
for possession in game.possessions.items:
    print(possession)
```

--------------------------------

### Load Enhanced PBP Data for a Game - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.live.enhanced_pbp

Demonstrates how to load enhanced play-by-play data for a specific NBA game using `LiveEnhancedPbpFileLoader` and `LiveEnhancedPbpLoader`. This snippet initializes the loaders and prints the data for the first event of the game. It requires the `pbpstats` library.

```python
from pbpstats.data_loader import LiveEnhancedPbpFileLoader, LiveEnhancedPbpLoader

source_loader = LiveEnhancedPbpFileLoader("/data")
pbp_loader = LiveEnhancedPbpLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game

```

--------------------------------

### Create StatsNbaEnhancedPbpFactory and Get Event Class (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/stats_nba/enhanced_pbp_factory

This example demonstrates how to instantiate the StatsNbaEnhancedPbpFactory and retrieve the specific event class for a given event type. The factory dynamically loads event classes from the stats_nba module, and this method allows access to the appropriate class for further processing. It handles cases where the event type might not be found by returning a default item class.

```python
from pbpstats.resources.enhanced_pbp.stats_nba.enhanced_pbp_factory import StatsNbaEnhancedPbpFactory

factory = StatsNbaEnhancedPbpFactory()
event_class = factory.get_event_class(1)
print(event_class)
```

--------------------------------

### Initialize DataNbaEnhancedPbpWebLoader - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.data_nba.enhanced_pbp

This snippet describes the DataNbaEnhancedPbpWebLoader class, used for fetching enhanced play-by-play data directly from the NBA Stats API. It accepts an optional file directory to save the response data. If no directory is provided, the response is not saved locally. This loader is also passed to DataNbaEnhancedPbpLoader for web-based data retrieval.

```Python
class DataNbaEnhancedPbpWebLoader(file_directory=None):
    # ... implementation details ...
    pass

```

--------------------------------

### Instantiate Season Object and Get Games (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/objects/season

This code snippet demonstrates how to instantiate the Client and Season objects from the pbpstats library. It shows how to configure settings for data loading, create a Season object for a specific league and season, and then iterate through the games within that season. The example assumes the 'data_nba' provider and 'web' source are configured for game data.

```python
from pbpstats.client import Client

settings = {
    "dir": "/response_data",
    "Games": {"source": "web", "data_provider": "data_nba"}
}
client = Client(settings)
season = client.Season("nba", "2019-20", "Regular Season")
for game in season.games.items:
    print(game)
```

--------------------------------

### Load Enhanced PBP Data from File - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.data_nba.enhanced_pbp

This snippet demonstrates how to load enhanced play-by-play data for a specific NBA game using the DataNbaEnhancedPbpFileLoader. It requires a game ID and a source loader configured for file-based data retrieval. The output is a list of EnhancedPbpItem objects, and the example prints the data dictionary of the first event.

```Python
from pbpstats.data_loader import DataNbaEnhancedPbpFileLoader, DataNbaEnhancedPbpLoader

source_loader = DataNbaEnhancedPbpFileLoader("/data")
pbp_loader = DataNbaEnhancedPbpLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game

```

--------------------------------

### Initialize DataNbaEnhancedPbpFileLoader - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.data_nba.enhanced_pbp

This snippet outlines the DataNbaEnhancedPbpFileLoader class, designed for loading enhanced PBP data from local files. It takes a file directory as an argument where the 'data_<game_id>.json' file is expected. This loader is intended to be passed to the DataNbaEnhancedPbpLoader when file-based loading is required.

```Python
class DataNbaEnhancedPbpFileLoader(file_directory=None):
    # ... implementation details ...
    pass

```

--------------------------------

### Possession Class Initialization and Properties (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/possessions/possession

Initializes the Possession object with a list of events and provides properties to access game ID, period, possession data, start time, end time, and start score margin. It handles cases where previous possessions might not exist.

```python
class Possession(object):
    """
    Class for possession

    :param list events: list of
        :obj:`~pbpstats.resources.enhanced_pbp.enhanced_pbp_item.EnhancedPbpItem` items for possession,
        typically from a possession data loader
    """

    def __init__(self, events):
        self.game_id = events[0].game_id
        self.period = events[0].period
        self.events = events

    def __repr__(self):
        return (
            f"<{type(self).__name__} GameId: {self.game_id}, Period: {self.period}, "
            f"Number: {self.number}, StartTime: {self.start_time}, EndTime: {self.end_time}, "
            f"OffenseTeamId: {self.offense_team_id}>"
        )

    @property
    def data(self):
        """
        returns dict possession data
        """
        return self.__dict__

    @property
    def start_time(self):
        """
        returns the time remaining (MM:SS) in the period when the possession started
        """
        if not hasattr(self, "previous_possession") or self.previous_possession is None:
            return self.events[0].clock
        return self.previous_possession.events[-1].clock

    @property
    def end_time(self):
        """
        returns the time remaining (MM:SS) in the period when the possession ended
        """
        return self.events[-1].clock

    @property
    def start_score_margin(self):
        """
        returns the score margin from the perspective of the team on offense when the possession started
        """
        if not hasattr(self, "previous_possession") or self.previous_possession is None:
            score = self.events[0].score
        else:
            score = self.previous_possession.events[-1].score
        offense_team_id = self.offense_team_id
        offense_points = score[offense_team_id]
        defense_points = 0
        for team_id, points in score.items():
            if team_id != offense_team_id:
                defense_points = points
        return offense_points - defense_points

```

--------------------------------

### Determine Possession Start Type - Python

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/possessions/possession

Classifies the start type of a possession based on various game conditions. It considers the first possession, timeouts, the outcome of the previous possession's ending event (made field goal, turnover, rebound, jump ball), and whether it was a live ball or dead ball situation.

```python
    @property
    def possession_start_type(self):
        """
        returns possession start type string
        """
        if self.number == 1:
            return pbpstats.OFF_DEADBALL_STRING
        if self.possession_has_timeout or self.previous_possession_has_timeout:
            return pbpstats.OFF_TIMEOUT_STRING
        previous_possession_ending_event = self.previous_possession_ending_event
        if (
            isinstance(previous_possession_ending_event, (FieldGoal, FreeThrow))
            and previous_possession_ending_event.is_made
        ):
            shot_type = previous_possession_ending_event.shot_type
            return f"Off{shot_type}{pbpstats.MAKE_STRING}"
        if isinstance(previous_possession_ending_event, Turnover):
            if previous_possession_ending_event.is_steal:
                return pbpstats.OFF_LIVE_BALL_TURNOVER_STRING
            return pbpstats.OFF_DEADBALL_STRING
        if isinstance(previous_possession_ending_event, Rebound):
            if previous_possession_ending_event.player1_id == 0:
                # team rebound
                return pbpstats.OFF_DEADBALL_STRING
            missed_shot = previous_possession_ending_event.missed_shot
            shot_type = missed_shot.shot_type
            if hasattr(missed_shot, "is_blocked") and missed_shot.is_blocked:
                return f"Off{shot_type}{pbpstats.BLOCK_STRING}"
            return f"Off{shot_type}{pbpstats.MISS_STRING}"

        if isinstance(previous_possession_ending_event, JumpBall):
            # jump balls tipped out of bounds have no player2_id and should be off deadball
            if not hasattr(previous_possession_ending_event, "player2_id"):
                return pbpstats.OFF_LIVE_BALL_TURNOVER_STRING
            else:
                return pbpstats.OFF_DEADBALL_STRING
        return pbpstats.OFF_DEADBALL_STRING
```

--------------------------------

### LiveEnhancedPbpFactory Class Definition and Initialization

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/live/enhanced_pbp_factory

Defines the `LiveEnhancedPbpFactory` class, which initializes by loading all available event classes from the `pbpstats.resources.enhanced_pbp.live` module into a dictionary. This allows for efficient lookup of event classes by their action and sub-types.

```python
import pbpstats.resources.enhanced_pbp.live as event_types
from pbpstats.resources.enhanced_pbp.live.enhanced_pbp_item import LiveEnhancedPbpItem


class LiveEnhancedPbpFactory(object):
    """
    Class for factory of event type classes. On initialization will load
    in all event classes in the :mod:`pbpstats.resources.enhanced_pbp.live` module
    """

    def __init__(self):
        self.event_classes = {}
        self._load_event_classes()

    def _load_event_classes(self):
        event_classes = dict(
            [
                (name, cls)
                for name, cls in event_types.__dict__.items()
                if isinstance(cls, type)
            ]
        )
        for _, event_cls in event_classes.items():
            if isinstance(event_cls.action_type, list):
                for action_type in event_cls.action_type:
                    self.event_classes[action_type] = event_cls
            elif hasattr(event_cls, "sub_type"):
                self.event_classes[
                    f"{event_cls.action_type}{event_cls.sub_type}"
                ] = event_cls
            else:
                self.event_classes[event_cls.action_type] = event_cls
```

--------------------------------

### Get Offense Team ID

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/data_nba/enhanced_pbp_item

Retrieves the team ID of the team that was on offense during the event. This is a straightforward getter method for the `offense_team_id` attribute.

```python
    def get_offense_team_id(self):
        """
        returns team id for team on offense for event
        """
        return self.offense_team_id
```

--------------------------------

### Get Turnover Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/enhanced_pbp

Returns a list of Turnover events that are not designated as 'no turnover'. It filters for Turnover instances where 'is_no_turnover' is false.

```python
    @property
    def turnovers(self):
        """
        returns list of :obj:`~pbpstats.resources.enhanced_pbp.field_goal.Turnover` events
        """
        return [
            item
            for item in self.items
            if isinstance(item, Turnover) and not item.is_no_turnover
        ]
```

--------------------------------

### Get All Play-by-Play Event Data

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/enhanced_pbp

Returns a list of all play-by-play event dictionaries. This property iterates through the stored items and extracts their data.

```python
    @property
    def data(self):
        """
        returns list of pbp event dicts
        """
        return [item.data for item in self.items]
```

--------------------------------

### Create Enhanced PBP Event Objects with DataNbaEnhancedPbpFactory (Python)

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.resources.enhanced_pbp.data_nba

Demonstrates how to use the DataNbaEnhancedPbpFactory to dynamically retrieve the appropriate event class based on an event type integer. This factory simplifies the process of parsing and creating specific PBP event objects from raw data. It requires the 'pbpstats' library.

```python
from pbpstats.resources.enhanced_pbp.data_nba.enhanced_pbp_factory import DataNbaEnhancedPbpFactory

factory = DataNbaEnhancedPbpFactory()
event_class = factory.get_event_class(1)
print(event_class)  # prints "<class 'pbpstats.resources.enhanced_pbp.data_nba.field_goal.DataFieldGoal'>"
```

--------------------------------

### Get Event Data as Dictionary (Python)

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/stats_nba/enhanced_pbp_item

Returns the event data as a dictionary. This property provides a convenient way to access all the processed attributes of the StatsEnhancedPbpItem object in a dictionary format.

```python
@property
def data(self):
    """
    returns event as a dict
    """
    return self.__dict__
```

--------------------------------

### Get Field Goal Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/enhanced_pbp

Returns a list of all FieldGoal events from the play-by-play data. It filters the items to include only those instances that are of the FieldGoal type.

```python
    @property
    def fgas(self):
        """
        returns list of :obj:`~pbpstats.resources.enhanced_pbp.field_goal.FieldGoal` events
        """
        return [item for item in self.items if isinstance(item, FieldGoal)]
```

--------------------------------

### Load Live Possession Data from File - Python

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.live.possessions

Loads possession data for a specified game ID from a pbp file using `LivePossessionFileLoader` and `LivePossessionLoader`. It then accesses and prints the data for the first event of the game. Requires the pbpstats library.

```python
from pbpstats.data_loader import LivePossessionFileLoader, LivePossessionLoader

source_loader = LivePossessionFileLoader("/data")
pbp_loader = LivePossessionLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game
```

--------------------------------

### Load PBP Data for a Game from File

Source: https://pbpstats.readthedocs.io/en/latest/pbpstats.data_loader.data_nba.pbp

Loads play-by-play data for a specified NBA game ID from a local file. It utilizes DataNbaPbpFileLoader to specify the data directory and DataNbaPbpLoader to load the game's events. The first event's raw data is then printed. Dependencies include DataNbaPbpFileLoader and DataNbaPbpLoader from the pbpstats.data_loader module. Input is a game ID string and a file loader object. Output is a dictionary of the first event's data.

```python
from pbpstats.data_loader import DataNbaPbpFileLoader, DataNbaPbpLoader

source_loader = DataNbaPbpFileLoader("/data")
pbp_loader = DataNbaPbpLoader("0021900001", source_loader)
print(pbp_loader.items[0].data)  # prints dict with the first event of the game
```

--------------------------------

### Get Rebound Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/enhanced_pbp

Returns a list of actual Rebound events from the play-by-play data. It filters for instances that are Rebound types and are considered 'real' rebounds.

```python
    @property
    def rebounds(self):
        """
        returns list of :obj:`~pbpstats.resources.enhanced_pbp.field_goal.Rebound` events
        """
        return [
            item
            for item in self.items
            if isinstance(item, Rebound) and item.is_real_rebound
        ]
```

--------------------------------

### Get Free Throw Attempt Events

Source: https://pbpstats.readthedocs.io/en/latest/_modules/pbpstats/resources/enhanced_pbp/enhanced_pbp

Returns a list of all FreeThrow events from the play-by-play data. It filters the items to include only those instances that are of the FreeThrow type.

```python
    @property
    def ftas(self):
        """
        returns list of :obj:`~pbpstats.resources.enhanced_pbp.free_throw.FreeThrow` events
        """
        return [item for item in self.items if isinstance(item, FreeThrow)]
```
Tokens:
Raw