claudetools/.claude/standards/python/windows-runtime.md

name, description, applies-to

name	description	applies-to
windows-runtime	Use `py` on Windows (not python3/python); use jq for JSON extraction; use Python scripts over heredocs with apostrophes	all

Python on Windows

Interpreter command

On Windows (DESKTOP-0O8A1RL, GURU-BEAST-ROG), use py to invoke Python:

# Correct
py script.py
py -c "import hashlib; print(hashlib.sha384(b'test').hexdigest())"
py -m bot.main

# Wrong — not in PATH on this machine
python3 script.py
python script.py

python3 and python are not in Git Bash's PATH on the Windows machines in this MSP. The Windows Launcher (py.exe) is the correct entry point and selects the installed Python version automatically. Store aliases are also disabled in this environment.

JSON extraction — use jq, not Python

For JSON extraction in shell scripts, use jq rather than a Python one-liner. jq is installed at:

C:/Users/guru/AppData/Local/Microsoft/WinGet/Links/jq

# Correct — jq for JSON extraction
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# Acceptable for complex extraction when jq is insufficient
py -c "import json,sys; d=json.load(sys.stdin); print(d['tool_input']['command'])"

Heredocs with apostrophes — use Write + py script

If a heredoc payload contains apostrophes (single quotes) in the content, Git Bash <<'EOF' terminates early at the apostrophe. Workaround: write the content to a file using the Write tool, then read it with Python:

# Write the file with Write tool first, then:
py script.py

Or use Python to build and send the payload without a heredoc at all:

py -c "
import urllib.request, json
data = json.dumps({'body': \"It's a note about John's machine\"}).encode()
req = urllib.request.Request(url, data=data, headers={'Content-Type': 'application/json'})
urllib.request.urlopen(req)
"

Unicode in log files

When reading log files that may contain non-UTF8 bytes (Windows logs, PowerShell output):

sys.stdout.buffer.write(output.encode('utf-8', errors='replace'))

Do not use open(file, 'r') without specifying encoding on Windows — the default encoding varies by system locale and may not be UTF-8.