dramatiq-crontab 1.0.0__tar.gz

dramatiq-crontab-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, voiio GmbH
+
+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.

dramatiq-crontab-1.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.1
+Name: dramatiq-crontab
+Version: 1.0.0
+Summary: Cron style scheduler for asynchronous Dramatiq tasks in Django.
+Keywords: Django,Dramatiq,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.8
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 3.2
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Requires-Dist: dramatiq
+Requires-Dist: apscheduler
+Requires-Dist: django
+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"
+Requires-Dist: dramatiq ; extra == "test"
+Requires-Dist: backports.zoneinfo ; extra == "test" and (python_version<'3.9')
+Project-URL: Changelog, https://github.com/voiio/dramatiq-crontab/releases
+Project-URL: Project-URL, https://github.com/voiio/dramatiq-crontab
+Provides-Extra: redis
+Provides-Extra: sentry
+Provides-Extra: test
+
+# Dramatiq Crontab
+
+![dramtiq-crontab logo: person in front of a schedule](https://raw.githubusercontent.com/voiio/dramatiq-crontab/main/dramatiq-crontab.png)
+
+**Cron style scheduler for asynchronous Dramatiq tasks in Django.**
+
+* setup recurring tasks via crontab syntax
+* lightweight helpers build on robust tools like [Dramatiq][dramatiq] and [APScheduler][apscheduler]
+* [Sentry][sentry] cron monitor support
+
+[![PyPi Version](https://img.shields.io/pypi/v/dramatiq-crontab.svg)](https://pypi.python.org/pypi/dramatiq-crontab/)
+[![Test Coverage](https://codecov.io/gh/voiio/dramatiq-crontab/branch/main/graph/badge.svg)](https://codecov.io/gh/voiio/dramatiq-crontab)
+[![GitHub License](https://img.shields.io/github/license/voiio/dramatiq-crontab)](https://raw.githubusercontent.com/voiio/dramatiq-crontab/master/LICENSE)
+
+## Setup
+
+You need to have [Dramatiq][dramatiq] installed and setup properly.
+
+```ShellSession
+python3 -m pip install dramatiq-crontab
+# or
+python3 -m pip install dramatiq-crontab[sentry]  # with sentry cron monitor support
+```
+
+Add `dramatiq_crontab` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'dramatiq_crontab',
+    # ...
+]
+```
+
+Finally, you lauch the scheduler in a separate process:
+
+```ShellSession
+python3 manage.py crontab
+```
+
+### 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.
+
+```python
+# settings.py
+DRAMATIQ_CRONTAB = {
+    "REDIS_URL": "redis://localhost:6379/0",
+}
+```
+
+## Usage
+
+```python
+# tasks.py
+import dramatiq
+from dramatiq_crontab import cron
+
+
+@cron("*/5 * * * *")  # every 5 minutes
+@dramatiq.actor
+def my_task():
+    my_task.logger.info("Hello World")
+```
+
+### Sentry Cron Monitors
+
+If you use [Sentry][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 dramatiq 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.
+```
+
+[dramatiq]: https://dramatiq.io/
+[apscheduler]: https://apscheduler.readthedocs.io/en/stable/
+[sentry]: https://docs.sentry.io/product/crons/

dramatiq-crontab-1.0.0/README.md

@@ -0,0 +1,91 @@
+# Dramatiq Crontab
+
+![dramtiq-crontab logo: person in front of a schedule](https://raw.githubusercontent.com/voiio/dramatiq-crontab/main/dramatiq-crontab.png)
+
+**Cron style scheduler for asynchronous Dramatiq tasks in Django.**
+
+* setup recurring tasks via crontab syntax
+* lightweight helpers build on robust tools like [Dramatiq][dramatiq] and [APScheduler][apscheduler]
+* [Sentry][sentry] cron monitor support
+
+[![PyPi Version](https://img.shields.io/pypi/v/dramatiq-crontab.svg)](https://pypi.python.org/pypi/dramatiq-crontab/)
+[![Test Coverage](https://codecov.io/gh/voiio/dramatiq-crontab/branch/main/graph/badge.svg)](https://codecov.io/gh/voiio/dramatiq-crontab)
+[![GitHub License](https://img.shields.io/github/license/voiio/dramatiq-crontab)](https://raw.githubusercontent.com/voiio/dramatiq-crontab/master/LICENSE)
+
+## Setup
+
+You need to have [Dramatiq][dramatiq] installed and setup properly.
+
+```ShellSession
+python3 -m pip install dramatiq-crontab
+# or
+python3 -m pip install dramatiq-crontab[sentry]  # with sentry cron monitor support
+```
+
+Add `dramatiq_crontab` to your `INSTALLED_APPS` in `settings.py`:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'dramatiq_crontab',
+    # ...
+]
+```
+
+Finally, you lauch the scheduler in a separate process:
+
+```ShellSession
+python3 manage.py crontab
+```
+
+### 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.
+
+```python
+# settings.py
+DRAMATIQ_CRONTAB = {
+    "REDIS_URL": "redis://localhost:6379/0",
+}
+```
+
+## Usage
+
+```python
+# tasks.py
+import dramatiq
+from dramatiq_crontab import cron
+
+
+@cron("*/5 * * * *")  # every 5 minutes
+@dramatiq.actor
+def my_task():
+    my_task.logger.info("Hello World")
+```
+
+### Sentry Cron Monitors
+
+If you use [Sentry][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 dramatiq 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.
+```
+
+[dramatiq]: https://dramatiq.io/
+[apscheduler]: https://apscheduler.readthedocs.io/en/stable/
+[sentry]: https://docs.sentry.io/product/crons/

dramatiq-crontab-1.0.0/dramatiq_crontab/__init__.py

@@ -0,0 +1,85 @@
+"""Cron style scheduler for asynchronous Dramatiq tasks in Django."""
+
+from apscheduler.schedulers.blocking import BlockingScheduler
+from apscheduler.triggers.cron import CronTrigger
+
+from . import _version
+
+try:
+    from sentry_sdk.crons import monitor
+except ImportError:
+    monitor = None
+
+__version__ = _version.version
+VERSION = _version.version_tuple
+
+
+__all__ = ["cron", "scheduler"]
+
+try:
+    from django.utils import timezone
+except ImportError:
+    timezone = None
+
+
+__all__ = ["cron"]
+
+scheduler = BlockingScheduler()
+
+
+def cron(schedule):
+    """
+    Run task on a scheduler with a cron schedule.
+
+    Usage:
+        @cron("0 0 * * *")
+        @dramatiq.actor
+        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(func):
+        *_, day_of_week = schedule.split(" ")
+
+        if day_of_week.lower() not in (
+            "*",
+            "mon",
+            "tue",
+            "wed",
+            "thu",
+            "fri",
+            "sat",
+            "sun",
+        ):
+            # 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.
+            raise ValueError(
+                "Please use a literal day of week (Mon, Tue, Wed, Thu, Fri, Sat, Sun) or *"
+            )
+
+        fn = getattr(func, "send")
+        if monitor is not None:
+            fn = monitor(func.actor_name)(fn)
+
+        scheduler.add_job(
+            fn,
+            CronTrigger.from_crontab(
+                schedule,
+                timezone=timezone.get_default_timezone(),
+            ),
+            name=func.actor_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 func
+
+    return decorator

dramatiq-crontab-1.0.0/dramatiq_crontab/_version.py

@@ -0,0 +1,4 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)

dramatiq-crontab-1.0.0/dramatiq_crontab/conf.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from django.conf import settings
+
+
+def get_settings():
+    return type(
+        "Settings",
+        (),
+        {
+            "REDIS_URL": None,
+            **getattr(settings, "DRAMATIQ_CRONTAB", {}),
+        },
+    )

dramatiq-crontab-1.0.0/dramatiq_crontab/management/commands/crontab.py

@@ -0,0 +1,96 @@
+import importlib
+import signal
+
+from django.apps import apps
+from django.core.management import BaseCommand
+
+try:
+    import redis
+    from redis.exceptions import LockError
+except ImportError:
+    redis = None
+    LockError = Exception
+
+try:
+    from sentry_sdk import capture_exception
+except ImportError:
+    capture_exception = lambda e: None
+
+from ... import scheduler
+from ...conf import get_settings
+
+
+def kill_softly(signum, frame):
+    """Raise a KeyboardInterrupt to stop the scheduler and release the lock."""
+    raise KeyboardInterrupt("Received SIGTERM!")
+
+
+def get_redis_client():
+    redis_url = get_settings().REDIS_URL
+    if redis and redis_url:
+        return redis.Redis.from_url(redis_url)
+
+
+class Command(BaseCommand):
+    """Run dramatiq 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("dramatiq_crontab.tasks")
+            self.stdout.write("Scheduling heartbeat.")
+        redis = get_redis_client()
+        if redis:
+            try:
+                # Lock scheduler to prevent multiple instances from running.
+                with redis.lock("dramatiq-scheduler", blocking_timeout=0):
+                    self.launch_scheduler()
+            except LockError as e:
+                capture_exception(e)
+                self.stderr.write("Another scheduler is already running.")
+        else:
+            self.launch_scheduler()
+
+    def launch_scheduler(self):
+        signal.signal(signal.SIGTERM, kill_softly)
+        self.stdout.write(self.style.SUCCESS("Starting scheduler…"))
+        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 == "dramatiq_crontab":
+                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

dramatiq-crontab-1.0.0/dramatiq_crontab/tasks.py

@@ -0,0 +1,9 @@
+import dramatiq
+
+from . import cron
+
+
+@cron("* * * * *")
+@dramatiq.actor
+def heartbeat():
+    heartbeat.logger.info("ﮩ٨ـﮩﮩ٨ـ♡ﮩ٨ـﮩﮩ٨ـ")

dramatiq-crontab-1.0.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["flit_core>=3.2", "flit_scm", "wheel"]
+build-backend = "flit_scm:buildapi"
+
+[project]
+name = "dramatiq-crontab"
+authors = [
+  { name = "Rust Saiargaliev", email = "fly.amureki@gmail.com" },
+  { name = "Johannes Maron", email = "johannes@maron.family" },
+  { name = "Mostafa Mohamed", email = "mostafa.anm91@gmail.com" },
+  { name = "Jacqueline Kraus", email = "jacquelinekraus1992@gmail.com" },
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+keywords = ["Django", "Dramatiq", "tasks", "scheduler"]
+dynamic = ["version", "description"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python",
+  "Environment :: Web Environment",
+  "License :: OSI Approved :: BSD License",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Topic :: Communications :: Email",
+  "Topic :: Text Processing :: Markup :: Markdown",
+  "Topic :: Software Development",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Framework :: Django",
+  "Framework :: Django :: 3.2",
+  "Framework :: Django :: 4.1",
+  "Framework :: Django :: 4.2",
+]
+requires-python = ">=3.8"
+dependencies = ["dramatiq", "apscheduler", "django"]
+
+[project.optional-dependencies]
+test = [
+  "pytest",
+  "pytest-cov",
+  "pytest-django",
+  "dramatiq",
+  "backports.zoneinfo;python_version<'3.9'"
+]
+sentry = ["sentry-sdk"]
+redis = ["redis"]
+
+[project.urls]
+Project-URL = "https://github.com/voiio/dramatiq-crontab"
+Changelog = "https://github.com/voiio/dramatiq-crontab/releases"
+
+[tool.flit.module]
+name = "dramatiq_crontab"
+
+[tool.setuptools_scm]
+write_to = "dramatiq_crontab/_version.py"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "--cov --tb=short -rxs"
+testpaths = ["tests"]
+DJANGO_SETTINGS_MODULE = "tests.testapp.settings"
+
+[tool.coverage.run]
+source = ["dramatiq_crontab"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.isort]
+atomic = true
+line_length = 88
+known_first_party = "dramatiq_crontab, tests"
+include_trailing_comma = true
+default_section = "THIRDPARTY"
+combine_as_imports = true
+multi_line_output = 3
+
+[tool.pydocstyle]
+add_ignore = "D1"
+
+[tool.djlint]
+profile="django"
+indent=2
+max_line_length=120
+exclude=".direnv,.venv,venv"