fix: handle timezone correctly when DJANGO_CELERY_BEAT_TZ_AWARE=False (Issue #924) by NeverStopDreamingWang · Pull Request #926 · celery/django-celery-beat

NeverStopDreamingWang · 2025-07-31T10:01:49Z

Timezone Handling Fix for django-celery-beat (Issue #924)

Description

This PR resolves timezone compatibility issues when DJANGO_CELERY_BEAT_TZ_AWARE=False by:

Ensuring consistent datetime comparisons in is_due()
Properly handling all combinations of:
- DJANGO_CELERY_BEAT_TZ_AWARE
- USE_TZ

Fixes #924

Technical Changes

1. Core Modifications

File	Changes
`schedulers.py`	- Rewrote `_default_now()` to handle timezone awareness logic hierarchy
	- Replaced `maybe_make_aware` with explicit `make_aware` conversion

📌 Core Changes

File	Changes
`schedulers.py`	- Rewrote `_default_now()` to handle timezone awareness logic hierarchy
	- Replaced `maybe_make_aware` with explicit `make_aware` conversion

… (Issue celery#924)

auvipy

the tests are failing, so the change proposed appears to be not right. what do you think?

… (Issue celery#924)

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

…t with the CELERY_TIMEZONE time zone. (Issue celery#924)

…Y_TIMEZONE. (Issue celery#924)

NeverStopDreamingWang · 2025-08-01T03:53:37Z

Fix: The issue where the local time obtained does not match the CELERY_TIMEZONE.

The previous fix version, DJANGO_CELERY_BEAT_TZ_AWARE = False, required that the local time should be consistent with the CELERY_TIMEZONE timezone.

DJANGO_CELERY_BEAT_TZ_AWARE = False At this point, the local time zone of the system is obtained, and then it is converted to the timezone of self.app.timezone using astimezone to ensure consistency with the Celery timezone.

codecov · 2025-08-01T04:42:44Z

Codecov Report

❌ Patch coverage is 60.00000% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.20%. Comparing base (f1f239c) to head (edbec2d).
⚠️ Report is 48 commits behind head on main.

Files with missing lines	Patch %	Lines
django_celery_beat/schedulers.py	60.00%	4 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #926      +/-   ##
==========================================
- Coverage   88.19%   87.20%   -0.99%     
==========================================
  Files          32       32              
  Lines        1008     1016       +8     
  Branches      105       84      -21     
==========================================
- Hits          889      886       -3     
- Misses        101      110       +9     
- Partials       18       20       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…ssue celery#924)

Copilot

Pull Request Overview

This PR fixes timezone handling issues when DJANGO_CELERY_BEAT_TZ_AWARE=False by improving datetime comparison logic and ensuring consistent timezone behavior across different configuration combinations.

Rewrote _default_now() method to properly handle timezone awareness based on both DJANGO_CELERY_BEAT_TZ_AWARE and USE_TZ settings
Replaced maybe_make_aware with explicit timezone handling logic in is_due() method
Updated test cases to use more realistic datetime generation that matches the new implementation

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
`django_celery_beat/schedulers.py`	Core timezone handling logic improvements in `_default_now()` and `is_due()` methods
`t/unit/test_schedulers.py`	Updated test datetime generation to align with new timezone-aware implementation

…ssue celery#924)

auvipy · 2025-08-05T07:15:15Z

I will need more eyes and bit more time before reaching to a consensus for this

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-04T07:42:41Z

+        # Handle both naive and timezone-aware last_run_at properly
+        if is_naive(self.last_run_at):
+            # Naive datetime - make it aware using app timezone
+            last_run_at_in_tz = make_aware(self.last_run_at, self.app.timezone)
+        else:
+            # Already timezone-aware - convert to app timezone if needed
+            last_run_at_in_tz = self.last_run_at.astimezone(self.app.timezone)


The comment on line 151 is misleading. The make_aware function assumes the naive datetime is in the system's default timezone (settings.TIME_ZONE), not the app timezone. Consider updating the comment to clarify this assumption or use a different approach if the naive datetime should be interpreted as being in the app timezone.

@NeverStopDreamingWang can you please cross check the comment? also if possible increase unit test coverage?

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auvipy

also please, improve test coverage

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

django_celery_beat/schedulers.py:135

is_due() compares now = self._default_now() against self.model.start_time / self.model.expires. When USE_TZ=True but DJANGO_CELERY_BEAT_TZ_AWARE=False, _default_now() currently returns a naive UTC datetime while Django ORM fields are timezone-aware, so these comparisons will raise TypeError: can't compare offset-naive and offset-aware datetimes. Make _default_now() (or the local now used for these comparisons) consistently match Django's USE_TZ behavior, or normalize both sides before comparing.

        # START DATE: only run after the `start_time`, if one exists.
        if self.model.start_time is not None:
            now = self._default_now()
            if now < self.model.start_time:
                # The datetime is before the start date - don't run.
                # send a delay to retry on start_time
                current_tz = now.tzinfo
                start_time = self.model.due_start_time(current_tz)
                time_remaining = start_time - now
                delay = math.ceil(time_remaining.total_seconds())

                return schedules.schedstate(False, delay)

        # EXPIRED TASK: Disable task when expired
        if self.model.expires is not None:
            now = self._default_now()
            if now >= self.model.expires:
                self._disable(self.model)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-01T18:03:17Z

        assert self.app.timezone.key == 'Europe/Berlin'

        # simulate last_run_at from DB - not TZ aware but localtime
-        right_now = datetime.utcnow()
+        right_now = timezone.now().astimezone(self.app.timezone).replace(tzinfo=None)



These tests now build a naive right_now via timezone.now().astimezone(self.app.timezone).replace(tzinfo=None) while the production _default_now() path for DJANGO_CELERY_BEAT_TZ_AWARE=False still returns datetime.utcnow(). As a result, the tests no longer simulate the same kind of value that _default_now() would generate/store, and can mask the UTC-vs-local interpretation bug. Align the test fixtures with the intended storage semantics for naive timestamps (UTC vs app-local) and update the comment accordingly.

Copilot · 2026-03-01T18:03:17Z

+            # Naive datetime - interpret as already in app timezone and attach tzinfo
+            last_run_at_in_tz = make_aware(self.last_run_at, self.app.timezone)


The new naive last_run_at handling assumes naive datetimes are already in self.app.timezone and attaches that tzinfo. But _default_now() still returns datetime.utcnow() (naive UTC) when timezone awareness is disabled, which means values produced/stored by this code path will later be interpreted as local app time and shifted by the timezone offset. Either interpret naive last_run_at as UTC (as the previous maybe_make_aware behavior did) or change _default_now() to return a naive datetime that is actually in self.app.timezone so the assumption is consistent.

Suggested change

# Naive datetime - interpret as already in app timezone and attach tzinfo

last_run_at_in_tz = make_aware(self.last_run_at, self.app.timezone)

# Naive datetime - interpret as UTC (for backwards compatibility)

# and then convert to the app's timezone.

last_run_at_utc = self.last_run_at.replace(tzinfo=datetime.timezone.utc)

last_run_at_in_tz = last_run_at_utc.astimezone(self.app.timezone)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-01T18:40:17Z

        # simulate last_run_at all none, doing the same thing that
        # _default_now() would do
-        right_now = datetime.utcnow()
+        right_now = timezone.now().astimezone(self.app.timezone).replace(tzinfo=None)

        m = self.create_model_crontab(


This test runs with USE_TZ=False, so django.utils.timezone.now() returns a naive datetime. Calling .astimezone(...) on a naive datetime raises ValueError. Use an aware datetime source (e.g., datetime.now(self.app.timezone) or django_celery_beat.utils.aware_now()) before stripping tzinfo, or avoid astimezone() here.

please cross check this

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T06:19:17Z

        # START DATE: only run after the `start_time`, if one exists.
        if self.model.start_time is not None:
            now = self._default_now()
-            if getattr(settings, 'DJANGO_CELERY_BEAT_TZ_AWARE', True):
-                now = maybe_make_aware(self._default_now())
            if now < self.model.start_time:
                # The datetime is before the start date - don't run.
                # send a delay to retry on start_time


When DJANGO_CELERY_BEAT_TZ_AWARE=False, _default_now() returns a naive datetime. If USE_TZ=True, Django will return aware start_time/expires values from the ORM, so comparisons like now < self.model.start_time (and later now >= self.model.expires) will still raise TypeError: can't compare offset-naive and offset-aware datetimes. The comparison logic needs to coerce both operands to the same timezone-awareness in all setting combinations.

Copilot · 2026-03-26T06:19:18Z

+            # Start from Django's notion of "now".
+            current = timezone.now()
+            # If Django returned a naive datetime (e.g. USE_TZ=False), make it
+            # aware in the Celery app's timezone.
+            if is_naive(current):
+                return make_aware(current, timezone=self.app.timezone)
+            # If it's already aware, express it in the Celery app's timezone.
+            return current.astimezone(self.app.timezone)


make_aware is referenced here but not imported/qualified, which will raise a NameError at runtime. Also, this branch passes self.app.timezone directly to make_aware(..., timezone=...) / astimezone(...); elsewhere in this file you already handle self.app.timezone being a str, so _default_now() should normalize it to a tzinfo (e.g., via ZoneInfo) before using it.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T08:14:05Z

+    def _default_now(self):
+        """Return the current time for last_run_at, honoring TZ awareness settings.
+
+        When DJANGO_CELERY_BEAT_TZ_AWARE is True (the default), always return
+        an aware datetime in the Celery app's timezone. This avoids mixing


Missing blank line between method definitions: def _default_now starts immediately after return self.schedule.is_due(...), which hurts readability and violates standard Python style within classes. Add a blank line between these methods.

Suggested change

def _default_now(self):

"""Return the current time for last_run_at, honoring TZ awareness settings.

When DJANGO_CELERY_BEAT_TZ_AWARE is True (the default), always return

an aware datetime in the Celery app's timezone. This avoids mixing

def _default_now(self):

"""Return the current time for last_run_at, honoring TZ awareness settings.

When DJANGO_CELERY_BEAT_TZ_AWARE is True (the default), always return

Copilot · 2026-03-26T08:14:05Z

    def test_entry_and_model_last_run_at_with_utc_no_use_tz(self, monkeypatch):
        old_tz = os.environ.get("TZ")
        os.environ["TZ"] = "Europe/Berlin"
        if hasattr(time, "tzset"):
            time.tzset()
        assert self.app.timezone.key == 'Europe/Berlin'
        # simulate last_run_at from DB - not TZ aware but localtime
-        right_now = datetime.utcnow()
+        right_now = datetime.now(self.app.timezone).replace(tzinfo=None)
        # make sure to use fixed date time


The test name test_entry_and_model_last_run_at_with_utc_no_use_tz is now misleading: right_now is created from datetime.now(self.app.timezone) (local app timezone), not UTC. Consider renaming the test (or adjusting the setup) so the name matches what’s being simulated.

Copilot · 2026-03-26T08:14:05Z

+    def _default_now(self):
+        """Return the current time for last_run_at, honoring TZ awareness settings.
+
+        When DJANGO_CELERY_BEAT_TZ_AWARE is True (the default), always return
+        an aware datetime in the Celery app's timezone. This avoids mixing
+        naive and aware datetimes when comparing against start_time/expires.
+
+        When DJANGO_CELERY_BEAT_TZ_AWARE is False, always return a naive
+        datetime (also in the Celery app's timezone), regardless of USE_TZ.
+        """
+        tz_aware = getattr(settings, 'DJANGO_CELERY_BEAT_TZ_AWARE', True)
+        tz = self.app.timezone
+        if isinstance(tz, str):
+            tz = ZoneInfo(tz)
+        if tz_aware:
+            # Start from Django's notion of "now".
+            current = timezone.now()
+            # If Django returned a naive datetime (e.g. USE_TZ=False), make it
+            # aware in the Celery app's timezone.
+            if is_naive(current):
+                return timezone.make_aware(current, timezone=tz)
+            # If it's already aware, express it in the Celery app's timezone.
+            return current.astimezone(tz)
+        # For tz-unaware beat operation, return a naive datetime representing
+        # the current time in the Celery app's timezone. This keeps the stored
+        # naive value aligned with what is_due() assumes for naive last_run_at.
+        return datetime.datetime.now(tz=tz).replace(tzinfo=None)


The PR claims to handle all combinations of DJANGO_CELERY_BEAT_TZ_AWARE and USE_TZ, but the updated tests only cover USE_TZ=False with DJANGO_CELERY_BEAT_TZ_AWARE=False. Add unit tests for the mismatch cases (USE_TZ=True & DJANGO_CELERY_BEAT_TZ_AWARE=False, and USE_TZ=False & DJANGO_CELERY_BEAT_TZ_AWARE=True), including scenarios where start_time/expires are set to ensure is_due() doesn’t raise and behaves consistently.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: handle timezone correctly when DJANGO_CELERY_BEAT_TZ_AWARE=False…

e5fe235

… (Issue celery#924)

NeverStopDreamingWang mentioned this pull request Jul 31, 2025

DJANGO_CELERY_BEAT_TZ_AWARE = False Time zone usage issue #924

Open

auvipy requested review from auvipy and Copilot July 31, 2025 11:00

This comment was marked as outdated.

Sign in to view

auvipy requested changes Jul 31, 2025

View reviewed changes

NeverStopDreamingWang and others added 2 commits July 31, 2025 20:45

fix: handle timezone correctly when DJANGO_CELERY_BEAT_TZ_AWARE=False…

90eff76

… (Issue celery#924)

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

5fbcd04

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

auvipy requested a review from Copilot July 31, 2025 15:03

This comment was marked as outdated.

Sign in to view

NeverStopDreamingWang added 2 commits August 1, 2025 09:30

fix: The local time obtained from the test sample should be consisten…

cf3a0e5

…t with the CELERY_TIMEZONE time zone. (Issue celery#924)

Merge remote-tracking branch 'origin/main'

027831f

NeverStopDreamingWang requested a review from auvipy August 1, 2025 02:28

fix: The issue where the local time obtained does not match the CELER…

8b49ecc

…Y_TIMEZONE. (Issue celery#924)

auvipy requested a review from Copilot August 1, 2025 04:49

This comment was marked as outdated.

Sign in to view

auvipy and others added 3 commits August 1, 2025 10:51

Update django_celery_beat/schedulers.py

f61ce19

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

fix: Line too long (104 > 88). (Issue celery#924)

6933370

fix: visually indented line with same indent as next logical line. (I…

baa65c9

…ssue celery#924)

auvipy requested a review from Copilot August 4, 2025 09:51

Copilot AI reviewed Aug 4, 2025

View reviewed changes

Comment thread django_celery_beat/schedulers.py Outdated

Comment thread django_celery_beat/schedulers.py Outdated

fix: visually indented line with same indent as next logical line. (I…

343d368

…ssue celery#924)

auvipy requested a review from Copilot October 4, 2025 07:42

Copilot AI reviewed Oct 4, 2025

View reviewed changes

Update django_celery_beat/schedulers.py

ddb88fb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

hugeterry mentioned this pull request Jan 18, 2026

Release 2.7.1 with Django 5.2 support #949

Open

auvipy requested a review from Copilot March 1, 2026 17:58

auvipy requested changes Mar 1, 2026

View reviewed changes

Copilot started reviewing on behalf of auvipy March 1, 2026 17:59 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes

auvipy and others added 2 commits March 2, 2026 00:35

Update django_celery_beat/schedulers.py

5b1a06c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update t/unit/test_schedulers.py

26c54e6

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auvipy requested a review from Copilot March 1, 2026 18:36

Copilot started reviewing on behalf of auvipy March 1, 2026 18:36 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes

auvipy and others added 4 commits March 2, 2026 00:56

Update django_celery_beat/schedulers.py

4880645

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update django_celery_beat/schedulers.py

427a75c

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update t/unit/test_schedulers.py

9f214b6

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update t/unit/test_schedulers.py

d67f550

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auvipy requested a review from Copilot March 1, 2026 18:57

Copilot started reviewing on behalf of auvipy March 1, 2026 18:58 View session

Copilot AI reviewed Mar 1, 2026

View reviewed changes

auvipy and others added 6 commits March 26, 2026 12:12

Update django_celery_beat/schedulers.py

9aab6ec

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update django_celery_beat/schedulers.py

932ad4f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update django_celery_beat/schedulers.py

ca3a217

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update django_celery_beat/schedulers.py

f0fa0c9

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update t/unit/test_schedulers.py

16e04b5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update django_celery_beat/schedulers.py

d7e27ba

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auvipy requested a review from Copilot March 26, 2026 06:13

Copilot started reviewing on behalf of auvipy March 26, 2026 06:14 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Update django_celery_beat/schedulers.py

edbec2d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auvipy requested a review from Copilot March 26, 2026 08:08

Copilot started reviewing on behalf of auvipy March 26, 2026 08:09 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

Update django_celery_beat/schedulers.py

6dfeb20

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

		# Naive datetime - interpret as already in app timezone and attach tzinfo
		last_run_at_in_tz = make_aware(self.last_run_at, self.app.timezone)

-            # Naive datetime - interpret as already in app timezone and attach tzinfo
-            last_run_at_in_tz = make_aware(self.last_run_at, self.app.timezone)
+            # Naive datetime - interpret as UTC (for backwards compatibility)
+            # and then convert to the app's timezone.
+            last_run_at_utc = self.last_run_at.replace(tzinfo=datetime.timezone.utc)
+            last_run_at_in_tz = last_run_at_utc.astimezone(self.app.timezone)

Conversation

NeverStopDreamingWang commented Jul 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Timezone Handling Fix for django-celery-beat (Issue #924)

Description

Technical Changes

1. Core Modifications

📌 Core Changes

Uh oh!

This comment was marked as outdated.

Uh oh!

auvipy left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

NeverStopDreamingWang commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

auvipy commented Aug 5, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Oct 4, 2025

Choose a reason for hiding this comment

Uh oh!

auvipy Oct 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

auvipy left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 1, 2026

Choose a reason for hiding this comment

Uh oh!

auvipy Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

NeverStopDreamingWang commented Jul 31, 2025 •

edited

Loading

NeverStopDreamingWang commented Aug 1, 2025 •

edited

Loading

codecov Bot commented Aug 1, 2025 •

edited

Loading