zenpulse-scheduler 0.1.0__tar.gz

zenpulse_scheduler-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,575 @@
+# ⚡ ZenPulse Scheduler for Django
+
+**Modern, Hybrid, and Zero-Latency Job Scheduler**
+
+ZenPulse Scheduler is a **Developer-First** background job scheduler for Django. Unlike traditional schedulers that either rely on heavy external infrastructure (Redis/Celery) or spam your database with polling queries, ZenPulse uses a **Smart Hybrid Architecture**.
+
+---
+
+## 🌟 Features
+
+- ✅ **No Redis/Celery Required** - Pure Django solution
+- ✅ **Zero DB Impact** - Smart file-based signaling system
+- ✅ **Hybrid Execution** - Config in DB, Runtime in RAM
+- ✅ **Selective Logging** - Log everything, nothing, or only failures
+- ✅ **Live Updates** - Change schedules without restarting
+- ✅ **Multi-Process Safe** - Built-in locking mechanisms
+- ✅ **Interval & Cron Support** - Flexible scheduling options
+
+---
+
+## 📦 Installation
+
+### Step 1: Install the Package
+
+```bash
+pip install zenpulse-scheduler
+```
+
+Or if installing from source:
+
+```bash
+cd /path/to/package
+pip install -e .
+```
+
+### Step 2: Add to Django Settings
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ... other apps
+    'zenpulse_scheduler',
+]
+```
+
+### Step 3: Run Migrations
+
+```bash
+python manage.py migrate
+```
+
+---
+
+## 🚀 Quick Start Guide
+
+### 1. Define Your Job
+
+Create a file (e.g., `yourapp/jobs.py`) and register your job:
+
+```python
+from zenpulse_scheduler.registry import zenpulse_job
+
+@zenpulse_job("send_daily_report")
+def send_daily_report():
+    """Send daily sales report via email"""
+    print("📧 Sending daily report...")
+    # Your business logic here
+```
+
+**Important:** Make sure this file is imported when Django starts. You can do this by:
+
+```python
+# yourapp/apps.py
+from django.apps import AppConfig
+
+class YourAppConfig(AppConfig):
+    name = 'yourapp'
+    
+    def ready(self):
+        import yourapp.jobs  # Import to register jobs
+```
+
+Or import it in your `urls.py`:
+
+```python
+# yourapp/urls.py
+import yourapp.jobs  # Ensure jobs are registered
+
+urlpatterns = [
+    # your urls
+]
+```
+
+### 2. Start the Scheduler
+
+Open a **separate terminal** and run:
+
+```bash
+python manage.py run_zenpulse_scheduler
+```
+
+You should see:
+
+```
+Starting ZenPulse Scheduler (Sync: 10s, Lock: False)...
+```
+
+### 3. Configure via Admin
+
+1. Go to **Django Admin** → **ZenPulse Scheduler** → **Schedule Configs**
+2. Click **Add Schedule Config**
+3. Fill in the details (see Configuration Guide below)
+4. Save
+
+Your job will start running automatically!
+
+---
+
+## 📚 Complete Configuration Guide
+
+All job scheduling is controlled through the **ScheduleConfig** model in Django Admin.
+
+### Core Fields
+
+#### **Job Key** (Required)
+- **Type:** Text (Unique)
+- **Description:** Must match the name you used in `@zenpulse_job("name")`
+- **Example:** `send_daily_report`
+
+#### **Enabled** (Required)
+- **Type:** Checkbox
+- **Description:** Controls whether the job runs
+- **Default:** ✅ Checked (Enabled)
+- **Behavior:**
+  - ✅ Checked → Job runs according to schedule
+  - ❌ Unchecked → Job stops immediately (within next sync interval)
+
+---
+
+### Trigger Configuration
+
+#### **Trigger Type** (Required)
+
+Choose how your job should be scheduled:
+
+| Choice | When to Use | Example |
+|--------|-------------|---------|
+| **Interval** | Repeating tasks that run in a loop | "Check for new emails every 5 minutes" |
+| **Cron** | Tasks that run at specific calendar times | "Send report every Monday at 9 AM" |
+
+---
+
+### Interval Configuration
+
+Use when **Trigger Type** = `Interval`
+
+#### **Interval Value** (Required for Interval)
+- **Type:** Number
+- **Description:** How many units to wait between runs
+- **Example:** `30` (combined with unit below)
+
+#### **Interval Unit** (Required for Interval)
+
+| Unit | Best For | Example Usage |
+|------|----------|---------------|
+| **Seconds** | High-frequency monitoring, heartbeats | `30` seconds = runs every 30 seconds |
+| **Minutes** | Standard periodic tasks | `15` minutes = runs every 15 minutes |
+| **Hours** | Regular updates, data sync | `4` hours = runs every 4 hours |
+| **Days** | Daily routines | `1` day = runs once per day |
+| **Weeks** | Weekly maintenance | `2` weeks = runs every 2 weeks |
+
+**Example Configurations:**
+
+```
+Interval Value: 10, Unit: Minutes → Runs every 10 minutes
+Interval Value: 1, Unit: Hours → Runs every hour
+Interval Value: 30, Unit: Seconds → Runs every 30 seconds
+```
+
+---
+
+### Cron Configuration
+
+Use when **Trigger Type** = `Cron`
+
+All cron fields support:
+- Specific values (e.g., `8` for 8 AM)
+- Wildcards (`*` means "every")
+- Lists (e.g., `mon,wed,fri`)
+- Ranges (e.g., `1-5`)
+
+#### **Cron Minute**
+- **Valid Values:** `0-59` or `*`
+- **Default:** `*` (every minute)
+- **Examples:**
+  - `0` = At the top of the hour
+  - `30` = At 30 minutes past the hour
+  - `*/15` = Every 15 minutes
+
+#### **Cron Hour**
+- **Valid Values:** `0-23` or `*`
+- **Default:** `*` (every hour)
+- **Examples:**
+  - `9` = 9 AM
+  - `14` = 2 PM
+  - `22` = 10 PM
+
+#### **Cron Day (of Month)**
+- **Valid Values:** `1-31` or `*`
+- **Default:** `*` (every day)
+- **Examples:**
+  - `1` = 1st of the month
+  - `15` = 15th of the month
+
+#### **Cron Month**
+- **Valid Values:** `1-12` or `*`
+- **Default:** `*` (every month)
+- **Examples:**
+  - `1` = January
+  - `12` = December
+
+#### **Cron Day of Week**
+- **Valid Values:** `0-6` (0=Sunday) or `mon,tue,wed,thu,fri,sat,sun` or `*`
+- **Default:** `*` (every day)
+- **Examples:**
+  - `mon` = Every Monday
+  - `0` = Every Sunday
+  - `mon,wed,fri` = Monday, Wednesday, Friday
+
+**Example Cron Configurations:**
+
+```
+Daily at 8:30 AM:
+  Minute: 30, Hour: 8, Day: *, Month: *, Day of Week: *
+
+Every Monday at 9 AM:
+  Minute: 0, Hour: 9, Day: *, Month: *, Day of Week: mon
+
+First day of every month at midnight:
+  Minute: 0, Hour: 0, Day: 1, Month: *, Day of Week: *
+
+Every weekday at 6 PM:
+  Minute: 0, Hour: 18, Day: *, Month: *, Day of Week: mon,tue,wed,thu,fri
+```
+
+---
+
+### Advanced Options
+
+#### **Max Instances**
+- **Type:** Number
+- **Default:** `1`
+- **Description:** Maximum number of this job that can run simultaneously
+- **Use Case:** Set to `3` if you want to allow up to 3 parallel executions
+
+#### **Coalesce**
+- **Type:** Checkbox
+- **Default:** ✅ Checked
+- **Description:** If multiple runs were missed (e.g., scheduler was down), combine them into one
+- **Behavior:**
+  - ✅ Checked → Run once to catch up
+  - ❌ Unchecked → Run all missed executions
+
+#### **Misfire Grace Time**
+- **Type:** Number (seconds)
+- **Default:** `60`
+- **Description:** How long after the scheduled time the job can still run
+- **Example:** If job was supposed to run at 10:00 but scheduler was busy, it can still run until 10:01 (60 seconds grace)
+
+---
+
+### Logging Configuration
+
+#### **Log Policy**
+
+Control how much execution history is saved to the database:
+
+| Policy | What Gets Logged | Database Impact | Best For |
+|--------|------------------|-----------------|----------|
+| **None** | Nothing | Zero writes | High-frequency jobs (every few seconds) |
+| **Failures Only** | Only when job crashes | Minimal writes | Production critical jobs (recommended) |
+| **All Executions** | Every success and failure | High writes | Debugging, auditing |
+
+**Recommendation:** Use `Failures Only` for production. This way:
+- ✅ You get full error traces when something breaks
+- ✅ Database stays clean
+- ✅ You can still monitor job health
+
+---
+
+## 🖥️ Admin Panel Examples
+
+### Example 1: Send Email Every 30 Minutes
+
+```
+Job Key: send_email_digest
+Enabled: ✅
+Trigger Type: Interval
+Interval Value: 30
+Interval Unit: Minutes
+Log Policy: Failures Only
+```
+
+### Example 2: Daily Report at 8:30 AM
+
+```
+Job Key: generate_daily_report
+Enabled: ✅
+Trigger Type: Cron
+Cron Minute: 30
+Cron Hour: 8
+Cron Day: *
+Cron Month: *
+Cron Day of Week: *
+Log Policy: All Executions
+```
+
+### Example 3: Weekly Cleanup Every Sunday at Midnight
+
+```
+Job Key: weekly_cleanup
+Enabled: ✅
+Trigger Type: Cron
+Cron Minute: 0
+Cron Hour: 0
+Cron Day: *
+Cron Month: *
+Cron Day of Week: sun
+Log Policy: Failures Only
+```
+
+---
+
+## ⚙️ Running the Scheduler
+
+### Development
+
+```bash
+python manage.py run_zenpulse_scheduler
+```
+
+### Production (with Safety Lock)
+
+```bash
+python manage.py run_zenpulse_scheduler --lock
+```
+
+The `--lock` flag prevents multiple scheduler instances from running simultaneously:
+- **PostgreSQL:** Uses advisory locks (recommended)
+- **MySQL:** Uses `GET_LOCK`
+- **SQLite/Others:** Uses file-based locking
+
+### Custom Sync Interval
+
+By default, the scheduler checks for config changes every 10 seconds. To reduce database queries:
+
+```bash
+python manage.py run_zenpulse_scheduler --sync-every 60
+```
+
+This checks only once per minute. Trade-off: Changes take up to 60 seconds to apply.
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐
+│  Django Admin   │  ← You configure jobs here
+└────────┬────────┘
+         │ Save Config
+         ↓
+┌─────────────────┐
+│    Database     │  ← Stores ScheduleConfig
+└────────┬────────┘
+         │ Sync (every 10s)
+         ↓
+┌─────────────────┐
+│   Scheduler     │  ← Runs in separate process
+│   (Memory)      │
+└────────┬────────┘
+         │ Execute
+         ↓
+┌─────────────────┐
+│   Your Job      │  ← @zenpulse_job decorated function
+└─────────────────┘
+```
+
+**Key Points:**
+1. Configuration lives in **Database** (persistent)
+2. Execution happens in **Memory** (fast)
+3. Scheduler syncs config changes automatically
+4. No Redis or external dependencies needed
+
+---
+
+## 📊 Monitoring Job Execution
+
+### View Execution Logs
+
+Go to **Django Admin** → **ZenPulse Scheduler** → **Job Execution Logs**
+
+You'll see:
+- **Job Key:** Which job ran
+- **Status:** Success or Fail
+- **Run Time:** When it executed (with seconds precision)
+- **Duration:** How long it took (in milliseconds)
+- **Exception Details:** Full traceback if it failed
+
+### Understanding Log Entries
+
+```
+Job Key: send_email_digest
+Status: Success
+Run Time: 2026-02-01 14:30:45
+Duration: 234.5 ms
+```
+
+If a job fails:
+
+```
+Job Key: send_email_digest
+Status: Fail
+Run Time: 2026-02-01 14:30:45
+Exception Type: SMTPException
+Exception Message: Connection refused
+Traceback: [Full Python traceback here]
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Job Not Running?
+
+1. **Check if job is registered:**
+   ```python
+   # In Django shell
+   from zenpulse_scheduler.registry import JobRegistry
+   print(JobRegistry.get_all_jobs())
+   ```
+   Your job should appear in the list.
+
+2. **Check if enabled in Admin:**
+   - Go to Schedule Configs
+   - Verify `Enabled` is checked
+
+3. **Check scheduler is running:**
+   - Look for `Starting ZenPulse Scheduler...` in terminal
+   - Check for any error messages
+
+### Duplicate Executions?
+
+- Make sure only **one** `run_zenpulse_scheduler` process is running
+- Use `--lock` flag in production
+- Check if you accidentally started it in multiple terminals
+
+### Jobs Running at Wrong Time?
+
+- Verify your `TIME_ZONE` setting in Django settings
+- Check cron configuration carefully
+- Use `Interval` for simple repeating tasks
+
+### Database Performance Issues?
+
+- Set `Log Policy` to `None` or `Failures Only`
+- Increase `--sync-every` to reduce config checks
+- Consider archiving old logs periodically
+
+---
+
+## 🚀 Production Deployment
+
+### Using Systemd (Linux)
+
+Create `/etc/systemd/system/zenpulse-scheduler.service`:
+
+```ini
+[Unit]
+Description=ZenPulse Scheduler
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/path/to/your/project
+ExecStart=/path/to/venv/bin/python manage.py run_zenpulse_scheduler --lock --sync-every 30
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl enable zenpulse-scheduler
+sudo systemctl start zenpulse-scheduler
+sudo systemctl status zenpulse-scheduler
+```
+
+### Using Supervisor
+
+```ini
+[program:zenpulse-scheduler]
+command=/path/to/venv/bin/python manage.py run_zenpulse_scheduler --lock
+directory=/path/to/your/project
+user=www-data
+autostart=true
+autorestart=true
+redirect_stderr=true
+stdout_logfile=/var/log/zenpulse-scheduler.log
+```
+
+### Using Docker
+
+```dockerfile
+# In your Dockerfile
+CMD ["python", "manage.py", "run_zenpulse_scheduler", "--lock"]
+```
+
+Or in `docker-compose.yml`:
+
+```yaml
+services:
+  scheduler:
+    build: .
+    command: python manage.py run_zenpulse_scheduler --lock
+    depends_on:
+      - db
+```
+
+---
+
+## ❓ FAQ
+
+**Q: Can I run this with Gunicorn/Uvicorn?**  
+A: Yes, but run the scheduler in a **separate process/container**. Never run it inside web workers.
+
+**Q: What happens if I restart the server?**  
+A: Configuration is in the database, so it persists. Just start the scheduler command again.
+
+**Q: Can jobs accept parameters?**  
+A: Currently, jobs should be parameter-less functions. For different parameters, create separate job functions.
+
+**Q: How do I delete old logs?**  
+A: You can manually delete from Admin or create a cleanup job:
+```python
+@zenpulse_job("cleanup_old_logs")
+def cleanup_old_logs():
+    from datetime import timedelta
+    from django.utils import timezone
+    from zenpulse_scheduler.models import JobExecutionLog
+    
+    cutoff = timezone.now() - timedelta(days=30)
+    JobExecutionLog.objects.filter(run_time__lt=cutoff).delete()
+```
+
+**Q: Is this production-ready?**  
+A: Yes! It's built on APScheduler (battle-tested library) with Django best practices.
+
+---
+
+## 📝 License
+
+[Your License Here]
+
+## 🤝 Contributing
+
+Contributions welcome! Please open an issue or PR.
+
+---
+
+**Made with ❤️ for Django developers who want simple, powerful scheduling.**

zenpulse_scheduler-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zenpulse_scheduler"
+version = "0.1.0"
+dependencies = [
+    "django>=3.2",
+    "apscheduler>=3.6.3",
+]
+description = "A DB-driven APScheduler for Django"
+readme = "zenpulse_scheduler/README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Framework :: Django",
+    "Programming Language :: Python :: 3",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["zenpulse_scheduler*"]

zenpulse_scheduler-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zenpulse_scheduler-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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/zenpulse_scheduler.egg-info/PKG-INFO

@@ -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/zenpulse_scheduler.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+zenpulse_scheduler/__init__.py
+zenpulse_scheduler/admin.py
+zenpulse_scheduler/apps.py
+zenpulse_scheduler/engine.py
+zenpulse_scheduler/listeners.py
+zenpulse_scheduler/locks.py
+zenpulse_scheduler/models.py
+zenpulse_scheduler/registry.py
+zenpulse_scheduler/sync.py
+zenpulse_scheduler/triggers.py
+zenpulse_scheduler.egg-info/PKG-INFO
+zenpulse_scheduler.egg-info/SOURCES.txt
+zenpulse_scheduler.egg-info/dependency_links.txt
+zenpulse_scheduler.egg-info/requires.txt
+zenpulse_scheduler.egg-info/top_level.txt
+zenpulse_scheduler/management/commands/run_zenpulse_scheduler.py

zenpulse_scheduler-0.1.0/zenpulse_scheduler.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zenpulse_scheduler-0.1.0/zenpulse_scheduler.egg-info/requires.txt

@@ -0,0 +1,2 @@
+django>=3.2
+apscheduler>=3.6.3

zenpulse_scheduler-0.1.0/zenpulse_scheduler.egg-info/top_level.txt

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