Docs / Strand / nodes/python-snippet

Python Snippet Node

Execute secure Python code snippets within your workflows.

The inspector previews the code inline; Edit Code opens the full editor with the module reference.

Overview

Python Snippet nodes allow you to write custom Python code to process and transform data. The code runs in a secure, sandboxed environment.

Use Python snippets for:

• Data transformation and calculations
• String processing and formatting
• Data validation and enrichment
• Simple business logic

Don't use Python snippets for:

• API calls (use HTTP Request or Connector nodes)
• File operations (use connectors)
• Long-running tasks
• Large data processing

Getting Started

Your First Python Snippet

When you create your first Python snippet, here's what to expect:

Typical Workflow

# Step 1: Access your input data
user_id = payload.get('user_id')
email = payload.get('email', '')

# Step 2: Process/transform the data
email_lower = email.lower()
is_valid = '@' in email and '.' in email.split('@')[1] if email else False

# Step 3: Return your result
return {
    'user_id': user_id,
    'email_normalized': email_lower,
    'is_valid': is_valid
}

What Happens When You Run

Available Variables

Your Python code has access to:

• payload (dict) - Your main input data
• Contains data from the previous node (if directly connected)
• Or contains the initial workflow input event
• Always a dictionary (empty {} if no data)

• meta (dict) - Execution metadata
• received_at is always present (ISO timestamp set when the worker picks up the event)
• workflow_id, workflow_name, and trigger_source are present on manual runs but not on webhook-triggered runs, so use meta.get('key') and don't assume they exist
• Useful for timestamps and workflow context

• vault (dict) - Encrypted secrets from the Global Vault
• Access via vault['key'] or vault.get('key')
• Read-only dictionary of your account's vault secrets
• Vault values in output are automatically replaced with {{ vault.key }} placeholders

• return / output - Pass results to the next node
• Use either return {...} or assign output = {...}; both work
• If you don't set a result, the input payload is passed through unchanged
• Must be a dictionary (non-dict values are wrapped as {'result': your_value})

Python vs Jinja: What's Available Where

Returning Output

Use return (or assign output = {...}) to pass data to the next node. If you don't set either, the input payload is passed through unchanged.

# Process the payload
result = payload.get('value', 0) * 2

# Return your result
return {
    'processed_value': result,
    'original': payload,
    'timestamp': meta.get('received_at')
}

Available Libraries

You can import the following safe libraries using standard Python import statements:

from datetime import datetime

Examples

Data Transformation

# Transform user data
user_data = payload.get('user', {})
full_name = f"{user_data.get('first_name', '')} {user_data.get('last_name', '')}".strip()

return {
    'user_id': user_data.get('id'),
    'full_name': full_name,
    'email': user_data.get('email'),
    'processed_at': meta.get('received_at')
}

Data Validation

# Validate and enrich data
email = payload.get('email', '')
is_valid = '@' in email and '.' in email.split('@')[1] if email else False

return {
    'email': email,
    'is_valid': is_valid,
    'domain': email.split('@')[1] if is_valid else None
}

Calculations

# Perform calculations
items = payload.get('items', [])
total = sum(item.get('price', 0) * item.get('quantity', 0) for item in items)
tax = total * 0.08
grand_total = total + tax

return {
    'subtotal': total,
    'tax': tax,
    'total': grand_total,
    'item_count': len(items)
}

Using Libraries

from datetime import datetime

# Parse JSON string
data = json.loads(payload.get('json_data', '{}'))

# Math operations
result = math.sqrt(payload.get('value', 0))

# Date operations
now = datetime.utcnow()
return {
    'processed_at': now.isoformat(),
    'result': result,
    'data': data
}

Security

Python snippets run in a secure, sandboxed environment with multiple layers of protection. Code is validated, executed in isolation, and subject to resource limits. Vault secrets are accessible via the vault variable, but any vault values in output are automatically replaced with {{ vault.key }} placeholders.

Resource Limits

Restrictions

What's NOT Allowed

• System module imports - Cannot import os, sys, subprocess, etc.
• File operations - No file system access
• Network access - No HTTP requests or sockets
• Code generation - No exec, eval, compile

What IS Allowed

• Safe builtins - len, str, int, dict, list, tuple, set, bool, float, min, max, sum, abs, round, sorted, reversed, enumerate, zip, range, all, any
• String operations - All standard string methods
• Math operations - pow, divmod, plus math library functions
• Safe libraries - json, math, datetime, re, collections, etc. (see Available Libraries above)
• Control flow - if, for, while, try/except
• Functions - Define and call functions
• List/Dict comprehensions - Full support

Error Handling

Handle errors gracefully in your code:

try:
    value = payload.get('value', 0)
    result = 100 / value
    return {'result': result}
except ZeroDivisionError:
    return {'error': 'Division by zero', 'result': None}
except Exception as e:
    return {'error': str(e), 'result': None}

Troubleshooting

Common Errors and Solutions

"Import of 'X' is not allowed"

• You tried to import a module not in the allowlist
• Use one of the allowed libraries listed above

"Code execution exceeded time limit"

• Your code took longer than the time limit
• Optimize your code or process less data
• Check for infinite loops

"Code execution exceeded memory limit"

• Your code used too much memory
• Process data in smaller chunks
• Use generators instead of lists where possible

"Output size exceeds maximum allowed size"

• Your return value is larger than 1MB
• Return only necessary data
• Summarize instead of returning full datasets

Performance Expectations

Best Practices

Related

• Connector Nodes - Overview of all connector types
• Passing Data Between Steps - How data flows
• Transform Node - Alternative for simple transformations
• Error Handling - Error handling patterns

← Back to Strand docs