← Cloudflare Workers / workers / languages / python

Основы

Как упоминалось в введение в Python Workers, Python Worker может состоять всего из четырех строк кода:

from workers import WorkerEntrypoint, Response

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

Как и у других Workers, основной точкой входа для Python worker является fetch обработчик который обрабатывает входящие запросы к Worker.

В Python Worker этот обработчик размещается в Default класс, расширяющий WorkerEntrypoint класс (который можно импортировать из workers модуля SDK).

request параметр, переданный в fetch обработчика является объект JavaScript Request, доступный через интерфейс внешних функций (FFI), что позволяет обращаться к нему напрямую из кода Python.

Попробуем изменить worker так, чтобы он принимал POST-запрос. Мы знаем из документация для Request который мы можем вызвать await request.json() внутри async функцию для разбора тела запроса как 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))

В Python Workers через FFI доступны и другие JavaScript API, поэтому вы можете вызывать другие методы аналогичным образом.

После того как вы отредактируете 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, используйте 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 можно использовать для доступа к переменные окружения, секреты, и привязки.

Например, попробуем задать и использовать переменную окружения в Worker на Python. Сначала добавьте переменную окружения в конфигурационный файл 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-08-28",
	"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-08-28"

[vars]
API_HOST = "example.com"

После этого вы сможете получить доступ к API_HOST переменную окружения через env параметр:

from workers import WorkerEntrypoint, Response

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

Код Python Workers можно разбить на несколько файлов.

Создадим новый файл Python с именем src/hello.py:

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 пакет предоставляет SDK среды выполнения для Python Workers. Этот пакет автоматически устанавливается и включается в ваш Worker, когда вы используете pywrangler, но его также можно установить вручную, чтобы воспользоваться подсказками типов и автодополнением в IDE.

Чтобы включить их, добавьте workers-runtime-sdk пакет в ваш pyproject.toml файл.

dependencies = [
  "workers-runtime-sdk"
]

Кроме того, можно сгенерировать типы на основе конфигурации Worker с помощью uv run pywrangler types

Сюда входит Env типы на основе ваших привязок, правил модулей и типы среды выполнения на основе compatibility_date и compatibility_flags в вашем конфигурационном файле. См.

Чтобы обновиться до последней версии pywrangler глобально, выполните следующую команду:

uv tool upgrade workers-py

Чтобы обновиться до последней версии pywrangler в конкретном проекте выполните следующую команду:

uv lock --upgrade-package workers-py

• Подробнее о локальной разработке, развёртывании и как работают Python Workers.
• Изучите пакет документации инструкции по использованию пакетов с Python Workers.
• Узнайте, какие части Python Standard Library поддерживаются в Python Workers.
• Подробнее о Python Workers: интерфейс внешних функций (FFI), и как использовать его для работы с привязки и Runtime API.