zenpulse-scheduler 0.1.0__py3-none-any.whl

zenpulse_scheduler/admin.py

@@ -0,0 +1,49 @@
+from django.contrib import admin
+from .models import ScheduleConfig, JobExecutionLog
+from .registry import JobRegistry
+
+@admin.register(ScheduleConfig)
+class ScheduleConfigAdmin(admin.ModelAdmin):
+    list_display = (
+        'job_key', 'enabled', 'trigger_type', 'schedule_display', 
+        'log_policy', 'updated_at'
+    )
+    list_filter = ('enabled', 'trigger_type', 'log_policy')
+    search_fields = ('job_key',)
+    
+    def schedule_display(self, obj):
+        if obj.trigger_type == 'interval':
+            return f"Every {obj.interval_value} {obj.interval_unit}"
+        else:
+            return f"{obj.cron_minute} {obj.cron_hour} {obj.cron_day} {obj.cron_month} {obj.cron_day_of_week}"
+    
+    schedule_display.short_description = "Schedule"
+
+    def formfield_for_choice_field(self, db_field, request, **kwargs):
+        if db_field.name == 'job_key':
+             # Populate with registered jobs dynamically?
+             # Standard CharField with choices is tricky if we want to allow typing new ones (if code updated but registry not loaded in admin process context fully).
+             # But if we can inspect registry, we can offer choices.
+             # Admin runs in WSGI, Registry jobs might be loaded if apps.ready imports them?
+             # Usually jobs are in app/jobs.py. If those aren't imported, Registry is empty.
+             # Let's simple Text Input for now with help_text.
+             pass
+        return super().formfield_for_choice_field(db_field, request, **kwargs)
+
+@admin.register(JobExecutionLog)
+class JobExecutionLogAdmin(admin.ModelAdmin):
+    list_display = ('job_key', 'status', 'run_time_display', 'duration_ms')
+    list_filter = ('job_key', 'status', 'run_time')
+    readonly_fields = ('run_time', 'traceback', 'exception_message', 'hostname', 'pid')
+
+    def run_time_display(self, obj):
+        return obj.run_time.strftime("%Y-%m-%d %H:%M:%S")
+    
+    run_time_display.admin_order_field = 'run_time'
+    run_time_display.short_description = 'Run Time'
+    
+    def has_add_permission(self, request):
+        return False
+    
+    def has_change_permission(self, request, obj=None):
+        return False

zenpulse_scheduler/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+class ZenPulseSchedulerConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'zenpulse_scheduler'

zenpulse_scheduler/engine.py

@@ -0,0 +1,87 @@
+import time
+import signal
+import sys
+import logging
+from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.jobstores.memory import MemoryJobStore
+from apscheduler.executors.pool import ThreadPoolExecutor
+from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR
+
+from django.conf import settings
+from .sync import sync_jobs
+from .listeners import handle_job_execution
+from .locks import get_best_lock
+
+logger = logging.getLogger(__name__)
+
+class ZenPulseEngine:
+    def __init__(self, sync_interval=10, use_lock=False):
+        self.sync_interval = sync_interval
+        self.use_lock = use_lock
+        self.lock = get_best_lock() if use_lock else None
+        self.running = False
+        
+        self.scheduler = BackgroundScheduler(
+            jobstores={'default': MemoryJobStore()},
+            executors={'default': ThreadPoolExecutor(20)},
+            job_defaults={
+                'coalesce': True,
+                'max_instances': 1
+            },
+            timezone=getattr(settings, 'TIME_ZONE', 'UTC')
+        )
+
+    def start(self):
+        # 1. Acquire Lock
+        if self.use_lock:
+            logger.info("Acquiring lock...")
+            if not self.lock.acquire():
+                logger.error("Could not acquire lock. Another instance is likely running. Exiting.")
+                return
+            logger.info("Lock acquired.")
+
+        # 2. Setup Signal Handlers
+        signal.signal(signal.SIGINT, self.shutdown)
+        signal.signal(signal.SIGTERM, self.shutdown)
+
+        # 3. Setup Listeners
+        self.scheduler.add_listener(handle_job_execution, EVENT_JOB_EXECUTED | EVENT_JOB_ERROR)
+
+        # 4. Start Scheduler
+        self.scheduler.start()
+        self.running = True
+        logger.info("ZenPulse Scheduler started.")
+
+        # Cache for simple change detection: {job_key: (enabled, updated_at_ts)}
+        self.last_synced_data = {}
+
+        # 5. Main Sync Loop
+        try:
+            while self.running:
+                try:
+                    sync_jobs(self.scheduler, self.last_synced_data)
+                except Exception as e:
+                    logger.error(f"Error in sync loop: {e}")
+                
+                # Sleep in small chunks to handle shutdown signals faster
+                for _ in range(self.sync_interval):
+                    if not self.running: 
+                        break
+                    time.sleep(1)
+        except Exception as e:
+            logger.critical(f"Engine crashed: {e}")
+        finally:
+            self.shutdown()
+
+    def shutdown(self, signum=None, frame=None):
+        if not self.running: return # Already stopped
+        
+        logger.info("Shutting down ZenPulse Scheduler...")
+        self.running = False
+        self.scheduler.shutdown()
+        
+        if self.use_lock:
+            self.lock.release()
+            logger.info("Lock released.")
+        
+        logger.info("Shutdown complete.")

zenpulse_scheduler/listeners.py

@@ -0,0 +1,82 @@
+import logging
+import traceback
+import socket
+import os
+from apscheduler.events import EVENT_JOB_EXECUTED, EVENT_JOB_ERROR
+from django.utils import timezone
+from .models import ScheduleConfig, JobExecutionLog
+
+logger = logging.getLogger(__name__)
+
+def get_config_log_policy(job_id):
+    """
+    Helper to fetch log policy for a given job_id.
+    Cache this or fetch from DB? Fetching from DB is safer for real-time updates,
+    but we might want to optimize if high throughput.
+    """
+    try:
+        # job_id in APScheduler will be the job_key from our model
+        config = ScheduleConfig.objects.filter(job_key=job_id).first()
+        if config:
+            return config.log_policy
+    except Exception:
+        pass
+    return 'none' # Default to none if not found
+
+def handle_job_execution(event):
+    """
+    Listener for SUCCESS and ERROR events.
+    """
+    job_id = event.job_id
+    policy = get_config_log_policy(job_id)
+
+    if policy == 'none':
+        return
+
+    is_error = event.exception is not None
+
+    # Logic:
+    # FAILURES: Record only if is_error
+    # ALL: Record everything
+    if policy == 'failures' and not is_error:
+        return
+
+    # Prepare Log Entry
+    status = 'fail' if is_error else 'success'
+    
+    # Calculate duration (APScheduler events might not have duration directly in all versions, 
+    # but let's check `event.retval` or simple generic logging)
+    # Actually `event` object in APScheduler has `scheduled_run_time` and loop time.
+    # We can infer valid duration if we wrap jobs, but here we might rely on estimated diff logic 
+    # or just record 0 if unavailable.
+    # NOTE: APScheduler `JobExecutionEvent` does not strictly capture duration easily without wrapper.
+    # However, we can just log the event.
+    
+    duration = 0.0 # Placeholder, or implement wrapper logic for precise timing later.
+
+    exception_type = None
+    exception_message = None
+    tb = None
+
+    if is_error:
+        exception_type = type(event.exception).__name__
+        exception_message = str(event.exception)
+        try:
+             tb = "".join(traceback.format_tb(event.traceback))
+        except:
+             tb = str(event.traceback)
+
+    try:
+        JobExecutionLog.objects.create(
+            job_key=job_id,
+            status=status,
+            duration_ms=duration, # Update if we implement wrapper timing
+            exception_type=exception_type,
+            exception_message=exception_message,
+            traceback=tb,
+            hostname=socket.gethostname(),
+            pid=os.getpid()
+        )
+    except Exception as e:
+        logger.error(f"Failed to write execution log for job {job_id}: {e}")
+

zenpulse_scheduler/locks.py

@@ -0,0 +1,107 @@
+import sys
+import atexit
+import os
+import logging
+from django.db import connection
+
+logger = logging.getLogger(__name__)
+
+class BaseLock:
+    def acquire(self):
+        raise NotImplementedError
+    
+    def release(self):
+        raise NotImplementedError
+
+class PIDFileLock(BaseLock):
+    def __init__(self, key="zenpulse_scheduler"):
+        self.lockfile = f"/tmp/{key}.lock" if sys.platform != "win32" else f"{os.getenv('TEMP')}/{key}.lock"
+        self._f = None
+
+    def acquire(self):
+        try:
+            if os.path.exists(self.lockfile):
+                # Check if pid exists
+                with open(self.lockfile, 'r') as f:
+                    pid = int(f.read().strip())
+                
+                # Check if process is running
+                try:
+                    # Signal 0 checks if process exists (Unix) or OpenProcess (Windows)
+                    os.kill(pid, 0)
+                    logger.warning(f"Lock file exists and process {pid} is running.")
+                    return False
+                except OSError:
+                    # Process dead, safe to take over
+                    pass
+            
+            self._f = open(self.lockfile, 'w')
+            self._f.write(str(os.getpid()))
+            self._f.flush()
+            atexit.register(self.release)
+            return True
+        except Exception as e:
+            logger.error(f"Failed to acquire PID lock: {e}")
+            return False
+
+    def release(self):
+        try:
+            if self._f:
+                self._f.close()
+                os.remove(self.lockfile)
+                self._f = None
+        except Exception:
+            pass
+
+class DatabaseAdvisoryLock(BaseLock):
+    """
+    Attempts to use DB-specific advisory locks.
+    Supports PostgreSQL and MySQL.
+    """
+    LOCK_ID = 808080 # arbitrary integer for advisory lock
+
+    def __init__(self):
+        self.acquired = False
+
+    def acquire(self):
+        if connection.vendor == 'postgresql':
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT pg_try_advisory_lock(%s)", [self.LOCK_ID])
+                row = cursor.fetchone()
+                if row and row[0]:
+                    self.acquired = True
+                    return True
+                return False
+        elif connection.vendor == 'mysql':
+            with connection.cursor() as cursor:
+                # GET_LOCK returns 1 if success, 0 if timeout, NULL on error
+                cursor.execute("SELECT GET_LOCK(%s, 0)", [str(self.LOCK_ID)])
+                row = cursor.fetchone()
+                if row and row[0] == 1:
+                    self.acquired = True
+                    return True
+                return False
+        else:
+            logger.warning("DatabaseAdvisoryLock not supported for this vendor. Falling back to PID lock.")
+            return PIDFileLock().acquire() # Fallback
+
+    def release(self):
+        if not self.acquired:
+            return
+
+        if connection.vendor == 'postgresql':
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT pg_advisory_unlock(%s)", [self.LOCK_ID])
+        elif connection.vendor == 'mysql':
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT RELEASE_LOCK(%s)", [str(self.LOCK_ID)])
+        
+        self.acquired = False
+
+def get_best_lock():
+    # Prefer DB lock usually, but for simplicity/universality check config or default to PID?
+    # User asked for DB lock optional.
+    # Let's try DB lock, if not supported (sqlite), fallback to PID.
+    if connection.vendor in ('postgresql', 'mysql'):
+        return DatabaseAdvisoryLock()
+    return PIDFileLock()

zenpulse_scheduler/management/commands/run_zenpulse_scheduler.py

@@ -0,0 +1,27 @@
+from django.core.management.base import BaseCommand
+from zenpulse_scheduler.engine import ZenPulseEngine
+
+class Command(BaseCommand):
+    help = 'Runs the ZenPulse Scheduler'
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            '--sync-every',
+            type=int,
+            default=10,
+            help='Seconds between DB config syncs (default: 10)'
+        )
+        parser.add_argument(
+            '--lock',
+            action='store_true',
+            help='Enable single-instance locking (DB or File)'
+        )
+
+    def handle(self, *args, **options):
+        sync_interval = options['sync_every']
+        use_lock = options['lock']
+        
+        self.stdout.write(self.style.SUCCESS(f"Starting ZenPulse Scheduler (Sync: {sync_interval}s, Lock: {use_lock})..."))
+        
+        engine = ZenPulseEngine(sync_interval=sync_interval, use_lock=use_lock)
+        engine.start()

zenpulse_scheduler/models.py

@@ -0,0 +1,86 @@
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+
+class ScheduleConfig(models.Model):
+    TRIGGER_CHOICES = (
+        ('interval', 'Interval'),
+        ('cron', 'Cron'),
+    )
+
+    LOG_POLICY_CHOICES = (
+        ('none', 'None'),
+        ('failures', 'Failures Only'),
+        ('all', 'All Executions'),
+    )
+
+    INTERVAL_UNIT_CHOICES = (
+        ('seconds', 'Seconds'),
+        ('minutes', 'Minutes'),
+        ('hours', 'Hours'),
+        ('days', 'Days'),
+        ('weeks', 'Weeks'),
+    )
+
+    job_key = models.CharField(
+        max_length=255, 
+        unique=True, 
+        help_text="Unique key identifier for the job (must match the registered job name)."
+    )
+    enabled = models.BooleanField(default=True)
+    trigger_type = models.CharField(max_length=20, choices=TRIGGER_CHOICES, default='interval')
+    
+    # Interval Fields
+    interval_value = models.IntegerField(null=True, blank=True, help_text="Value for interval trigger.")
+    interval_unit = models.CharField(
+        max_length=20, 
+        choices=INTERVAL_UNIT_CHOICES, 
+        default='minutes',
+        null=True, blank=True
+    )
+
+    # Cron Fields
+    cron_minute = models.CharField(max_length=100, default='*', help_text="Cron minute (0-59 or *)")
+    cron_hour = models.CharField(max_length=100, default='*', help_text="Cron hour (0-23 or *)")
+    cron_day = models.CharField(max_length=100, default='*', help_text="Cron day of month (1-31 or *)")
+    cron_month = models.CharField(max_length=100, default='*', help_text="Cron month (1-12 or *)")
+    cron_day_of_week = models.CharField(max_length=100, default='*', help_text="Cron day of week (0-6 or mon,tue... or *)")
+
+    # Options
+    max_instances = models.IntegerField(default=1, help_text="Maximum number of concurrently running instances allowed.")
+    coalesce = models.BooleanField(default=True, help_text="Combine missed runs into one.")
+    misfire_grace_time = models.IntegerField(default=60, help_text="Seconds after the designated run time that the job is still allowed to run.")
+    
+    log_policy = models.CharField(max_length=20, choices=LOG_POLICY_CHOICES, default='failures')
+    
+    updated_at = models.DateTimeField(auto_now=True)
+
+    def __str__(self):
+        return f"{self.job_key} ({self.trigger_type})"
+
+class JobExecutionLog(models.Model):
+    STATUS_CHOICES = (
+        ('success', 'Success'),
+        ('fail', 'Fail'),
+    )
+
+    job_key = models.CharField(max_length=255, db_index=True)
+    run_time = models.DateTimeField(auto_now_add=True)
+    status = models.CharField(max_length=10, choices=STATUS_CHOICES)
+    duration_ms = models.FloatField(help_text="Execution duration in milliseconds")
+    
+    exception_type = models.CharField(max_length=255, null=True, blank=True)
+    exception_message = models.TextField(null=True, blank=True)
+    traceback = models.TextField(null=True, blank=True)
+    
+    hostname = models.CharField(max_length=255, null=True, blank=True)
+    pid = models.IntegerField(null=True, blank=True)
+
+    class Meta:
+        ordering = ['-run_time']
+        indexes = [
+            models.Index(fields=['job_key', 'status']),
+            models.Index(fields=['run_time']),
+        ]
+
+    def __str__(self):
+        return f"{self.job_key} - {self.status} at {self.run_time}"

zenpulse_scheduler/registry.py

@@ -0,0 +1,34 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
+class JobRegistry:
+    _registry = {}
+
+    @classmethod
+    def register(cls, name):
+        def decorator(func):
+            if name in cls._registry:
+                logger.warning(f"Job with key '{name}' already registered. Overwriting.")
+            cls._registry[name] = func
+            return func
+        return decorator
+
+    @classmethod
+    def get_job(cls, name):
+        return cls._registry.get(name)
+
+    @classmethod
+    def get_all_jobs(cls):
+        return cls._registry
+
+# Initializer for the decorator
+def zenpulse_job(name):
+    """
+    Decorator to register a function as a ZenPulse job.
+    Usage:
+    @zenpulse_job('my_unique_job_key')
+    def my_job_function():
+        pass
+    """
+    return JobRegistry.register(name)

zenpulse_scheduler/sync.py

@@ -0,0 +1,76 @@
+import logging
+from .models import ScheduleConfig
+from .registry import JobRegistry
+from .triggers import build_trigger
+
+logger = logging.getLogger(__name__)
+
+def sync_jobs(scheduler, last_synced_data):
+    """
+    Reconciles the DB ScheduleConfig with the in-memory APScheduler.
+    last_synced_data: dict {job_key: (enabled, updated_at_timestamp)}
+    """
+    logger.debug("Starting sync_jobs...")
+    # print("DEBUG: Syncing jobs...") 
+    configs = ScheduleConfig.objects.all()
+    # print(f"DEBUG: Found {len(configs)} configs in DB.")
+    
+    # Track which jobs we've seen in the DB to handle removals
+    active_db_jobs = set()
+
+    for config in configs:
+        job_key = config.job_key
+        active_db_jobs.add(job_key)
+        
+        # Check cache to see if update is needed
+        current_state = (config.enabled, config.updated_at.timestamp())
+        if job_key in last_synced_data and last_synced_data[job_key] == current_state:
+            # No changes, skip
+            continue
+            
+        last_synced_data[job_key] = current_state
+
+        # 1. Check if job is in registry
+        func = JobRegistry.get_job(job_key)
+        if not func:
+            logger.warning(f"Job '{job_key}' found in config but NOT in registry. Skipping.")
+            continue
+        
+        # 2. Check if job exists in scheduler
+        existing_job = scheduler.get_job(job_key)
+        
+        # 3. Handle Enabled/Disabled
+        if not config.enabled:
+            # If exists, remove it
+            if existing_job:
+                logger.info(f"Removing disabled job: {job_key}")
+                scheduler.remove_job(job_key)
+            continue
+        
+        # 4. Handle Active Jobs
+        trigger = build_trigger(config)
+        
+        kwargs = {
+            'id': job_key,
+            'name': job_key,
+            'func': func,
+            'trigger': trigger,
+            'replace_existing': True,
+            'coalesce': config.coalesce,
+            'max_instances': config.max_instances,
+            'misfire_grace_time': config.misfire_grace_time,
+        }
+
+        # Update or Add
+        logger.info(f"Syncing job: {job_key}")
+        try:
+            scheduler.add_job(**kwargs)
+        except Exception as e:
+            logger.error(f"Failed to add/update job {job_key}: {e}")
+
+    # 5. Remove jobs that are in Scheduler but NOT in Config (or deleted from DB)
+    # Be careful not to remove internal scheduler jobs if any (usually none in MemoryJobStore unless added manually)
+    for job in scheduler.get_jobs():
+        if job.id not in active_db_jobs:
+            logger.info(f"Job {job.id} not in DB config. Removing.")
+            scheduler.remove_job(job.id)

zenpulse_scheduler/triggers.py

@@ -0,0 +1,42 @@
+from apscheduler.triggers.interval import IntervalTrigger
+from apscheduler.triggers.cron import CronTrigger
+
+def build_trigger(config):
+    """
+    Builds an APScheduler trigger (IntervalTrigger or CronTrigger) 
+    based on the ScheduleConfig model instance.
+    """
+    if config.trigger_type == 'interval':
+        # Default to minutes if not specified or invalid
+        unit = config.interval_unit or 'minutes'
+        value = config.interval_value or 1
+        
+        # Mapping unit to arguments for IntervalTrigger
+        kwargs = {}
+        if unit == 'seconds':
+            kwargs['seconds'] = value
+        elif unit == 'minutes':
+            kwargs['minutes'] = value
+        elif unit == 'hours':
+            kwargs['hours'] = value
+        elif unit == 'days':
+            kwargs['days'] = value
+        elif unit == 'weeks':
+            kwargs['weeks'] = value
+        else:
+            kwargs['minutes'] = value # Fallback
+            
+        return IntervalTrigger(**kwargs)
+
+    elif config.trigger_type == 'cron':
+        # Use config fields for CronTrigger
+        return CronTrigger(
+            minute=config.cron_minute,
+            hour=config.cron_hour,
+            day=config.cron_day,
+            month=config.cron_month,
+            day_of_week=config.cron_day_of_week,
+            timezone=config.timezone if hasattr(config, 'timezone') and config.timezone else None
+        )
+    
+    return None

zenpulse_scheduler-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: zenpulse_scheduler
+Version: 0.1.0
+Summary: A DB-driven APScheduler for Django
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: django>=3.2
+Requires-Dist: apscheduler>=3.6.3

zenpulse_scheduler-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+zenpulse_scheduler/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zenpulse_scheduler/admin.py,sha256=gyhR_w42OMy-HWP-Ihc7d4xL7-PGZJ4pELndJ83xDiA,2158
+zenpulse_scheduler/apps.py,sha256=-El1L4XXmOT6da9nsavAKkodFodN4H8XHnnc2c9Ync0,166
+zenpulse_scheduler/engine.py,sha256=JBXEg-lCcAwpDLiVMKXWIL5FPP4Seylk1tqzTS5XPSk,2952
+zenpulse_scheduler/listeners.py,sha256=zk6L5jxOKSbQSKkBsqmyfOdbyt_IxL7_N-ayC-sbFIU,2669
+zenpulse_scheduler/locks.py,sha256=iHSUjGrTmZz8G62AWusJna9fy_N-uHMMH7A90vp6Sns,3681
+zenpulse_scheduler/models.py,sha256=c9Vs7ZcQznO2gTxGvEOvDKFRq6NR4DCPWJmk2glJupo,3307
+zenpulse_scheduler/registry.py,sha256=TSvIFq4VgmtXjR77r5LbUh23J5uIHnHoWjyvzi-pQlw,800
+zenpulse_scheduler/sync.py,sha256=KbqbFDuTLmct2s3XWHHKK8zIWGzFgw44xt7ZKqViXKM,2702
+zenpulse_scheduler/triggers.py,sha256=56ucYsxs5UA69802MC8nZAAgR1vpIaqx37RNd6UZRLk,1430
+zenpulse_scheduler/management/commands/run_zenpulse_scheduler.py,sha256=szJj2CV5avKxWi0DIxHiME-rOfqNuKUqwveSA7fS_yQ,915
+zenpulse_scheduler-0.1.0.dist-info/METADATA,sha256=xYvEgIcMP6OiIzhrGJ6XxDdRApbBUkhZGdWtg_biWxw,310
+zenpulse_scheduler-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+zenpulse_scheduler-0.1.0.dist-info/top_level.txt,sha256=6aLspn3Yg8Me-MY6p0DK4NCmWfmLy2j5jxnqOyM0XNo,19
+zenpulse_scheduler-0.1.0.dist-info/RECORD,,

zenpulse_scheduler-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zenpulse_scheduler-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zenpulse_scheduler