n8n-code-python

# Python Code Node (Beta) Expert guidance for writing Python code in n8n Code nodes. --- ## ⚠️ Important: JavaScript First **Recommendation**: Use **JavaScript for 95% of use cases**. Only use Python when: - You need specific Python standard library functions - You're significantly more comfortable with Python syntax - You're doing data transformations better suited to Python **Why JavaScript is preferred:** - Full n8n helper functions ($helpers.httpRequest, etc.) - Luxon DateTime library for advanced date/time operations - No external library limitations - Better n8n documentation and community support --- ## Quick Start ```python # Basic template for Python Code nodes items = _input.all() # Process data processed = [] for item in items: processed.append({ "json": { **item["json"], "processed": True, "timestamp": datetime.now().isoformat() } }) return processed ``` ### Essential Rules 1. **Consider JavaScript first** - Use Python only when necessary 2. **Access data**: `_input.all()`, `_input.first()`, or `_input.item` 3. **CRITICAL**: Must return `[{"json": {...}}]` format 4. **CRITICAL**: Webhook data is under `_json["body"]` (not `_json` directly) 5. **CRITICAL LIMITATION**: **No external libraries** (no requests, pandas, numpy) 6. **Standard library only**: json, datetime, re, base64, hashlib, urllib.parse, math, random, statistics --- ## Mode Selection Guide Same as JavaScript - choose based on your use case: ### Run Once for All Items (Recommended - Default) **Use this mode for:** 95% of use cases - **How it works**: Code executes **once** regardless of input count - **Data access**: `_input.all()` or `_items` array (Native mode) - **Best for**: Aggregation, filtering, batch processing, transformations - **Performance**: Faster for multiple items (single execution) ```python # Example: Calculate total from all items all_items = _input.all() total = sum(item["json"].get("amount", 0) for item in all_items) return [{ "json": { "total": total, "count": len(all_items), "average": total / len(all_items) if all_items else 0 } }] ``` ### Run Once for Each Item **Use this mode for:** Specialized cases only - **How it works**: Code executes **separately** for each input item - **Data access**: `_input.item` or `_item` (Native mode) - **Best for**: Item-specific logic, independent operations, per-item validation - **Performance**: Slower for large datasets (multiple executions) ```python # Example: Add processing timestamp to each item item = _input.item return [{ "json": { **item["json"], "processed": True, "processed_at": datetime.now().isoformat() } }] ``` --- ## Python Modes: Beta vs Native n8n offers two Python execution modes: ### Python (Beta) - Recommended - **Use**: `_input`, `_json`, `_node` helper syntax - **Best for**: Most Python use cases - **Helpers available**: `_now`, `_today`, `_jmespath()` - **Import**: `from datetime import datetime` ```python # Python (Beta) example items = _input.all() now = _now # Built-in datetime object return [{ "json": { "count": len(items), "timestamp": now.isoformat() } }] ``` ### Python (Native) (Beta) - **Use**: `_items`, `_item` variables only - **No helpers**: No `_input`, `_now`, etc. - **More limited**: Standard Python only - **Use when**: Need pure Python without n8n helpers ```python # Python (Native) example processed = [] for item in _items: processed.append({ "json": { "id": item["json"].get("id"), "processed": True } }) return processed ``` **Recommendation**: Use **Python (Beta)** for better n8n integration. --- ## Data Access Patterns ### Pattern 1: _input.all() - Most Common **Use when**: Processing arrays, batch operations, aggregations ```python # Get all items from previous node all_items = _input.all() # Filter, transform as needed valid = [item for item in all_items if item["json"].get("status") == "active"] processed = [] for item in valid: processed.append({ "json": { "id": item["json"]["id"], "name": item["json"]["name"] } }) return processed ``` ### Pattern 2: _input.first() - Very Common **Use when**: Working with single objects, API responses ```python # Get first item only first_item = _input.first() data = first_item["json"] return [{ "json": { "result": process_data(data), "processed_at": datetime.now().isoformat() } }] ``` ### Pattern 3: _input.item - Each Item Mode Only **Use when**: In "Run Once for Each Item" mode ```python # Current item in loop (Each Item mode only) current_item = _input.item return [{ "json": { **current_item["json"], "item_processed": True } }] ``` ### Pattern 4: _node - Reference Other Nodes **Use when**: Need data from specific nodes in workflow ```python # Get output from specific node webhook_data = _node["Webhook"]["json"] http_data = _node["HTTP Request"]["json"] return [{ "json": { "combined": { "webhook": webhook_data, "api": http_data } } }] ``` **See**: DATA_ACCESS.md for comprehensive guide --- ## Critical: Webhook Data Structure **MOST COMMON MISTAKE**: Webhook data is nested under `["body"]` ```python # ❌ WRONG - Will raise KeyError name = _json["name"] email = _json["email"] # ✅ CORRECT - Webhook data is under ["body"] name = _json["body"]["name"] email = _json["body"]["email"] # ✅ SAFER - Use .get() for safe access webhook_data = _json.get("body", {}) name = webhook_data.get("name") ``` **Why**: Webhook node wraps all request data under `body` property. This includes POST data, query parameters, and JSON payloads. **See**: DATA_ACCESS.md for full webhook structure details --- ## Return Format Requirements **CRITICAL RULE**: Always return list of dictionaries with `"json"` key ### Correct Return Formats ```python # ✅ Single result return [{ "json": { "field1": value1, "field2": value2 } }] # ✅ Multiple results return [ {"json": {"id": 1, "data": "first"}}, {"json": {"id": 2, "data": "second"}} ] # ✅ List comprehension transformed = [ {"json": {"id": item["json"]["id"], "processed": True}} for item in _input.all() if item["json"].get("valid") ] return transformed # ✅ Empty result (when no data to return) return [] # ✅ Conditional return if should_process: return [{"json": processed_data}] else: return [] ``` ### Incorrect Return Formats ```python # ❌ WRONG: Dictionary without list wrapper return { "json": {"field": value} } # ❌ WRONG: List without json wrapper return [{"field": value}] # ❌ WRONG: Plain string return "processed" # ❌ WRONG: Incomplete structure return [{"data": value}] # Should be {"json": value} ``` **Why it matters**: Next nodes expect list format. Incorrect format causes workflow execution to fail. **See**: ERROR_PATTERNS.md #2 for detailed error solutions --- ## Critical Limitation: No External Libraries **MOST IMPORTANT PYTHON LIMITATION**: Cannot import external packages ### What's NOT Available ```python # ❌ NOT AVAILABLE - Will raise ModuleNotFoundError import requests # ❌ No import pandas # ❌ No import numpy # ❌ No import scipy # ❌ No from bs4 import BeautifulSoup # ❌ No import lxml # ❌ No ``` ### What IS Available (Standard Library) ```python # ✅ AVAILABLE - Standard library only import json # ✅ JSON parsing import datetime # ✅ Date/time operations import re # ✅ Regular expressions import base64 # ✅ Base64 encoding/decoding import hashlib # ✅ Hashing functions import urllib.parse # ✅ URL parsing import math # ✅ Math functions import random # ✅ Random numbers import statistics # ✅ Statistical functions ``` ### Workarounds **Need HTTP requests?** - ✅ Use **HTTP Request node** before Code node - ✅ Or switch to **JavaScript** and use `$helpers.httpRequest()` **Need data analysis (pandas/numpy)?** - ✅ Use Python **statistics** module for basic stats - ✅ Or switch to **JavaScript** for most operations - ✅ Manual calculations with lists and dictionaries **Need web scraping (BeautifulSoup)?** - ✅ Use **HTTP Request node** + **HTML Extract node** - ✅ Or switch to **JavaScript** with regex/string methods **See**: STANDARD_LIBRARY.md for complete reference --- ## Common Patterns Overview Based on production workflows, here are the most useful Python patterns: ### 1. Data Transformation Transform all items with list comprehensions ```python items = _input.all() return [ { "json": { "id": item["json"].get("id"), "name": item["json"].get("name", "Unknown").upper(), "processed": True } } for item in items ] ``` ### 2. Filtering & Aggregation Sum, filter, count with built-in functions ```python items = _input.all() total = sum(item["json"].get("amount", 0) for item in items) valid_items = [item for item in items if item["json"].get("amount", 0) > 0] return [{ "json": { "total": total, "count": len(valid_items) } }] ``` ### 3. String Processing with Regex Extract patterns from text ```python import re items = _input.all() email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' all_emails = [] for item in items: text = item["json"].get("text", "") emails = re.findall(email_pattern, text) all_emails.extend(emails) # Remove duplicates unique_emails = list(set(all_emails)) return [{ "json": { "emails": unique_emails, "count": len(unique_emails) } }] ``` ### 4. Data Validation Validate and clean data ```python items = _input.all() validated = [] for item in items: