ScheduleZero is a resource-conscious, distributed task scheduling system built entirely in Python. Perfect for scenarios where heavyweight solutions like Celery are overkill—especially on memory-constrained systems like small VMs or edge devices.

Why ScheduleZero?

• 🪶 Lightweight: No message broker required (RabbitMQ/Redis)
• 🚀 Fast: Built on modern async Python (asyncio, Tornado)
• 🔄 Distributed: Scale horizontally with worker handlers
• 💾 Persistent: SQLite-based job storage
• 🎨 Beautiful UI: Modern web interface for monitoring
• 🔌 Brokerless: Direct RPC communication via zerorpc
• 🛡️ Reliable: Built-in retry logic with exponential backoff

• 🕐 Flexible Scheduling: Date, interval, and cron triggers via APScheduler 4.x
• 📡 Remote Execution: Distribute jobs across multiple handler processes
• 🔄 Auto-Discovery: Handlers self-register with the central server
• 💪 Resilient: Automatic retries with exponential backoff + jitter
• 📊 REST API: Full HTTP API for programmatic control
• 🎛️ Web Dashboard: Real-time monitoring and job management
• 💾 Persistent Storage: Jobs survive restarts via SQLite
• 🔐 Thread-Safe: Concurrent job execution with proper locking

• Dynamic Handler Registration: Add/remove workers on-the-fly
• Method-Level Routing: Route jobs to specific handler methods
• Status Tracking: Monitor handler availability and job execution
• Configuration Management: YAML-based instance configuration
• Graceful Shutdown: Clean termination of all components
• Exponential Backoff: Smart retry logic for failed jobs

# Using Poetry (recommended)
poetry install

# Or using pip
pip install -r requirements.txt

Create config.yaml in your project root:

instance_name: "My ScheduleZero Instance"
description: "Production task scheduler"
admin_contact: "[email protected]"
version: "1.0.0"

Terminal 1 - Start the Server:

poetry run schedule-zero-server
# Server starts on http://127.0.0.1:8888

Terminal 2 - Start a Handler:

poetry run schedule-zero-handler
# Handler auto-registers and starts listening

Terminal 3 - Test the System:

poetry run python test_schedule.py
# Runs end-to-end tests

Open your browser to http://localhost:8888

┌─────────────────────────────────────────────────────────┐
│               ScheduleZero Central Server               │
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Tornado    │  │  APScheduler │  │   zerorpc    │  │
│  │  Web Server  │──│   4.x Async  │──│Registration  │  │
│  │   :8888      │  │   Scheduler  │  │Server :4242  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│         │                  │                  │          │
│         │                  │                  │          │
│    ┌────▼─────┐      ┌────▼──────┐     ┌────▼──────┐  │
│    │   HTTP   │      │  SQLite   │     │ Handler   │  │
│    │   API    │      │  JobStore │     │ Registry  │  │
│    └──────────┘      └───────────┘     └───────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
                          │  zerorpc (tcp)
                          │
        ┌─────────────────┴─────────────────┐
        │                                   │
        ▼                                   ▼
┌───────────────┐                   ┌───────────────┐
│   Handler 1   │                   │   Handler 2   │
│   :4243       │                   │   :4244       │
│               │                   │               │
│  • do_work()  │                   │  • process()  │
│  • backup()   │                   │  • analyze()  │
└───────────────┘                   └───────────────┘

• Native asyncio support for APScheduler 4.x integration
• Efficient async I/O for handling many connections
• Built-in web server—no external dependencies

• Modern async-first design
• Flexible trigger types (date, interval, cron)
• Persistent job storage with datastore abstraction

• No message broker required (unlike Celery)
• Minimal memory footprint
• Built-in heartbeat and timeout handling
• Automatic serialization with MessagePack

• Zero configuration database
• Low memory usage (< 1MB typical)
• Perfect for embedded/edge deployments
• ACID transactions for reliability

src/schedule_zero/
├── app_configuration.py          # App config & environment vars
├── handler_registry.py            # Handler registration & clients
├── job_executor.py                # Job execution with retries
├── zerorpc_registration_server.py # RPC server for registration
├── tornado_app_server.py          # Main server orchestration
├── server.py                      # CLI entry point
├── api/
│   ├── tornado_base_handlers.py   # Base Tornado handlers
│   ├── handler_list_api.py        # Handler endpoints
│   ├── job_scheduling_api.py      # Job scheduling endpoints
│   └── config_api.py              # Configuration endpoint
└── handlers/
    ├── base.py                    # Abstract handler base class
    └── example.py                 # Example handler implementation

Documentation Files:

• REFACTORING_SUMMARY.md - Detailed refactoring notes
• TESTING_STATUS.md - Current testing status & known issues

GET /api/handlers

Response:

{
  "handlers": [
    {
      "id": "handler_12345",
      "address": "tcp://127.0.0.1:4243",
      "methods": ["do_work", "backup", "process"],
      "status": "Connected"
    }
  ]
}

POST /api/schedule
Content-Type: application/json

{
  "handler_id": "handler_12345",
  "method_name": "do_work",
  "job_params": {
    "input_file": "/data/file.txt",
    "output_dir": "/results/"
  },
  "trigger_config": {
    "type": "interval",
    "hours": 1
  }
}

Response:

{
  "status": "success",
  "schedule_id": "job_67890"
}

POST /api/run_now
Content-Type: application/json

{
  "handler_id": "handler_12345",
  "method_name": "do_work",
  "job_params": {
    "message": "Hello World"
  }
}

GET /api/schedules

Response:

{
  "schedules": [
    {
      "id": "job_67890",
      "next_fire_time": "2025-10-27T15:30:00Z",
      "trigger": "interval[1:00:00]",
      "args": ["handler_12345", "do_work", {...}]
    }
  ],
  "count": 1
}

GET /api/config

GET /api/health

{
  "type": "date",
  "run_date": "2025-10-27T15:30:00"
}

{
  "type": "interval",
  "hours": 1,
  "minutes": 30
}

{
  "type": "cron",
  "hour": "*/2",
  "minute": "0"
}

# Start server and handler in separate terminals, then:
poetry run python test_schedule.py

# Expected output:
# ✓ Handlers listed successfully
# ✓ Job executed immediately
# ✓ Job scheduled for future execution

• Authentication & authorization
• Job execution history & logs
• Advanced UI with charts & graphs
• Docker containerization
• Handler health monitoring
• Job dependency management
• Multi-instance clustering
• Prometheus metrics export
• WebSocket support for real-time updates

Contributions are welcome! Please feel free to submit a Pull Request.

This project is licensed under the MIT License - see the LICENSE file for details.

Built with these excellent libraries:

• Tornado - Async web framework
• APScheduler - Job scheduling
• zerorpc - RPC framework
• ZeroMQ - Messaging library
• SQLAlchemy - Database toolkit