Little documentation & better naming

schedule/__init__.py

@@ -724,7 +724,7 @@ def _schedule_next_run(self) -> None:
             next_run = _move_to_next_weekday(next_run, self.start_day)
 
         if self.at_time is not None:
-            next_run = self._move_to_time(next_run)
+            next_run = self._move_to_at_time(next_run)
 
         period = datetime.timedelta(**{self.unit: interval})
         if interval != 1:
@@ -733,7 +733,7 @@ def _schedule_next_run(self) -> None:
         while next_run <= now:
             next_run += period
 
-        next_run = self._align_utc_offset(
+        next_run = self._correct_utc_offset(
             next_run, fixate_time=(self.at_time is not None)
         )
 
@@ -747,7 +747,10 @@ def _schedule_next_run(self) -> None:
 
         self.next_run = next_run
 
-    def _move_to_time(self, moment: datetime.datetime) -> datetime.datetime:
+    def _move_to_at_time(self, moment: datetime.datetime) -> datetime.datetime:
+        """
+        Takes a datetime and moves the time-component to the job's at_time.
+        """
         if self.at_time is None:
             return moment
 
@@ -763,13 +766,18 @@ def _move_to_time(self, moment: datetime.datetime) -> datetime.datetime:
 
         # When we set the time elements, we might end up in a different UTC-offset than the current offset.
         # This happens when we cross into or out of daylight saving time.
-        moment = self._align_utc_offset(moment, fixate_time=True)
+        moment = self._correct_utc_offset(moment, fixate_time=True)
 
         return moment
 
-    def _align_utc_offset(
+    def _correct_utc_offset(
         self, moment: datetime.datetime, fixate_time: bool
     ) -> datetime.datetime:
+        """
+        Given a datetime, corrects any mistakes in the utc offset.
+        This is similar to pytz' normalize, but adds the ability to attempt
+        keeping the time-component at the same hour/minute/second.
+        """
         if self.at_time_zone is None:
             return moment
         # Normalize corrects the utc-offset to match the timezone

test_schedule.py

@@ -1156,7 +1156,7 @@ def test_tz_invalid_timezone_exceptions(self):
     def test_align_utc_offset_no_timezone(self):
         job = schedule.every().day.at("10:00").do(make_mock_job())
         now = datetime.datetime(2024, 5, 11, 10, 30, 55, 0)
-        aligned_time = job._align_utc_offset(now, fixate_time=True)
+        aligned_time = job._correct_utc_offset(now, fixate_time=True)
         self.assertEqual(now, aligned_time)
 
     def setup_utc_offset_test(self):
@@ -1175,14 +1175,14 @@ def setup_utc_offset_test(self):
     def test_align_utc_offset_no_change(self):
         (job, tz) = self.setup_utc_offset_test()
         now = tz.localize(datetime.datetime(2023, 3, 26, 1, 30))
-        aligned_time = job._align_utc_offset(now, fixate_time=False)
+        aligned_time = job._correct_utc_offset(now, fixate_time=False)
         self.assertEqual(now, aligned_time)
 
     def test_align_utc_offset_with_dst_gap(self):
         (job, tz) = self.setup_utc_offset_test()
         # Non-existent time in Berlin timezone
         gap_time = tz.localize(datetime.datetime(2024, 3, 31, 2, 30, 0))
-        aligned_time = job._align_utc_offset(gap_time, fixate_time=True)
+        aligned_time = job._correct_utc_offset(gap_time, fixate_time=True)
 
         assert aligned_time.utcoffset() == datetime.timedelta(hours=2)
         assert aligned_time.day == 31
@@ -1193,7 +1193,7 @@ def test_align_utc_offset_with_dst_fold(self):
         (job, tz) = self.setup_utc_offset_test()
         # This time exists twice, this is the first occurance
         overlap_time = tz.localize(datetime.datetime(2024, 10, 27, 2, 30))
-        aligned_time = job._align_utc_offset(overlap_time, fixate_time=False)
+        aligned_time = job._correct_utc_offset(overlap_time, fixate_time=False)
         # Since the time exists twice, no fixate_time flag should yield the first occurrence
         first_occurrence = tz.localize(datetime.datetime(2024, 10, 27, 2, 30, fold=0))
         self.assertEqual(first_occurrence, aligned_time)
@@ -1206,7 +1206,7 @@ def test_align_utc_offset_with_dst_fold_fixate_1(self):
             hours=1
         )  # puts it at 02:30+02:00 (Which exists once)
 
-        aligned_time = job._align_utc_offset(overlap_time, fixate_time=True)
+        aligned_time = job._correct_utc_offset(overlap_time, fixate_time=True)
         # The time should not have moved, because the original time is valid
         assert aligned_time.utcoffset() == datetime.timedelta(hours=2)
         assert aligned_time.hour == 2
@@ -1219,7 +1219,7 @@ def test_align_utc_offset_with_dst_fold_fixate_2(self):
         overlap_time = tz.localize(datetime.datetime(2024, 10, 27, 2, 30), is_dst=False)
         # The time 2024-10-27 02:30:00+01:00 exists once
 
-        aligned_time = job._align_utc_offset(overlap_time, fixate_time=True)
+        aligned_time = job._correct_utc_offset(overlap_time, fixate_time=True)
         # The time was valid, should not have been moved
         assert aligned_time.utcoffset() == datetime.timedelta(hours=1)
         assert aligned_time.hour == 2
@@ -1232,7 +1232,7 @@ def test_align_utc_offset_after_fold_fixate(self):
         duplicate_time = tz.localize(datetime.datetime(2024, 10, 27, 2, 30))
         duplicate_time += datetime.timedelta(hours=1)
 
-        aligned_time = job._align_utc_offset(duplicate_time, fixate_time=False)
+        aligned_time = job._correct_utc_offset(duplicate_time, fixate_time=False)
 
         assert aligned_time.utcoffset() == datetime.timedelta(hours=1)
         assert aligned_time.hour == 3