adewale Cloudflare Python Workers Skill
Everything that is different, surprising, or error-prone when building Cloudflare Workers in Python instead of JavaScript/TypeScript. This skill does NOT duplicate general Cloudflare Workers documentation — it focuses on the Python-specific gaps.
Quick Decision Trees
"I need to set up a Python Worker"
New project?
├─ Quick start with pywrangler -> README.md
├─ Python-specific config flags -> configuration.md
├─ Add Python packages (Pyodide compat) -> configuration.md (Packages)
├─ Local dev secrets (.dev.vars) -> configuration.md (Local Development)
├─ Set up pytest with mock bindings -> patterns.md (Testing)
└─ Migrate from pre-Dec 2025 Worker -> gotchas.md (#1)
"I need to use a Cloudflare binding from Python"
Which binding?
├─ Any binding (D1, KV, Queues, etc.) -> api.md (Binding Access)
│ The API is the same as JS, BUT:
│ ├─ Results come back as JsProxy -> gotchas.md (#8) + patterns.md (FFI)
│ ├─ Dicts must use dict_converter -> gotchas.md (#5)
│ ├─ None = undefined ≠ null -> gotchas.md (#3)
│ └─ Convert at boundary, not inline -> patterns.md (FFI Boundary Layer)
├─ Durable Objects -> patterns.md (Durable Objects From Python)
│ ├─ Transactional storage -> patterns.md (DO Transactional Storage)
│ ├─ Alarms (scheduled wake-ups) -> patterns.md (DO Alarms)
│ ├─ WebSocket hibernation -> patterns.md (DO WebSocket Hibernation API)
│ └─ Outbound WebSocket client -> patterns.md (Outbound WebSocket Client)
├─ Workflows (multi-step) -> api.md (Workflows)
├─ Service Bindings / RPC -> api.md (Service Bindings)
│ └─ dict→Map serialization caveat -> api.md (Service Bindings note)
├─ Static Assets (special — no Worker!) -> patterns.md (Static Assets)
├─ Pass Python callable to JS API -> api.md (create_proxy)
└─ JS API rejects wrapped request/resp -> patterns.md (request.js_object)
"I need to cross the JS/Python boundary"
FFI task?
├─ Convert JS → Python -> api.md (FFI) — .to_py() method
├─ Convert Python → JS -> api.md (FFI) — to_js + dict_converter
├─ Type compatibility matrix -> api.md (FFI Type-Compatibility Matrix)
├─ None = undefined ≠ null -> gotchas.md (#3)
├─ Python bytes to R2/KV -> gotchas.md (#14) — to_js(bytes) for Uint8Array
├─ Binary Response (images/files) -> api.md (Binary Response)
├─ Deep/recursive conversion -> patterns.md (Safe JsProxy Conversion)
├─ Bidirectional boundary wrappers -> patterns.md (FFI — The boundary is bidirectional)
├─ D1 results are JsProxy -> patterns.md (D1 Row Conversion)
├─ Large binary data (>10MB) -> gotchas.md (#17) — bypass Python
└─ js.eval() is disallowed -> gotchas.md (#4)
"I need to test my Python Worker"
Testing task?
├─ Unit test with mock bindings -> patterns.md (Testing — Mock Bindings)
├─ The HAS_PYODIDE testability pattern -> patterns.md (Testing — HAS_PYODIDE)
├─ Test both HAS_PYODIDE branches -> patterns.md (Testing — Test both branches)
├─ Pyodide fakes for FFI testing -> patterns.md (Testing — Two-tier FFI testing)
├─ Mocks pass but prod fails (JsProxy) -> patterns.md (Testing — E2E)
├─ Mock D1 / Vectorize / AI / Queue -> patterns.md (Testing — Mock Bindings)
└─ Run tests (pytest) -> configuration.md (Test Setup)
"Something isn't working"
Common issues?
├─ D1 returns JsProxy not dict -> gotchas.md (#8) + patterns.md (FFI)
├─ Dict rejected by Cloudflare API -> gotchas.md (#5) — dict_converter
├─ None = undefined ≠ null in D1 -> gotchas.md (#3)
├─ Cold start too slow -> gotchas.md (#6) + patterns.md (Per-Isolate Init)
├─ PRNG fails at module level -> gotchas.md (#7)
├─ Package not found / won't install -> gotchas.md (#12)
├─ "python_workers flag required" -> configuration.md
├─ js.eval() disallowed -> gotchas.md (#4)
├─ R2/KV rejects Python bytes -> gotchas.md (#14) — to_js(bytes)
├─ Queue msg canceled on cold start -> gotchas.md (#15) — inherent behavior
├─ Queue msgs not delivered locally -> gotchas.md (#16) — use /process-now
├─ Worker crashes on large R2 objects -> gotchas.md (#17) — bypass Python
├─ Tests pass but prod fails -> patterns.md (Testing — E2E)
└─ No filesystem access for templates -> patterns.md (Jinja2 SSR)
Reference Files
All in references/python-workers/:
| File | Contents |
|---|---|
README.md |
Runtime overview, quick start, how Pyodide works, project structure |
api.md |
Python-specific handler signatures, FFI functions (to_js/to_py/create_proxy), binding access patterns, Response (including binary), Service Bindings (RPC + dict→Map note), Workflows, workers.fetch() |
configuration.md |
Python-specific config (compatibility flags, pyproject.toml, packages + confirmed working list, CPU limits, .dev.vars, rules for JS bundling, triggers.crons, test setup) |
patterns.md |
FFI boundary layer, D1 row conversion, queue message handling, Static Assets architecture, Durable Objects (storage, alarms, WebSocket hibernation, outbound WS), per-isolate initialization, request.js_object unwrapping, testing (3-tier with mocks), Jinja2 without filesystem, FastAPI ASGI bridge |
gotchas.md |
17 Python-specific issues with error signatures and fixes |
Anti-Patterns
Raw JsProxy in Business Logic
# NEVER — JsProxy leaks into app code, breaks serialization/iteration
results = await env.DB.prepare("SELECT * FROM feeds").all()
return results.results # JsProxy!
# ALWAYS — convert at the boundary
results = await env.DB.prepare("SELECT * FROM feeds").all()
rows = [dict(r) for r in results.results.to_py()] # Native Python
Python Dict to JS Without dict_converter
# NEVER — creates JS Map, most Cloudflare APIs reject it
js_obj = to_js({"topK": 50})
# ALWAYS — creates JS Object
js_obj = to_js({"topK": 50}, dict_converter=Object.fromEntries)
Module-Level PRNG
# NEVER — breaks Wasm snapshot, deployment FAILS
import random
random.seed(42)
# ALWAYS — inside handlers
class Default(WorkerEntrypoint):
async def fetch(self, request):
random.seed(42) # OK
Routing Static Assets Through the Worker
# NEVER — wakes up Python Worker for CSS/JS/images (1s+ cold start)
class Default(WorkerEntrypoint):
async def fetch(self, request):
if path.startswith("/static/"):
return await self.env.ASSETS.fetch(request) # Worker is already awake!
# ALWAYS — let Workers Static Assets serve directly from the edge
# Configure in wrangler.jsonc — requests to /static/ never reach your Python code
"assets": { "directory": "./assets/" }
# No binding needed. No Worker invocation. ~15-90ms TTFB.
Python bytes to Binary APIs
# NEVER — PyProxy, R2/KV will reject it
await env.BUCKET.put("key", my_bytes)
# ALWAYS — convert to Uint8Array
await env.BUCKET.put("key", to_js(my_bytes))