cloudflare / cloudflare/workers-py
`scheduled` not working
- 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
Assessment
This issue has not been assessed yet.