Shell quoting breaks with complex strings (quotes, apostrophes, f-strings) and multiple statements. Heredoc keeps the Python code intact.

How do I prevent shell expansion in the code?

Quote the delimiter: use << 'PYTHON_CODE' so $variables and backticks are treated literally.

Are there required rules I must follow?

Yes. Always use uv run python, always quote the delimiter, ensure the closing PYTHON_CODE is on its own line with no leading whitespace, and never use python -c for non-trivial code.

python-heredoc

Scanned

npx machina-cli add skill crypdick/pynchy/python-heredoc --openclaw

Files (1)

SKILL.md

1.3 KB

Python Heredoc Pattern

When you need to run Python code via Bash, never use python -c "..." for anything beyond trivial one-liners. Shell quoting breaks with f-strings, apostrophes, nested quotes, and escape sequences.

Use heredoc syntax instead

uv run python << 'PYTHON_CODE'
import json

data = {"name": "it's working", "value": f"{1 + 2}"}
print(json.dumps(data, indent=2))
PYTHON_CODE

The single quotes around 'PYTHON_CODE' prevent shell variable expansion, so $variables and backticks are treated as literal Python code.

With dependencies

uv run --with requests python << 'PYTHON_CODE'
import requests

resp = requests.get("https://api.example.com/data")
print(resp.json())
PYTHON_CODE

Rules

Always use uv run python (not bare python or python3)
Always quote the delimiter: << 'PYTHON_CODE' (not << PYTHON_CODE)
The closing PYTHON_CODE must be on its own line with no leading whitespace
Never use python -c for code containing quotes, f-strings, or multiple statements

Source

git clone https://github.com/crypdick/pynchy/blob/main/src/pynchy/agent/skills/python-heredoc/SKILL.mdView on GitHub

Overview

Python-heredoc teaches you to run multi-line Python code from Bash using a heredoc, avoiding shell quoting issues that arise with python -c. It emphasizes uv run python with a quoted delimiter to keep quotes, apostrophes, and f-strings intact. This approach improves reliability and readability in automation scripts.

How This Skill Works

Instead of python -c, you invoke uv run python and place your Python code between a heredoc marker, such as << 'PYTHON_CODE'. The closing PYTHON_CODE must be on its own line with no leading whitespace, and the single quotes around the delimiter prevent shell expansion, preserving Python syntax.

When to Use It

Running multi-line Python code from Bash without quoting issues
Code that includes quotes, apostrophes, f-strings, or backticks
Using external dependencies (e.g., --with requests) inside the heredoc
When you need to prevent shell variable expansion in the embedded code
When you want a clear, maintainable replacement for python -c for non-trivial scripts

Quick Start

Step 1: Write your Python code block
Step 2: Wrap it with uv run python << 'PYTHON_CODE' and end with PYTHON_CODE
Step 3: Run the command and confirm the output

Best Practices

Always use uv run python (not bare python or python3)
Always quote the delimiter: << 'PYTHON_CODE'
Ensure the closing PYTHON_CODE is on its own line with no leading whitespace
Never use python -c for code containing quotes, f-strings, or multiple statements
Keep heredoc blocks readable by aligning with your script's indentation

Example Use Cases

uv run python << 'PYTHON_CODE' import json data = {"name": "it's working", "value": f"{1 + 2}"} print(json.dumps(data, indent=2)) PYTHON_CODE
uv run --with requests python << 'PYTHON_CODE' import requests resp = requests.get("https://api.example.com/data") print(resp.json()) PYTHON_CODE
uv run python << 'PYTHON_CODE' print("She said, '\''Hello'\''") print(f"Sum: {3 + 4}") PYTHON_CODE
uv run --with requests python << 'PYTHON_CODE' import requests r = requests.get("https://example.org") print(r.status_code) PYTHON_CODE
uv run python << 'PYTHON_CODE' # CI-friendly Python script in a single block for i in range(3): print(f"line {i}") PYTHON_CODE

Frequently Asked Questions

Add this skill to your agents