cfbd_json_py.coaches

  1# Creation Date: 08/30/2023 01:13 EDT
  2# Last Updated Date: 08/13/2024 02:10 PM EDT
  3# Author: Joseph Armstrong (armstrongjoseph08@gmail.com)
  4# File Name: coaches.py
  5# Purpose: Houses functions pertaining to coaching data within the CFBD API.
  6###############################################################################
  7
  8import logging
  9import warnings
 10
 11import pandas as pd
 12import requests
 13from tqdm import tqdm
 14
 15from cfbd_json_py.utls import get_cfbd_api_token
 16
 17
 18def get_cfbd_coaches_info(
 19    api_key: str = None,
 20    api_key_dir: str = None,
 21    first_name: str = None,
 22    last_name: str = None,
 23    team: str = None,
 24    season: int = None,
 25    min_season: int = None,
 26    max_season: int = None,
 27    year: int = None,
 28    return_as_dict: bool = False,
 29):
 30    """
 31    Retrieves information from the CFBD API on CFB Head Coaches.
 32
 33    Parameters
 34    ----------
 35    `api_key` (str, optional):
 36        Semi-optional argument.
 37        If `api_key` is null, this function will attempt to load a CFBD API key
 38        from the python environment, or from a file on this computer.
 39        If `api_key` is not null,
 40        this function will automatically assume that the
 41        inputted `api_key` is a valid CFBD API key.
 42
 43    `api_key_dir` (str, optional):
 44        Optional argument.
 45        If `api_key` is set to am empty string, this variable is ignored.
 46        If `api_key_dir` is null, and `api_key` is null,
 47        this function will try to find
 48        a CFBD API key file in this user's home directory.
 49        If `api_key_dir` is set to a string, and `api_key` is null,
 50        this function will assume that `api_key_dir` is a directory,
 51        and will try to find a CFBD API key file in that directory.
 52
 53    `first_name` (str, optional):
 54        Optional argument.
 55        If you want to only look up coaches with a specific first name,
 56        set this variable to that specific first name, and this function
 57        will attempt to look up coaches with that specific first name.
 58
 59    `last_name` (str, optional):
 60        Optional argument.
 61        If you want to only look up coaches with a specific last name,
 62        set this variable to that specific first name, and this function
 63        will attempt to look up coaches with that specific last name.
 64
 65    `team` (str, optional):
 66        Optional argument.
 67        If you want to filter and drill down to coaches who coached a specific
 68        CFB team, set this
 69
 70    `season` (int, optional):
 71        Optional argument.
 72        If you only want coaches from a specific season,
 73        set this variable to that season.
 74
 75    `min_season` (int, optional):
 76        Optional argument.
 77        Similar to `year`, but used in tandem with `max_season`
 78        to get coaches who coached with in a range of seasons.
 79
 80    `max_season` (int, optional):
 81        Optional argument.
 82        Similar to `year`, but used in tandem with `min_season`
 83        to get coaches who coached with in a range of seasons.
 84
 85    `year` (int):
 86        Alternative keyword for `season`
 87
 88    `return_as_dict` (bool, semi-optional):
 89        Semi-optional argument.
 90        If you want this function to return the data
 91        as a dictionary (read: JSON object),
 92        instead of a pandas `DataFrame` object,
 93        set `return_as_dict` to `True`.
 94
 95    Usage
 96    ----------
 97    ```
 98    import time
 99
100    from cfbd_json_py.coaches import get_cfbd_coaches_info
101
102    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
103
104    if cfbd_key is not "tigersAreAwesome":
105        print(
106            "Using the user's API key declared in this script "+
107            "for this example."
108        )
109
110        # Getting all coaches in the 2020 CFB season
111        print("Getting every coach in the 2020 CFB season.")
112        json_data = get_cfbd_coaches_info(
113            api_key=cfbd_key,
114            season=2020
115        )
116        print(json_data)
117        time.sleep(5)
118
119        # Getting all coaches in the 2020 CFB season,
120        # with a first name of "Luke"
121        print(
122            "Getting every coach in the 2020 CFB season, "+
123            "with a first name of \"Luke\"."
124        )
125        json_data = get_cfbd_coaches_info(
126            api_key=cfbd_key,
127            season=2020,
128            first_name="Luke"
129        )
130        print(json_data)
131        time.sleep(5)
132
133        # Getting all coaches in the 2020 CFB season, with a last name of "Day"
134        print(
135            "Getting all coaches in the 2020 CFB season, " +
136            "with a last name of \"Day\"."
137        )
138        json_data = get_cfbd_coaches_info(
139            api_key=cfbd_key,
140            season=2020,
141            last_name="Day"
142        )
143        print(json_data)
144        time.sleep(5)
145
146        # Getting every head coach for
147        # the 2020 Southern Mississippi Golden Eagles
148        print(
149            "Getting every head coach for " +
150            "the 2020 Southern Mississippi Golden Eagles."
151        )
152        json_data = get_cfbd_coaches_info(
153            api_key=cfbd_key,
154            season=2020,
155            team="Southern Mississippi"
156        )
157        print(json_data)
158        time.sleep(5)
159
160        # Getting every head coach between the 2019 and 2022 CFB seasons
161        print("Getting every head coach between the 2019 and 2022 CFB seasons")
162        json_data = get_cfbd_coaches_info(
163            api_key=cfbd_key,
164            min_season=2019,
165            max_season=2022
166        )
167        print(json_data)
168        time.sleep(5)
169
170        # You can also tell this function to just return the API call
171        # as a Dictionary (read: JSON) object.
172        print(
173            "You can also tell this function to just return the API call " +
174            "as a Dictionary (read: JSON) object."
175        )
176        json_data = get_cfbd_coaches_info(
177            api_key=cfbd_key,
178            season=2022,
179            team="Cincinnati",
180            return_as_dict=True
181        )
182        print(json_data)
183
184    else:
185        # Alternatively, if the CFBD API key exists in this python environment,
186        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
187        # you could just call these functions directly,
188        # without setting the API key in the script.
189        print(
190            "Using the user's API key supposedly loaded " +
191            "into this python environment for this example."
192        )
193
194        # Getting every coach in the 2020 CFB season.
195        print("Getting every coach in the 2020 CFB season.")
196        json_data = get_cfbd_coaches_info(season=2020)
197        print(json_data)
198        time.sleep(5)
199
200
201        # Getting every coach in the 2020 CFB season,
202        # with a first name of "Luke".
203        print(
204            "Getting every coach in the 2020 CFB season, " +
205            "with a first name of \"Luke\"."
206        )
207        json_data = get_cfbd_coaches_info(
208            season=2020,
209            first_name="Luke"
210        )
211        print(json_data)
212        time.sleep(5)
213
214        # Getting every coach in the 2020 CFB season,
215        # with a last name of "Day".
216        print(
217            "Getting every coach in the 2020 CFB season, " +
218            "with a last name of \"Day\"."
219        )
220        json_data = get_cfbd_coaches_info(
221            season=2020,
222            last_name="Day"
223        )
224        print(json_data)
225        time.sleep(5)
226
227        # Getting every head coach for
228        # the 2020 Southern Mississippi Golden Eagles.
229        print(
230            "Getting every head coach for the " +
231            "2020 Southern Mississippi Golden Eagles."
232        )
233        json_data = get_cfbd_coaches_info(
234            season=2020,
235            team="Southern Mississippi"
236        )
237        print(json_data)
238        time.sleep(5)
239
240        # Getting every head coach between the 2019 and 2022 CFB seasons.
241        print(
242            "Getting every head coach between the 2019 and 2022 CFB seasons."
243        )
244        json_data = get_cfbd_coaches_info(
245            min_season=2019,
246            max_season=2022
247        )
248        print(json_data)
249        time.sleep(5)
250
251        # You can also tell this function to just return the API call
252        # as a Dictionary (read: JSON) object.
253        print(
254            "You can also tell this function to just return the API call " +
255            "as a Dictionary (read: JSON) object."
256        )
257        json_data = get_cfbd_coaches_info(
258            season=2022,
259            team="Cincinnati",
260            return_as_dict=True
261        )
262        print(json_data)
263
264    ```
265    Returns
266    ----------
267    A pandas `DataFrame` object with CFB head coach data,
268    or (if `return_as_dict` is set to `True`)
269    a dictionary object with CFB head coach data.
270    """
271    warnings.simplefilter(action="ignore", category=FutureWarning)
272
273    coaches_df = pd.DataFrame()
274    row_df = pd.DataFrame()
275    url = "https://api.collegefootballdata.com/coaches"
276
277    # Input validation
278    ##########################################################################
279
280    # `year` to `season`
281    if season is not None and year is not None and (year is not season):
282        raise ValueError(
283            "When using this function, "
284            + "please specify a season in EITHER `year` or `season`."
285        )
286    if season is not None:
287        pass
288    elif year is not None:
289        season = year
290    else:
291        raise ValueError("No year/season inputted for this function.")
292
293    if api_key is not None:
294        real_api_key = api_key
295        del api_key
296    else:
297        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
298
299    if real_api_key == "tigersAreAwesome":
300        raise ValueError(
301            "You actually need to change `cfbd_key` to your CFBD API key."
302        )
303    elif "Bearer " in real_api_key:
304        pass
305    elif "Bearer" in real_api_key:
306        real_api_key = real_api_key.replace("Bearer", "Bearer ")
307    else:
308        real_api_key = "Bearer " + real_api_key
309
310    if min_season is not None and max_season is None:
311        if season is not None and min_season is not season:
312            raise LookupError(
313                "It is ambiguous which year you want coaching information "
314                + "from, because you set the following values "
315                + "for the following variables:"
316                + f"\n- `year`: {season}"
317                + f"\n- `min_season`: {min_season}"
318                + f"\n`max_season`: {max_season}"
319                + "\nIf you want to get coaches who coached in "
320                + "a specified range of seasons, "
321                + "set `min_season` and `max_season` to the range of seasons "
322                + "you want coaching information from."
323            )
324        elif season is not None and min_season is season:
325            logging.warning(
326                "If you only want coaching information for a single season, "
327                + "and not for a range of seasons, only set `year` "
328                + "to the season you want coaching info for, "
329                + "and leave `min_season` and `max_season` as `None` (NULL)."
330            )
331            min_season = None
332        elif season is None:
333            logging.warning(
334                "If you only want coaching information for a single season, "
335                + "and not for a range of seasons, only set `year` to "
336                + "the season you want coaching info for, "
337                + "and leave `min_season` and `max_season` as `None` (NULL)."
338            )
339            season = min_season
340            min_season = None
341
342    elif min_season is None and max_season is not None:
343        if season is not None and max_season is not season:
344            raise LookupError(
345                "It is ambiguous which year you want "
346                + "coaching information from, "
347                + "because you set the following values "
348                + "for the following variables:"
349                + f"\n- `year`: {season}"
350                + f"\n- `min_season`: {min_season}"
351                + f"\n`max_season`: {max_season}"
352                + "\nIf you want to get coaches who coached "
353                + "in a specified range of seasons, "
354                + "set `min_season` and `max_season` to the range of seasons "
355                + "you want coaching information from."
356            )
357        elif season is not None and max_season == season:
358            logging.warning(
359                "If you only want coaching information for "
360                + "a single season, and not for a range of seasons, "
361                + "only set `year` to the season you want coaching info for, "
362                + "and leave `min_season` and `max_season` as `None` (NULL)."
363            )
364            min_season = None
365        elif season is None:
366            logging.warning(
367                "If you only want coaching information for "
368                + "a single season, and not for a range of seasons, "
369                + "only set `year` to the season you want coaching info for, "
370                + "and leave `min_season` and `max_season` as `None` (NULL)."
371            )
372            season = max_season
373            max_season = None
374
375    if min_season is not None and max_season is not None:
376        if season is not None:
377            raise LookupError(
378                "It is ambiguous which year you want "
379                + "coaching information from, because you set "
380                + "the following values for the following variables:"
381                + f"\n- `year`: {season}"
382                + f"\n- `min_season`: {min_season}"
383                + f"\n`max_season`: {max_season}"
384                + "\nIf you want to get coaches who coached in "
385                + "a specified range of seasons, "
386                + "set `min_season` and `max_season` to the range of "
387                + "seasons you want coaching information from."
388            )
389        elif min_season > max_season:
390            raise ValueError(
391                "`min_season` cannot be greater than `max_season`."
392            )
393
394    # URL builder
395    ##########################################################################
396
397    url_elements = 0
398
399    if first_name is not None and url_elements == 0:
400        url += f"?firstName={first_name}"
401        url_elements += 1
402    elif first_name is not None:
403        url += f"&firstName={first_name}"
404        url_elements += 1
405
406    if last_name is not None and url_elements == 0:
407        url += f"?lastName={last_name}"
408        url_elements += 1
409    elif last_name is not None:
410        url += f"&lastName={last_name}"
411        url_elements += 1
412
413    if team is not None and url_elements == 0:
414        url += f"?team={team}"
415        url_elements += 1
416    elif team is not None:
417        url += f"&team={team}"
418        url_elements += 1
419
420    if season is not None:
421        if season is not None and url_elements == 0:
422            url += f"?year={season}"
423            url_elements += 1
424        elif season is not None:
425            url += f"&year={season}"
426            url_elements += 1
427
428    elif min_season is not None and max_season is not None:
429        if url_elements == 0:
430            url += f"?minYear={min_season}&maxYear={max_season}"
431            url_elements += 1
432        else:
433            url += f"&minYear={min_season}&maxYear={max_season}"
434            url_elements += 1
435
436    headers = {
437        "Authorization": f"{real_api_key}", "accept": "application/json"
438    }
439
440    response = requests.get(url, headers=headers)
441
442    if response.status_code == 200:
443        pass
444    elif response.status_code == 401:
445        raise ConnectionRefusedError(
446            "Could not connect. The connection was refused.\n" +
447            "HTTP Status Code 401."
448        )
449    else:
450        raise ConnectionError(
451            f"Could not connect.\nHTTP Status code {response.status_code}"
452        )
453
454    json_data = response.json()
455
456    if return_as_dict is True:
457        return json_data
458
459    for coach in tqdm(json_data):
460        coach_first_name = coach["first_name"]
461        coach_last_name = coach["last_name"]
462        coach_hire_date = coach["hire_date"]
463
464        row_df = pd.json_normalize(coach["seasons"])
465        row_df["coach_first_name"] = coach_first_name
466        row_df["coach_last_name"] = coach_last_name
467        row_df["coach_hire_date"] = coach_hire_date
468
469        coaches_df = pd.concat([coaches_df, row_df], ignore_index=True)
470
471        del coach_first_name, coach_last_name, coach_hire_date
472    # coaches_df = pd.json_normalize(json_data)
473    return coaches_df