version: "1.0.2" name: reliable-script-execution description: Execute Python scripts reliably using file-first approach instead of heredoc

Reliable Script Execution

When executing Python code via shell commands, avoid inline heredoc execution which can fail unpredictably with 'unknown error'. Use this two-step file-first approach for more reliable script execution.

Problem

Direct heredoc Python execution like:

python3 << 'EOF'
# complex code here
EOF

Can fail with 'unknown error', especially when:

• Script contains multiple lines or complex logic
• Special characters or quotes are present
• Working directory context matters

Solution: File-First Approach

Step 1: Write Python Script to File

Use write_file to save your Python code to a .py file:

write_file(path="./temp_script.py", content="""
import json
 
data = {"key": "value"}
print(json.dumps(data))
""")

Step 2: Execute via Shell

Use run_shell with explicit working directory:

run_shell(command="python3 ./temp_script.py", timeout=60)

Step 3: Clean Up (Optional)

Remove temporary files after execution:

run_shell(command="rm ./temp_script.py")

Complete Example

Task: Generate a JSON report with calculations

# Step 1: Write the script
write_file(
    path="./generate_report.py",
    content="""
import json
from datetime import datetime
 
revenue = 500000.00
expenses = 379577.06
net_income = revenue - expenses
 
report = {
    "generated": datetime.now().isoformat(),
    "revenue": revenue,
    "expenses": expenses,
    "net_income": net_income
}
 
print(json.dumps(report, indent=2))
"""
)
 
# Step 2: Execute
run_shell(command="python3 ./generate_report.py", timeout=60)
 
# Step 3: Clean up
run_shell(command="rm ./generate_report.py")

Best Practices

1. Use descriptive filenames: Name scripts according to their purpose (e.g., calculate_pnl.py, transform_data.py)

1. Set appropriate timeouts: For data processing scripts, use longer timeouts (60-300 seconds)

1. Specify working directory: If the script depends on relative paths, include cd /path && python3 script.py

1. Handle errors gracefully: Check shell output for errors and retry if needed

1. Clean up temporary files: Don't leave .py files cluttering the workspace unless they need to persist

When to Use This Pattern

• Executing multi-line Python code via shell
• Scripts with complex string handling or special characters
• When heredoc execution has failed previously
• Any scenario where reliability matters more than brevity

Anti-Pattern to Avoid

Do NOT rely on heredoc for production-critical scripts:

# Unreliable - may fail with 'unknown error'
python3 << 'EOF'
# Your code here
EOF

Use file-first approach instead for consistent, debuggable execution.