Metadata-Version: 2.4
Name: xqueue
Version: 0.2.0
Summary: A distributed task queue with cron scheduling built on top of Redis
Home-page: https://github.com/chishui/xq
Author: chishui
Author-email: chishui2@gmail.com
Project-URL: Bug Reports, https://github.com/chishui/xq/issues
Project-URL: Source, https://github.com/chishui/xq
Keywords: queue,redis,messaging,cron,scheduler,task,distributed
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8, <4
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=5.0.0
Requires-Dist: croniter>=6.0.0
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == "server"
Requires-Dist: uvicorn>=0.27.0; extra == "server"
Requires-Dist: jinja2>=3.1.0; extra == "server"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# xq
A distributed queue system built on top of Redis with cron-based scheduling support

XQ is a lightweight distributed task queue that allows you to:
- Schedule tasks to run at specific times using cron expressions
- Run tasks immediately or on a recurring schedule
- Poll tasks based on their scheduled execution time
- Manage queues and tasks through code or a web interface

# Install
```bash
pip3 install -r requirements.txt
```

# Use
## Producer
```python
import redis
from xq.queue import Queue

# connect to Redis
r = redis.Redis(host='localhost', port=6379)
# create queue
q = Queue(r, "test_queue")

# enqueue a task to run immediately
q.enqueue("this is a one-time message")

# enqueue a task with cron scheduling (runs every 5 minutes)
q.enqueue("this is a recurring message", cron_expression="*/5 * * * *")

# enqueue a task to run at midnight every day
q.enqueue("this runs at midnight", cron_expression="0 0 * * *")
```

## Consumer
```python
import redis
from xq.queue import Queue

# connect to Redis
r = redis.Redis(host='localhost', port=6379)
# create queue
q = Queue(r, "test_queue")

# poll for tasks that are ready to be executed
messages = q.poll()
for message in messages:
    print(f"Processing message: {message.body}")
    # For recurring tasks (with cron expressions), they will be 
    # automatically re-enqueued for their next scheduled run
```

## Use Worker
```python
import redis
from xq.queue import Queue
from xq.worker import Worker

def process_message(message):
    print(f"Worker processing: {message.body}")
    # Your task processing logic here

# connect to Redis
r = redis.Redis(host='localhost', port=6379)
# create queue
q = Queue(r, "test_queue")
# create and run worker
worker = Worker(q, process_message)
# worker will continuously poll for tasks based on their scheduled time
worker.run()
```

# Scheduling with Cron Expressions

XQ supports cron expressions for scheduling recurring tasks:

| Cron Expression | Description |
|----------------|-------------|
| `* * * * *` | Run every minute |
| `*/5 * * * *` | Run every 5 minutes |
| `0 * * * *` | Run at the start of every hour |
| `0 0 * * *` | Run once a day at midnight |
| `0 0 * * 0` | Run once a week on Sunday at midnight |
| `0 0 1 * *` | Run once a month on the 1st at midnight |

The cron format consists of five fields: `minute hour day-of-month month day-of-week`

# Web UI & API Server

XQ includes a web interface and API for managing queues and messages with built-in cron expression interpretation.

## Setup

1. Install the required dependencies:
```bash
pip install -r server/requirements.txt
```

2. Make sure Redis is running on localhost:6379

3. Start the server:
```bash
python server/api.py
```

4. Open your browser and navigate to http://localhost:8000

## Features

- View all available queues
- Create new queues
- View messages in a queue with human-readable cron interpretations
- Add new messages with optional cron scheduling
- Delete messages from a queue
- Poll messages from a queue

## API Endpoints

- `GET /api/queues` - List all available queues
- `GET /api/queues/{queue_name}/messages` - List all messages in a queue
- `POST /api/queues/{queue_name}/messages` - Add a new message to a queue
- `DELETE /api/queues/{queue_name}/messages/{message_id}` - Delete a message from a queue
- `POST /api/queues/{queue_name}/poll` - Poll messages from a queue
