[go: up one dir, main page]
Skip to content
Cloudflare Docs

Python

Cloudflare Workers provides first-class support for Python, including support for:

Get started

You need uv ↗ and Node.

Terminal window
git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/01-hello
uv run pywrangler dev

A Python Worker can be as simple as three lines of code:

Python
from workers import WorkerEntrypoint, Response


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

Similar to Workers written in JavaScript, TypeScript, or Rust, the main entry point for a Python worker is the fetch handler. In a Python Worker, this handler is placed in a Default class that extends the WorkerEntrypoint class (which you can import from the workers SDK module).

To run a Python Worker locally, you use pywrangler, the CLI for Python Workers. To set it up, first you need to set up your development environment:

uv init
uv tool install workers-py
uv run pywrangler init

This will create a pyproject.toml file with workers-py as a development dependency. pywrangler init will create a wrangler config file. You can then run pywrangler with:

Terminal window
uv run pywrangler dev

To deploy a Python Worker to Cloudflare, run pywrangler deploy:

Terminal window
uv run pywrangler deploy

Modules

Python workers can be split across multiple files. Let's create a new Python file, called src/hello.py:

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

Now, we can modify src/entry.py to make use of the new module.

Python
from hello import hello
from workers import WorkerEntrypoint, Response


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

Once you edit src/entry.py, Wrangler will automatically detect the change and reload your Worker.

The Request Interface

The request parameter passed to your fetch handler is a JavaScript Request object, exposed via the foreign function interface, allowing you to access it directly from your Python code.

Let's try editing the worker to accept a POST request. We know from the documentation for Request that we can call await request.json() within an async function to parse the request body as JSON. In a Python Worker, you would write:

Python
from workers import WorkerEntrypoint, Response
from hello import hello


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

Once you edit the src/entry.py, Wrangler should automatically restart the local development server. Now, if you send a POST request with the appropriate body, your Worker should respond with a personalized message.

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

The env Attribute

The env attribute on the WorkerEntrypoint can be used to access environment variables, secrets,and bindings.

For example, let us try setting and using an environment variable in a Python Worker. First, add the environment variable to your Worker's Wrangler configuration file:

{
  "name": "hello-python-worker",
  "main": "src/entry.py",
  "compatibility_flags": [
    "python_workers"
  ],
  "compatibility_date": "2024-03-20",
  "vars": {
    "API_HOST": "example.com"
  }
}

Then, you can access the API_HOST environment variable via the env parameter:

Python
from workers import WorkerEntrypoint, Response


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

Further Reading