| Name | hyperate JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | https://hyperate.io/ |
| Summary | Python client for the HypeRate WebSocket API |
| upload_time | 2025-10-11 20:21:34 |
| maintainer | None |
| docs_url | None |
| author | Serpensin |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Official HypeRate Python Bindings
[](https://github.com/Serpensin/HypeRate-Python/actions/workflows/code-quality.yml)
[](https://github.com/Serpensin/HypeRate-Python/actions/workflows/tests.yml)
[](https://codecov.io/gh/Serpensin/HypeRate-Python)\
[](https://github.com/Serpensin/HypeRate-Python)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/hyperate)
A Python client library for connecting to the HypeRate WebSocket API to receive real-time heartbeat and clip data.
## Features
- **Real-time heartbeat monitoring** - Subscribe to live heart rate data from HypeRate devices
- **Clip notifications** - Receive notifications when clips are created
- **Async/await support** - Built with asyncio for efficient WebSocket handling
- **Event-driven architecture** - Register handlers for different event types
- **Type hints** - Full type annotation support for better IDE integration
- **Comprehensive logging** - Built-in logging with configurable levels
- **Error handling** - Robust error handling and connection management
## Supported Python Versions
This library supports and is tested on:
- Python 3.8
- Python 3.9
- Python 3.10
- Python 3.11
- Python 3.12
- Python 3.13
- Python 3.14
## Installation
```bash
pip install hyperate
```
## Quick Start
```python
import asyncio
import hyperate
async def main():
# Initialize and connect to HypeRate
client = hyperate.HypeRate("your_api_token_here")
await client.connect()
# Define and register event handlers
def on_heartbeat(data):
print(f"Heartbeat received: {data['hr']} BPM")
def on_connected():
print("Connected to HypeRate!")
def on_clip(data):
print(f"New clip: {data['twitch_slug']}")
client.on('heartbeat', on_heartbeat)
client.on('connected', on_connected) # Note: this fires after connection is already established
client.on('clip', on_clip)
# Subscribe to a device's heartbeat data
await client.join_heartbeat_channel("internal-testing") # Use "internal-testing" for testing
# Keep the connection alive
try:
while True:
await asyncio.sleep(1)
except KeyboardInterrupt:
print("Exiting...")
finally:
await client.disconnect()
# Run the client
if __name__ == "__main__":
asyncio.run(main())
```
### Alternative Quick Start (Lambda Style)
```python
import asyncio
from hyperate import HypeRate
async def main():
client = HypeRate("your_api_token_here")
await client.connect()
# Register handlers with lambda functions
client.on('heartbeat', lambda data: print(f"❤️ {data['hr']} BPM"))
client.on('clip', lambda data: print(f"🎬 Clip: {data['twitch_slug']}"))
await client.join_heartbeat_channel("internal-testing")
try:
while True:
await asyncio.sleep(1)
except KeyboardInterrupt:
pass
finally:
await client.disconnect()
asyncio.run(main())
```
## API Documentation
### HypeRate Class
#### Constructor
```python
HypeRate(api_token: str, base_url: str = "wss://app.hyperate.io/socket/websocket", logger: Optional[logging.Logger] = None)
```
#### Methods
- `connect()` - Connect to the HypeRate WebSocket
- `disconnect()` - Disconnect from the WebSocket
- `join_heartbeat_channel(device_id)` - Subscribe to heartbeat data for a device
- `leave_heartbeat_channel(device_id)` - Unsubscribe from heartbeat data
- `join_clips_channel(device_id)` - Subscribe to clip notifications for a device
- `leave_clips_channel(device_id)` - Unsubscribe from clip notifications
- `on(event, handler)` - Register an event handler
#### Events
- `connected` - Fired when connected to HypeRate
- `disconnected` - Fired when disconnected from HypeRate
- `heartbeat` - Fired when heartbeat data is received
- `clip` - Fired when clip data is received
- `channel_joined` - Fired when a channel is successfully joined
- `channel_left` - Fired when a channel is successfully left
#### Usage Notes
- Connect to HypeRate first with `await client.connect()` before registering handlers
- Use `"internal-testing"` as device ID for testing purposes
- Event handlers registered after connection won't receive the initial `connected` event
- Use `while True:` for the main loop as the client manages the connection state internally
### Device Class
Utility class for device ID validation and extraction.
#### Methods
- `is_valid_device_id(device_id)` - Check if a device ID is valid
- `extract_device_id(input_str)` - Extract device ID from URL or string
## Development
### Setting up the development environment
1. Clone the repository
2. Install development dependencies:
```bash
pip install -r .\Tests\test_requirements.txt
```
3. Install the package in development mode:
```bash
pip install -e .
```
### Running Tests
Use the comprehensive test runner:
```bash
# Run all tests
python Tests/run_tests.py --all
# Run specific test types
python Tests/run_tests.py --unit # Unit tests only
python Tests/run_tests.py --integration # Mocked scenario tests
python Tests/run_tests.py --real-integration --token=your_token # Real API integration
python Tests/run_tests.py --performance # Performance tests
# Run with coverage
python Tests/run_tests.py --coverage
# Run code quality checks
python Tests/run_tests.py --lint
```
#### Real Integration Tests
To run tests against the actual HypeRate API, provide your API token via command line:
```bash
# Using pytest (recommended)
python -m pytest Tests/test_real_integration.py --token=your_actual_api_token_here
# Using direct script execution
python Tests/test_real_integration.py --token=your_actual_api_token_here
# Using the test runner with token
python Tests/run_tests.py --real-integration --token=your_actual_api_token_here
```
### Code Quality
This project maintains high code quality standards:
- **Code Quality Checks**: PyLint (10.0/10.0), Mypy (strict mode), and Flake8 style checking
- **Test Coverage**: Minimum 85% code coverage required
- **Comprehensive Testing**: Unit, integration, and performance tests
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass and code quality checks pass
6. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [HypeRate Website](https://hyperate.io/)
- [Documentation](https://github.com/Serpensin/HypeRate-Python#readme)
- [PyPI Package](https://pypi.org/project/hyperate/)
- [GitHub Repository](https://github.com/Serpensin/HypeRate-Python)
Raw data
{
"_id": null,
"home_page": "https://hyperate.io/",
"name": "hyperate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Serpensin",
"author_email": "serpensin@serpensin.com",
"download_url": "https://files.pythonhosted.org/packages/f4/cd/6843331c1080e1d0ff24488393410b22701bba97240190bac2e8afb4572e/hyperate-1.0.1.tar.gz",
"platform": null,
"description": "\ufeff# Official HypeRate Python Bindings\n\n[](https://github.com/Serpensin/HypeRate-Python/actions/workflows/code-quality.yml)\n[](https://github.com/Serpensin/HypeRate-Python/actions/workflows/tests.yml)\n[](https://codecov.io/gh/Serpensin/HypeRate-Python)\\\n[](https://github.com/Serpensin/HypeRate-Python)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/hyperate)\n\nA Python client library for connecting to the HypeRate WebSocket API to receive real-time heartbeat and clip data.\n\n## Features\n\n- **Real-time heartbeat monitoring** - Subscribe to live heart rate data from HypeRate devices\n- **Clip notifications** - Receive notifications when clips are created\n- **Async/await support** - Built with asyncio for efficient WebSocket handling\n- **Event-driven architecture** - Register handlers for different event types\n- **Type hints** - Full type annotation support for better IDE integration\n- **Comprehensive logging** - Built-in logging with configurable levels\n- **Error handling** - Robust error handling and connection management\n\n## Supported Python Versions\n\nThis library supports and is tested on:\n- Python 3.8\n- Python 3.9\n- Python 3.10\n- Python 3.11\n- Python 3.12\n- Python 3.13\n- Python 3.14\n\n## Installation\n\n```bash\npip install hyperate\n```\n\n## Quick Start\n\n```python\nimport asyncio\nimport hyperate\n\nasync def main():\n # Initialize and connect to HypeRate\n client = hyperate.HypeRate(\"your_api_token_here\")\n await client.connect()\n\n # Define and register event handlers\n def on_heartbeat(data):\n print(f\"Heartbeat received: {data['hr']} BPM\")\n\n def on_connected():\n print(\"Connected to HypeRate!\")\n\n def on_clip(data):\n print(f\"New clip: {data['twitch_slug']}\")\n\n client.on('heartbeat', on_heartbeat)\n client.on('connected', on_connected) # Note: this fires after connection is already established\n client.on('clip', on_clip)\n\n # Subscribe to a device's heartbeat data\n await client.join_heartbeat_channel(\"internal-testing\") # Use \"internal-testing\" for testing\n\n # Keep the connection alive\n try:\n while True:\n await asyncio.sleep(1)\n except KeyboardInterrupt:\n print(\"Exiting...\")\n finally:\n await client.disconnect()\n\n# Run the client\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### Alternative Quick Start (Lambda Style)\n\n```python\nimport asyncio\nfrom hyperate import HypeRate\n\nasync def main():\n client = HypeRate(\"your_api_token_here\")\n await client.connect()\n\n # Register handlers with lambda functions\n client.on('heartbeat', lambda data: print(f\"\u2764\ufe0f {data['hr']} BPM\"))\n client.on('clip', lambda data: print(f\"\ud83c\udfac Clip: {data['twitch_slug']}\"))\n\n await client.join_heartbeat_channel(\"internal-testing\")\n\n try:\n while True:\n await asyncio.sleep(1)\n except KeyboardInterrupt:\n pass\n finally:\n await client.disconnect()\n\nasyncio.run(main())\n```\n\n## API Documentation\n\n### HypeRate Class\n\n#### Constructor\n```python\nHypeRate(api_token: str, base_url: str = \"wss://app.hyperate.io/socket/websocket\", logger: Optional[logging.Logger] = None)\n```\n\n#### Methods\n- `connect()` - Connect to the HypeRate WebSocket\n- `disconnect()` - Disconnect from the WebSocket\n- `join_heartbeat_channel(device_id)` - Subscribe to heartbeat data for a device\n- `leave_heartbeat_channel(device_id)` - Unsubscribe from heartbeat data\n- `join_clips_channel(device_id)` - Subscribe to clip notifications for a device\n- `leave_clips_channel(device_id)` - Unsubscribe from clip notifications\n- `on(event, handler)` - Register an event handler\n\n#### Events\n- `connected` - Fired when connected to HypeRate\n- `disconnected` - Fired when disconnected from HypeRate\n- `heartbeat` - Fired when heartbeat data is received\n- `clip` - Fired when clip data is received\n- `channel_joined` - Fired when a channel is successfully joined\n- `channel_left` - Fired when a channel is successfully left\n\n#### Usage Notes\n- Connect to HypeRate first with `await client.connect()` before registering handlers\n- Use `\"internal-testing\"` as device ID for testing purposes\n- Event handlers registered after connection won't receive the initial `connected` event\n- Use `while True:` for the main loop as the client manages the connection state internally\n\n### Device Class\n\nUtility class for device ID validation and extraction.\n\n#### Methods\n- `is_valid_device_id(device_id)` - Check if a device ID is valid\n- `extract_device_id(input_str)` - Extract device ID from URL or string\n\n## Development\n\n### Setting up the development environment\n\n1. Clone the repository\n2. Install development dependencies:\n ```bash\n pip install -r .\\Tests\\test_requirements.txt\n ```\n3. Install the package in development mode:\n ```bash\n pip install -e .\n ```\n\n### Running Tests\n\nUse the comprehensive test runner:\n\n```bash\n# Run all tests\npython Tests/run_tests.py --all\n\n# Run specific test types\npython Tests/run_tests.py --unit # Unit tests only\npython Tests/run_tests.py --integration # Mocked scenario tests\npython Tests/run_tests.py --real-integration --token=your_token # Real API integration\npython Tests/run_tests.py --performance # Performance tests\n\n# Run with coverage\npython Tests/run_tests.py --coverage\n\n# Run code quality checks\npython Tests/run_tests.py --lint\n```\n\n#### Real Integration Tests\n\nTo run tests against the actual HypeRate API, provide your API token via command line:\n\n```bash\n# Using pytest (recommended)\npython -m pytest Tests/test_real_integration.py --token=your_actual_api_token_here\n\n# Using direct script execution\npython Tests/test_real_integration.py --token=your_actual_api_token_here\n\n# Using the test runner with token\npython Tests/run_tests.py --real-integration --token=your_actual_api_token_here\n```\n\n### Code Quality\n\nThis project maintains high code quality standards:\n\n- **Code Quality Checks**: PyLint (10.0/10.0), Mypy (strict mode), and Flake8 style checking\n- **Test Coverage**: Minimum 85% code coverage required\n- **Comprehensive Testing**: Unit, integration, and performance tests\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass and code quality checks pass\n6. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [HypeRate Website](https://hyperate.io/)\n- [Documentation](https://github.com/Serpensin/HypeRate-Python#readme)\n- [PyPI Package](https://pypi.org/project/hyperate/)\n- [GitHub Repository](https://github.com/Serpensin/HypeRate-Python)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for the HypeRate WebSocket API",
"version": "1.0.1",
"project_urls": {
"Bug Reports": "https://github.com/Serpensin/HypeRate-Python/issues",
"Documentation": "https://github.com/Serpensin/HypeRate-Python#readme",
"Homepage": "https://hyperate.io/",
"Source": "https://github.com/Serpensin/HypeRate-Python"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6886f4fab8f841fa7bd4d57de3db007f4b3e22f05a2c9131d8b810d19ca643de",
"md5": "4cbfa42192ab6f517dadb580cf5534b0",
"sha256": "2723f0e2eb3289d0b7126429240cb7de05d4cdcd122777285af3bd1ddbfed3e4"
},
"downloads": -1,
"filename": "hyperate-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4cbfa42192ab6f517dadb580cf5534b0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10574,
"upload_time": "2025-10-11T20:21:33",
"upload_time_iso_8601": "2025-10-11T20:21:33.044862Z",
"url": "https://files.pythonhosted.org/packages/68/86/f4fab8f841fa7bd4d57de3db007f4b3e22f05a2c9131d8b810d19ca643de/hyperate-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f4cd6843331c1080e1d0ff24488393410b22701bba97240190bac2e8afb4572e",
"md5": "f23e774e1e31b7f583883bc5b9f433f2",
"sha256": "96511256e870d3c09589187f12cadb82e8365be9420c82b80e9511bc5e3173fa"
},
"downloads": -1,
"filename": "hyperate-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f23e774e1e31b7f583883bc5b9f433f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12840,
"upload_time": "2025-10-11T20:21:34",
"upload_time_iso_8601": "2025-10-11T20:21:34.849275Z",
"url": "https://files.pythonhosted.org/packages/f4/cd/6843331c1080e1d0ff24488393410b22701bba97240190bac2e8afb4572e/hyperate-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 20:21:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Serpensin",
"github_project": "HypeRate-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hyperate"
}
