Python Starter Template

Beginner-friendly plugin template in Python with clear, readable code.

Overview

The Python starter template provides an easy-to-understand foundation for building HyperHQ plugins:

✅ Simple, readable Python syntax
✅ Basic stdin/stdout communication (can be extended with Socket.IO)
✅ Easy debugging with print statements and logs
✅ PyInstaller support for creating executables
✅ Cross-platform compatible

Prerequisites

Python 3.8 or later
pip (Python package installer)
Basic understanding of Python

Quick Start

1. Get the Template

Navigate to the templates directory in your HyperHQ installation:

Terminal
cd "C:\HyperHQ\docs\templates\python-starter"

Or copy the python-starter folder from HyperHQ's docs/templates directory to your development location.

2. Install Dependencies (Optional)

For Socket.IO support, install python-socketio:

Terminal
pip install python-socketio[client]

For building executables:

Terminal
pip install pyinstaller

3. Test Locally

Terminal
# Test with stdin/stdout
echo '{"id":"test","method":"test","data":{}}' | python plugin.py

4. Build Executable

Terminal
pyinstaller --onefile plugin.py

The executable will be in dist/plugin.exe (Windows) or dist/plugin (macOS/Linux).

5. Install in HyperHQ

Terminal
# Create plugin directory
mkdir "C:\HyperHQ\plugins\my-python-plugin"

# Copy files
copy dist\plugin.exe "C:\HyperHQ\plugins\my-python-plugin\"
copy plugin.json "C:\HyperHQ\plugins\my-python-plugin\"

Key Features

Class-Based Structure

Clean, object-oriented design:

plugin.py
class MyPlugin:
    def __init__(self):
        self.settings = {}
        self.plugin_data_dir = os.getenv('PLUGIN_DATA_DIR', './data')
        self.debug_mode = os.getenv('PLUGIN_DEBUG', 'false').lower() == 'true'

    def initialize(self, data):
        self.settings = data.get('settings', {})
        return "initialized"

    def execute(self, data):
        action = data.get('action', 'default')
        # Handle actions...

Debug Logging

Built-in debug logging:

plugin.py
def debug_log(self, message):
    if self.debug_mode:
        with open('plugin-debug.log', 'a') as f:
            f.write(f"DEBUG: {message}\n")

Standard Plugin Methods

All required methods included:

plugin.py
def initialize(self, data):
    """Initialize plugin with settings from HyperHQ"""
    pass

def execute(self, data):
    """Main plugin execution method"""
    pass

def test(self, data):
    """Health check for the plugin"""
    pass

def shutdown(self, data):
    """Clean up before plugin exits"""
    pass

Template Structure

python-starter/
├── plugin.py         # Main plugin code
├── plugin.json       # Plugin manifest
├── requirements.txt  # Python dependencies (optional)
└── build.sh/bat      # Build scripts

Customization

1. Update Plugin Metadata

Edit plugin.json:

plugin.json
{
  "id": "my-python-plugin",
  "name": "My Python Plugin",
  "version": "1.0.0",
  "executable": "plugin.exe"
}

2. Add Custom Actions

plugin.py
def execute(self, data):
    action = data.get('action', 'default')

    if action == 'my_custom_action':
        return self.handle_my_action(data)
    elif action == 'process_data':
        return self.process_data(data)
    else:
        return {"error": f"Unknown action: {action}"}

def handle_my_action(self, data):
    # Your custom logic here
    return {"success": True, "message": "Action completed"}

3. Add Dependencies

Create requirements.txt:

python-socketio[client]==5.10.0
requests==2.31.0

Install:

Terminal
pip install -r requirements.txt

Adding Socket.IO Support

For real-time communication, add Socket.IO:

plugin.py
import socketio

class MyPlugin:
    def __init__(self):
        self.sio = socketio.Client()
        self.plugin_id = os.getenv('HYPERHQ_PLUGIN_ID')
        self.auth_challenge = os.getenv('HYPERHQ_AUTH_CHALLENGE')
        self.session_token = None

    def connect_socketio(self):
        @self.sio.event
        def connect():
            print('Connected to HyperHQ')
            # Authenticate
            self.sio.emit('authenticate', {
                'pluginId': self.plugin_id,
                'challenge': self.auth_challenge
            })

        @self.sio.on('authenticated')
        def on_authenticated(data):
            if data.get('success'):
                self.session_token = data.get('sessionToken')
                print('Authentication successful')

                # Register plugin
                self.sio.emit('plugin:register', {
                    'id': self.plugin_id,
                    'type': 'executable',
                    'capabilities': ['socketio']
                })

        # Connect to HyperHQ
        socket_port = os.getenv('HYPERHQ_SOCKET_PORT', '52789')
        self.sio.connect(f'http://localhost:{socket_port}/plugin')

Building for Production

Basic Build

Terminal
pyinstaller --onefile plugin.py

Optimized Build

Terminal
pyinstaller --onefile \
  --clean \
  --noconfirm \
  --log-level WARN \
  plugin.py

Include Data Files

Terminal
pyinstaller --onefile \
  --add-data "config.json:." \
  --add-data "templates:templates" \
  plugin.py

Performance Tips

Use generators for large datasets
Cache results when appropriate
Async I/O with asyncio for concurrent operations
Profile with cProfile to find bottlenecks

Troubleshooting

"ModuleNotFoundError"

Install missing module:

Terminal
pip install module-name

Or add to PyInstaller:

Terminal
pyinstaller --onefile --hidden-import=module_name plugin.py

Executable too large

Use --exclude-module to remove unused packages:

Terminal
pyinstaller --onefile \
  --exclude-module matplotlib \
  --exclude-module scipy \
  plugin.py

"Failed to execute script"

Test script directly: python plugin.py
Check for missing dependencies
Use --debug all with PyInstaller

Common Patterns

Reading Configuration

plugin.py
import json

def load_config(self):
    config_path = os.path.join(self.plugin_data_dir, 'config.json')
    if os.path.exists(config_path):
        with open(config_path, 'r') as f:
            return json.load(f)
    return {}

HTTP Requests

plugin.py
import requests

def fetch_data(self, url):
    try:
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.RequestException as e:
        self.debug_log(f"Request failed: {e}")
        return None

File Processing

plugin.py
def scan_files(self, directory):
    files = []
    for root, dirs, filenames in os.walk(directory):
        for filename in filenames:
            if filename.endswith('.xml'):
                files.append(os.path.join(root, filename))
    return files

Overview​

Prerequisites​

Quick Start​

1. Get the Template​

2. Install Dependencies (Optional)​

3. Test Locally​

4. Build Executable​

5. Install in HyperHQ​

Key Features​

Class-Based Structure​

Debug Logging​

Standard Plugin Methods​

Template Structure​

Customization​

1. Update Plugin Metadata​

2. Add Custom Actions​

3. Add Dependencies​

Adding Socket.IO Support​

Building for Production​

Basic Build​

Optimized Build​

Include Data Files​

Performance Tips​

Troubleshooting​

"ModuleNotFoundError"​

Executable too large​

"Failed to execute script"​

Common Patterns​

Reading Configuration​

HTTP Requests​

File Processing​

Learn More​