django-crontask 1.0.0__py3-none-any.whl

crontask/__init__.py

@@ -0,0 +1,133 @@
+"""Cron style scheduler for Django's task framework."""
+
+from unittest.mock import Mock
+
+from apscheduler.schedulers.base import STATE_STOPPED
+from apscheduler.schedulers.blocking import BlockingScheduler
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.triggers.interval import IntervalTrigger
+from django.utils import timezone
+
+from . import _version
+
+try:
+    from sentry_sdk.crons import monitor
+except ImportError:
+    monitor = None
+
+__version__ = _version.version
+VERSION = _version.version_tuple
+
+__all__ = ["cron", "interval", "scheduler"]
+
+
+class LazyBlockingScheduler(BlockingScheduler):
+    """Avoid annoying info logs for pending jobs."""
+
+    def add_job(self, *args, **kwargs):
+        logger = self._logger
+        if self.state == STATE_STOPPED:
+            # We don't want to schedule jobs before the scheduler is started.
+            self._logger = Mock()
+        super().add_job(*args, **kwargs)
+        self._logger = logger
+
+
+scheduler = LazyBlockingScheduler()
+
+
+def cron(schedule):
+    """
+    Run task on a scheduler with a cron schedule.
+
+    Usage:
+        @cron("0 0 * * *")
+        @task
+        def cron_test():
+            print("Cron test")
+
+
+    Please don't forget to set up a sentry monitor for the actor, otherwise you won't
+    get any notifications if the cron job fails.
+
+    The monitor slug is your actor name, the schedule should be set to the same
+    cron schedule as the cron decorator. The schedule type should be set to cron.
+    The monitors timezone should be set to Europe/Berlin.
+    """
+
+    def decorator(task):
+        *_, day_schedule = schedule.split(" ")
+
+        # CronTrigger uses Python's timezone dependent first weekday,
+        # so in Berlin monday is 0 and sunday is 6. We use literals to avoid
+        # confusion. Literals are also more readable and crontab conform.
+        if any(i.isdigit() for i in day_schedule):
+            raise ValueError(
+                "Please use a literal day of week (Mon, Tue, Wed, Thu, Fri, Sat, Sun) or *"
+            )
+
+        if monitor is not None:
+            task = type(task)(
+                priority=task.priority,
+                func=monitor(task.name)(task.func),
+                queue_name=task.queue_name,
+                backend=task.backend,
+                takes_context=task.takes_context,
+                run_after=task.run_after,
+            )
+
+        scheduler.add_job(
+            task.enqueue,
+            CronTrigger.from_crontab(
+                schedule,
+                timezone=timezone.get_default_timezone(),
+            ),
+            name=task.name,
+        )
+        # We don't add the Sentry monitor on the actor itself, because we only want to
+        # monitor the cron job, not the actor itself, or it's direct invocations.
+        return task
+
+    return decorator
+
+
+def interval(*, seconds):
+    """
+    Run task on a periodic interval.
+
+    Usage:
+        @interval(seconds=30)
+        @task
+        def interval_test():
+            print("Interval test")
+
+    Please note that the interval is relative to the time the scheduler is started. For
+    example, if you start the scheduler at 12:00:00, the first run will be at 12:00:30.
+    However, if you restart the scheduler at 12:00:15, the first run will be at
+    12:00:45.
+
+    For an interval that is consistent with the clock, use the `cron` decorator instead.
+    """
+
+    def decorator(task):
+        if monitor is not None:
+            task = type(task)(
+                priority=task.priority,
+                func=monitor(task.name)(task.func),
+                queue_name=task.queue_name,
+                backend=task.backend,
+                takes_context=task.takes_context,
+                run_after=task.run_after,
+            )
+
+        scheduler.add_job(
+            task.enqueue,
+            IntervalTrigger(
+                seconds=seconds,
+                timezone=timezone.get_default_timezone(),
+            ),
+            name=task.name,
+        )
+        return task
+
+    return decorator

crontask/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = 'g6bc77cf86'

crontask/conf.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from django.conf import settings
+
+
+def get_settings():
+    return type(
+        "Settings",
+        (),
+        {
+            "REDIS_URL": None,
+            "LOCK_REFRESH_INTERVAL": 5,
+            "LOCK_TIMEOUT": 10,
+            "LOCK_BLOCKING_TIMEOUT": 15,
+            **getattr(settings, "CRONTASK", {}),
+        },
+    )

crontask/management/commands/crontask.py

@@ -0,0 +1,99 @@
+import importlib
+import signal
+
+from apscheduler.triggers.interval import IntervalTrigger
+from django.apps import apps
+from django.core.management import BaseCommand
+
+from ... import conf, utils
+
+try:
+    from sentry_sdk import capture_exception
+except ImportError:
+    capture_exception = lambda e: None  # noqa: E731
+
+from ... import scheduler
+
+
+def kill_softly(signum, frame):
+    """Raise a KeyboardInterrupt to stop the scheduler and release the lock."""
+    signame = signal.Signals(signum).name
+    raise KeyboardInterrupt(f"Received {signame} ({signum}), shutting down…")
+
+
+class Command(BaseCommand):
+    """Run task scheduler for all tasks with the `cron` decorator."""
+
+    help = __doc__
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--no-task-loading",
+            action="store_true",
+            help="Don't load tasks from installed apps.",
+        )
+        parser.add_argument(
+            "--no-heartbeat",
+            action="store_true",
+            help="Don't start the heartbeat actor.",
+        )
+
+    def handle(self, *args, **options):
+        if not options["no_task_loading"]:
+            self.load_tasks(options)
+        if not options["no_heartbeat"]:
+            importlib.import_module("crontask.tasks")
+            self.stdout.write("Scheduling heartbeat.")
+        try:
+            if not isinstance(utils.lock, utils.FakeLock):
+                self.stdout.write("Acquiring lock…")
+            # Lock scheduler to prevent multiple instances from running.
+            with utils.lock as lock:
+                self.launch_scheduler(lock, scheduler)
+        except utils.LockNotOwnedError as e:
+            capture_exception(e)
+            self.stderr.write(
+                "The lock is no longer owned by the scheduler. Shutting down."
+            )
+        except utils.LockError as e:
+            capture_exception(e)
+            self.stderr.write("Another scheduler is already running.")
+
+    def launch_scheduler(self, lock, scheduler):
+        signal.signal(signal.SIGHUP, kill_softly)
+        signal.signal(signal.SIGTERM, kill_softly)
+        signal.signal(signal.SIGINT, kill_softly)
+        self.stdout.write(self.style.SUCCESS("Starting scheduler…"))
+        # Periodically extend TTL of lock if needed
+        # https://redis-py.readthedocs.io/en/stable/lock.html#redis.lock.Lock.extend
+        scheduler.add_job(
+            utils.extend_lock,
+            IntervalTrigger(seconds=conf.get_settings().LOCK_REFRESH_INTERVAL),
+            args=(lock, scheduler),
+            name="contask.utils.lock.extend",
+        )
+        try:
+            scheduler.start()
+        except KeyboardInterrupt as e:
+            self.stdout.write(self.style.WARNING(str(e)))
+            self.stdout.write(self.style.NOTICE("Shutting down scheduler…"))
+            scheduler.shutdown()
+
+    def load_tasks(self, options):
+        """
+        Load all tasks modules within installed apps.
+
+        If they are not imported, they will not have registered
+        their tasks with the scheduler.
+        """
+        for app in apps.get_app_configs():
+            if app.name == "contask":
+                continue
+            if app.ready:
+                try:
+                    importlib.import_module(f"{app.name}.tasks")
+                    self.stdout.write(
+                        f"Loaded tasks from {self.style.NOTICE(app.name)}."
+                    )
+                except ImportError:
+                    pass

crontask/tasks.py

@@ -0,0 +1,13 @@
+import logging
+
+from django.tasks import task
+
+from . import cron
+
+logger = logging.getLogger(__name__)
+
+
+@cron("* * * * *")
+@task
+def heartbeat():
+    logger.info("ﮩ٨ـﮩﮩ٨ـ♡ﮩ٨ـﮩﮩ٨ـ")

crontask/utils.py

@@ -0,0 +1,45 @@
+from crontask.conf import get_settings
+
+__all__ = ["LockError", "lock"]
+
+
+class FakeLock:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+    def extend(self, additional_time=None, replace_ttl=False):
+        return True
+
+
+if redis_url := get_settings().REDIS_URL:
+    import redis
+    from redis.exceptions import LockError, LockNotOwnedError  # noqa
+
+    redis_client = redis.Redis.from_url(redis_url)
+    lock = redis_client.lock(
+        "crontask-lock",
+        blocking_timeout=get_settings().LOCK_BLOCKING_TIMEOUT,
+        timeout=get_settings().LOCK_TIMEOUT,
+        thread_local=False,
+    )
+else:
+
+    class LockError(Exception):
+        pass
+
+    class LockNotOwnedError(LockError):
+        pass
+
+    lock = FakeLock()
+
+
+def extend_lock(lock, scheduler):
+    """Extend the lock for a scheduler or shut it down."""
+    try:
+        lock.extend(get_settings().LOCK_TIMEOUT, True)
+    except LockError:
+        scheduler.shutdown()
+        raise

django_crontask-1.0.0.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: django-crontask
+Version: 1.0.0
+Summary: Cron style scheduler for Django's task framework.
+Keywords: Django,cron,tasks,scheduler
+Author-email: Rust Saiargaliev <fly.amureki@gmail.com>, Johannes Maron <johannes@maron.family>, Mostafa Mohamed <mostafa.anm91@gmail.com>, Jacqueline Kraus <jacquelinekraus1992@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+License-File: LICENSE
+Requires-Dist: apscheduler
+Requires-Dist: django>=6.0
+Requires-Dist: redis ; extra == "redis"
+Requires-Dist: sentry-sdk ; extra == "sentry"
+Requires-Dist: pytest ; extra == "test"
+Requires-Dist: pytest-cov ; extra == "test"
+Requires-Dist: pytest-django ; extra == "test"
+Project-URL: Changelog, https://github.com/codingjoe/django-crontask/releases
+Project-URL: Project-URL, https://github.com/codingjoe/django-crontask
+Provides-Extra: redis
+Provides-Extra: sentry
+Provides-Extra: test
+
+# Django CronTask
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./images/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="./images/logo-light.svg">
+    <img alt="esimport: Blazing fast ESM compiler and importmap generator" src="./images/logo-light.svg">
+  </picture>
+</p>
+
+**Cron style scheduler for asynchronous tasks in Django.**
+
+- setup recurring tasks via crontab syntax
+- lightweight helpers build [APScheduler]
+- [Sentry] cron monitor support
+
+[![PyPi Version](https://img.shields.io/pypi/v/django-crontask.svg)](https://pypi.python.org/pypi/django-crontask/)
+[![Test Coverage](https://codecov.io/gh/codingjoe/django-crontask/branch/main/graph/badge.svg)](https://codecov.io/gh/codingjoe/django-crontask)
+[![GitHub License](https://img.shields.io/github/license/codingjoe/django-crontask)](https://raw.githubusercontent.com/codingjoe/django-crontask/master/LICENSE)
+
+## Setup
+
+You need to have [Django's Task framework][django-tasks] setup properly.
+
+```ShellSession
+python3 -m pip install django-crontask
+# or
+python3 -m pip install django-crontask[sentry]  # with sentry cron monitor support
+```
+
+Add `crontask` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    "crontask",
+    # ...
+]
+```
+
+Finally, you lauch the scheduler in a separate process:
+
+```ShellSession
+python3 manage.py crontask
+```
+
+### Setup Redis as a lock backend (optional)
+
+If you use Redis as a broker, you can use Redis as a lock backend as well.
+The lock backend is used to prevent multiple instances of the scheduler
+from running at the same time. This is important if you have multiple
+instances of your application running.
+
+```python
+# settings.py
+CRONTASK = {
+    "REDIS_URL": "redis://localhost:6379/0",
+}
+```
+
+## Usage
+
+```python
+# tasks.py
+from django.tasks import task
+from crontask import cron
+
+
+@cron("*/5 * * * *")  # every 5 minutes
+@task
+def my_task():
+    my_task.logger.info("Hello World")
+```
+
+### Interval
+
+If you want to run a task more frequently than once a minute, you can use the
+`interval` decorator.
+
+```python
+# tasks.py
+from django.tasks import task
+from crontask import interval
+
+
+@interval(seconds=30)
+@task
+def my_task():
+    my_task.logger.info("Hello World")
+```
+
+Please note that the interval is relative to the time the scheduler is started.
+For example, if you start the scheduler at 12:00:00, the first run will be at
+12:00:30. However, if you restart the scheduler at 12:00:15, the first run will
+be at 12:00:45.
+
+### Sentry Cron Monitors
+
+If you use [Sentry] you can add cron monitors to your tasks.
+The monitor's slug will be the actor's name. Like `my_task` in the example above.
+
+### The crontab command
+
+```ShellSession
+$ python3 manage.py crontab --help
+usage: manage.py crontab [-h] [--no-task-loading] [--no-heartbeat] [--version] [-v {0,1,2,3}]
+                         [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color]
+                         [--force-color] [--skip-checks]
+
+Run task scheduler for all tasks with the `cron` decorator.
+
+options:
+  -h, --help            show this help message and exit
+  --no-task-loading     Don't load tasks from installed apps.
+  --no-heartbeat        Don't start the heartbeat actor.
+```
+
+[apscheduler]: https://apscheduler.readthedocs.io/en/stable/
+[django-tasks]: https://docs.djangoproject.com/en/6.0/topics/tasks/
+[sentry]: https://docs.sentry.io/product/crons/
+

django_crontask-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+crontask/__init__.py,sha256=wKdFUbifg1Aas1O_JivgUaOeFCyeRJr43c9rIVEFQbU,4023
+crontask/_version.py,sha256=nmABswtRZESJbYL80328NqscwdgtDAHAxjah3c4EY5w,712
+crontask/conf.py,sha256=Xpkf3XqcBfAVmVNPk3iub1YuP7GA7VNQMEntzX7FdmI,360
+crontask/tasks.py,sha256=QJvg5nH7kEoQRMKkhjmqEjtaD5xGK5lJckQYqgvDdJU,205
+crontask/utils.py,sha256=j_0UISFmjYiyYHU5-hXM9Zqd3eTZ9tz01kfP28GpGGg,1017
+crontask/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crontask/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crontask/management/commands/crontask.py,sha256=fk5KK3Ik68kC8bqcj3CR3JZrIv_ysGTWg7bRWN1KYyI,3489
+django_crontask-1.0.0.dist-info/licenses/LICENSE,sha256=Coot8xpmcvR9BOTZs8b0zU6-FIfvh3Pjh8ktxvSzTRc,1528
+django_crontask-1.0.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_crontask-1.0.0.dist-info/METADATA,sha256=NfpBxhvHYBWhxmjedZk02TrhuhTta4ZFeU1xTMIMy7M,5184
+django_crontask-1.0.0.dist-info/RECORD,,

django_crontask-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

django_crontask-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Johannes Maron, voiio GmbH & contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.