Play

Play Class Documentation

Represents a single play within an ESPN sports event.

This class parses and stores data related to an individual play, such as the team involved, score, text descriptions, and various metadata about the play.

Attributes:

Name	Type	Description
play_json	dict	Raw JSON data representing the play.
espn_instance	PYESPN	The parent ESPN API wrapper instance.
event_instance	Event	The parent event this play belongs to.
drive_instance	Drive or None	The parent drive (if applicable).
team	Team or None	The team associated with the play.
id	str	Unique identifier for the play.
text	str	Full text description of the play.
short_text	str	Shortened description of the play.
alt_text	str	Alternative description of the play.
short_alt_text	str	Shortened alternative text.
home_score	int	Score for the home team at this play.
away_score	int	Score for the away team at this play.
sequence_number	int	Play's sequence number in the event.
type	str	Type of the play.
period	dict	Information about the game period (e.g., quarter, half).
clock	dict	Game clock status at time of play.
scoring_play	bool	Whether the play resulted in scoring.
priority	int	Display priority of the play.
score_value	int	Amount of points scored on the play.
start	dict	Start context for the play.
end	dict	End context for the play.
wallclock	str	Wallclock timestamp of the play.
modified	str	Last modification time.
probability	dict or None	Win probability shift, if present.
stat_yardage	int or None	Yardage gained or lost (football-specific).
participants	list or None	Athletes involved in the play.
shooting_play	bool or None	Whether the play is a shooting play (basketball).
coordinate	dict or None	X/Y position of the play (if supported).

Source code in pyespn/classes/gamelog.py

@validate_json("play_json")
class Play:
    """
    Represents a single play within an ESPN sports event.

    This class parses and stores data related to an individual play, such as the
    team involved, score, text descriptions, and various metadata about the play.

    Attributes:
        play_json (dict): Raw JSON data representing the play.
        espn_instance (PYESPN): The parent ESPN API wrapper instance.
        event_instance (Event): The parent event this play belongs to.
        drive_instance (Drive or None): The parent drive (if applicable).
        team (Team or None): The team associated with the play.
        id (str): Unique identifier for the play.
        text (str): Full text description of the play.
        short_text (str): Shortened description of the play.
        alt_text (str): Alternative description of the play.
        short_alt_text (str): Shortened alternative text.
        home_score (int): Score for the home team at this play.
        away_score (int): Score for the away team at this play.
        sequence_number (int): Play's sequence number in the event.
        type (str): Type of the play.
        period (dict): Information about the game period (e.g., quarter, half).
        clock (dict): Game clock status at time of play.
        scoring_play (bool): Whether the play resulted in scoring.
        priority (int): Display priority of the play.
        score_value (int): Amount of points scored on the play.
        start (dict): Start context for the play.
        end (dict): End context for the play.
        wallclock (str): Wallclock timestamp of the play.
        modified (str): Last modification time.
        probability (dict or None): Win probability shift, if present.
        stat_yardage (int or None): Yardage gained or lost (football-specific).
        participants (list or None): Athletes involved in the play.
        shooting_play (bool or None): Whether the play is a shooting play (basketball).
        coordinate (dict or None): X/Y position of the play (if supported).
    """

    def __init__(self, play_json, espn_instance,
                 event_instance, drive_instance):
        """
        Initializes a Play instance using the provided JSON data.

        Args:
            play_json (dict): The JSON data representing the play.
            espn_instance (PYESPN): The ESPN API interface instance.
            event_instance (Event): The event this play belongs to.
            drive_instance (Drive or None): The drive this play belongs to (if applicable).
        """
        self.play_json = play_json
        self._espn_instance = espn_instance
        self.event_instance = event_instance
        self.drive_instance = drive_instance
        self._load_play_data()

    def __repr__(self):
        """
        Returns a string representation of the Play instance.
        """
        return f"<Play | {self.team.name} | {self.short_text}>"

    @property
    def espn_instance(self):
        """
            PYESPN: the espn client instance associated with the class
        """
        return self._espn_instance

    def _load_play_data(self):
        """
        Internal method to parse and assign play-related data from the JSON payload.
        """
        self.ref = self.play_json.get('$ref')
        self.id = self.play_json.get('id')
        self.text = self.play_json.get('text')
        self.alt_text = self.play_json.get('alternativeText')
        self.short_text = self.play_json.get('shortText')
        self.home_score = self.play_json.get('homeScore')
        self.away_score = self.play_json.get('awayScore')
        self.sequence_number = self.play_json.get('sequenceNumber')
        self.type = self.play_json.get('type')
        self.short_alt_text = self.play_json.get('shortAlternativeText')
        self.period = self.play_json.get('period')
        self.clock = self.play_json.get('clock')
        self.scoring_play = self.play_json.get('scoringPlay')
        self.priority = self.play_json.get('priority')
        self.score_value = self.play_json.get('scoreValue')
        self.start = self.play_json.get('start')
        self.end = self.play_json.get('end')
        self.wallclock = self.play_json.get('wallclock')
        self.modified = self.play_json.get('modified')
        # todo this is probably its own class
        self.probability = self.play_json.get('probability')
        self.stat_yardage = self.play_json.get('statYardage')
        if 'team' in self.play_json:
            team_id = get_team_id(self.play_json.get('team', {}).get('$ref'))
            self.team = self._espn_instance.get_team_by_id(team_id=team_id)
        else:
            self.team = None
        # todo these look like a list of athletes
        self.participants = self.play_json.get('participants')
        self.shooting_play = self.play_json.get('shootingPlay')
        self.coordinate = self.play_json.get('coordinate')

    def to_dict(self) -> dict:
        """
        Converts the Play instance to its original JSON dictionary.

        Returns:
            dict: The plays's raw JSON data.
        """
        return self.play_json

espn_instance property

PYESPN: the espn client instance associated with the class

__init__(play_json, espn_instance, event_instance, drive_instance)

Initializes a Play instance using the provided JSON data.

Parameters:

Name	Type	Description	Default
play_json	dict	The JSON data representing the play.	required
espn_instance	PYESPN	The ESPN API interface instance.	required
event_instance	Event	The event this play belongs to.	required
drive_instance	Drive or None	The drive this play belongs to (if applicable).	required

Source code in pyespn/classes/gamelog.py

def __init__(self, play_json, espn_instance,
             event_instance, drive_instance):
    """
    Initializes a Play instance using the provided JSON data.

    Args:
        play_json (dict): The JSON data representing the play.
        espn_instance (PYESPN): The ESPN API interface instance.
        event_instance (Event): The event this play belongs to.
        drive_instance (Drive or None): The drive this play belongs to (if applicable).
    """
    self.play_json = play_json
    self._espn_instance = espn_instance
    self.event_instance = event_instance
    self.drive_instance = drive_instance
    self._load_play_data()

__repr__()

Returns a string representation of the Play instance.

Source code in pyespn/classes/gamelog.py

def __repr__(self):
    """
    Returns a string representation of the Play instance.
    """
    return f"<Play | {self.team.name} | {self.short_text}>"

to_dict()

Converts the Play instance to its original JSON dictionary.

Returns:

Name	Type	Description
dict	dict	The plays's raw JSON data.

Source code in pyespn/classes/gamelog.py

def to_dict(self) -> dict:
    """
    Converts the Play instance to its original JSON dictionary.

    Returns:
        dict: The plays's raw JSON data.
    """
    return self.play_json