feat: add new CronTrigger task type (#1632)

* [feat] Add CronTrigger

* [feat] Add timezone support to CronTrigger

* docs: utc -> tz rename

Signed-off-by: 18 <[email protected]>

* ci: correct from checks.

* docs: specify tz as datetime attribute

I'm aware that datetime is not what it actually is, but we shouldn't be using private data types in our docstrings. Developers will additionally be using it as a reference, not the literal representation when using

Signed-off-by: 18 <[email protected]>

---------

Signed-off-by: 18 <[email protected]>
Co-authored-by: 18 <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

interactions/models/internal/tasks/triggers.py

@@ -1,5 +1,7 @@
 from abc import ABC, abstractmethod
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timedelta, timezone, _TzInfo
+
+from croniter import croniter
 
 __all__ = ("BaseTrigger", "IntervalTrigger", "DateTrigger", "TimeTrigger", "OrTrigger")
 
@@ -140,3 +142,21 @@ def _set_current_trigger(self) -> BaseTrigger | None:
 
     def next_fire(self) -> datetime | None:
         return self.current_trigger.next_fire() if self._set_current_trigger() else None
+
+
+class CronTrigger(BaseTrigger):
+    """
+    Trigger the task based on a cron schedule.
+
+    Attributes:
+        cron str: The cron schedule, use https://crontab.guru for help
+        tz datetime: Whether or not to use UTC for the time (uses timezone information)
+
+    """
+
+    def __init__(self, cron: str, tz: _TzInfo = timezone.utc) -> None:
+        self.cron = cron
+        self.tz = tz
+
+    def next_fire(self) -> datetime | None:
+        return croniter(self.cron, datetime.now(tz=self.tz)).next(datetime)