Merge pull request #15 from armstjc/0.0.10-The-Metrics-Update

0.0.10: The "Metrics" Update

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 0.0.10: The "Metrics" Update
 
+- Implemented `cfbd_json_py.metrics.get_cfbd_pregame_win_probability_data()`, a function that allows a user to get pregame win probability data from the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_game_win_probability_data()`, a function that allows a user to get win probability data from a valid game ID in the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_player_season_ppa_data()`, a function that allows a user to get player game PPA data from the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_player_game_ppa_data()`, a function that allows a user to get player season PPA data from the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_team_game_ppa_data()`, a function that allows a user to get team game PPA data from the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_team_season_ppa_data()`, a function that allows a user to get team season PPA data from the CFBD API.
+- Implemented `cfbd_json_py.metrics.get_cfbd_predicted_ppa_from_down_distance()`, a function that allows a user to get predicted PPA values from the CFBD API, given a down and distance (like 1st and 10).
+- Updated the function descriptions for the following functions:
+  - `cfbd_json_py.utls.reverse_cipher_encrypt()`
+  - `cfbd_json_py.utls.reverse_cipher_decrypt()`
+  - `cfbd_json_py.utls.get_cfbd_api_token()`
+- Updated the `README.md` file to give users a general idea on what this python package is, how to install it, and how to access this python package's docs.
+- Added a front page to the Docs website for this python package.
+- Updated the package version to `0.0.10`.
+
 ## 0.0.9: The "Bug Fixes 1" Update
 - Attempted another fix for the `generate_docs.yml` GitHub Workflow to allow it to call `pdoc` properly within GitHub Actions.
 - Removed the PyArrow package as a required package for this python package.

README.md

@@ -1,2 +1,50 @@
 # cfbd-json-py
 Allows users to access the CFBD API, and get the resulting data in either a dictionary (think JSON), or in a pandas DataFrame (think spreadsheet).
+
+## How to Install
+
+This package is is available through the `pip` package manager, and can be installed through one of the following commands in your terminal/shell:
+
+```
+pip install cfbd_json_py
+```
+
+OR
+
+```
+python -m pip install cfbd_json_py
+```
+
+If you are using a Linux/Mac instance, you may need to specify `python3` when installing.
+
+```
+python3 -m pip install cfbd_json_py
+```
+
+Alternatively, `cfbd-json-py` can be installed from this GitHub repository with the following command through pip:
+
+```
+pip install git+https://github.com/armstjc/cfbd-json-py
+```
+
+OR
+
+```
+python -m pip install git+https://github.com/armstjc/cfbd-json-py
+```
+
+OR
+
+```
+python3 -m pip install git+https://github.com/armstjc/cfbd-json-py
+```
+
+## Project Staus
+You can view the status of the project [by clicking on this link](https://github.com/users/armstjc/projects/4). It will be updated periodically as more features are implemented into this python package.
+
+## Bugs/Issues
+
+If you find an issue/bug while using this python package, [please feel free to raise an issue](https://github.com/armstjc/cfbd-json-py/issues), we're only human, and there will inevitably be issues found!
+
+## Docs
+For the cfbd-json-py docs, they can be found at [armstjc.github.io/cfbd-json-py/](armstjc.github.io/cfbd-json-py/)

cfbd_json_py/__init__.py

@@ -1,11 +1,107 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/06/2023 08:06 PM EDT
+# Last Updated Date: 10/20/2023 02:33 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: __init__.py
 # Purpose: Allows for the python package to function,
 #          by allowing you to to access functions within
 #          this package.
 ####################################################################################################
+"""
+# Welcome!
+This is the official docs page for the `cfbd_json_py` python package.
+
+To the left of this page are various endpoints for this python package.
+- `cfbd_json_py.betting`: 
+    Holds functions for betting lines and betting data from the CFBD API.
+- `cfbd_json_py.coaches`: 
+    Holds functions for you to get coaching data (past and present).
+- `cfbd_json_py.conferences`: 
+    Holds functions for you to get information for CFB confrences.
+- `cfbd_json_py.draft`: 
+    Holds functions for you to get NFL draft information/data for 
+    various players in the CFBD API
+- `cfbd_json_py.drives`: 
+    Holds functions for you to get data for offensive and/or defensive drives 
+    within the CFBD API.
+- `cfbd_json_py.games`: 
+    Holds functions for you to get various datapoints pertaining to 
+    actual CFB games within the CFBD API.
+- `cfbd_json_py.metrics`: 
+    Holds functions to allow you to calculate or retrive various advanced metrics 
+    from the CFBD API.
+- `cfbd_json_py.players`: 
+    Holds functions for you to get various 
+    data endpoints related to player stats, 
+    player information, and player data.
+- `cfbd_json_py.plays`: 
+    Holds functions for play-by-play (PBP) data for CFB games, 
+    as well as a way to calculate stats from PBP data.
+- `cfbd_json_py.rankings`: 
+    Holds functions for various CFB team ranking polls, 
+    and their results.
+- `cfbd_json_py.ratings`: 
+    Holds functions to allow you to get various team ratings data 
+    (like SP+, SRS, and Elo team ratings) from the CFBD API.
+- `cfbd_json_py.recruiting`: 
+    Holds functions for you to access CFB recruting data and information, 
+    as well as team and player ratings for recruiting.
+- `cfbd_json_py.stats`: 
+    Holds functions for you to get various team stats from the CFBD API.
+- `cfbd_json_py.teams`: 
+    Holds functions for you to get team information and data, 
+    as well as head-to-head records and matchup history.
+- `cfbd_json_py.utls`: 
+    Various utilities that can be used from this package.
+    Outside of `cfbd_json_py.utls.set_cfbd_api_token()`, 
+    you don't need to call any of these functions directly.
+- `cfbd_json_py.venues`: 
+    Holds functions for you to get information on 
+    various venues/stadiums within the college football world.
+    
+# Basic Setup
+
+If you have a CFBD API key, you have three ways to set it for this python package to use:
+1. Declare the API key as a string variable in a python script (not reccomended, extreme security risk).
+2. Declare the API key in your environment as `CFBD_API_KEY`.
+    - `cfbd_json_py` will first look for your environment, 
+    if you don't declare the API key as a string variable, 
+    when calling any function in this python package that uses a CFBD API call.
+    - If you're using GitHub Actions with this package, 
+    just set a repository secret with the name `CFBD_API_KEY`. 
+    Again, this package will automatically know where to look, 
+    if you've set your API key in the environment 
+3. Use `cfbd_json_py.utls.set_cfbd_api_token()` to store the API key in an encrypted file on your machine.
+    - To set the API key for this package with this function, 
+    run this code in a python script, 
+    replacing `"TigersAreAwesome"` with your API key:
+
+```
+from cfbd_api_key.utls import set_cfbd_api_token
+
+cfbd_api_key = "TigersAreAwesome" # replace this with your actual API key
+set_cfbd_api_token(api_key=cfbd_api_key)
+```
+
+> **NOTE:** *In a future version, 
+    there will be an executable application seperate from this package
+    for Windows, Mac, and Linux users to effectively do the same thing 
+    as the above code block, but with a graphical user interface (GUI).*
+
+If you want to see how to use this python package after setting up your API key,
+click on one of the submodules on the left 
+to view the various functions within each submodule.
+Each function has a tutorial script on the various ways you can call that function.
+
+# Other Notes
+- If you want to see all CFBD API endpoints that are currently supported, 
+    [click here](https://api.collegefootballdata.com/api/docs/?url=/api-docs.json#/)
+    to access the current Swagger docs for the entire API.
+- If you want to see the source code for this package, 
+    [click here](https://github.com/armstjc/cfbd-json-py) to see the current stable build of this python package on GitHub.
+- If you want to see the active changelog for this python package, 
+    [click here]() to view the changelog of this python package on GitHub.
+
+"""
 
 # Generated Functions:
 from cfbd_json_py._early_access import *
@@ -31,3 +127,4 @@
 # Utils
 
 from cfbd_json_py.utls import *
+

cfbd_json_py/betting.py

@@ -1,13 +1,11 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/06/2023 07:52 PM EDT
+# Last Updated Date: 10/23/2023 04:09 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: betting.py
 # Purpose: Houses functions pertaining to betting data within the CFBD API.
 ####################################################################################################
 
-import time
 import warnings
-# from datetime import datetime
 
 import pandas as pd
 import requests
@@ -49,7 +47,7 @@ def get_cfbd_betting_lines(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -337,7 +335,7 @@ def get_cfbd_betting_lines(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass

cfbd_json_py/coaches.py

@@ -1,12 +1,11 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/09/2023 08:00 PM EDT
+# Last Updated Date: 10/23/2023 04:09 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: coaches.py
 # Purpose: Houses functions pertaining to coaching data within the CFBD API.
 ####################################################################################################
 
 import logging
-import time
 
 import pandas as pd
 import requests
@@ -40,7 +39,7 @@ def get_cfbd_coaches_info(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -336,7 +335,7 @@ def get_cfbd_coaches_info(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass

cfbd_json_py/conferences.py

@@ -1,11 +1,10 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/06/2023 07:35 PM EDT
+# Last Updated Date: 10/23/2023 04:09 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: conferences.py
 # Purpose: Houses functions pertaining to CFB conference data within the CFBD API.
 ####################################################################################################
 
-import time
 import pandas as pd
 import requests
 
@@ -30,7 +29,7 @@ def get_cfbd_conference_info(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -124,7 +123,7 @@ def get_cfbd_conference_info(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass

cfbd_json_py/draft.py

@@ -1,13 +1,12 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/07/2023 10:56 AM EDT
+# Last Updated Date: 10/23/2023 04:09 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: draft.py
 # Purpose: Houses functions pertaining to NFL Draft data within the CFBD API.
 ####################################################################################################
 
 from datetime import datetime
 import logging
-import time
 import pandas as pd
 import requests
 from tqdm import tqdm
@@ -33,7 +32,7 @@ def get_cfbd_nfl_teams(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -128,7 +127,7 @@ def get_cfbd_nfl_teams(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass
@@ -189,7 +188,7 @@ def get_cfbd_nfl_positions(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -283,7 +282,7 @@ def get_cfbd_nfl_positions(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass
@@ -343,7 +342,7 @@ def get_cfbd_nfl_draft_info(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -615,7 +614,7 @@ def get_cfbd_nfl_draft_info(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass

cfbd_json_py/drives.py

@@ -1,13 +1,12 @@
 # Creation Date: 08/30/2023 01:13 EDT
-# Last Updated Date: 10/11/2023 8:58 PM EDT
+# Last Updated Date: 10/23/2023 04:09 PM EDT
 # Author: Joseph Armstrong ([email protected])
 # File Name: drives.py
 # Purpose: Houses functions pertaining to CFB drive data within the CFBD API.
 ####################################################################################################
 
 from datetime import datetime
 import logging
-import time
 import pandas as pd
 import requests
 from tqdm import tqdm
@@ -49,7 +48,7 @@ def get_cfbd_drives_info(
 
     `api_key_dir` (str, optional):
         Optional argument.
-        If `api_key` is set to a string non-empty string, this variable is ignored.
+        If `api_key` is set to am empty string, this variable is ignored.
         If `api_key_dir` is null, and `api_key` is null, 
         this function will try to find a CFBD API key file in this user's home directory.
         If `api_key_dir` is set to a string, and `api_key` is null,
@@ -475,7 +474,7 @@ def get_cfbd_drives_info(
     }
 
     response = requests.get(url, headers=headers)
-    time.sleep(0.1)
+
 
     if response.status_code == 200:
         pass