HawkinPy v1.1.1 w/ Athlete Creation & GetTests changes

.github/workflows/push-test.yml

@@ -45,7 +45,7 @@ jobs:
 
     - name: Install Poetry
       if: steps.cache.outputs.cache-hit != 'true'
-      run:
+      run: |
         python -m pip install --upgrade pip
         pip install poetry
 

.github/workflows/python-docpage.yml

@@ -2,16 +2,18 @@
 name: Publish Docs Page
 
 on:
-  release:
-    types: [published]
+  pull_request:
+    branches:
+      - main
+    types: [closed]
 
 permissions:
   contents: write
 
 jobs:
-
   deploy:
     runs-on: ubuntu-latest
+    if: github.event.pull_request.merged == true
     steps:
     - name: Checkout Code
       uses: actions/checkout@v4
@@ -22,16 +24,16 @@ jobs:
       with:
         python-version: '3.x'
 
-    - name:
+    - name: Cache dependencies
       uses: actions/cache@v4
       with:
         key: ${{ github.ref }}
         path: .cache
 
-    - name: install mkdocs
-      run:
+    - name: Install mkdocs
+      run: |
         pip install mkdocs
         pip install mkdocs-material
 
-    - name: deploy-page
+    - name: Deploy page
       run: mkdocs gh-deploy --force

.github/workflows/tag-release-publish.yml

@@ -18,7 +18,12 @@ jobs:
     - name: Checkout Code
       uses: actions/checkout@v4
 
+    - name: Fix Git ownership issue
+      run: |
+        git config --global --add safe.directory /github/workspace
+
     - name: Build and publish to pypi
       uses: JRubics/[email protected]
       with:
         pypi_token: ${{ secrets.PYPI_TOKEN }}
+        plugins: "poetry-dynamic-versioning[plugin]"

.gitignore

@@ -31,6 +31,7 @@ MANIFEST
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 *.manifest
 *.spec
+get-pip.py
 
 # Installer logs
 pip-log.txt

README.md

@@ -1,11 +1,11 @@
-# HDFORCE <img src="docs/img/hdlogo_sm.png" align="right" alt="" width="120" />
+# HDFORCE v1.1.1 <img src="docs/img/hdlogo_sm.png" align="right" alt="" width="120" />
 
 **Get your data from the Hawkin Dynamics API**
 
 <!-- badges: start -->
-![Static Badge](https://img.shields.io/badge/release-v1.0.1-blue)
+![Static Badge](https://img.shields.io/badge/release-v1.1.0-blue)
 ![Static Badge](https://img.shields.io/badge/OS_and_Py_Version_Tests-pass-success)
-![Static Badge](https://img.shields.io/badge/last_commit-2024--05--06-blue)
+![Static Badge](https://img.shields.io/badge/last_commit-2024--07--30-blue)
 [![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/)

docs/About/changelog.md

@@ -1,5 +1,15 @@
 # Changelogs
 
+## hdforce v1.1.1
+
+* Corrected versioning and documentation
+
+## hdforce v1.1.0
+
+* Additions of CreateAthlete and UpdateAthlete functions
+* Expansion of GetTests function to include 'team', 'group', type', and 'athlete' arguments
+* Deprecation of GetTestsAth, GetTestsType, GetTestsTeam, and GetTestsGroup
+
 ## hdforce v1.0.01
 
 * Initial release of production package

docs/Functions/CreateAthletes.md

@@ -0,0 +1,57 @@
+__`CreateAthletes(athletes: List[NewAthletes])`__
+
+### Description
+Create athletes for your account. Up to 500 at one time.
+
+### Parameters
+`athletes`: (_list_) A list of Athletes with class of `NewAthlete`, which requires a "name". If other parameters are left, they will assume default values.
+
+### Classes
+`NewAthlete`: (_class_) 
+**REQUIRED**
+* name: _str_
+* active: _str_
+*Optional*
+* teams: _list_
+* groups: _list_
+* external: _dict_ {externalName1 : externalValue1, externalName2 : externalValue2}
+
+### Returns
+A list of AthleteResult objects indicating the success or failure of each athlete creation.
+
+* __successful__: list of names of athletes added successfully
+* __failures__: list of athletes that failed in execution, grouped by their reason for failure.
+
+### Raises
+**Exception**
+
+* No Access Token Found.
+* If the HTTP response status is not 200, indicating an unsuccessful API request, or if there is a failure in parsing the JSON response.
+
+
+### Example
+
+``` Python
+from hdforce import CreateAthletes, NewAthlete
+
+# Create list of athletes to add using NewAthlete class
+players = [
+  NewAthlete(name= "New Guy", active=False, teams=[], groups=[], external={"Title": "Younger Brother"}),
+  NewAthlete(name= "Old Guy", active=False, teams=[], groups=[], external={"Title": "Older Brother"})
+]
+
+# Create players
+newRoster = CreateAthletes(athletes = players)
+
+# Print lgCreation Response
+print(newRoster)
+```
+
+_output_
+
+{
+  "successful": ["New Guy", "Old Guy"],
+  "failures": []
+}
+
+

docs/Functions/GetTests.md

@@ -1,4 +1,4 @@
-__`GetTests(from_: int = None, to_: int = None, sync: bool = False, active: bool = True)`__
+__`GetTests(from_: int = None, to_: int = None, sync: bool = False, athleteId: str = None, typeId: str = None, teamId: str = None,groupId: str = None, includeInactive: bool = False)`__
 
 ### Description
 Get all test trials from an account. Allows filtering of results based on time frames, synchronization needs, and the active status of tests.
@@ -10,7 +10,15 @@ __`to_`__: _(int)_ Unix timestamp specifying the end time until which tests shou
 
 __`sync`__: _(bool)_ If True, the function fetches updated and newly created tests to synchronize with the database. Default is False.
 
-__`active`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
+__`athleteId`__: _(str)_ The unique identifier of the athlete whose tests are to be retrieved.
+
+__`typeId`__: _(str)_ The canonical test ID, test type name, or test name abbreviation. Must correspond to known test types.
+
+__`teamId`__: _(str)_ A single team ID, tuple or list of team IDs to receive tests from specific teams.
+
+__`groupId`__: _(str)_ A single group ID, tuple or list of group IDs to receive tests from specific groups.
+
+__`includeInactive`__: _(bool)_ Default to False, where only active tests are returned. If True, all tests including inactive ones are returned.
 
 ### Returns
 A Pandas DataFrame containing details of the test trial, with columns:

docs/Functions/GetTestsAth.md

@@ -1,4 +1,7 @@
-__`GetTestsAth(athleteId: str, from_: int = None, to_: int = None, sync: bool = False, active: bool = True)`__
+__`GetTestsAth(athleteId: str, from_: int = None, to_: int = None, sync: bool = False, includeInactive: bool = False)`__
+
+> As of July 10, 2024 `GetTestsTeam` has been deprecated for the preferred use 
+> of `GetTests`. This function will be fully superseded Jan 01, 2025 12:00:00.
 
 ### Description
 Get test trials only from a specific athlete. Allows filtering of results based on time frames, synchronization needs, and the active status of tests.
@@ -12,7 +15,7 @@ __`to_`__: _(int)_ Unix timestamp specifying the end time until which tests shou
 
 __`sync`__: _(bool)_ If True, the function fetches updated and newly created tests to synchronize with the database. Default is False.
 
-__`active`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
+__`includeInactive`__: _(bool)_ Default to False, where only active tests are returned. If True, all tests including inactive ones are returned.
 
 ### Returns
 A Pandas DataFrame containing details of the test trial, with columns:

docs/Functions/GetTestsGroup.md

@@ -1,4 +1,7 @@
-__`GetTestsGroup(groupId: str, from_: int = None, to_: int = None, sync: bool = False, active: bool = True)`__
+__`GetTestsGroup(groupId: str, from_: int = None, to_: int = None, sync: bool = False, includeInactive: bool = False)`__
+
+> As of July 10, 2024 `GetTestsTeam` has been deprecated for the preferred use 
+> of `GetTests`. This function will be fully superseded Jan 01, 2025 12:00:00.
 
 ### Description
 Get test trials for specified group(s). Allows filtering of results based on time frames, synchronization needs, and the active status of tests.
@@ -12,7 +15,7 @@ __`to_`__: _(int)_ Unix timestamp specifying the end time until which tests shou
 
 __`sync`__: _(bool)_ If True, the function fetches updated and newly created tests to synchronize with the database. Default is False.
 
-__`active`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
+__`includeInactive`__: _(bool)_ Default to False, where only active tests are returned. If True, all tests including inactive ones are returned.
 
 ### Returns
 A Pandas DataFrame containing details of the test trial, with columns:

docs/Functions/GetTestsTeam.md

@@ -1,4 +1,7 @@
-__`GetTestsTeam(teamId: str, from_: int = None, to_: int = None, sync: bool = False, active: bool = True)`__
+__`GetTestsTeam(teamId: str, from_: int = None, to_: int = None, sync: bool = False, includeInactive: bool = False)`__
+
+> As of July 10, 2024 `GetTestsTeam` has been deprecated for the preferred use 
+> of `GetTests`. This function will be fully superseded Jan 01, 2025 12:00:00.
 
 ### Description
 Get test trials for specified team(s). Allows filtering of results based on time frames, synchronization needs, and the active status of tests.
@@ -12,7 +15,7 @@ __`to_`__: _(int)_ Unix timestamp specifying the end time until which tests shou
 
 __`sync`__: _(bool)_ If True, the function fetches updated and newly created tests to synchronize with the database. Default is False.
 
-__`active`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
+__`includeInactive`__: _(bool)_ Default to False, where only active tests are returned. If True, all tests including inactive ones are returned.
 
 ### Returns
 A Pandas DataFrame containing details of the test trial, with columns:

docs/Functions/GetTestsType.md

@@ -1,4 +1,7 @@
-__`GetTestsType(typeId: str, from_: int = None, to_: int = None, sync: bool = False, active: bool = True)`__
+__`GetTestsType(typeId: str, from_: int = None, to_: int = None, sync: bool = False, includeInactive: bool = False)`__
+
+> As of July 10, 2024 `GetTestsTeam` has been deprecated for the preferred use 
+> of `GetTests`. This function will be fully superseded Jan 01, 2025 12:00:00.
 
 ### Description
 Get test trials only from a specific type of test. Allows filtering of results based on time frames, synchronization needs, and the active status of tests.
@@ -26,7 +29,7 @@ __`to_`__: _(int)_ Unix timestamp specifying the end time until which tests shou
 
 __`sync`__: _(bool)_ If True, the function fetches updated and newly created tests to synchronize with the database. Default is False.
 
-__`active`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
+__`includeInactive`__: _(bool)_ If True, only active tests are fetched. If False, all tests including inactive ones are fetched. Default is True.
 
 ### Returns
 A Pandas DataFrame containing details of the test trial, with columns:

docs/Functions/UpdateAthletes.md

@@ -0,0 +1,54 @@
+__`UpdateAthletes(athletes: List[Athletes])`__
+
+### Description
+Update athletes for your account. Up to 500 at one time.
+
+### Parameters
+`athletes`: (_list_) A list of Athletes with class of `Athlete`, which requires an "id", "name", and "active" for eah athlete entered. Any parameters omitted will retain their current values. Except for "external", which will be removed unless explicitly stated during update.
+
+### Classes
+`Athlete`: (_class_) 
+**REQUIRED**
+* id: _str_
+* name: _str_
+* active: _str_
+*Optional*
+* teams: _list_
+* groups: _list_
+* external: _dict_ {externalName1 : externalValue1, externalName2 : externalValue2}
+
+### Returns
+A list of AthleteResult objects indicating the success or failure of each athlete creation.
+
+* __AthleteResult__: Class with athlete name, id, success status, and reason.
+
+### Raises
+**Exception**
+
+* No Access Token Found.
+* If the HTTP response status is not 200, indicating an unsuccessful API request, or if there is a failure in parsing the JSON response.
+
+### Example
+
+``` Python
+from hdforce import UpdateAthletes, Athlete
+
+# Create list of athletes to add using NewAthlete class
+players = [
+  Athlete(id= "N3wGuy$Un1q131D", name= "New Guy", active=False, external={"Title": "Younger Brother"}),
+  Athlete(id= "0ldGuy$Un1q131D", name= "Old Guy", active=False, external={"Title": "Older Brother"})
+]
+
+# Create players
+updates = UpdateAthletes(athletes = players)
+
+# Print lgCreation Response
+print(updates)
+```
+
+_output_
+
+[
+  AthleteResult(name= 'New Guy', id='N3wGuy$Un1q131D', successful=True, reason=None),
+  AthleteResult(name= 'Old Guy', id='0ldGuy$Un1q131D', successful=True, reason=None)
+]

docs/UserGuide/GetData.md

@@ -10,7 +10,7 @@ While the purpose of the package is to help with accessing data specific to your
 
 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` parameter is set to TRUE. The response will be a data frame containing the athletes that match this query.
+* `GetAthletes()` - Get the athletes for an account. Inactive players will only be included if `includeInactive` parameter is set to 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.
@@ -27,13 +27,17 @@ value you will receive every test. This parameter is best suited for bulk export
 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.
+* `includeInactive` = Default to False, where only active tests are returned. If True, all tests including inactive ones are returned.
 
 #### 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).
+> As of July 10, 2024, `GetTestsAth`, `GetTestsType`, `GetTestsTeam`, and `GetTestsGroup` 
+> have been deprecated for the preferred use of `GetTests`. This function will be fully 
+> superseded Jan 01, 2025 12:00:00.
+
+* `GetTests()` - The primary function to call tests is `get_tests`. This is a base request for tests that, as of 2024-07-10, accepts all arguments : 'from', 'to', 'sync', 'includeInactive', 'athleteId', 'testTypeId', 'teamId', and 'groupId'. Using this function, you have complete control of the tests being requested from the cloud. It is important to understand that requests can **NOT** include any combination of 'athleteId', 'testTypeId', 'teamId', or 'groupId'. This will result in and error. Any of these arguments **CAN** be used with 'from', 'to', 'active', and 'sync'.
 * `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.
+* `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.