added timezone support for cron schedules in periodic tasks #1474

dreackm · 2025-11-05T23:36:01Z

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):

PR type: breaking 💥 Contains breaking changes
PR type: feature ⭐️ Contains new features
PR type: bugfix 🕵️ Contains bug fix
PR type: miscellaneous 👾 Contains misc changes
PR type: dependencies 🤖 Contains only dependencies updates
PR type: documentation 📚 Contains documentation updates

for more information, see https://pre-commit.ci

github-actions · 2025-11-06T06:51:07Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
procrastinate
blueprints.py
periodic.py					51-55, 57
Project Total

_{This report was generated by python-coverage-comment-action}

ewjoachim

Nice work so far, we're missing tests. Also, I'd prefer we reach a consensus on the issue before merging the PR, as we may decide on a slightly different API to mitigate the risks.

ewjoachim · 2025-11-06T06:50:06Z

procrastinate/periodic.py

+                logger.error(f"{tzinfo} is not a valid timezone.")
+                return None


A failure could be impactful, I think we need to raise.

The only issue I can see is that it might confuse users when their chosen timezone isn’t applied. Besides that, does it have any other impact?

And if we’re okay with it crashing, wouldn’t it be simpler not to catch the error in the first place?

The only issue I can see is that it might confuse users when their chosen timezone isn’t applied. Besides that, does it have any other impact?

If I have scheduled batch processing at 12AM while there's no activity, and it happens at 2PM during peak hours, it could easily cause disruption.

ewjoachim · 2025-11-06T06:51:31Z

procrastinate/periodic.py

        cron: str,
        periodic_id: str,
        configure_kwargs: tasks.ConfigureTaskOptions,
+        tzinfo: str | None | ZoneInfo = None,


(Please put None last in the types)

ewjoachim · 2025-11-06T06:53:24Z

procrastinate/periodic.py

    cron: str
    periodic_id: str
    configure_kwargs: tasks.ConfigureTaskOptions
+    tzinfo: str | None | ZoneInfo = None


I'd rather we convert str to ZoneInfo at constructor time, and we only ever store ZoneInfo (or None) on the object

Meaning we shouldn't accept a ZoneInfo object?

Other than being simpler for the user, do you have any other specific reason for restricting it to a string value?

Ah no, I meant: whether we recieve a str or a ZoneInfo, what we store is a ZoneInfo.

I was confused. Okay.

ewjoachim · 2025-11-06T06:56:19Z

procrastinate/periodic.py

-        return croniter.croniter(self.cron)
+        croniter_instance = croniter.croniter(self.cron)
+        # croniter sets the timezone info object in
+        croniter_instance.tzinfo = self.get_tzinfo()


Is that the public API of croniter ? I couldn't find the official doc, so it's hard to say.

Also, I believe, support of ZoneInfo is recent, which means we need to severly restrict the accepted versions in pyproject.toml (which might create some conflict, but the lib didn't move a lot)

I realise the comment was incomplete. It's not the public API, but at least it's not a private attribute. They set tzinfo attribute in the initialiser of the croniter instance.

How do you mean by the ZoneInfo support being recent? As I believe it's supported in v6.0.0 (from December, 2024)

I will see if I run into any issues once I write tests.

ewjoachim · 2025-11-06T06:59:09Z

procrastinate/blueprints.py

+            Timezone in which the cron expression should be interpreted. Accepts a
+            timezone name string (e.g., "Africa/Blantyre"), a `zoneinfo.ZoneInfo` instance,
+            or `None`. When `None` (the default), the underlying `croniter` library
+            will interpret the schedule in UTC (the current behaviour).


The mention (the current behaviour) makes sense as a PR comment because we're talking code evolution, but doesn't make sense in the docstring. In 2 years time, what will "current" refer to ?

This makes sense. It's indeed confusing.

added timezone support for cron schedules in periodic tasks

4c902bc

dreackm requested a review from a team as a code owner November 5, 2025 23:36

github-actions bot added the PR type: feature ⭐️ Contains new features label Nov 5, 2025

[pre-commit.ci] auto fixes from pre-commit.com hooks

221b950

for more information, see https://pre-commit.ci

dreackm marked this pull request as draft November 5, 2025 23:39

dreackm marked this pull request as ready for review November 5, 2025 23:42

ewjoachim reviewed Nov 6, 2025

View reviewed changes

		logger.error(f"{tzinfo} is not a valid timezone.")
		return None

Uh oh!

added timezone support for cron schedules in periodic tasks #1474

Are you sure you want to change the base?

added timezone support for cron schedules in periodic tasks #1474

Uh oh!

Conversation

dreackm commented Nov 5, 2025

Key Changes

Example Usage

Successful PR Checklist:

PR label(s):

Uh oh!

github-actions bot commented Nov 6, 2025

Coverage report

Uh oh!

ewjoachim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants