pyhockey.goalie_seasons

 1"""
 2Module for handling calls to the 'goalies' table, which holds season summaries for each goalie,
 3divided by game state.
 4"""
 5
 6import polars as pl
 7
 8from pyhockey.util.query_table import query_table
 9from pyhockey.util.data_disclaimer import print_data_disclaimer
10
11
12# Define custom type for inputs into our queries
13type QueryValue = str | int | float | list[str] | list[int] | list[float]
14
15
16def goalie_seasons(season: int | list[int],
17                   team: str | list[str] = 'ALL',
18                   min_games_played: int = 0,
19                   situation: str = 'all',
20                   combine_seasons: bool = False,
21                 quiet: bool = False) -> pl.DataFrame:
22    """ Return goalie-level season summaries.
23
24    Primary function for retrieving goalie-level season summaries. Given a season or list of
25    seasons, return goalie data summaries for each of those seasons. 
26
27    Can provide further filters via a team or list of teams, a minimum games-played cutoff, or
28    a specific situation/game state.
29
30    Args:
31
32        season: 
33            The (list of) season(s) for which to return data
34        team: 
35            The (list of) team(s) for which to return data, defaults to 'ALL'
36        min_icetime: 
37            A minimum icetime (in minutes) cut-off to apply, defaults to 0
38        situation: 
39            One of 'all', '5on5', '4on5', '5on4', or 'other', defaults to 'all'
40        combine_seasons: 
41            If True, and given multiple seasons, combine the results of each season into a
42            single entry for each player, defaults to False
43        quiet: 
44            If set to True, don't print the data disclaimer, defaults to False
45
46    Returns:
47
48        A polars DataFrame containing all of the requested data.
49        
50    Raises:
51    
52        ValueError: An input of either incorrect value or type was provided.
53    """
54
55    column_mapping: dict[str, QueryValue] = {
56        'season': season,
57        'team': team,
58        'situation': situation
59    }
60
61    qualifiers: dict[str, str] = {
62        'gamesPlayed': f'>={min_games_played}'
63    }
64
65    results: pl.DataFrame = query_table(table='goalies', column_mapping=column_mapping,
66                                        qualifiers=qualifiers, combine_seasons=combine_seasons,
67                                        order_by=['team', 'season'])
68
69    if not quiet:
70        print_data_disclaimer(source='MoneyPuck')
71
72    return results