Python Workers の基本 · Cloudflare Workers ドキュメント

Fetch ハンドラー

Python Workers の概要で述べたとおり、Python Worker は次の 4 行でも書けます。

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response("Hello World!")

ほかの Workers と同様、Python Worker の主なエントリポイントは fetch ハンドラーです。Worker に届いたリクエストを処理します。

Python Worker では、このハンドラーを WorkerEntrypoint クラス（workers SDK モジュールからインポートできます）を継承した Default クラスに置きます。

`Request` インターフェイス

fetch ハンドラーに渡される request パラメーターは、JavaScript の Request オブジェクトです。foreign function interface（FFI）経由で公開されるため、Python コードから直接アクセスできます。

Worker を編集して POST リクエストを受け付けるようにしてみます。Request のドキュメントによると、async 関数内で await request.json() を呼ぶと、リクエストボディを JSON として解析できます。

Python Worker では、次のように書きます。

from workers import WorkerEntrypoint, Response
from hello import hello

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        body = await request.json()
        name = body["name"]
        return Response(hello(name))

ほかの多くの JavaScript API も FFI 経由で Python Workers から使えます。同じ要領でほかのメソッドも呼べます。

src/entry.py を編集すると、Wrangler はローカル開発サーバーを自動で再起動します。

適切なボディで POST リクエストを送ると、Worker はパーソナライズされたメッセージを返します。

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name": "Python"}' http://localhost:8787

Hello, Python!

JSON レスポンスを返す

Python Worker から JSON を返すには、Response.json() を使います。

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        data = {"message": "Hello", "status": "ok"}
        return Response.json(data)

`env` 属性

WorkerEntrypoint の env 属性で、環境変数、シークレット、バインディングにアクセスできます。

例として、Python Worker で環境変数を設定して使ってみます。まず、Worker の Wrangler 設定ファイルに環境変数を追加します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "hello-python-worker",
	"main": "src/entry.py",
	"compatibility_flags": [
		"python_workers"
	],
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"vars": {
		"API_HOST": "example.com"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "hello-python-worker"
main = "src/entry.py"
compatibility_flags = [ "python_workers" ]
# Set this to today's date
compatibility_date = "2026-09-20"

[vars]
API_HOST = "example.com"

その後、env パラメーター経由で API_HOST 環境変数にアクセスできます。

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(self.env.API_HOST)

モジュール

Python Worker は複数ファイルに分割できます。

src/hello.py という新しい Python ファイルを作成します。

def hello(name):
    return "Hello, " + name + "!"

次に、新しいモジュールを使うように src/entry.py を変更します。

from hello import hello
from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        return Response(hello("World"))

src/entry.py を編集すると、pywrangler が変更を自動検出し、Worker をリロードします。

型と自動補完

workers-runtime-sdk パッケージは、Python Workers 用のランタイム SDK です。pywrangler を使うと、このパッケージは自動でインストールされ Worker に含まれます。型ヒントと IDE の自動補完を使うために、手動でインストールすることもできます。

有効にするには、pyproject.toml ファイルに workers-runtime-sdk パッケージを追加します。

dependencies = [
  "workers-runtime-sdk"
]

加えて、uv run pywrangler types で Worker 設定に基づく型を生成できます。

バインディングに基づく Env 型、モジュールルール、設定ファイルの compatibility_date と compatibility_flags に基づくランタイム型が含まれます。

`pywrangler` のアップグレード

pywrangler をグローバルに最新バージョンへアップグレードするには、次のコマンドを実行します。

uv tool upgrade workers-py

特定のプロジェクトで pywrangler を最新バージョンへアップグレードするには、次のコマンドを実行します。

uv lock --upgrade-package workers-py

次のステップ

ローカル開発、デプロイ、Python Workers の仕組みの詳細を確認します。
Python Workers でパッケージを使う手順は、パッケージのドキュメントを参照してください。
Python Workers でサポートされる Python 標準ライブラリの範囲を確認します。
Python Workers の foreign function interface（FFI）と、バインディングおよび Runtime APIs との使い方を学びます。