hdforce 1.0.0__tar.gz

hdforce-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hawkin Dynamics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hdforce-1.0.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.1
+Name: hdforce
+Version: 1.0.0
+Summary: Get your data from the Hawkin Dynamics API
+Home-page: https://www.hawkindynamics.com/
+Keywords: hawkin,force plates,sports science
+Author: laureng-hd
+Author-email: lauren@hawkindynamics.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Dist: flake8 (>=7.0.0,<8.0.0)
+Requires-Dist: pandas (>=2.2.0,<3.0.0)
+Requires-Dist: pytest (>=8.2.0,<9.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Project-URL: Documentation, https://silver-adventure-22j19qq.pages.github.io/
+Project-URL: Repository, https://github.com/HawkinDynamics/hawkinPy
+Description-Content-Type: text/markdown
+
+# HDFORCE <img src="docs/img/hdlogo_sm.png" align="right" alt="" width="120" />
+
+**Get your data from the Hawkin Dynamics API**
+
+<!-- badges: start -->
+![GitHub Release](https://img.shields.io/github/v/release/HawkinDynamics/hawkinPy)
+[![Test Py Versions and OS](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml/badge.svg?branch=dev_env)](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml)
+![GitHub last commit (branch)](https://img.shields.io/github/last-commit/HawkinDynamics/hawkinPy/dev_env)
+[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://www.tidyverse.org/lifecycle/#stable)
+[![license](https://img.shields.io/badge/license-MIT%20+%20file%20LICENSE-lightgrey.svg)](https://choosealicense.com/)
+<!-- badges: end -->
+
+## How To Use The HDFORCE Package
+
+HDFORCE provides simple functionality with Hawkin Dynamics API. These functions are for use with ‘Hawkin Dynamics Beta API’ version 1.10-beta. You must be a Hawkin Dynamics user with an active integration account to utilize functions within the package.
+
+## Functions
+This API is designed to get data out of your Hawkin Dynamics server and interact with your data more intimately. It is not designed to be accessed from client applications directly. There is a limit on the amount of data that can be returned in a single request (256 MB). As your database grows, it will be necessary to use the `from` and `to` parameters to limit the size of the responses. Responses that exceed the memory limit will timeout and fail. It is advised that you design your client to handle this from the beginning. A recommended pattern would be to have two methods of fetching data. A scheduled pull that uses the `from` and `to` parameters to constrain the returned data to only tests that have occurred since the last fetch e.g. every day or every 5 minutes. And then a pull that fetches the entire database since you began testing that is only executed when necessary. A recommended way of doing this is to generate the `from` and `to` parameters for each month since you started and send a request for each either in parallel or sequentially.
+
+This package was meant to help execute requests to the Hawkin Dynamics API with a single line of code. There are 13 functions to help execute 4 primary objectives:
+
+### Authentication
+Use the Refresh Token generated by https://cloud.hawkindynamics.com/integrations to get a valid Access Token. Only the organization administrator account can generate API tokens. Use this function to initiate access to your data in the cloud. All other HDFORCE functions will depend on the values returned from this function.
+
+In HDFORCE, we can create and manage your authentication settings with the `authManager` function. The arguments passed will be used to handle authentication for the other functions used in the program. With this function, you can control these settings:
+
+* __region__: Sets the URL prefix of your cloud site.
+* __authMethod__: Sets storage method of auth variables. One of env, file, or manual. Default to 'env'.
+* __refreshToken_name__: Provide or set the name of the refresh Token variable. Default to "HD_REFRESH_TOKEN".
+* __refreshToken__: Optionally provided to pass a token for authentication when authMethod="manual". Else it will set the refresh token value when provided.
+* __env_file_name__: Required when authManager="file". Directs storage location of variables.
+
+The authentication manager allows the user to manage authentication with various development strategies. The 'env' method was designed to allow for simple authentication while developing in a local or contained environment, where the refresh token and variables are stored in the system environment. The 'file' method can be used for more visible and dynamic interaction with the auth variables, as the refresh token and variables are stored with a .env file. While the 'manual' method allows for the use of the package without storing sensitive data, in so the refresh token is not stored and is only used for authentication. This could be helpful in the scenario of developing a password-protected application where the token can be used as a password.
+
+In the case of the "file" method, the user will need to save a .env file in the source directory. When using this method, you will also need to pass the file name to the `env_file_name` argument as a string. It's most common to use something as simple as ".env", but you can name your file anything ending with .env.
+
+Below is an example of what the .env file can look like. This can be used as a template, as the variable name "HD_REFRESH_TOKEN" is the default to what the `authManager` function will use for the `refreshToken_name`. If you want to use a different variable name, simply pass the string through the `refreshToken_name` argument, along with the token to the `refreshToken` argument. The other values for ACCESS_TOKEN, TOKEN_EXPIRATION, and CLOUD_URL are defaults within the `authManager` function and should be maintained.
+
+``` PowerShell
+# Inside your .env file
+
+HD_REFRESH_TOKEN=your_api_token     # Replace With Your Refresh Token
+REGION=your_region                  # Replace With Your URL region
+ACCESS_TOKEN=                       # Access token will be stored here
+TOKEN_EXPIRATION=                   # Token Expiration will be stored here
+CLOUD_URL=                          # Your region's URL here
+```
+
+With the variables stored, we can use them with our other functions without worrying about authentication for each call.
+
+``` Python
+# Run authentication manager
+AuthManager(authMethod="env", region= "Americas")
+
+# Run authentication manager with file method
+AuthManager(authMethod="file", env_file_name=".env", region= "Americas")
+
+# Run authentication manager with manual method
+AuthManager(authMethod="manual", region="Americas", refreshToken="your_refresh_token")
+
+```
+
+### Hawkin Specific data
+While the purpose of the package is to help with accessing data specific to your organization, it may be helpful to store some data that is specific to Hawkin and the Hawkin Dynamics system. Things like test types and test metrics will help you call your data more efficiently and better understand the values you are seeing.
+
+* `GetTypes` - Get the test type names and IDs for all the test types in the system. The response will be a data frame containing the tests that are in the HD system.
+* `GetMetrics` - Get all the metrics for each test type. The response will be a data frame containing the test canonical ID, test type name, metric ID, metric label, a metric unit of measure, and description.
+
+### Organization Specific Data
+Every organization has data specific to them. With that, these entities will have unique IDs. It is important to have these IDs available to make the most of your test calls.
+
+* `GetAthletes()` - Get the athletes for an account. Inactive players will only be included if `inactive` = True. The response will be a data frame containing the athletes that match this query.
+* `GetTeams()` - Get the team names and IDs for all the teams in the org. The response will be a data frame containing the teams that are in the organization.
+* `GetGroups()` - Get the group names and IDs for all the groups in the org. The response will be a data frame containing the groups that are in the organization.
+* `GetTags()` - Get the tag names, IDs, and descriptions for tags created by users in your org. The response will be a data frame.
+
+### Get Test Data
+This is what you are here for. These functions allow you to call test data most efficiently. It is encouraged that you take advantage of the `from_`, `to_`, and `sync` parameters. This will help prevent from having calls with large payloads that may timeout and fail.
+
+#### Get Test Arguments
+* `from_` =  Optionally supply a time (Unix timestamp) you want the tests from. If you do not supply this
+value you will receive every test. This parameter is best suited for bulk exports of historical data.
+* `to_` = Optionally supply a time (Unix timestamp) you want the tests to. If you do not supply this value
+you will receive every test from the beginning of time or the optionally supplied `from_`
+parameter. This parameter is best suited for bulk exports of historical data
+* `sync` = The result set will include updated and newly created tests, following the time constraints of `from_` and `to_`. This parameter is best suited to keep your database in sync with the Hawkin database. It cannot and should not be used to fetch your entire database. A recommended strategy would be to have a job that runs on a short interval e.g. every five minutes that sends the `lastSyncTime` that it received as the `from_` parameter with `sync=True`.
+* `active` = If True, only active tests are fetched. If False, all tests including inactive ones are fetched. The default is set to True.
+
+#### Get Test Function
+* `GetTests()` - Get the tests for your account. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). The Response will be a data frame containing the trials within the time range (if specified).
+* `GetTestsAth()` - Get only tests of the specified athlete from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from the athlete, within the time range (if specified).
+* `GetTestsType()` - Get only tests of the specified test type from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from that test type, within the time range (if specified).
+* `GetTestsTeam()` - Get only tests of the specified teams from your organization. Requires a `teamId` argument, which expects a text string, list or tuple (max of 10 teams). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those teams, within the time range (if specified).
+* `GetTestsGroup()` - Get only tests of the specified groups from your organization. Requires a `groupId` argument, which expects a text string, list or tuple (max of 10 groups). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those groups, within the time range (if specified).
+* `GetForceTime()` - Get the force-time data for a specific test by id. This includes both left, right and combined force data at 1000hz (per millisecond). Calculated velocity, displacement, and power at each time interval will also be included.
+
+## Examples
+This is a basic example that shows a common workflow:
+
+### Authenticate Session
+``` Python
+# Dependencies
+import hdforce
+# Run authentication manager
+AuthManager(authMethod="env", region= "Americas")
+```
+### Get HD Data
+#### Test Types
+``` Python
+# Test Types
+types = hdforce.GetTypes()
+
+types
+```
+
+### Organization Data
+#### Get Athletes
+``` Python
+# Get Athletes
+roster = hdforce.GetAthletes( inactive= False) # inactive is default to False
+
+# Athlete example
+roster[roster['name'] =="Lauren Green"]
+```
+
+#### Get Tags
+``` Python
+# Get Tags
+tags = hdforce.GetTags()
+
+# Tags example
+tags[0:6]
+```
+
+### Get Tests
+``` Python
+# Get Tags
+allTests = hdforce.GetTests()
+# Filter my tests
+mytests = allTests[allTests['athlete.name'] =="Lauren Green"]
+# Slice some rows and columns
+df = mytests.iloc[:5,:15]
+
+df
+```

hdforce-1.0.0/README.md

@@ -0,0 +1,146 @@
+# HDFORCE <img src="docs/img/hdlogo_sm.png" align="right" alt="" width="120" />
+
+**Get your data from the Hawkin Dynamics API**
+
+<!-- badges: start -->
+![GitHub Release](https://img.shields.io/github/v/release/HawkinDynamics/hawkinPy)
+[![Test Py Versions and OS](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml/badge.svg?branch=dev_env)](https://github.com/HawkinDynamics/hawkinPy/actions/workflows/push-test.yml)
+![GitHub last commit (branch)](https://img.shields.io/github/last-commit/HawkinDynamics/hawkinPy/dev_env)
+[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![lifecycle](https://img.shields.io/badge/lifecycle-stable-green.svg)](https://www.tidyverse.org/lifecycle/#stable)
+[![license](https://img.shields.io/badge/license-MIT%20+%20file%20LICENSE-lightgrey.svg)](https://choosealicense.com/)
+<!-- badges: end -->
+
+## How To Use The HDFORCE Package
+
+HDFORCE provides simple functionality with Hawkin Dynamics API. These functions are for use with ‘Hawkin Dynamics Beta API’ version 1.10-beta. You must be a Hawkin Dynamics user with an active integration account to utilize functions within the package.
+
+## Functions
+This API is designed to get data out of your Hawkin Dynamics server and interact with your data more intimately. It is not designed to be accessed from client applications directly. There is a limit on the amount of data that can be returned in a single request (256 MB). As your database grows, it will be necessary to use the `from` and `to` parameters to limit the size of the responses. Responses that exceed the memory limit will timeout and fail. It is advised that you design your client to handle this from the beginning. A recommended pattern would be to have two methods of fetching data. A scheduled pull that uses the `from` and `to` parameters to constrain the returned data to only tests that have occurred since the last fetch e.g. every day or every 5 minutes. And then a pull that fetches the entire database since you began testing that is only executed when necessary. A recommended way of doing this is to generate the `from` and `to` parameters for each month since you started and send a request for each either in parallel or sequentially.
+
+This package was meant to help execute requests to the Hawkin Dynamics API with a single line of code. There are 13 functions to help execute 4 primary objectives:
+
+### Authentication
+Use the Refresh Token generated by https://cloud.hawkindynamics.com/integrations to get a valid Access Token. Only the organization administrator account can generate API tokens. Use this function to initiate access to your data in the cloud. All other HDFORCE functions will depend on the values returned from this function.
+
+In HDFORCE, we can create and manage your authentication settings with the `authManager` function. The arguments passed will be used to handle authentication for the other functions used in the program. With this function, you can control these settings:
+
+* __region__: Sets the URL prefix of your cloud site.
+* __authMethod__: Sets storage method of auth variables. One of env, file, or manual. Default to 'env'.
+* __refreshToken_name__: Provide or set the name of the refresh Token variable. Default to "HD_REFRESH_TOKEN".
+* __refreshToken__: Optionally provided to pass a token for authentication when authMethod="manual". Else it will set the refresh token value when provided.
+* __env_file_name__: Required when authManager="file". Directs storage location of variables.
+
+The authentication manager allows the user to manage authentication with various development strategies. The 'env' method was designed to allow for simple authentication while developing in a local or contained environment, where the refresh token and variables are stored in the system environment. The 'file' method can be used for more visible and dynamic interaction with the auth variables, as the refresh token and variables are stored with a .env file. While the 'manual' method allows for the use of the package without storing sensitive data, in so the refresh token is not stored and is only used for authentication. This could be helpful in the scenario of developing a password-protected application where the token can be used as a password.
+
+In the case of the "file" method, the user will need to save a .env file in the source directory. When using this method, you will also need to pass the file name to the `env_file_name` argument as a string. It's most common to use something as simple as ".env", but you can name your file anything ending with .env.
+
+Below is an example of what the .env file can look like. This can be used as a template, as the variable name "HD_REFRESH_TOKEN" is the default to what the `authManager` function will use for the `refreshToken_name`. If you want to use a different variable name, simply pass the string through the `refreshToken_name` argument, along with the token to the `refreshToken` argument. The other values for ACCESS_TOKEN, TOKEN_EXPIRATION, and CLOUD_URL are defaults within the `authManager` function and should be maintained.
+
+``` PowerShell
+# Inside your .env file
+
+HD_REFRESH_TOKEN=your_api_token     # Replace With Your Refresh Token
+REGION=your_region                  # Replace With Your URL region
+ACCESS_TOKEN=                       # Access token will be stored here
+TOKEN_EXPIRATION=                   # Token Expiration will be stored here
+CLOUD_URL=                          # Your region's URL here
+```
+
+With the variables stored, we can use them with our other functions without worrying about authentication for each call.
+
+``` Python
+# Run authentication manager
+AuthManager(authMethod="env", region= "Americas")
+
+# Run authentication manager with file method
+AuthManager(authMethod="file", env_file_name=".env", region= "Americas")
+
+# Run authentication manager with manual method
+AuthManager(authMethod="manual", region="Americas", refreshToken="your_refresh_token")
+
+```
+
+### Hawkin Specific data
+While the purpose of the package is to help with accessing data specific to your organization, it may be helpful to store some data that is specific to Hawkin and the Hawkin Dynamics system. Things like test types and test metrics will help you call your data more efficiently and better understand the values you are seeing.
+
+* `GetTypes` - Get the test type names and IDs for all the test types in the system. The response will be a data frame containing the tests that are in the HD system.
+* `GetMetrics` - Get all the metrics for each test type. The response will be a data frame containing the test canonical ID, test type name, metric ID, metric label, a metric unit of measure, and description.
+
+### Organization Specific Data
+Every organization has data specific to them. With that, these entities will have unique IDs. It is important to have these IDs available to make the most of your test calls.
+
+* `GetAthletes()` - Get the athletes for an account. Inactive players will only be included if `inactive` = True. The response will be a data frame containing the athletes that match this query.
+* `GetTeams()` - Get the team names and IDs for all the teams in the org. The response will be a data frame containing the teams that are in the organization.
+* `GetGroups()` - Get the group names and IDs for all the groups in the org. The response will be a data frame containing the groups that are in the organization.
+* `GetTags()` - Get the tag names, IDs, and descriptions for tags created by users in your org. The response will be a data frame.
+
+### Get Test Data
+This is what you are here for. These functions allow you to call test data most efficiently. It is encouraged that you take advantage of the `from_`, `to_`, and `sync` parameters. This will help prevent from having calls with large payloads that may timeout and fail.
+
+#### Get Test Arguments
+* `from_` =  Optionally supply a time (Unix timestamp) you want the tests from. If you do not supply this
+value you will receive every test. This parameter is best suited for bulk exports of historical data.
+* `to_` = Optionally supply a time (Unix timestamp) you want the tests to. If you do not supply this value
+you will receive every test from the beginning of time or the optionally supplied `from_`
+parameter. This parameter is best suited for bulk exports of historical data
+* `sync` = The result set will include updated and newly created tests, following the time constraints of `from_` and `to_`. This parameter is best suited to keep your database in sync with the Hawkin database. It cannot and should not be used to fetch your entire database. A recommended strategy would be to have a job that runs on a short interval e.g. every five minutes that sends the `lastSyncTime` that it received as the `from_` parameter with `sync=True`.
+* `active` = If True, only active tests are fetched. If False, all tests including inactive ones are fetched. The default is set to True.
+
+#### Get Test Function
+* `GetTests()` - Get the tests for your account. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). The Response will be a data frame containing the trials within the time range (if specified).
+* `GetTestsAth()` - Get only tests of the specified athlete from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from the athlete, within the time range (if specified).
+* `GetTestsType()` - Get only tests of the specified test type from your organization. You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from that test type, within the time range (if specified).
+* `GetTestsTeam()` - Get only tests of the specified teams from your organization. Requires a `teamId` argument, which expects a text string, list or tuple (max of 10 teams). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those teams, within the time range (if specified).
+* `GetTestsGroup()` - Get only tests of the specified groups from your organization. Requires a `groupId` argument, which expects a text string, list or tuple (max of 10 groups). You can specify a time frame `from_`, or `to_`, which the tests should come (or be synced). Response will be a data frame containing the trials from those groups, within the time range (if specified).
+* `GetForceTime()` - Get the force-time data for a specific test by id. This includes both left, right and combined force data at 1000hz (per millisecond). Calculated velocity, displacement, and power at each time interval will also be included.
+
+## Examples
+This is a basic example that shows a common workflow:
+
+### Authenticate Session
+``` Python
+# Dependencies
+import hdforce
+# Run authentication manager
+AuthManager(authMethod="env", region= "Americas")
+```
+### Get HD Data
+#### Test Types
+``` Python
+# Test Types
+types = hdforce.GetTypes()
+
+types
+```
+
+### Organization Data
+#### Get Athletes
+``` Python
+# Get Athletes
+roster = hdforce.GetAthletes( inactive= False) # inactive is default to False
+
+# Athlete example
+roster[roster['name'] =="Lauren Green"]
+```
+
+#### Get Tags
+``` Python
+# Get Tags
+tags = hdforce.GetTags()
+
+# Tags example
+tags[0:6]
+```
+
+### Get Tests
+``` Python
+# Get Tags
+allTests = hdforce.GetTests()
+# Filter my tests
+mytests = allTests[allTests['athlete.name'] =="Lauren Green"]
+# Slice some rows and columns
+df = mytests.iloc[:5,:15]
+
+df
+```

hdforce-1.0.0/hdforce/AuthManager.py

@@ -0,0 +1,170 @@
+import os
+from dotenv import load_dotenv, set_key
+# Package imports
+from .LoggerConfig import LoggerConfig
+from .utils import TokenManager, varsManager, ConfigManager
+
+# Get a logger specific to this module
+logger = LoggerConfig.get_logger(__name__)
+
+# -------------------- #
+# Authenticator
+
+
+def AuthManager(authMethod: str = "env", refreshToken_name: str = "HD_REFRESH_TOKEN", refreshToken: str = None, env_file_name: str = None, region: str = "Americas") -> None:
+    """ Choose the authentication settings
+
+
+    Parameters
+    ----------
+    region : str required
+        The region that designates the url prefix.
+
+    authMethod : str required
+        Determine method of storing authentication variables, including refresh token. One of 'env', 'file', 'manual'. env = use of system environment. file = use of .env file. manual = no stored refresh token.
+
+    refreshToken_name : str
+        Specific name of refresh token variable saved in system environment or .env file
+
+    refreshToken : str
+        If used with authMethod='manual', token will be used to authenticate without being stored. Else token will be used set as the new refresh token value with method selected.
+
+    env_file_name : str
+        Required with authMethod='file'. Provides file name for variable storage.
+
+
+    Raises
+    ------
+    ValueError
+        If authMethod not one of env, file, or method.
+        If authMethod = 'file' and no file name provided
+        If authMethod='manual' and no refreshToken provided
+
+    """
+    # auth method options
+    methods = ['env', 'file', 'manual']
+
+    # Check for valid method choice
+    if authMethod not in methods:
+        logger.error(f"{authMethod} is invalid authentication method.")
+        raise ValueError(f"Invalid auth method. Allowed methods are: {methods}")
+    else:
+        logger.debug(f"Authentication method selected: {authMethod}.")
+
+    # Load environment file if necessary
+    if authMethod == 'file':
+        if env_file_name:
+            load_dotenv(str(env_file_name), override=True)
+            logger.debug(f"Environment variables loaded from {env_file_name}.")
+        else:
+            logger.error("No file name given")
+            raise ValueError("No file name given. Must be provided with authMethod='file'")
+
+    # Retrieve or set the refresh token
+    if authMethod == 'manual':
+        if refreshToken is None:
+            logger.error("No refresh token found given")
+            raise ValueError("Refresh token must be provided with 'manual' authentication method.")
+        else:
+            key = refreshToken
+            kabrv = key[0:6]
+            #logger.debug(f"Manual auth method used with token {kabrv}xxxx")
+    else:
+        key = varsManager(name=refreshToken_name, value=refreshToken, method=authMethod, file=env_file_name)
+        kabrv = key[0:6]
+        logger.debug(f"Refresh token: {kabrv}xxxx method: {authMethod}")
+
+    # Setup session assuming TokenManager handles authentication
+    session = TokenManager(refreshToken=key, region=region, fileName=env_file_name)
+
+    # Create objects of classes
+    accessToken = str(session.accessToken)
+    tokenExpiration = str(session.ExpirationVal)
+    expirationStr = str(session.ExpirationStr)
+    cloudURL = str(session.url_cloud)
+    fileName = str(session.fileName)
+
+    if authMethod == 'file':
+        load_dotenv(str(fileName), override=True)
+
+        # Set environment variables
+        set_key(fileName, "ACCESS_TOKEN", accessToken)
+        # Environment variable debugging: Access Token
+        if accessToken == os.getenv("ACCESS_TOKEN"):
+            logger.debug(f"New Access Token Set")
+        else:
+            logger.debug(f"Error: new token not found")
+
+        # Environment variable debugging: Token Expiration
+        set_key(fileName, "TOKEN_EXPIRATION", tokenExpiration)
+        if tokenExpiration == os.getenv("TOKEN_EXPIRATION"):
+            logger.debug(f"New expiration Set")
+        else:
+            logger.debug(f"Error: new expiration not passed")
+
+        # Environment variable debugging: Cloud URL
+        set_key(fileName, "CLOUD_URL", cloudURL)
+        if cloudURL == os.getenv("CLOUD_URL"):
+            logger.debug(f"New URL set")
+        else:
+            logger.debug(f"Error: new URL not passed")
+
+    else:
+        # Environment variable debugging: Access Token
+        os.environ['ACCESS_TOKEN'] = accessToken
+        if accessToken == os.getenv("ACCESS_TOKEN"):
+            logger.debug(f"New Access Token Set")
+        else:
+            logger.debug(f"Error: new token not found")
+
+        # Environment variable debugging: Token Expiration
+        os.environ['TOKEN_EXPIRATION'] = tokenExpiration
+        if tokenExpiration == os.getenv("TOKEN_EXPIRATION"):
+            logger.debug(f"New expiration Set")
+        else:
+            logger.debug(f"Error: new expiration not passed")
+
+        # Environment variable debugging: Cloud URL
+        os.environ['CLOUD_URL'] = cloudURL
+        if cloudURL == os.getenv("CLOUD_URL"):
+            logger.debug(f"New URL set")
+        else:
+            logger.debug(f"Error: new URL not passed")
+
+    # Set environment source in ConfigManager based on authMethod
+    if authMethod == 'file':
+        # Check if filename passed
+        if not isinstance(fileName, str):
+            logger.error("File path must be provided when source is 'file'")
+            raise ValueError("File path must be provided when source is 'file'")
+        # if filename exists and string initialize dotenv
+        load_dotenv(str(fileName), override=True)
+        # run configuration manager
+        ConfigManager.set_env_source(region=region, method=authMethod, fileName=fileName, token_name=refreshToken_name, token=key)
+        logger.debug(f"ConfigManager methods passed with file env: {fileName}")
+
+    # Using environment variables
+    elif authMethod == 'env' or 'manual':
+        # run configuration manager
+        ConfigManager.set_env_source(region=region, method=authMethod, fileName=fileName, token_name=refreshToken_name, token=key)
+        logger.debug(f"ConfigManager methods passed with {authMethod} method")
+
+    # Alert of missing variables
+    else:
+        # List to hold the names of empty variables
+        empty_variables = []
+
+        # Check each variable and add the name to the list if it is empty
+        if not accessToken:
+            empty_variables.append("Access Token")
+        if not tokenExpiration:
+            empty_variables.append("token Expiration")
+        if not cloudURL:
+            empty_variables.append("Cloud URL")
+
+        # Create a message based on which variables are empty
+        if empty_variables:
+            # Join the names of the empty variables into a comma-separated string
+            empty_vars_str = ", ".join(empty_variables)
+            logger.error(f"Missing variables: {empty_vars_str}.")
+            raise ValueError(f"The following variables are empty: {empty_vars_str}.")

hdforce-1.0.0/hdforce/GetAthletes.py

@@ -0,0 +1,124 @@
+# Dependencies -----
+import requests
+import os
+import datetime
+import pandas as pd
+# Package imports
+from .AuthManager import AuthManager
+from .utils import ConfigManager
+from .LoggerConfig import LoggerConfig
+
+# Get a logger specific to this module
+logger = LoggerConfig.get_logger(__name__)
+
+# -------------------- #
+# Get Athletes
+
+
+def GetAthletes(inactive: bool = False) -> pd.DataFrame:
+    """Get the athlete information from an account.
+
+    Parameters
+    ----------
+    inactive : bool, optional
+        A boolean that specifies whether to include inactive athletes in the results. Default is False, meaning by default inactive athletes are not included.
+
+    Returns
+    -------
+    pd.DataFrame
+        A Pandas DataFrame containing the athletes' information, with columns:
+        - id: Athlete's unique identifier.
+        - names: Athlete's given full name.
+        - teams: A nested list of athlete's team ids as strings.
+        - groups: A nested list of athlete's group ids as strings.
+        - active: Boolean indicating if the athlete's profile is active (not archived).
+        - external: Columns dynamically created for each external attribute associated with the athletes. (example = external.ExternalId: value)
+
+    Raises
+    ------
+    Exception
+        If the HTTP response status is not 200, indicating an unsuccessful API request, or if there is a failure in parsing the JSON response.
+    """
+    # Retrieve Access Token and check expiration
+    a_token = ConfigManager.get_env_variable("ACCESS_TOKEN")
+    tokenExp = int(ConfigManager.get_env_variable("TOKEN_EXPIRATION"))
+    logger.debug(f"Access Token retrieved. expires {datetime.datetime.fromtimestamp(tokenExp)}")
+
+    # get current time in timestamp
+    now = datetime.datetime.now()
+    nowtime = datetime.datetime.timestamp(now)
+    if nowtime < tokenExp:
+        logger.debug(f"Access Token valid through: {datetime.datetime.fromtimestamp(tokenExp)}")
+
+    # Validate refresh token and expiration
+    if a_token is None:
+        logger.error("No Access Token found.")
+        raise Exception("No Access Token found.")
+    elif int(nowtime) >= tokenExp:
+        logger.debug(f"Token Expired: {datetime.datetime.fromtimestamp(tokenExp)}")
+        # authenticate
+        try:
+            AuthManager(
+                region=ConfigManager.region,
+                authMethod=ConfigManager.env_method,
+                refreshToken_name=ConfigManager.token_name,
+                refreshToken=ConfigManager.refresh_token,
+                env_file_name=ConfigManager.file_name
+            )
+            # Retrieve Access Token and check expiration
+            a_token = ConfigManager.get_env_variable("ACCESS_TOKEN")
+            logger.debug("New ACCESS_TOKEN retrieved")
+            tokenExp = int(ConfigManager.get_env_variable("TOKEN_EXPIRATION"))
+            logger.debug("TOKEN_EXPIRATION retrieved")
+            if a_token is None:
+                logger.error("No Access Token found.")
+                raise Exception("No Access Token found.")
+            elif int(nowtime) >= tokenExp:
+                logger.debug(f"Token Expired: {datetime.datetime.fromtimestamp(tokenExp)}")
+                raise Exception("Token expired")
+            else:
+                logger.debug(f"New Access Token valid through: {datetime.datetime.fromtimestamp(tokenExp)}")
+                pass
+        except ValueError:
+            logger.error("Failed to authenticate. Try AuthManager")
+            raise Exception("Failed to authenticate. Try AuthManage")
+    else:
+        logger.debug(f"New Access Token valid through: {datetime.datetime.fromtimestamp(tokenExp)}")
+
+    # API Cloud URL
+    url_cloud = os.getenv("CLOUD_URL")
+
+    # Create URL for request
+    url = f"{url_cloud}/athletes?inactive={inactive}"
+
+    # GET Request
+    headers = {"Authorization": f"Bearer {a_token}"}
+
+    # Create Response
+    response = requests.get(url, headers=headers)
+    if inactive:
+        logger.debug("GET Request: Athletes (inactive = true)")
+    else:
+        logger.debug("GET Request: Athletes (inactive = false)")
+
+    # Response Handling
+    # If Error show error
+    if response.status_code != 200:
+        logger.error(f"Error {response.status_code}: {response.reason}")
+        raise Exception(f"Error {response.status_code}: {response.reason}")
+
+    # If successful
+    try:
+        data = response.json()['data']
+        df = pd.json_normalize(data, meta=['count'], errors='ignore')
+
+        # Setting attributes
+        df.attrs['Count'] = int(len(df.index))
+        count = str(len(df.index))
+        logger.info(f"Request successful. Athletes returned: {count}")
+        return df
+
+    # Bad parse or none returned
+    except ValueError:
+        logger.error("Failed to parse JSON response or no data returned.")
+        raise Exception("Failed to parse JSON response or no data returned.")