You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
parse: fix time zone handling in scheduler time parsing - #2515
Users reported that run_daily() and other scheduler functions were scheduling callbacks at incorrect times, sometimes with unexpected offsets from the expected time. This regression was introduced after v4.4.2.
Expected execution: 08:00:00
Actual execution: 09:07:00
What Caused the Regression
In v4.4.2, the code correctly handled pytz timezones:
# Old approach (correct)event=datetime.combine(today, when) # 1. Create NAIVE datetimeaware_event=self.AD.sched.convert_naive(event) # 2. Localize with tz.localize()
The convert_naive() method properly used self.AD.tz.localize(dt), which is the required pattern for pytz timezones to correctly determine the UTC offset based on DST for that specific date.
When the time parsing was refactored into parse.py, this pattern was replaced with:
# New approach (broken)result=datetime.combine(date, parsed_time, tzinfo=now.tzinfo)
This is incorrect for pytz timezones. Unlike standard tzinfo implementations, pytz timezones are stateful and require the localize() method to properly determine the UTC offset. When you pass a pytz timezone directly to datetime.combine() or use dt.replace(tzinfo=...), pytz may apply an incorrect default offset that doesn't account for DST on that specific date.
Solution
Instead of reverting to the old localize() pattern (which is pytz-specific and non-standard), we normalize pytz timezones to ZoneInfo (PEP 615) at the boundary:
normalize_tz(tz) - Converts pytz timezones to their equivalent ZoneInfo using the IANA zone name. ZoneInfo behaves like a standard tzinfo and handles DST correctly with normal replace(tzinfo=...) calls.
localize_naive(naive_dt, tz) - A helper that normalizes the timezone first, then uses standard replace(tzinfo=...).
This approach:
Centralizes the pytz→ZoneInfo conversion in one place
Uses standard Python datetime semantics after normalization
Properly handles DST by letting ZoneInfo interpret wall-clock times correctly
Avoids pytz-specific API calls scattered throughout the codebase
I think this fix can be a stepping stone toward a medium/long-term cleanup: prefer zoneinfo internally, while continuing to accept pytz at the boundary for backwards compatibility.
Why move toward zoneinfo?
pytz does not implement “normal” tzinfo semantics: it requires localize()/normalize(), and attaching a pytz zone via replace(tzinfo=...) is explicitly error-prone (this regression is a concrete example of how easy it is to get wrong).
zoneinfo (PEP 615) is the stdlib timezone implementation. It behaves like a regular tzinfo, so the “obvious” datetime operations do the right thing (replace(tzinfo=...), astimezone(), arithmetic).
Centralizing on zoneinfo reduces the surface area for DST bugs and makes the code easier to reason about.
It also reduces dependency complexity long-term (stdlib + optional tzdata on platforms that need it).
The workaround SteLu1803 found in #2391 (comment) confirms the root cause. They discovered that passing a string to run_daily instead of a datetime.time object works correctly.
This hit the case time(): branch in parse.py that was incorrectly using datetime.combine(..., tzinfo=pytz_tz).
Working workaround (using string):
parsed_time=self.app.parse_time("08:00:00", aware=True)
self.app.run_daily(callback, parsed_time) # ✅ Bypasses the bug
When you pass a string, it goes through a different code path. And by passing aware=True, they get back a properly localized datetime that was already correctly converted.
The fix addresses this directly - after the fix, users can use datetime.time objects as intended without needing the string workaround. The fix ensures that when a time object comes in, it's properly converted by:
Creating a naive datetime first
Normalizing the pytz timezone to ZoneInfo
Using standard replace(tzinfo=...) which works correctly with ZoneInfo
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Users reported that
run_daily()and other scheduler functions were scheduling callbacks at incorrect times, sometimes with unexpected offsets from the expected time. This regression was introduced after v4.4.2.Example from issue:
Expected execution:
08:00:00Actual execution:
09:07:00What Caused the Regression
In v4.4.2, the code correctly handled pytz timezones:
The
convert_naive()method properly usedself.AD.tz.localize(dt), which is the required pattern for pytz timezones to correctly determine the UTC offset based on DST for that specific date.When the time parsing was refactored into
parse.py, this pattern was replaced with:This is incorrect for pytz timezones. Unlike standard
tzinfoimplementations, pytz timezones are stateful and require thelocalize()method to properly determine the UTC offset. When you pass a pytz timezone directly todatetime.combine()or usedt.replace(tzinfo=...), pytz may apply an incorrect default offset that doesn't account for DST on that specific date.Solution
Instead of reverting to the old
localize()pattern (which is pytz-specific and non-standard), we normalize pytz timezones toZoneInfo(PEP 615) at the boundary:normalize_tz(tz)- Converts pytz timezones to their equivalentZoneInfousing the IANA zone name. ZoneInfo behaves like a standardtzinfoand handles DST correctly with normalreplace(tzinfo=...)calls.localize_naive(naive_dt, tz)- A helper that normalizes the timezone first, then uses standardreplace(tzinfo=...).This approach:
Fixes #2338
Fixes #2388
Fixes #2391
Fixes #2393
Fixes #2400