fix: handle timezone correctly when DJANGO_CELERY_BEAT_TZ_AWARE=False (Issue #924)

[NeverStopDreamingWang]

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

Description

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

1. Ensuring consistent datetime comparisons in is_due()
2. 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

[auvipy]

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

[NeverStopDreamingWang]

Dear Copilot Team, Thank you for your thorough review and constructive feedback on this PR—we truly appreciate your expertise in helping refine the timezone handling logic. Below, we address your two key points to clarify the rationale and ensure alignment with Django’s behavior. 1. Use of  "timezone.now()" when  "DJANGO_CELERY_BEAT_TZ_AWARE=False" We understand your concern about  "timezone.now()" returning a timezone-aware datetime when  "USE_TZ=True", even if  "DJANGO_CELERY_BEAT_TZ_AWARE=False". However, this choice is intentional to maintain consistency with Django’s database timezone handling. When  "USE_TZ=True" (Django’s default), Django stores and retrieves datetimes in UTC from the database. The  "timezone.now()" method explicitly returns a timezone-aware datetime in UTC under this condition, ensuring alignment with the database’s UTC-based timestamps. Even when  "DJANGO_CELERY_BEAT_TZ_AWARE=False" (which skips forcing certain datetimes to be timezone-aware), using  "timezone.now()" guarantees that the generated  "now" value matches the UTC timezone of database-stored datetimes. This prevents mismatches during critical comparisons (e.g., checking if a task is due), which rely on consistent timezone contexts. In summary,  "timezone.now()" is the correct choice here because it synchronizes with Django’s UTC-based database operations, regardless of the  "DJANGO_CELERY_BEAT_TZ_AWARE" setting. 2. Removing Timezone Info with  ".replace(tzinfo=None)" We appreciate your caution about potential ambiguity when stripping timezone awareness. In this specific scenario, however, the approach is safe and necessary due to Django’s behavior when  "USE_TZ=False". When  "DJANGO_CELERY_BEAT_TZ_AWARE=True" but  "USE_TZ=False", Django does not auto-convert datetimes to UTC for storage. Instead, it stores them as naive datetimes in the local timezone (configured via  "TIME_ZONE"). To generate a naive datetime that matches this stored format, we first anchor the datetime to  "self.app.timezone" (the explicitly configured timezone) using  "datetime.datetime.now(self.app.timezone)", then strip the timezone info with  ".replace(tzinfo=None)". For example, if  "self.app.timezone" is  "Asia/Shanghai" (UTC+8),  "datetime.datetime.now(self.app.timezone)" produces a timezone-aware datetime like  "2025-07-31 14:30:00+08:00". Stripping the timezone with  ".replace(tzinfo=None)" converts this to a naive datetime  "2025-07-31 14:30:00", which aligns with how Django stores datetimes when  "USE_TZ=False". Using  "datetime.datetime.now()" (without a timezone parameter) would instead return a naive datetime in the system’s local time, which may not match Django’s configured  "TIME_ZONE" when  "USE_TZ=False". Thus, grounding the datetime to  "self.app.timezone" before stripping the timezone ensures accuracy. We hope this clarifies the logic behind these changes. We remain committed to robust timezone handling and welcome further feedback to strengthen the fix. Please feel free to reach out with additional questions—we’re happy to discuss further.

…

---Original--- From: ***@***.***> Date: Thu, Jul 31, 2025 23:04 PM To: ***@***.***>; Cc: ***@***.******@***.***>; Subject: Re: [celery/django-celery-beat] fix: handle timezone correctly whenDJANGO_CELERY_BEAT_TZ_AWARE=False (Issue #924) (PR #926) @Copilot commented on this pull request. Pull Request Overview This PR fixes timezone handling issues in django-celery-beat when DJANGO_CELERY_BEAT_TZ_AWARE=False by ensuring consistent datetime comparisons and properly handling all combinations of timezone settings. Rewrote _default_now() method to handle timezone awareness logic hierarchy more clearly Replaced maybe_make_aware with explicit make_aware conversion for better timezone handling Updated test cases to use timezone.now() instead of datetime.utcnow() for consistency 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 updates in is_due() and _default_now() methods t/unit/test_schedulers.py Updated test cases to use Django's timezone.now() instead of datetime.utcnow() In django_celery_beat/schedulers.py: > + # Use the default time zone time of Django + now = timezone.now() When DJANGO_CELERY_BEAT_TZ_AWARE=False, using timezone.now() will return a timezone-aware datetime if USE_TZ=True, which contradicts the intent of the setting. This should return a naive datetime to be consistent with the setting's purpose. ⬇️ Suggested change - # Use the default time zone time of Django - now = timezone.now() + # Use the default time zone time of Django and convert to naive datetime + now = timezone.now().replace(tzinfo=None) In django_celery_beat/schedulers.py: > + # Remove the time zone information (convert to naive datetime) + now = datetime.datetime.now(self.app.timezone).replace(tzinfo=None) Converting a timezone-aware datetime to naive by removing tzinfo can lead to ambiguous results. Consider using datetime.datetime.now() without timezone parameter to get a truly naive datetime in the local timezone. ⬇️ Suggested change - # Remove the time zone information (convert to naive datetime) - now = datetime.datetime.now(self.app.timezone).replace(tzinfo=None) + # Get a naive datetime object in the local timezone + now = datetime.datetime.now() — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: ***@***.***>

[NeverStopDreamingWang]

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]

Codecov Report

❌ Patch coverage is 80.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.29%. Comparing base (f1f239c) to head (ddb88fb).
⚠️ Report is 13 commits behind head on main.

Files with missing lines	Patch %	Lines
django_celery_beat/schedulers.py	80.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #926      +/-   ##
==========================================
+ Coverage   88.19%   88.29%   +0.09%     
==========================================
  Files          32       32              
  Lines        1008     1008              
  Branches      105      105              
==========================================
+ Hits          889      890       +1     
  Misses        101      101              
+ Partials       18       17       -1     

☔ 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.

[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

[auvipy]

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]

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.

[auvipy]

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