cfbd_json_py.conferences

  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: conferences.py
  5# Purpose: Houses functions pertaining to CFB conference data
  6#    within the CFBD API.
  7###############################################################################
  8
  9import pandas as pd
 10import requests
 11
 12from cfbd_json_py.utls import get_cfbd_api_token
 13
 14
 15def get_cfbd_conference_info(
 16    api_key: str = None, api_key_dir: str = None, return_as_dict: bool = False
 17):
 18    """
 19    Retrieves a list of CFB conferences from the CFBD API.
 20
 21    Parameters
 22    ----------
 23    `api_key` (str, optional):
 24        Semi-optional argument.
 25        If `api_key` is null, this function will attempt to load a CFBD API key
 26        from the python environment, or from a file on this computer.
 27        If `api_key` is not null,
 28        this function will automatically assume that the
 29        inputted `api_key` is a valid CFBD API key.
 30
 31    `api_key_dir` (str, optional):
 32        Optional argument.
 33        If `api_key` is set to am empty string, this variable is ignored.
 34        If `api_key_dir` is null, and `api_key` is null,
 35        this function will try to find
 36        a CFBD API key file in this user's home directory.
 37        If `api_key_dir` is set to a string, and `api_key` is null,
 38        this function will assume that `api_key_dir` is a directory,
 39        and will try to find a CFBD API key file in that directory.
 40
 41    `return_as_dict` (bool, semi-optional):
 42        Semi-optional argument.
 43        If you want this function to return the data
 44        as a dictionary (read: JSON object),
 45        instead of a pandas `DataFrame` object,
 46        set `return_as_dict` to `True`.
 47
 48    Usage
 49    ----------
 50    ```
 51    import time
 52
 53    from cfbd_json_py.conferences import get_cfbd_conference_info
 54
 55    cfbd_key = "tigersAreAwesome"  # placeholder for your CFBD API Key.
 56
 57    if cfbd_key is not "tigersAreAwesome":
 58        print(
 59            "Using the user's API key declared in this script " +
 60            "for this example."
 61        )
 62
 63        # Gets CFB conference info from the CFBD API.
 64        print("Gets CFB conference info from the CFBD API.")
 65        json_data = get_cfbd_conference_info(api_key=cfbd_key)
 66        print(json_data)
 67        time.sleep(5)
 68
 69        # You can also tell this function to just return the API call
 70        # as a Dictionary (read: JSON) object.
 71        print(
 72            "You can also tell this function to just return the API call " +
 73            "as a Dictionary (read: JSON) object."
 74        )
 75        json_data = get_cfbd_conference_info(
 76            api_key=cfbd_key,
 77            return_as_dict=True)
 78        print(json_data)
 79
 80    else:
 81        # Alternatively, if the CFBD API key exists in this python environment,
 82        # or it's been set by cfbd_json_py.utls.set_cfbd_api_token(),
 83        # you could just call these functions directly,
 84        # without setting the API key in the script.
 85        print(
 86            "Using the user's API key supposedly loaded " +
 87            "into this python environment for this example."
 88        )
 89
 90        # Gets CFB conference info from the CFBD API.
 91        print("Gets CFB conference info from the CFBD API.")
 92        json_data = get_cfbd_conference_info()
 93        print(json_data)
 94        time.sleep(5)
 95
 96        # You can also tell this function to just return the API call
 97        # as a Dictionary (read: JSON) object.
 98        print(
 99            "You can also tell this function to just return the API call " +
100            "as a Dictionary (read: JSON) object."
101        )
102        json_data = get_cfbd_conference_info(return_as_dict=True)
103        print(json_data)
104
105    ```
106
107    Returns
108    ----------
109    A pandas `DataFrame` object with CFB conference data,
110    or (if `return_as_dict` is set to `True`)
111    a dictionary object with CFB conference data.
112    """
113
114    conference_df = pd.DataFrame()
115    # row_df = pd.DataFrame()
116    url = "https://api.collegefootballdata.com/conferences"
117
118    # Input validation
119    ##########################################################################
120
121    if api_key is not None:
122        real_api_key = api_key
123        del api_key
124    else:
125        real_api_key = get_cfbd_api_token(api_key_dir=api_key_dir)
126
127    if real_api_key == "tigersAreAwesome":
128        raise ValueError(
129            "You actually need to change `cfbd_key` to your CFBD API key."
130        )
131    elif "Bearer " in real_api_key:
132        pass
133    elif "Bearer" in real_api_key:
134        real_api_key = real_api_key.replace("Bearer", "Bearer ")
135    else:
136        real_api_key = "Bearer " + real_api_key
137
138    headers = {
139        "Authorization": f"{real_api_key}", "accept": "application/json"
140    }
141
142    response = requests.get(url, headers=headers)
143
144    if response.status_code == 200:
145        pass
146    elif response.status_code == 401:
147        raise ConnectionRefusedError(
148            "Could not connect. The connection was refused.\n" +
149            "HTTP Status Code 401."
150        )
151    else:
152        raise ConnectionError(
153            f"Could not connect.\nHTTP Status code {response.status_code}"
154        )
155
156    json_data = response.json()
157
158    if return_as_dict is True:
159        return json_data
160
161    conference_df = pd.json_normalize(json_data)
162    conference_df.rename(
163        columns={
164            "id": "conference_id",
165            "name": "conference_name",
166            "short_name": "conference_short_name",
167            "abbreviation": "conference",
168        },
169        inplace=True,
170    )
171    return conference_df