pynotiq-client 0.7.0
Python client library for adding messages to PyNotiQ queue with local and remote support
Requires Python: >=3.6

# PyNotiQ Client

A Python library for adding messages to PyNotiQ queues with support for both local JSON files and remote PyNotiQ servers.

## Installation

```sh
pip install pynotiq_client
```

## Usage

### Local Queue (JSON File)

```python
from pynotiq_client import PyNotiQ

# Initialize local queue
notifier = PyNotiQ(queue_type="local", queue_file="queue.json")

# Add message with auto-generated ID
notifier.add_message({
    "message_field_1": "Message Field Value 1",
    "message_field_2": "Message Field Value 2",
})

# Add message with custom ID
notifier.add_message({
    "message_field_1": "Another Message",
    "message_field_2": "Another Value",
}, item_id="custom-message-id-123")

# Retrieve all messages
messages = notifier.get_messages()
print(messages)

# Update a message
notifier.update_message("custom-message-id-123", {
    "message_field_1": "Updated Message",
    "status": "processed"
})

# Remove a message
notifier.remove_message("custom-message-id-123")

# Clear all messages
notifier.clear_queue()
```

### Remote Queue (PyNotiQ Server)

```python
from pynotiq_client import PyNotiQ

# Initialize remote queue client
notifier = PyNotiQ(
    queue_type="remote",
    server_url="http://localhost:8000",
    queue_name="my-queue",
    timeout=30
)

# Add message to remote queue
notifier.add_message({
    "user_id": 12345,
    "action": "send_email",
    "email": "user@example.com",
    "template": "welcome"
})

# Receive messages (SQS-style with visibility timeout)
messages = notifier.receive_messages(max_messages=10, visibility_timeout=30)
for message in messages:
    # Process message
    print(f"Processing message: {message['Id']}")
    
    # Delete message after processing (using receipt handle)
    notifier.delete_message(message['ReceiptHandle'])

# Get queue information
queue_info = notifier.get_queue_info()
print(f"Queue has {queue_info['message_count']} messages")

# Health check
if notifier.health_check():
    print("Remote server is healthy")
```

### Consumer Pattern

```python
import time
from pynotiq_client import PyNotiQ

# Consumer for processing messages
consumer = PyNotiQ(
    queue_type="remote",
    server_url="http://localhost:8000",
    queue_name="task-queue"
)

def process_message(message):
    """Process a single message"""
    print(f"Processing: {message['message_body']}")
    # Your processing logic here
    time.sleep(1)  # Simulate work
    return True

# Main consumer loop
while True:
    try:
        # Receive messages with visibility timeout
        messages = consumer.receive_messages(max_messages=5, visibility_timeout=60)
        
        for message in messages:
            try:
                # Process the message
                if process_message(message):
                    # Delete message after successful processing
                    consumer.delete_message(message['ReceiptHandle'])
                    print(f"✅ Message {message['Id']} processed successfully")
                else:
                    print(f"❌ Failed to process message {message['Id']}")
                    
            except Exception as e:
                print(f"Error processing message {message['Id']}: {e}")
        
        if not messages:
            # No messages available, wait before polling again
            time.sleep(5)
            
    except KeyboardInterrupt:
        print("Consumer stopped")
        break
    except Exception as e:
        print(f"Consumer error: {e}")
        time.sleep(10)  # Wait before retrying
```

## ✨ Features

### 🔄 Queue Management
- **Local & Remote Queues** - Support for both JSON file storage and remote PyNotiQ servers
- **Add Messages** - Easily add structured messages to queues
- **Retrieve Messages** - Get messages from queues for processing
- **SQS-like API** - Familiar receive/delete pattern with visibility timeouts
- **Message Updates** - Update existing messages in the queue
- **Queue Operations** - Clear, remove, and manage queue contents

### 🌐 Remote Server Support
- **HTTP API** - RESTful API for remote queue operations
- **Connection Management** - Automatic session handling and error recovery
- **Health Checks** - Monitor server availability
- **Configurable Timeouts** - Control request timeouts for reliability
- **Multiple Queues** - Support for named queues on the same server

### 🛠️ Developer Experience
- **Simple API** - Intuitive interface for quick integration
- **Unified Interface** - Same API for both local and remote queues
- **JSON Format** - Standard JSON structure for easy data handling
- **Flexible Schema** - Support for custom message fields and structures
- **Lightweight** - Minimal dependencies for fast installation and usage
- **Type Hints** - Full type annotation support for better IDE experience

### 📊 Data Structure
- **Unique IDs** - Each message gets a unique identifier for tracking
- **Timestamps** - Automatic timestamp generation for message ordering
- **Receipt Handles** - SQS-style receipt handles for message processing
- **Custom Fields** - Add any custom data fields to your message body
- **Type Safety** - Structured data format ensures consistency

## API Reference

### Initialization

```python
# Local queue
PyNotiQ(queue_type="local", queue_file="queue.json")

# Remote queue
PyNotiQ(
    queue_type="remote", 
    server_url="http://localhost:8000",
    queue_name="default",
    timeout=30
)
```

### Methods

- `add_message(message, item_id=None)` - Add a message to the queue
- `get_messages()` - Get all messages from the queue
- `receive_messages(max_messages=10, visibility_timeout=30)` - Receive messages (SQS-style)
- `delete_message(receipt_handle)` - Delete a message using receipt handle
- `remove_message(item_id)` - Remove a message by ID
- `update_message(item_id, new_message)` - Update an existing message
- `clear_queue()` - Remove all messages from the queue
- `get_queue_info()` - Get queue statistics and information
- `health_check()` - Check if the queue is accessible

## Requirements

- Python >= 3.6
- requests >= 2.25.0
- urllib3 >= 1.26.0

## License

MIT License