pyhockey.skater_games

 1"""
 2Main module for returning game-by-game statistics for each skater.
 3"""
 4import polars as pl
 5
 6from pyhockey.util.query_table import query_table
 7from pyhockey.util.data_disclaimer import print_data_disclaimer
 8
 9
10# Define custom type for inputs into our queries
11type QueryValue = str | int | float | list[str] | list[int] | list[float]
12
13
14def skater_games(season: int | list[int] | None = None,
15                 name: str | list[str] | None = None,
16                 team: str | list[str] = 'ALL',
17                 start_date: str | None = None,
18                 end_date: str | None = None,
19                 situation: str | None= None,
20                 quiet: bool = False) -> pl.DataFrame:
21    """ Returns skater-level game-by-game statistics.
22
23    Primary function for returning game-by-game skater statistics. Accepts one or multiple teams, 
24    one or multiple skater names, one or multiple seasons, or alternatively, a start- and end-date
25    for which to return game-by-game metrics.
26
27    Args:
28
29        season: 
30            Either one or a list of seasons for which to return all games. Disregarded if both 
31            start_date and end_date are also provided, defaults to None
32        name: 
33            Either one or a list of names for which to return stats. Can be a full name, partial
34            name, or just first/last name. defaults to None.
35        team: 
36            Either one or a list of teams, provided in 3-letter acronyms, defaults to 'ALL'
37        start_date: 
38            A date from which to return all games on and after that date, in YYYY-MM-DD format,
39            defaults to None
40        end_date: 
41            A date from which to return all games before and on that date, in YYYY-MM-DD format,
42            defaults to None
43        situation: 
44            Either None (so return everything), or one of 'all', '5on5', '4on5', or '5on4',
45            defaults to None
46        quiet: 
47            If set to True, don't print the data disclaimer, defaults to False
48
49    Returns:
50
51        A polars DataFrame containing all of the requested data.
52
53    Raises:
54    
55        ValueError: An input of either incorrect value or type was provided.
56    """
57
58    if not season and not start_date and not end_date:
59        raise ValueError("No values provided for 'season', 'start_date', or 'end_date'. Must "\
60                         "provide value for at least one of these.")
61
62    qualifers: dict[str, str] = {}
63
64    if start_date:
65        qualifers['start_date'] = start_date
66    if end_date:
67        qualifers['end_date'] = end_date
68
69    column_mapping: dict[str, QueryValue] = {
70        'season': season,
71        'name': name,
72        'team': team,
73        'situation': situation
74    }
75
76    results: pl.DataFrame = query_table(table='skater_games', column_mapping=column_mapping,
77                                        qualifiers=qualifers, order_by=['team', 'gameDate'])
78
79    if not quiet:
80        print_data_disclaimer(source='NaturalStatTrick')
81
82    return results