Players

Player-related functionality in Edgework.

Player Methods

Client for fetching player data.

Initialize the player client.

Parameters:

Name	Type	Description	Default
http_client	HttpClient	HTTP client instance	required

get_all_players(active=None, limit=10000)

Get all players from the NHL search API.

Parameters:

Name	Type	Description	Default
active	Optional[bool]	Filter by active status (True for active, False for inactive, None for all)	None
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of Player objects

get_active_players(limit=10000)

Get all active players.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of active Player objects

get_inactive_players(limit=10000)

Get all inactive players.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of inactive Player objects

get_player_landing(player_id)

Fetch player landing page data with comprehensive player information.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Dict	Dictionary with player landing data including:
Dict	Player profile information
Dict	Career statistics
Dict	Current season stats
Dict	Recent games
Dict	Player bio and media

get_player_game_logs(player_id, season, game_type=2)

Fetch game-by-game statistics for a player in a specific season.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required
season	str	Season in format "YYYY-YYYY" (e.g., "2023-2024")	required
game_type	int	Game type - 2 for Regular Season (default), 3 for Playoffs, 1 for Pre-season	2

Returns:

Type	Description
Dict	Dictionary with game logs including:
Dict	Season statistics
Dict	Game-by-game breakdown
Dict	Home/away splits
Dict	Monthly splits

get_player_game_log_now(player_id)

Fetch game-by-game statistics for the current season.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Dict	Dictionary with current season game logs

get_player_spotlight()

Fetch featured/spotlight players from the NHL.

Returns:

Type	Description
List[Dict]	List of dictionaries with spotlight player information

get_player(player_id)

Fetch player data by ID using the landing endpoint.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Player	Player object with comprehensive data

get_player_by_id(player_id)

Get a player by their NHL ID.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Optional[Player]	Player object if found, None otherwise

Fetch skater stats for a report as SkaterStats objects.

Targets the documented /{lang}/skater/{report} route (registry key stats_skater_report); report names are validated against :mod:edgework.stats_reports.

Parameters:

Name	Type	Description	Default
report	str	Report name (default "summary").	'summary'
aggregate	bool	Whether to aggregate the stats.	False
game	bool	Whether to return game-level stats.	True
limit	int	Number of results (-1 for all).	-1
start	int	Starting index for pagination.	0
sort	str	Field to sort by.	'points'
season	Optional[int]	Season in YYYYYYYY format; defaults to the current season.	None
game_type	Optional[int]	Optional game type (2=regular season, 3=playoffs) appended to the season filter.	None
direction	Optional[str]	Optional sort direction ("ASC"/"DESC") for the dir query parameter.	None
cayenne_exp	Optional[str]	Raw Cayenne filter expression (escape hatch that overrides the season/game-type expression).	None
fact_cayenne_exp	Optional[Union[str, list[str]]]	Optional factCayenneExp query filter.	None
include	Optional[Union[str, list[str]]]	Optional include query filter (string or list; a list is sent as repeated query parameters).	None
exclude	Optional[Union[str, list[str]]]	Optional exclude query filter (string or list).	None
lang	str	Language code for the Stats API request (default "en").	'en'
extra_params	Optional[dict[str, Any]]	Raw escape hatch for additional query parameters, merged last.	None

Returns:

Type	Description
list[SkaterStats]	List of SkaterStats objects (one per report row).

Fetch goalie stats for a report as GoalieStats objects.

Targets the documented /{lang}/goalie/{report} route (registry key stats_goalie_report); report names are validated against :mod:edgework.stats_reports.

Parameters:

Name	Type	Description	Default
season	Optional[int]	Season in YYYYYYYY format; defaults to the current season.	None
report	str	Report name (default "summary").	'summary'
aggregate	bool	Whether to aggregate the stats.	False
game	bool	Whether to return game-level stats.	True
limit	int	Number of results (-1 for all).	-1
start	int	Starting index for pagination.	0
sort	str	Field to sort by (default "wins").	'wins'
game_type	Optional[int]	Optional game type (2=regular season, 3=playoffs) appended to the season filter.	None
direction	Optional[str]	Optional sort direction ("ASC"/"DESC") for the dir query parameter.	None
cayenne_exp	Optional[str]	Raw Cayenne filter expression (escape hatch that overrides the season/game-type expression).	None
fact_cayenne_exp	Optional[Union[str, list[str]]]	Optional factCayenneExp query filter.	None
include	Optional[Union[str, list[str]]]	Optional include query filter (string or list).	None
exclude	Optional[Union[str, list[str]]]	Optional exclude query filter (string or list).	None
lang	str	Language code for the Stats API request (default "en").	'en'
extra_params	Optional[dict[str, Any]]	Raw escape hatch for additional query parameters, merged last.	None

Returns:

Type	Description
list[GoalieStats]	List of GoalieStats objects (one per report row).

Player Model

edgework.models.player.Player(edgework_client=None, obj_id=None, **kwargs)

Bases: BaseNHLModel

Player model to store player information.

Initialize a Player object with dynamic attributes.

Parameters:

Name	Type	Description	Default
edgework_client		The Edgework client (optional for player data from API)	None
obj_id		The ID of the player object	None
**kwargs		Dynamic attributes for player properties	{}

full_name property

Get the player's full name.

Returns:

Name	Type	Description
str		The player's full name (first name + last name). Example: "Connor McDavid".

name property

Alias for full_name.

Returns:

Name	Type	Description
str		The player's full name (first name + last name). Example: "Connor McDavid".

age property

Calculate player's age from birth_date.

Returns:

Type	Description
	int | None: The player's age in years, or None if birth_date is not available or cannot be parsed.

headshot property

Get the player's headshot image URL.

Returns:

Type	Description
	str | None: URL to the player's headshot image, or None if not available.

hero_image property

Get the player's action shot/hero image URL.

Returns:

Type	Description
	str | None: URL to the player's hero image, or None if not available.

awards property

Get the player's awards and trophies.

Returns:

Type	Description
	list | None: List of awards with trophy names and season details, or None if not available.

badges property

Get the player's special badges (e.g., All-Star, events).

Returns:

Type	Description
	list | None: List of special badges with logos and titles, or None if not available.

team_logo property

Get the current team's logo URL.

Returns:

Type	Description
	str | None: URL to the current team's logo, or None if not available.

last_5_games property

Get the player's last 5 games statistics.

Returns:

Type	Description
	list | None: List of the last 5 games with stats, or None if not available.

season_totals property

Get the player's season-by-season statistics.

Returns:

Type	Description
	list | None: List of season totals for each year played, or None if not available.

current_team_roster property

Get the player's current team roster.

Returns:

Type	Description
	list | None: List of current teammates, or None if not available.

birth_city property

Get the player's birth city.

Returns:

Type	Description
	str | None: The player's birth city, or None if not available.

birth_state_province property

Get the player's birth state or province.

Returns:

Type	Description
	str | None: The player's birth state/province, or None if not available.

birth_country property

Get the player's birth country.

Returns:

Type	Description
	str | None: The player's birth country code, or None if not available.

height_formatted property

Get the player's height in formatted string (e.g., '6' 1"').

Returns:

Type	Description
	str | None: Formatted height string, or None if not available.

weight property

Get the player's weight in kilograms.

Returns:

Type	Description
	int | None: Weight in kilograms, or None if not available.

weight_pounds property

Get the player's weight in pounds.

Returns:

Type	Description
	int | None: Weight in pounds, or None if not available.

draft_year property

Get the player's draft year.

Returns:

Type	Description
	datetime | int | None: Draft year as datetime object or integer, or None if not available.

draft_round property

Get the player's draft round.

Returns:

Type	Description
	int | None: Draft round number, or None if not available.

draft_overall_pick property

Get the player's overall draft pick number.

Returns:

Type	Description
	int | None: Overall pick number, or None if not available.

career_totals property

Get the player's career totals (regular season and playoffs).

Returns:

Type	Description
	dict | None: Dictionary with career statistics, or None if not available. Contains keys like 'career_totals_regular_season_goals', 'career_totals_playoffs_assists', etc.

__str__()

String representation showing player name and number.

Returns:

Name	Type	Description
str	str	Formatted string with player name, number, and team abbreviation. Examples: "#97 Connor McDavid (EDM)", "Connor McDavid (EDM)", "#97 Connor McDavid", or "Connor McDavid".

__repr__()

Developer representation of the Player object.

Returns:

Name	Type	Description
str		Developer-friendly string representation showing the player ID. Example: "Player(id=8478402)".

__eq__(other)

Compare players by their player_id.

Parameters:

Name	Type	Description	Default
other		The other object to compare with.	required

Returns:

Name	Type	Description
bool	bool	True if both objects are Player instances with the same player_id, False otherwise.

__hash__()

Hash based on player_id for use in sets and dicts.

Returns:

Name	Type	Description
int		Hash value based on the player_id.

fetch_data()

Fetch the data for the player from the API.

Uses the NHL Web API player landing endpoint to get detailed player information.

Raises:

Type	Description
ValueError	If no client is available to fetch player data.
ValueError	If no player ID is available to fetch data.

get_attribute(attr_name)

Get any attribute from the player data.

Parameters:

Name	Type	Description	Default
attr_name	str	The name of the attribute to retrieve.	required

Returns:

Name	Type	Description
Any		The value of the attribute, or None if not found.

Example

player.get_attribute('shop_link') player.get_attribute('featured_stats_regular_season_sub_season_goals')

get_all_attributes()

Get all available attributes for this player.

Returns:

Name	Type	Description
dict		Dictionary of all player attributes and their values.

list_attributes(filter_prefix=None)

List all available attribute names.

Parameters:

Name	Type	Description	Default
filter_prefix	str	Only show attributes starting with this prefix.	None

Returns:

Name	Type	Description
list		List of attribute names.

Example

player.list_attributes() # All attributes player.list_attributes('career_totals_') # Only career totals player.list_attributes('featured_stats_') # Only featured stats

Player Client

edgework.clients.player_client.PlayerClient(http_client)

Client for fetching player data.

Initialize the player client.

Parameters:

Name	Type	Description	Default
http_client	HttpClient	HTTP client instance	required

get_all_players(active=None, limit=10000)

Get all players from the NHL search API.

Parameters:

Name	Type	Description	Default
active	Optional[bool]	Filter by active status (True for active, False for inactive, None for all)	None
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of Player objects

get_active_players(limit=10000)

Get all active players.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of active Player objects

get_inactive_players(limit=10000)

Get all inactive players.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of players to return	10000

Returns:

Type	Description
List[Player]	List of inactive Player objects

get_player_landing(player_id)

Fetch player landing page data with comprehensive player information.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Dict	Dictionary with player landing data including:
Dict	Player profile information
Dict	Career statistics
Dict	Current season stats
Dict	Recent games
Dict	Player bio and media

get_player_game_logs(player_id, season, game_type=2)

Fetch game-by-game statistics for a player in a specific season.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required
season	str	Season in format "YYYY-YYYY" (e.g., "2023-2024")	required
game_type	int	Game type - 2 for Regular Season (default), 3 for Playoffs, 1 for Pre-season	2

Returns:

Type	Description
Dict	Dictionary with game logs including:
Dict	Season statistics
Dict	Game-by-game breakdown
Dict	Home/away splits
Dict	Monthly splits

get_player_game_log_now(player_id)

Fetch game-by-game statistics for the current season.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Dict	Dictionary with current season game logs

get_player_spotlight()

Fetch featured/spotlight players from the NHL.

Returns:

Type	Description
List[Dict]	List of dictionaries with spotlight player information

get_player(player_id)

Fetch player data by ID using the landing endpoint.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Player	Player object with comprehensive data

get_player_by_id(player_id)

Get a player by their NHL ID.

Parameters:

Name	Type	Description	Default
player_id	int	The NHL player ID	required

Returns:

Type	Description
Optional[Player]	Player object if found, None otherwise