Appearance

node-red-contrib-rosepetal-python-executor ​

A high-performance Node-RED node for executing Python code within your flows. Features syntax highlighting, automatic image handling, and support for both single execution and persistent process modes.

Features ​

  • Syntax Highlighted Editor: Built-in Python code editor with syntax highlighting
  • High Performance: Two execution modes:
    • Single execution: Spawns new Python process for each message (more secure)
    • Persistent process: Keeps Python process running for ~10x better performance
  • Automatic Image Handling: Images in messages are automatically converted to/from base64
  • Data Science Ready: Built-in support for numpy, pandas, and PIL if installed
  • Security Features: Optional code validation and restricted execution environment
  • Error Handling: Comprehensive error reporting with stack traces
  • Timeout Protection: Configurable timeout for long-running operations

Installation ​

bash
npm install node-red-contrib-rosepetal-python-executor

Or install directly from the Node-RED palette manager.

Usage ​

  1. Drag the "python executor" node from the function category into your flow
  2. Double-click to configure:
    • Name: Optional name for the node
    • Python Path: Path to Python executable (default: python3)
    • Timeout: Maximum execution time in milliseconds (default: 5000)
    • Execution Mode: Choose between single or persistent process mode
    • Python Code: Write your Python code in the syntax-highlighted editor

Message Access ​

The incoming message is available as a msg dictionary in Python:

python
# Access the payload
data = msg['payload']

# Modify the message
msg['payload'] = data * 2
msg['processed'] = True

# Return the modified message
return msg

Example Code ​

Simple calculation:

python
# Square the input
value = msg['payload']
msg['payload'] = value ** 2
return msg

Working with arrays:

python
import numpy as np

data = np.array(msg['payload'])
msg['mean'] = float(np.mean(data))
msg['std'] = float(np.std(data))
return msg

Image processing:

python
from PIL import Image
import numpy as np

# Images are automatically decoded from base64
img = Image.fromarray(msg['payload'])

# Process the image
img = img.rotate(90)

# Convert back to array (will be encoded to base64 automatically)
msg['payload'] = np.array(img)
return msg

Performance Modes ​

Single Execution Mode ​

  • Spawns a new Python process for each message
  • More secure as each execution is isolated
  • ~50-100ms overhead per execution
  • Suitable for low-frequency operations

Persistent Process Mode ​

  • Maintains a running Python process
  • ~5-10ms overhead per execution
  • Automatically restarts if the process crashes
  • Ideal for high-frequency operations

Available Libraries ​

The following libraries are available by default:

  • json, base64, math, datetime, random, re, collections, itertools

If installed, these libraries are also available:

  • numpy (as np)
  • pandas (as pd)
  • PIL / Image

Security ​

The node includes optional security features:

  • Code validation to prevent dangerous operations
  • Restricted import whitelist
  • Timeout protection
  • Optional sandboxed execution

For maximum security, use single execution mode and keep timeouts short.

Error Handling ​

Errors are reported through Node-RED's standard error handling:

  • Python exceptions are caught and reported with full stack traces
  • Timeout errors are reported if execution exceeds the configured limit
  • Process errors are reported if Python fails to start

Example Flow ​

Import the example flow from examples/example-flow.json to see the node in action.

Requirements ​

  • Node-RED >= 2.0.0
  • Python 3.x installed and accessible
  • Optional: numpy, pandas, PIL for data science operations

License ​

MIT

Author ​

Jordi

Contributing ​

Issues and pull requests are welcome at the GitHub repository.