Drive

Drive Class Documentation

Represents a single drive within a sports event.

A drive typically consists of a sequence of plays executed by the offensive team, and may result in a score, turnover, or punt. This class handles loading and structuring that information from the ESPN API response.

Attributes:

Name	Type	Description
drive_json	dict	Raw JSON data for the drive.
espn_instance	PYESPN	The ESPN API interface instance.
event_instance	Event	The parent event this drive belongs to.
plays	list[Play]	List of Play objects associated with this drive.
description	str	Summary of the drive.
id	str	Unique drive identifier.
sequence_number	int	Order of the drive within the event.
ref	str	API reference URL to this drive.
start	dict	Metadata about how the drive started.
end	dict	Metadata about how the drive ended.
time_elapsed	dict	Duration of the drive.
yards	int	Total yardage gained during the drive.
is_score	bool	Whether the drive resulted in a score.
offensive_plays	int	Number of offensive plays run during the drive.
result	str	Raw result string (e.g., 'Touchdown', 'Punt').
result_display	str	Formatted display result.
team	Team	Team that had possession during the drive.
end_team	Team	Team that was on defense at the end of the drive.
plays_ref	str	API reference to the list of plays in this drive.

Source code in pyespn/classes/gamelog.py

@validate_json("drive_json")
class Drive:
    """
    Represents a single drive within a sports event.

    A drive typically consists of a sequence of plays executed by the offensive team,
    and may result in a score, turnover, or punt. This class handles loading and
    structuring that information from the ESPN API response.

    Attributes:
        drive_json (dict): Raw JSON data for the drive.
        espn_instance (PYESPN): The ESPN API interface instance.
        event_instance (Event): The parent event this drive belongs to.
        plays (list[Play]): List of Play objects associated with this drive.
        description (str): Summary of the drive.
        id (str): Unique drive identifier.
        sequence_number (int): Order of the drive within the event.
        ref (str): API reference URL to this drive.
        start (dict): Metadata about how the drive started.
        end (dict): Metadata about how the drive ended.
        time_elapsed (dict): Duration of the drive.
        yards (int): Total yardage gained during the drive.
        is_score (bool): Whether the drive resulted in a score.
        offensive_plays (int): Number of offensive plays run during the drive.
        result (str): Raw result string (e.g., 'Touchdown', 'Punt').
        result_display (str): Formatted display result.
        team (Team): Team that had possession during the drive.
        end_team (Team): Team that was on defense at the end of the drive.
        plays_ref (str): API reference to the list of plays in this drive.
    """

    def __init__(self, drive_json, espn_instance, event_instance):
        """
        Initializes a Drive instance using the provided drive JSON.

        Args:
            drive_json (dict): JSON representation of the drive.
            espn_instance (PYESPN): The ESPN API interface instance.
            event_instance (Event): The event this drive belongs to.
        """
        self.drive_json = drive_json
        self._espn_instance = espn_instance
        self.event_instance = event_instance
        self._plays = None
        self._load_drive_data()

    def __repr__(self) -> str:
        """
        Returns a human-readable string representation of the Drive instance.

        Returns:
            str: A formatted string in the form "<Drive | Team Name | Drive Result>".
        """
        return f"<Drive | {self.team.name} | {self.result_display}>"

    def _load_drive_data(self):
        """
        Internal method to parse and load data from the drive JSON payload.
        Creates `Play` objects for each play in the drive.
        """
        self.description = self.drive_json.get('description')
        self.id = self.drive_json.get('id')
        self.sequence_number = self.drive_json.get('sequence_number')
        self.ref = self.drive_json.get('$ref')
        self.start = self.drive_json.get('start')
        self.end = self.drive_json.get('end')
        self.time_elapsed = self.drive_json.get('timeElapsed')
        self.yards = self.drive_json.get('yards')
        self.is_score = self.drive_json.get('isScore')
        self.offensive_plays = self.drive_json.get('offensivePlays')
        self.result = self.drive_json.get('result')
        self.result_display = self.drive_json.get('displayResult')
        team_id = get_team_id(self.drive_json.get('team', {}).get('$ref'))
        self.team = self._espn_instance.get_team_by_id(team_id=team_id)
        end_team_id = get_team_id(self.drive_json.get('endTeam', {}).get('$ref'))
        self.end_team = self._espn_instance.get_team_by_id(team_id=end_team_id)
        self.plays_ref = self.drive_json.get('plays', {}).get('$ref')

        self._load_plays()

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

    @property
    def plays(self):
        """
            list[Play]: a list of plays for the drive
        """
        return self._plays

    def _load_plays(self):
        plays = []
        for play in self.drive_json.get('plays', {}).get('items'):
            plays.append(Play(play_json=play,
                              espn_instance=self._espn_instance,
                              event_instance=self.event_instance,
                              drive_instance=self))
        self._plays = plays

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

        Returns:
            dict: The drives's raw JSON data.
        """
        return self.drive_json

espn_instance property

PYESPN: the espn client instance associated with the class

plays property

list[Play]: a list of plays for the drive

__init__(drive_json, espn_instance, event_instance)

Initializes a Drive instance using the provided drive JSON.

Parameters:

Name	Type	Description	Default
drive_json	dict	JSON representation of the drive.	required
espn_instance	PYESPN	The ESPN API interface instance.	required
event_instance	Event	The event this drive belongs to.	required

Source code in pyespn/classes/gamelog.py

def __init__(self, drive_json, espn_instance, event_instance):
    """
    Initializes a Drive instance using the provided drive JSON.

    Args:
        drive_json (dict): JSON representation of the drive.
        espn_instance (PYESPN): The ESPN API interface instance.
        event_instance (Event): The event this drive belongs to.
    """
    self.drive_json = drive_json
    self._espn_instance = espn_instance
    self.event_instance = event_instance
    self._plays = None
    self._load_drive_data()

__repr__()

Returns a human-readable string representation of the Drive instance.

Returns:

Name	Type	Description
str	str	A formatted string in the form "".

Source code in pyespn/classes/gamelog.py

def __repr__(self) -> str:
    """
    Returns a human-readable string representation of the Drive instance.

    Returns:
        str: A formatted string in the form "<Drive | Team Name | Drive Result>".
    """
    return f"<Drive | {self.team.name} | {self.result_display}>"

to_dict()

Converts the Drive instance to its original JSON dictionary.

Returns:

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

Source code in pyespn/classes/gamelog.py

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

    Returns:
        dict: The drives's raw JSON data.
    """
    return self.drive_json