added timezone support for cron schedules in periodic tasks

Open dreackm opened this issue 2 months ago • 1 comments

Closes #1472

This PR adds native timezone support to Procrastinate’s periodic task scheduler.

The Blueprint.periodic decorator now accepts a tzinfo argument, which can be either a string or a zoneinfo.ZoneInfo object. When provided, croniter will evaluate the cron expression in the specified timezone rather than defaulting to UTC.

Previously, users had to manually convert local times to UTC to ensure tasks ran at the intended hours. This often led to confusion and misaligned schedules. With this enhancement, users can define periodic tasks directly in their local timezone, improving predictability and reducing the risk of scheduling errors.

Key Changes

The tzinfo attribute is now set on the croniter instance within PeriodicTask.

Example Usage

from zoneinfo import ZoneInfo

tzinfo = "Africa/Blantyre" or ZoneInfo("Africa/Blantyre")  # UTC+2

@app.periodic(cron="* 8-17 * * *", tzinfo=tzinfo, ...)
@app.task(...)
def between_5_and_7(timestamp): ...

Without tzinfo: runs from 10 AM to 7 PM UTC
With tzinfo: runs from 8 AM to 5 PM local time

Successful PR Checklist:

[ ] Tests
- [ ] (not applicable?)
[ ] Documentation
- [ ] (not applicable?)

PR label(s):

[ ] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20breaking%20%F0%9F%92%A5
[x] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20feature%20%E2%AD%90%EF%B8%8F
[ ] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20bugfix%20%F0%9F%95%B5%EF%B8%8F
[ ] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20miscellaneous%20%F0%9F%91%BE
[ ] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20dependencies%20%F0%9F%A4%96
[ ] https://github.com/procrastinate-org/procrastinate/labels/PR%20type%3A%20documentation%20%F0%9F%93%9A