nhl-api-py 3.2.3__tar.gz → 3.3.0__tar.gz

{nhl_api_py-3.2.3 → nhl_api_py-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nhl-api-py
-Version: 3.2.3
+Version: 3.3.0
 Summary: NHL API (Updated for 2025/2026) and EDGE Stats.  For standings, team stats, outcomes, player information.  Contains each individual API endpoint as well as convience methods as well as pythonic query builder for more indepth EDGE stats.
 Home-page: https://github.com/coreyjs/nhl-api-py
 License: Apache-2.0

{nhl_api_py-3.2.3 → nhl_api_py-3.3.0}/nhlpy/api/edge.py

@@ -27,6 +27,19 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the skater
 
+        Key Response Fields:
+            player.firstName.default (str): Player first name
+            player.lastName.default (str): Player last name
+            player.goals (int): Total goals scored
+            player.points (int): Total points
+            topShotSpeed.imperial (float): Top shot speed in mph
+            skatingSpeed.speedMax.imperial (float): Maximum skating speed in mph
+            totalDistanceSkated.imperial (float): Total distance skated in miles
+            zoneTimeDetails.offensiveZonePctg (float): Offensive zone time percentage
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.skater_detail(player_id=8478402)
             client.edge.skater_detail(player_id=8478402, season=20232024, game_type=2)
@@ -47,6 +60,14 @@ class Edge:
 
         Returns:
             dict: Shot speed statistics including maximum and average speeds
+
+        Key Response Fields:
+            shotSpeedData (list): Shot speed entries with percentiles
+            topShotSpeed.imperial (float): Top shot speed in mph
+            averageShotSpeed.imperial (float): Average shot speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-shot-speed-detail/{player_id}/now"
@@ -64,6 +85,14 @@ class Edge:
 
         Returns:
             dict: Skating speed statistics including burst speed and average speed
+
+        Key Response Fields:
+            skatingSpeedData (list): Skating speed entries with burst counts
+            speedMax.imperial (float): Maximum skating speed in mph
+            burstCount (int): Number of speed bursts
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-skating-speed-detail/{player_id}/now"
@@ -81,6 +110,14 @@ class Edge:
 
         Returns:
             dict: Shot location data including shooting patterns and heat maps
+
+        Key Response Fields:
+            shotLocations (list): Shot data grouped by area
+            area (str): Ice zone identifier
+            shotCount (int): Number of shots from each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-shot-location-detail/{player_id}/now"
@@ -98,6 +135,14 @@ class Edge:
 
         Returns:
             dict: Distance traveled statistics per game and per shift
+
+        Key Response Fields:
+            distanceData (list): Distance entries per game
+            totalDistance.imperial (float): Total distance skated in miles
+            gameMax.imperial (float): Maximum distance skated in a single game in miles
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-skating-distance-detail/{player_id}/now"
@@ -115,6 +160,14 @@ class Edge:
 
         Returns:
             dict: Comparison data relative to league averages
+
+        Key Response Fields:
+            comparisonData (list): Comparison metrics vs league
+            leagueAverage (float): League average value for each metric
+            playerValue (float): Player value for each metric
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-comparison/{player_id}/now"
@@ -132,6 +185,14 @@ class Edge:
 
         Returns:
             dict: Time spent in offensive, defensive, and neutral zones
+
+        Key Response Fields:
+            offensiveZonePctg (float): Offensive zone time percentage
+            defensiveZonePctg (float): Defensive zone time percentage
+            neutralZonePctg (float): Neutral zone time percentage
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-zone-time/{player_id}/now"
@@ -150,6 +211,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide skater EDGE statistics
+
+        Key Response Fields:
+            leaders.hardestShot (list): League leaders for hardest shot
+            leaders.maxSkatingSpeed (list): League leaders for max skating speed
+            leaders.totalDistanceSkated (list): League leaders for total distance skated
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/skater-landing/now"
@@ -167,6 +236,14 @@ class Edge:
 
         Returns:
             dict: CAT EDGE statistics for the skater
+
+        Key Response Fields:
+            player (dict): Compact player summary with EDGE highlights
+            shotSpeed (dict): Condensed shot speed data
+            skatingSpeed (dict): Condensed skating speed data
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"cat/edge/skater-detail/{player_id}/now"
@@ -194,6 +271,16 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the goalie
 
+        Key Response Fields:
+            player.wins (int): Total wins
+            player.savePctg (float): Overall save percentage
+            stats.goalsAgainstAvg.value (float): Goals against average
+            stats.gamesAbove900.value (float): Games with save pct above .900
+            shotLocationSummary (list): Save data grouped by shot area
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.goalie_detail(player_id=8476945)
             client.edge.goalie_detail(player_id=8476945, season=20232024, game_type=2)
@@ -214,6 +301,14 @@ class Edge:
 
         Returns:
             dict: Shot location data faced by the goalie including save percentages by zone
+
+        Key Response Fields:
+            shotLocations (list): Save data grouped by shot location
+            area (str): Ice zone identifier
+            savePctg (float): Save percentage for each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-shot-location-detail/{player_id}/now"
@@ -231,6 +326,14 @@ class Edge:
 
         Returns:
             dict: 5-on-5 performance statistics and save percentages
+
+        Key Response Fields:
+            fiveOnFiveStats (dict): 5-on-5 performance metrics
+            savePctg5v5 (float): Save percentage at 5-on-5
+            goalsAgainstAvg5v5 (float): Goals against average at 5-on-5
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-5v5-detail/{player_id}/now"
@@ -248,6 +351,14 @@ class Edge:
 
         Returns:
             dict: Comparison data relative to league averages
+
+        Key Response Fields:
+            comparisonData (list): Comparison metrics vs league
+            leagueAverage (float): League average value for each metric
+            playerValue (float): Player value for each metric
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-comparison/{player_id}/now"
@@ -265,6 +376,14 @@ class Edge:
 
         Returns:
             dict: Detailed save percentage breakdowns by situation and location
+
+        Key Response Fields:
+            savePctgBreakdown (list): Save percentage by situation type
+            overallSavePctg (float): Overall save percentage
+            highDangerSavePctg (float): Save percentage on high-danger chances
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-save-percentage-detail/{player_id}/now"
@@ -283,6 +402,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide goalie EDGE statistics
+
+        Key Response Fields:
+            leaders (dict): League leaders for goalie EDGE stats
+            topSavePctg (list): Leaders by save percentage
+            topGamesAbove900 (list): Leaders by games above .900
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/goalie-landing/now"
@@ -300,6 +427,14 @@ class Edge:
 
         Returns:
             dict: CAT EDGE statistics for the goalie
+
+        Key Response Fields:
+            player (dict): Compact goalie summary with EDGE highlights
+            savePctg (float): Condensed save percentage data
+            goalsAgainstAvg (float): Condensed goals against average
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"cat/edge/goalie-detail/{player_id}/now"
@@ -327,6 +462,18 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the team
 
+        Key Response Fields:
+            team.abbrev (str): Team abbreviation
+            team.wins (int): Total wins
+            team.points (int): Total points
+            shotSpeed.topShotSpeed.imperial (float): Top shot speed in mph
+            skatingSpeed.speedMax.imperial (float): Maximum skating speed in mph
+            distanceSkated.total.imperial (float): Total distance skated in miles
+            zoneTimeDetails.offensiveZonePctg (float): Offensive zone time percentage
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.team_detail(team_id=10)
             client.edge.team_detail(team_id=10, season=20232024, game_type=2)
@@ -347,6 +494,14 @@ class Edge:
 
         Returns:
             dict: Team skating distance statistics per game and per player
+
+        Key Response Fields:
+            distanceData (list): Distance entries per game and per player
+            totalDistance.imperial (float): Total team distance skated in miles
+            perGameAvg.imperial (float): Average distance per game in miles
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-skating-distance-detail/{team_id}/now"
@@ -364,6 +519,14 @@ class Edge:
 
         Returns:
             dict: Team time spent in offensive, defensive, and neutral zones
+
+        Key Response Fields:
+            offensiveZonePctg (float): Offensive zone time percentage
+            defensiveZonePctg (float): Defensive zone time percentage
+            neutralZonePctg (float): Neutral zone time percentage
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-zone-time-details/{team_id}/now"
@@ -381,6 +544,14 @@ class Edge:
 
         Returns:
             dict: Team shot location data including shooting patterns and heat maps
+
+        Key Response Fields:
+            shotLocations (list): Shot data grouped by area
+            area (str): Ice zone identifier
+            shotCount (int): Number of shots from each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-shot-location-detail/{team_id}/now"
@@ -399,6 +570,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide team EDGE statistics
+
+        Key Response Fields:
+            leaders (dict): Team EDGE leaders across categories
+            topShotSpeed (list): Leaders by team shot speed
+            topSkatingSpeed (list): Leaders by team skating speed
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/team-landing/now"
@@ -416,6 +595,14 @@ class Edge:
 
         Returns:
             dict: Team shot speed statistics including maximum and average speeds
+
+        Key Response Fields:
+            shotSpeedData (list): Shot speed entries by player
+            topShotSpeed.imperial (float): Top team shot speed in mph
+            averageShotSpeed.imperial (float): Average team shot speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-shot-speed-detail/{team_id}/now"
@@ -433,6 +620,14 @@ class Edge:
 
         Returns:
             dict: Team skating speed statistics including burst speed and average speed
+
+        Key Response Fields:
+            skatingSpeedData (list): Skating speed entries by player
+            speedMax.imperial (float): Maximum team skating speed in mph
+            averageSpeed.imperial (float): Average team skating speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-skating-speed-detail/{team_id}/now"

nhl_api_py-3.3.0/nhlpy/api/game_center.py

@@ -0,0 +1,214 @@
+from typing import Optional, List
+from nhlpy.http_client import HttpClient, Endpoint
+
+
+class GameCenter:
+    def __init__(self, http_client: HttpClient):
+        self.client = http_client
+
+    def boxscore(self, game_id: str) -> dict:
+        """Get the full boxscore for a specific NHL game, including team scores, shots on goal,
+        and per-player stats broken down by position. Game IDs can be retrieved from the schedule endpoint.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280").
+
+        Key Response Fields:
+            gameState (str): Current state of the game ("FUT", "LIVE", "OFF", "FINAL").
+            awayTeam.abbrev (str): Away team abbreviation (e.g. "TOR").
+            awayTeam.score (int): Away team total goals.
+            homeTeam.abbrev (str): Home team abbreviation (e.g. "BOS").
+            homeTeam.score (int): Home team total goals.
+            awayTeam.sog (int): Away team shots on goal.
+            homeTeam.sog (int): Home team shots on goal.
+            playerByGameStats.awayTeam.forwards (list): Per-player stats for away forwards.
+            gameOutcome.lastPeriodType (str): Period type the game ended in ("REG", "OT", "SO").
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.boxscore(game_id="2023020280")
+
+        Returns:
+            dict: Full boxscore data including team totals and player-level game stats.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"gamecenter/{game_id}/boxscore").json()
+
+    def play_by_play(self, game_id: str) -> dict:
+        """Get the full play-by-play feed for a specific NHL game, containing every recorded event
+        such as shots, goals, faceoffs, hits, and penalties. Game IDs can be retrieved from the
+        schedule endpoint.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280").
+
+        Key Response Fields:
+            plays (list): All game events (~340 per game), ordered chronologically.
+            plays[].typeDescKey (str): Event type descriptor (e.g. "shot-on-goal", "goal", "faceoff").
+            plays[].timeInPeriod (str): Time elapsed in the period (e.g. "12:34").
+            plays[].periodDescriptor.number (int): Period number (1, 2, 3, 4 for OT).
+            plays[].details.xCoord (float): Ice x-coordinate of the event.
+            plays[].details.yCoord (float): Ice y-coordinate of the event.
+            rosterSpots (list): Player info for all rostered players in the game.
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.play_by_play(game_id="2023020280")
+
+        Returns:
+            dict: Complete play-by-play data including all events and roster information.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"gamecenter/{game_id}/play-by-play").json()
+
+    def match_up(self, game_id: str) -> dict:
+        """Get the landing-page summary for a specific NHL game, including scoring by period,
+        three-stars selections, and penalty details. Game IDs can be retrieved from the
+        schedule endpoint.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280").
+
+        Key Response Fields:
+            summary.scoring (list): Goals broken down by period.
+            summary.threeStars (list): Three stars of the game, each containing:
+                star (int), playerId (int), teamAbbrev (str), name (str), position (str).
+            summary.penalties (list): All penalties assessed during the game.
+            summary.teamGameStats (list): Head-to-head team stats (SOG, faceoff %, PIM, etc.).
+            awayTeam.abbrev (str): Away team abbreviation.
+            homeTeam.abbrev (str): Home team abbreviation.
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.match_up(game_id="2023020280")
+
+        Returns:
+            dict: Detailed game matchup data including scoring summary, three stars, and penalties.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"gamecenter/{game_id}/landing").json()
+
+    def daily_scores(self, date: Optional[str] = None) -> dict:
+        """Get scores and game states for all NHL games on a given date. Returns the current
+        day's scoreboard when no date is provided, along with navigation links to adjacent dates.
+
+        Args:
+            date (str, optional): Date in YYYY-MM-DD format (e.g. "2024-01-15").
+                If not provided, returns the current day's scores.
+
+        Key Response Fields:
+            currentDate (str): The date for the returned scores (YYYY-MM-DD).
+            prevDate (str): Previous date with NHL games, for pagination.
+            nextDate (str): Next date with NHL games, for pagination.
+            games (list): All games on the requested date.
+            games[].awayTeam.abbrev (str): Away team abbreviation (e.g. "NYR").
+            games[].awayTeam.score (int): Away team score.
+            games[].homeTeam.abbrev (str): Home team abbreviation (e.g. "PIT").
+            games[].homeTeam.score (int): Home team score.
+            games[].gameState (str): Game state ("FUT", "LIVE", "OFF", "FINAL").
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.daily_scores(date="2024-01-15")
+
+        Returns:
+            dict: Scoreboard data with all games, scores, statuses, and date navigation.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"score/{date if date else 'now'}").json()
+
+    def shift_chart_data(self, game_id: str, excludes: List[str] = None) -> dict:
+        """Get individual player shift data for a specific game, including start/end times and
+        durations for every shift. A typical game contains ~740 shift records across both teams.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280"). Game IDs can be
+                retrieved from the schedule endpoint.
+            excludes (List[str], optional): Fields to exclude from the response.
+                Defaults to ["eventDetails"] if not provided.
+
+        Key Response Fields:
+            data (list): All shift records (~740 per game).
+            data[].firstName (str): Player's first name.
+            data[].lastName (str): Player's last name.
+            data[].teamAbbrev (str): Team abbreviation for the player.
+            data[].period (int): Period number the shift occurred in.
+            data[].startTime (str): Shift start time within the period (e.g. "05:23").
+            data[].duration (str): Length of the shift (e.g. "00:45").
+            total (int): Total number of shift records returned.
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.shift_chart_data(game_id="2023020280")
+
+        Returns:
+            dict: Shift chart data containing individual shift records for all players.
+        """
+        if excludes is None:
+            excludes = ["eventDetails"]
+
+        exclude_p: str = ",".join(excludes)
+        expr_p: str = f"gameId={game_id} and ((duration != '00:00' and typeCode = 517) or typeCode != 517 )"
+        return self.client.get(
+            endpoint=Endpoint.API_STATS, resource=f"en/shiftcharts?cayenneExp={expr_p}&exclude={exclude_p}"
+        ).json()
+
+    def season_series_matchup(self, game_id: str) -> dict:
+        """Get the season-series record and contextual stats for a specific game, including
+        head-to-head win totals, team game stats, and linescore data from the right-rail panel.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280"). Game IDs can be
+                retrieved from the schedule endpoint.
+
+        Key Response Fields:
+            seasonSeries (list): Results of all regular-season matchups between the two teams.
+            seasonSeriesWins (object): Win counts keyed by team ID.
+            teamGameStats (list): Comparative team stats for this game (SOG, faceoff %, etc.).
+            linescore (object): Period-by-period scoring breakdown.
+            gameReports (object): Links to official game reports (e.g. summary, event summary).
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.season_series_matchup(game_id="2023020280")
+
+        Returns:
+            dict: Season series record, team game stats, linescore, and game report links.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"gamecenter/{game_id}/right-rail").json()
+
+    def game_story(self, game_id: str) -> dict:
+        """Get the narrative game story for a specific game, including scoring summaries,
+        three-stars selections, and head-to-head team statistics. This is the data behind
+        the NHL's post-game recap page.
+
+        Args:
+            game_id (str): The unique game identifier (e.g. "2023020280"). Game IDs can be
+                retrieved from the schedule endpoint.
+
+        Key Response Fields:
+            summary.scoring (list): Goals organized by period, with scorer and assist details.
+            summary.threeStars (list): Three stars of the game with player info.
+            summary.teamGameStats (list): Comparative team stats (SOG, faceoff %, PIM, hits, etc.).
+            awayTeam.abbrev (str): Away team abbreviation.
+            homeTeam.abbrev (str): Home team abbreviation.
+            gameState (str): Current state of the game ("FUT", "LIVE", "OFF", "FINAL").
+
+        Response Docs:
+            See ``docs/game_center.md`` for the complete response schema.
+
+        Example:
+            client.game_center.game_story(game_id="2023020280")
+
+        Returns:
+            dict: Game story data with scoring summary, three stars, and team stat comparisons.
+        """
+        return self.client.get(endpoint=Endpoint.API_WEB_V1, resource=f"wsc/game-story/{game_id}").json()

{nhl_api_py-3.2.3 → nhl_api_py-3.3.0}/nhlpy/api/helpers.py

@@ -21,18 +21,31 @@ class Helpers:
         return name[ntype]["default"]
 
     def game_ids_by_season(self, season: str, game_types: List[int] = None, api_sleep_rate: float = 1) -> List[str]:
-        """Gets all game IDs for a specified season.
+        """Gets all game IDs for a specified season by querying every team's schedule.
+
+        Iterates over all 32 NHL teams and collects game IDs from each team's
+        season schedule.  Expect roughly 2,600 IDs for a full regular season
+        and approximately 32 API calls (one per team).
 
         Args:
-           season (str): Season to retrieve game IDs for in YYYYYYYY format (e.g., 20232024).
-           game_types (List[int]): List of game types to include. Valid types:
-               1: Preseason
-               2: Regular season
-               3: Playoffs
-        api_sleep_rate (float): Sleep rate in seconds between API calls to avoid hitting rate limits.
+            season (str): Season in YYYYYYYY format (e.g., "20232024").
+            game_types (List[int], optional): Game types to include. Valid values:
+
+                - ``1`` -- Preseason
+                - ``2`` -- Regular season
+                - ``3`` -- Playoffs
+
+                Defaults to ``None`` (all game types).
+            api_sleep_rate (float): Seconds to sleep between API calls to
+                avoid rate limiting. Defaults to ``1``.
 
         Returns:
-           List of game IDs for the specified season and game types.
+            List[str]: Game IDs matching the requested season and game types.
+
+        Note:
+            This method makes one API call per team (~32 calls) and respects
+            ``api_sleep_rate`` between each call. Total runtime depends on the
+            sleep rate chosen.
         """
         from nhlpy.api.teams import Teams
         from nhlpy.api.schedule import Schedule
@@ -60,13 +73,30 @@ class Helpers:
         return game_ids
 
     def all_players(self, season: str, api_sleep_rate: float = 0.5) -> List[dict[str, Any]]:
-        """Gets all player base stats.
+        """Gets every rostered player across all 32 NHL teams for a given season.
+
+        Iterates over every team roster and returns a flat list of player
+        dicts with cleaned name fields and an added ``team`` key.  Makes
+        approximately 32 API calls (one per team).
 
         Args:
-            api_sleep_rate (float): Sleep rate in seconds between API calls to avoid hitting rate limits.
+            season (str): Season in YYYYYYYY format (e.g., "20232024").
+            api_sleep_rate (float): Seconds to sleep between API calls to
+                avoid rate limiting. Defaults to ``0.5``.
 
         Returns:
-            List of player base stats.
+            List[dict[str, Any]]: List of player dicts. Key fields include:
+
+                - ``id`` (int): Player ID.
+                - ``firstName`` (str): Cleaned first name (``default`` value).
+                - ``lastName`` (str): Cleaned last name (``default`` value).
+                - ``sweaterNumber`` (int): Jersey number.
+                - ``positionCode`` (str): Position code (e.g., "C", "D", "G").
+                - ``team`` (str): Team abbreviation added by this method.
+
+        Note:
+            This method makes one API call per team (~32 calls) and respects
+            ``api_sleep_rate`` between each call.
         """
         from nhlpy.api.teams import Teams
 
@@ -90,7 +120,28 @@ class Helpers:
         return out_data
 
     def all_players_summary_statistics(self, season: str, api_sleep_rate: float = 1):
-        """Gets all player summary statistics for a specified season."""
+        """Gets summary statistics for every skater in a given season.
+
+        Combines roster data from ``all_players()`` with per-team summary
+        stats fetched through the query builder, then merges the two datasets
+        on player ID.  Makes multiple paginated API calls (one roster call
+        per team plus one stats call per team franchise).
+
+        Args:
+            season (str): Season in YYYYYYYY format (e.g., "20232024").
+            api_sleep_rate (float): Seconds to sleep between API calls to
+                avoid rate limiting. Defaults to ``1``.
+
+        Returns:
+            list[dict]: Merged player and summary-stats dicts.  Each entry
+            contains the roster fields from ``all_players()`` plus stats
+            fields such as ``goals``, ``assists``, ``points``,
+            ``gamesPlayed``, and other summary report columns.
+
+        Warning:
+            This method is slow and makes a large number of API calls.
+            Increase ``api_sleep_rate`` if you encounter rate limiting.
+        """
         logging.warning(
             "This method will take a while to run.  In the event of rate limiting, you may need to increase the api_sleep_rate."
         )