@validate_json('player_json')
class Player:
from pyespn.core.orchestration import get_players_historical_stats_core
"""
Represents a player within the ESPN API framework.
This class stores player-related information and maintains a reference
to a `PYESPN` instance, allowing access to league-specific details.
Attributes:
espn_instance (PYESPN): The parent `PYESPN` instance providing access to league details.
player_json (dict): The raw player data retrieved from the ESPN API.
api_ref (str | None): API reference link for the player.
id (str | None): The unique identifier for the player.
uid (str | None): The ESPN UID for the player.
guid (str | None): The GUID associated with the player.
type (str | None): The type of player (e.g., 'athlete').
flag (dict | None): The player's flag data (for nationality, mainly in racing).
citizenship (str | None): The player's citizenship code.
experience (dict | int | None): Raw experience data from API.
experience_years (int | None): Number of years of experience.
event_log (dict | None): Reference to player's event log.
stats_log (dict | None): Raw statistics log.
alternate_ids (str | None): Alternate ID, e.g., SDR ID.
first_name (str | None): The player’s first name.
last_name (str | None): The player’s last name.
full_name (str | None): The player’s full name.
display_name (str | None): Display name.
short_name (str | None): Shortened name.
weight (int | None): Weight in pounds.
display_weight (str | None): Formatted display weight.
height (int | None): Height in inches.
display_height (str | None): Formatted display height.
age (int | None): Age.
date_of_birth (str | None): Date of birth (YYYY-MM-DD).
debut_year (int | None): Debut year.
college_athlete_ref (str | None): Ref to the college athlete profile.
links (list[dict]): Related links for the player.
birth_city (str | None): City of birth.
birth_state (str | None): State of birth.
college_ref (str | None): College reference.
slug (str | None): URL slug for the player.
jersey (str | None): Jersey number.
position_ref (str | None): API reference for position.
position_id (str | None): Position ID.
position_name (str | None): Full position name.
position_display_name (str | None): Position display label.
position_abbreviation (str | None): Position abbreviation (e.g., "QB").
position_leaf (bool | None): Whether it's a leaf node in hierarchy.
position_parent_ref (str | None): Reference to parent position node.
linked (str | None): Linked player info, if available.
team_ref (str | None): Ref to current team.
statistics_ref (str | None): Ref to statistical summary.
contracts_ref (str | None): Ref to contract data.
active (bool | None): Whether the player is active.
status_id (str | None): Status ID.
status_name (str | None): Status name.
status_type (str | None): Status type (e.g., "Active", "Injured").
status_abbreviation (str | None): Abbreviation of status.
statistics_log_ref (str | None): Ref to full stat log.
vehicles (list[Vehicle] | None): List of vehicles (racing-specific).
stats (dict): Historical statistics loaded via `load_player_historical_stats()`.
Methods:
__repr__() -> str:
Returns a string representation of the Player instance, including full name, position abbreviation, and jersey number.
_set_player_data() -> None:
Internal method that parses and assigns player data from the provided JSON.
load_player_historical_stats() -> None:
Loads the historical statistics for the player and stores them in the `stats` attribute.
to_dict() -> dict:
Returns the raw player JSON data as a dictionary.
"""
def __init__(self, espn_instance, player_json: dict):
"""
Initializes a Player instance.
Args:
espn_instance (PYESPN): The parent `PYESPN` instance, providing access to league details.
player_json (dict): The raw player data retrieved from the ESPN API.
"""
self.player_json = player_json
self._espn_instance = espn_instance
self.api_info = self._espn_instance.api_mapping
self._stats = {}
self._stats_game_log = {}
self._set_player_data()
@property
def espn_instance(self):
"""
PYESPN: the espn client instance associated with the class
"""
return self._espn_instance
@property
def stats_game_log(self):
"""
dict: with season as a key and has a list of StatCategory Objects
"""
return self._stats_game_log
@property
def stats(self):
"""
dict: with season as key with list of Stats Objects
"""
return self._stats
@property
def id(self):
"""
str: the id for the player
"""
return self._id
def __repr__(self) -> str:
"""
Returns a string representation of the Player instance.
Returns:
str: A formatted string with the players's name, position and jersey.
"""
return f"<Player | {self.full_name}, {self.position_abbreviation} ({self.jersey})>"
def _set_player_data(self):
"""
Extracts and sets player data from the provided JSON.
"""
self.api_ref = self.player_json.get('$ref')
self._id = self.player_json.get('id')
self.uid = self.player_json.get('uid')
self.guid = self.player_json.get('guid')
self.type = self.player_json.get('type')
self.flag = self.player_json.get('flag')
self.citizenship = self.player_json.get('citizenship')
self.experience = self.player_json.get('experience')
self.event_log = self.player_json.get('eventLog')
self.stats_log = self.player_json.get('statisticslog')
self.alternate_ids = self.player_json.get('alternateIds', {}).get('sdr')
self.first_name = self.player_json.get('firstName')
self.last_name = self.player_json.get('lastName')
self.full_name = self.player_json.get('fullName')
if not self.full_name:
self.full_name = self.first_name + ' ' + self.last_name
self.display_name = self.player_json.get('displayName')
self.short_name = self.player_json.get('shortName')
self.weight = self.player_json.get('weight')
self.display_weight = self.player_json.get('displayWeight')
self.height = self.player_json.get('height')
self.display_height = self.player_json.get('displayHeight')
self.age = self.player_json.get('age')
self.date_of_birth = self.player_json.get('dateOfBirth')
self.debut_year = self.player_json.get('debutYear')
self.college_athlete_ref = self.player_json.get('collegeAthlete', {}).get('$ref')
self.links = self.player_json.get('links', [])
birth_place = self.player_json.get('birthPlace', {})
self.birth_city = birth_place.get('city')
self.birth_state = birth_place.get('state')
self.college_ref = self.player_json.get('college', {}).get('$ref')
self.slug = self.player_json.get('slug')
self.jersey = self.player_json.get('jersey', '--')
position = self.player_json.get('position', {})
self.position_ref = position.get('$ref')
self.position_id = position.get('id')
self.position_name = position.get('name')
self.position_display_name = position.get('displayName')
self.position_abbreviation = position.get('abbreviation')
self.position_leaf = position.get('leaf')
self.position_parent_ref = position.get('parent', {}).get('$ref')
self.linked = self.player_json.get('linked')
self.team_ref = self.player_json.get('team', {}).get('$ref')
self.statistics_ref = self.player_json.get('statistics', {}).get('$ref')
self.contracts_ref = self.player_json.get('contracts', {}).get('$ref')
experience = self.player_json.get('experience', {})
if type(experience) == dict:
self.experience_years = experience.get('years')
elif type(experience) == int:
self.experience_years = experience
self.active = self.player_json.get('active')
status = self.player_json.get('status', {})
self.status_id = status.get('id')
self.status_name = status.get('name')
self.status_type = status.get('type')
self.status_abbreviation = status.get('abbreviation')
self.headshot = self.player_json.get('headshot')
if self.headshot:
self.headshot = Image(image_json=self.headshot,
espn_instance=self._espn_instance)
self.statistics_log_ref = self.player_json.get('statisticslog', {}).get('$ref')
if 'vehicles' in self.player_json:
self.vehicles = []
for vehicle in self.player_json.get('vehicles'):
self.vehicles.append(Vehicle(vehicle_json=vehicle,
espn_instance=self._espn_instance))
def load_player_historical_stats(self) -> None:
"""
Loads the historical statistics for the player.
This method fetches and assigns the player's historical stats using the ESPN API.
The stats are stored in the `self._stats` attribute.
Returns:
None
"""
self._stats = self.get_players_historical_stats_core(player_id=self._id,
league_abbv=self._espn_instance.league_abbv,
espn_instance=self._espn_instance)
def load_player_box_scores_season(self, season):
"""
Loads the player's box score statistics for every game in the given season.
This method fetches the event log for a player for a specific season using ESPN's API.
It iterates through each event (game) the player participated in, retrieves the game event data,
and corresponding statistics, then stores it in the player's `_stats_game_log` cache.
Args:
season (int): The season year to load player game-by-game statistics for.
Side Effects:
Populates the `_stats_game_log` dictionary with a list of game stat dictionaries for the given season.
Each entry in the list is a dictionary containing:
- 'event' (`Event`): The event object representing the game.
- 'stats' (List[`StatCategory`]): A list of stat category objects for that game.
"""
url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/{self.api_info["sport"]}/leagues/{self.api_info["league"]}/seasons/{season}/athletes/{self._id}/eventlog'
page_content = fetch_espn_data(url)
pages = page_content.get('events', {}).get('pageCount', 0)
event_list = []
for page in range(1, pages + 1):
paged_url = url + f'?page={page}'
event_log_content = fetch_espn_data(paged_url)
for event_log in event_log_content.get('events', {}).get('items', []):
event_list.append(event_log)
event_stats_log = []
for event in event_list:
event_id = get_an_id(event.get('event', {}).get('$ref'), 'events')
event_find = self._espn_instance.league.get_event_by_season(season=season,
event_id=event_id)
if not event_find:
event_content = fetch_espn_data(event.get('event', {}).get('$ref'))
event_find = Event(event_json=event_content,
espn_instance=self._espn_instance)
stats = []
if event.get('played'):
stats_content = fetch_espn_data(event.get('statistics', {}).get('$ref'))
for category in stats_content.get('splits', {}).get('categories'):
stats.append(StatCategory(record_json=category,
espn_instance=self._espn_instance))
event_record = {
'event': event_find,
'stats': stats,
}
event_stats_log.append(event_record)
self._stats_game_log[season] = event_stats_log
def load_player_contracts(self):
# todo i haven't seen this filled in at all yet in the api
url = f'http://sports.core.api.espn.com/{self._espn_instance.v}/sports/football/leagues/nfl/athletes/4360807/contracts?lang=en®ion=us'
def to_dict(self) -> dict:
"""
Returns the raw player JSON data as a dictionary.
Returns:
dict: The original player data retrieved from the ESPN API.
"""
return self.player_json