valdpy 0.1.0__tar.gz

valdpy-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,283 @@
+# Contributing to VALDPY
+
+Thank you for your interest in contributing to VALDPY! This document provides guidelines for contributing to the project.
+
+## Code of Conduct
+
+- Be respectful and professional in all interactions
+- Provide constructive feedback
+- Focus on the issue, not the person
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/Valdpy.git`
+3. Create a virtual environment: `python -m venv venv`
+4. Activate it: `source venv/bin/activate` (or `venv\Scripts\activate` on Windows)
+5. Install development dependencies: `pip install -e ".[dev]"`
+
+## Development Workflow
+
+### Before You Start
+- Check [Issues](https://github.com/dgaytanjenkins/Valdpy/issues) to see if someone is already working on it
+- Create an issue to discuss major changes before starting
+
+### Making Changes
+
+1. Create a feature branch: `git checkout -b feature/your-feature-name`
+2. Make your changes following the code style guidelines below
+3. Add tests for new functionality
+4. Update documentation as needed
+5. Ensure all tests pass: `pytest`
+
+### Code Style
+
+This project uses:
+- **Black** for code formatting (line length: 100)
+- **isort** for import ordering
+- **MyPy** for type hints (where practical)
+- **Flake8** for linting
+
+Format your code before committing:
+```bash
+black valdpy/
+isort valdpy/
+flake8 valdpy/
+```
+
+### Type Hints
+
+Use type hints for function signatures:
+
+```python
+def get_tests(
+    self,
+    date: str | datetime,
+    profile_id: Optional[str] = None
+) -> pd.DataFrame:
+    """Get tests from a specific date."""
+    pass
+```
+
+### Docstring Style
+
+Use NumPy docstring format:
+
+```python
+def my_function(param1: str, param2: int) -> bool:
+    """
+    Short description.
+    
+    Longer description with more details about what
+    the function does and how to use it.
+    
+    Parameters
+    ----------
+    param1 : str
+        Description of param1
+    param2 : int
+        Description of param2
+        
+    Returns
+    -------
+    bool
+        Description of return value
+        
+    Raises
+    ------
+    ValueError
+        Description of when this is raised
+        
+    Examples
+    --------
+    >>> result = my_function("hello", 42)
+    >>> result
+    True
+    """
+    pass
+```
+
+## Testing
+
+### Write Tests
+```python
+# tests/test_auth.py
+import pytest
+from valdpy import ValdAuth
+
+def test_auth_initialization():
+    auth = ValdAuth("client_id", "client_secret")
+    assert auth.client_id == "client_id"
+
+def test_invalid_region():
+    with pytest.raises(ValueError):
+        ValdAuth("id", "secret", region="Invalid")
+```
+
+### Run Tests
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=valdpy
+
+# Run specific test file
+pytest tests/test_auth.py
+
+# Run specific test
+pytest tests/test_auth.py::test_auth_initialization
+```
+
+## Commit Messages
+
+Use clear, descriptive commit messages:
+
+```
+Add: New feature description
+Fix: Bug fix description
+Refactor: Code refactoring description
+Docs: Documentation update description
+Tests: Test update description
+
+[OPTIONAL: Longer description explaining why this change
+was necessary, what problem it solves, etc.]
+```
+
+Example:
+```
+Add: ForceFrame API data pagination support
+
+Implements automatic pagination for ForceFrame API
+to handle datasets larger than the single request limit.
+Adds get_tests() method with automatic continuation
+token handling.
+```
+
+## Pull Request Process
+
+1. Update [CHANGELOG.md](CHANGELOG.md) with your changes
+2. Ensure all tests pass: `pytest`
+3. Update documentation if needed
+4. Submit PR with clear description of changes
+5. Respond to review feedback promptly
+
+### PR Title Format
+```
+[Type]: Brief description
+
+Types: Feature, Fix, Refactor, Docs, Tests, CI
+Example: [Feature]: Add automatic pagination for ForceFrame API
+```
+
+### PR Description Template
+```markdown
+## Description
+Brief explanation of what this PR does.
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Related Issues
+Fixes #123
+
+## Testing
+Describe how you tested these changes.
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] Code formatted with Black
+- [ ] All tests passing
+```
+
+## Reporting Bugs
+
+Use the [Issue Template](https://github.com/dgaytanjenkins/Valdpy/issues/new) and include:
+
+1. **Description**: What is the bug?
+2. **Expected Behavior**: What should happen?
+3. **Actual Behavior**: What actually happens?
+4. **Steps to Reproduce**: How can someone reproduce this?
+5. **Environment**: Python version, OS, VALDPY version
+6. **Error Message**: Full traceback if applicable
+
+Example:
+```markdown
+## Description
+API returns empty DataFrame when filtering by profile_id
+
+## Expected Behavior
+Should return DataFrame with tests for that profile
+
+## Actual Behavior
+Returns empty DataFrame with message "No data found"
+
+## Steps to Reproduce
+1. Initialize ForeDecksAPI
+2. Call get_tests_info('01/01/2025', profile_id='123')
+3. Observe empty result
+
+## Environment
+- Python 3.9
+- VALDPY 0.1.0
+- Windows 10
+```
+
+## Feature Requests
+
+Suggest new features by [creating an issue](https://github.com/dgaytanjenkins/Valdpy/issues) with:
+
+1. **Use Case**: Why is this feature needed?
+2. **Proposed Solution**: How should it work?
+3. **Alternatives**: Are there other ways to solve this?
+
+## Documentation
+
+Contributions to documentation are welcome:
+
+- Fix typos and clarify explanations
+- Add examples and use cases
+- Improve API documentation
+- Create tutorials
+
+Documentation files:
+- Main docs: `docs/*.md`
+- API reference: `docs/api_reference/*.md`
+- Examples: `examples/*.ipynb`
+
+## Project Structure
+
+```
+valdpy/
+├── api/                  # API client implementations
+├── utils.py              # Utility functions
+└── __init__.py          # Package initialization
+
+docs/                     # Documentation
+examples/                 # Jupyter notebook examples
+tests/                    # Test suite
+
+setup.py
+pyproject.toml
+README.md
+LICENSE
+```
+
+## Questions?
+
+- Check [FAQ](docs/faq.md)
+- Open a [Discussion](https://github.com/dgaytanjenkins/Valdpy/discussions)
+- Email: dgaytanj@uoregon.edu
+
+## Recognition
+
+All contributors will be recognized in:
+- CHANGELOG.md
+- README.md (Contributors section)
+- GitHub contributors page
+
+Thank you for contributing to VALDPY! 🎉

valdpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danny Gaytan-Jenkins
+
+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.

valdpy-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include requirements.txt
+recursive-include docs *.md
+recursive-include examples *.ipynb

valdpy-0.1.0/PKG-INFO

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: valdpy
+Version: 0.1.0
+Summary: Python SDK for VALD Performance APIs
+Home-page: https://github.com/dgaytanjenkins/Valdpy
+Author: Danny Gaytan-Jenkins
+Author-email: Danny Gaytan-Jenkins <dgaytanj@uoregon.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/dgaytanjenkins/Valdpy
+Project-URL: Bug Reports, https://github.com/dgaytanjenkins/Valdpy/issues
+Project-URL: Documentation, https://github.com/dgaytanjenkins/Valdpy#readme
+Project-URL: Source Code, https://github.com/dgaytanjenkins/Valdpy
+Keywords: vald,performance,forcedecks,dynamo,testing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pandas>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=4.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: sphinx>=4.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# VALDPY - Python SDK for VALD Performance APIs
+
+A comprehensive Python wrapper for **VALD Performance** APIs, providing easy access to data from ForceDecks, Dynamo, ForceFrame, NordBord, and SmartSpeed testing platforms.
+
+![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Status](https://img.shields.io/badge/status-alpha-yellow)
+
+## Overview
+
+VALDPY simplifies integration with VALD Performance's test data APIs. Whether you're analyzing jump performance, force production, sprint times, or strength metrics, this SDK provides a clean, Pythonic interface for authentication, data retrieval, and processing.
+
+Built on the [VALD API Documentation](https://support.vald.com/hc/en-au/articles/23415335574553-How-to-integrate-with-VALD-APIs), this package handles:
+- OAuth 2.0 authentication
+- Multi-region API access (USA, Australia, Europe)
+- Test data retrieval across all VALD platforms
+- Automatic pagination for large datasets
+- Data parsing into pandas DataFrames
+
+## Installation
+
+### From PyPI (Coming Soon)
+```bash
+pip install valdpy
+```
+
+### From Source
+```bash
+git clone https://github.com/dgaytanjenkins/Valdpy.git
+cd Valdpy
+pip install -e .
+```
+
+### Development Installation
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+### 1. Setup Credentials
+
+Create a JSON credentials file (`vald_api_cred.txt`):
+```json
+{
+    "client_id": "your_client_id",
+    "client_secret": "your_client_secret",
+    "tenant_id": "your_tenant_id"
+}
+```
+
+### 2. Basic Usage
+
+```python
+from valdpy import ValdAuth, ForeDecksAPI
+from valdpy.utils import read_credentials
+
+# Load credentials
+creds = read_credentials('vald_api_cred.txt')
+
+# Initialize authentication
+auth = ValdAuth(
+    client_id=creds['client_id'],
+    client_secret=creds['client_secret'],
+    tenant_id=creds['tenant_id'],
+    region='USA'
+)
+
+# Get access token
+auth.get_token()
+
+# Initialize ForceDecks API
+fd = ForeDecksAPI(
+    tenant_id=auth.tenant_id,
+    header=auth.header,
+    region='USA'
+)
+
+# Retrieve tests from a specific date
+tests_df = fd.get_tests_info('01/01/2025')
+print(tests_df.head())
+
+# Get results for a specific test
+test_id = tests_df['id'].iloc[0]
+results_df = fd.get_test_results(test_id)
+```
+
+## Supported Platforms
+
+### ForceDecks
+Force plate testing for power, landing mechanics, and injury risk assessment.
+
+```python
+from valdpy import ForeDecksAPI
+
+fd = ForeDecksAPI(tenant_id, header, region='USA')
+tests_df = fd.get_tests_info('01/01/2025')
+results_df = fd.get_test_results(test_id)
+force_trace = fd.get_force_trace(test_id)  # Raw force data
+recording_details = fd.get_recording_details(test_id)
+```
+
+### Dynamo
+Jump and power testing platform for assessing lower body power production.
+
+```python
+from valdpy import DynamoAPI
+
+dynamo = DynamoAPI(tenant_id, header)
+tests_df = dynamo.get_tests('01/01/2025', '31/01/2025')
+results_df = dynamo.get_test_results(test_id)
+```
+
+### ForceFrame
+Advanced force measurement system for detailed biomechanical analysis.
+
+```python
+from valdpy import ForceFrameAPI
+
+ff = ForceFrameAPI(tenant_id, header)
+tests_df = ff.get_tests_info('01/01/2025')
+results_df = ff.get_test_results(test_id)
+```
+
+### NordBord
+Leg press strength testing platform for lower body strength assessment.
+
+```python
+from valdpy import NordBordAPI
+
+nb = NordBordAPI(tenant_id, header)
+tests_df = nb.get_tests_info('01/01/2025')
+results_df = nb.get_test_results(test_id)
+```
+
+### SmartSpeed
+Timing gate system for sprint, agility, and acceleration testing.
+
+```python
+from valdpy import SmartSpeedAPI
+
+ss = SmartSpeedAPI(tenant_id, header)
+tests_df = ss.get_tests_info('01/01/2025')
+results_df = ss.get_test_results(test_id)
+```
+
+## API Reference
+
+### ValdAuth
+Main authentication class for VALD APIs.
+
+**Methods:**
+- `get_token()` - Obtain OAuth 2.0 access token
+- `get_all_tenants()` - List all accessible tenants
+- `get_tenant_info(tenant_id)` - Get specific tenant details
+- `get_tenant_categories()` - List categories (e.g., Team, Injured)
+- `get_tenant_groups()` - List all groups in tenant
+- `get_group_profiles(group_name, category_name)` - List profiles in a group
+- `assign_groups(profile_id, group_ids)` - Assign groups to a profile
+
+### Utility Functions
+Located in `valdpy.utils`:
+
+- `read_credentials(filepath)` - Load credentials from JSON file
+- `convert_ticks_to_datetime(ticks)` - Convert .NET ticks to datetime
+- `format_date_to_iso8601(date)` - Format datetime to ISO 8601
+- `get_call()` - Make GET requests to API
+- `post_call()` - Make POST requests to API
+- `put_call()` - Make PUT requests to API
+
+## Examples
+
+Complete example notebooks are available in the `examples/` directory:
+
+- [ForceDecks Example](examples/Vald_forceDecks_Example.ipynb)
+- [Dynamo Example](examples/Vald_Dynamo_Example.ipynb)
+- [ForceFrame Example](examples/Vald_forceFrame_Example.ipynb)
+- [NordBord Example](examples/Vald_Nordbord_Example.ipynb)
+- [SmartSpeed Example](examples/Vald_Smartspeed_Example.ipynb)
+
+## Data Processing Examples
+
+### Filter tests by date range
+```python
+from datetime import datetime
+import pandas as pd
+
+# Get tests for January 2025
+start = '01/01/2025'
+end = '31/01/2025'
+tests_df = dynamo.get_tests(start, end)
+
+# Filter by specific profile
+specific_profile = tests_df[tests_df['profileId'] == 'profile_123']
+```
+
+### Combine results across multiple tests
+```python
+all_results = []
+
+for test_id in tests_df['id'].head(10):
+    results = fd.get_test_results(test_id)
+    all_results.append(results)
+
+combined_df = pd.concat(all_results, ignore_index=True)
+```
+
+### Export to CSV
+```python
+tests_df.to_csv('forcedecks_tests.csv', index=False)
+results_df.to_csv('test_results.csv', index=False)
+```
+
+## Regional Endpoints
+
+VALDPY supports three regional endpoints:
+
+- **USA**: Primary US endpoint
+- **Australia**: AU/NZ endpoint
+- **Europe**: European endpoint
+
+Specify region when initializing clients:
+
+```python
+auth = ValdAuth(..., region='Australia')
+fd = ForeDecksAPI(..., region='Europe')
+```
+
+## Configuration
+
+Environment variables can override defaults:
+
+```bash
+export VALD_REGION=USA
+export VALD_CREDENTIALS_PATH=/path/to/credentials.json
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=valdpy
+```
+
+## Development
+
+### Project Structure
+```
+valdpy/
+├── api/                    # API client implementations
+│   ├── __init__.py
+│   ├── auth.py            # Authentication
+│   ├── dynamo.py          # Dynamo API
+│   ├── forcedecks.py      # ForceDecks API
+│   ├── forceframe.py      # ForceFrame API
+│   ├── nordbord.py        # NordBord API
+│   └── smartspeed.py      # SmartSpeed API
+├── utils.py               # Utility functions
+└── __init__.py            # Package initialization
+
+examples/                  # Jupyter notebook examples
+docs/                      # Documentation
+tests/                     # Test suite
+```
+
+### Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Code Style
+
+This project uses:
+- **Black** for code formatting
+- **isort** for import sorting
+- **MyPy** for type checking
+- **Flake8** for linting
+
+Run formatters:
+```bash
+black valdpy/
+isort valdpy/
+```
+
+## Documentation
+
+Full API documentation is available in [docs/](docs/).
+
+### Building Documentation Locally
+```bash
+pip install -e ".[docs]"
+cd docs
+make html
+open _build/html/index.html
+```
+
+## Troubleshooting
+
+### Authentication Fails
+- Verify credentials in `vald_api_cred.txt`
+- Check that client credentials have appropriate permissions
+- Ensure credentials are valid and not expired
+
+### No Data Returned
+- Verify date range (max 180 days for some endpoints)
+- Check that tenant_id and profile_id are correct
+- Ensure modified dates are in ISO 8601 format
+
+### Network Errors
+- Verify API region is correct
+- Check internet connectivity
+- Review VALD API status page
+
+## Changelog
+
+### Version 0.1.0 (2025-05-25)
+- Initial release
+- Support for all five VALD platforms
+- OAuth 2.0 authentication
+- Multi-region support
+- Pandas DataFrame outputs
+
+## License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
+
+## Citation
+
+If you use VALDPY in your research, please cite:
+
+```bibtex
+@software{gaytan_jenkins_2025_valdpy,
+  title={VALDPY: Python SDK for VALD Performance APIs},
+  author={Gaytan-Jenkins, Danny},
+  year={2025},
+  url={https://github.com/dgaytanjenkins/Valdpy}
+}
+```
+
+## Support
+
+- 📖 [VALD API Documentation](https://support.vald.com/hc/en-au/articles/23415335574553-How-to-integrate-with-VALD-APIs)
+- 🐛 [Report Issues](https://github.com/dgaytanjenkins/Valdpy/issues)
+- 💬 [Discussions](https://github.com/dgaytanjenkins/Valdpy/discussions)
+
+## Disclaimer
+
+This package is provided as-is and is not officially affiliated with VALD Performance. Users are responsible for complying with VALD's API terms of service and any applicable licensing agreements.
+
+---
+
+**Built by:** Danny Gaytan-Jenkins  
+**Email:** dgaytanj@uoregon.edu  
+**Last Updated:** May 25, 2025