cloudflare / cloudflare/workers-py

`scheduled` not working

Open
#27 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
103
Forks
22
Avg merge
2d 1h
Merged PRs (30d)
30

Description

I've tried to run a worker on a schedule as described in the docs and in these examples.
## Conflicting documentation
The [documentation](https://developers.cloudflare.com/workers/configuration/cron-triggers/) mentions the use of `on_scheduled` and the `handler` decorator (same in the [changelog](https://developers.cloudflare.com/changelog/2025-04-22-python-worker-cron-triggers/)).

Both seem outdated, as the only way I found it to get picked up (complains about `scheduled` function not being available otherwise) is through

```python
from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
async def scheduled(self, controller, env, ctx):
print("Hello World!")
```

(Using a `WorkerEntrypoint` in lieu of the `handler` decorator, and using a `scheduled` method in lieu of a `on_scheduled` function)

## Actual issue
While this now gets picked up, the [scheduled handler documentation](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/) claims there is no way to perform local testing by simply using `wrangler.toml`. You [have to pass](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/#background) the `--test-schedule` flag to `wrangler dev`.

In my case, this raise a `TypeError: Couldn't convert object to Python type, got ScheduledController`.

## Steps to reproduce
1. Clone https://github.com/cloudflare/python-workers-examples/tree/main/01-hello
2. Replace the `fetch` method by the `scheduled` method above
3. Start wrangler with `uv run pywrangler dev --test-scheduled`
4. `curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*"`

## Closing words
Given the conflicting/incomplete documentation/examples and the difficulty of introspecting `pyodide`, I might be doing something wrong here; but let's say getting up and running with Python workers in the current state of affairs is not easy. I'd love to use them :)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.