gopherqueue 1.1.2

Python SDK for GopherQueue - Enterprise-grade background job processing

GopherQueue Python SDK

A Python client library for GopherQueue, an enterprise-grade background job processing system.

Installation

pip install gopherqueue

Or install from source:

pip install -e .

Quick Start

import asyncio
from gopherqueue import GopherQueue

async def main():
    # Create client
    client = GopherQueue("http://localhost:8080")

    # Submit a job
    job = await client.submit("email", {"to": "[e-mail]", "subject": "Hello!"})
    print(f"Job created: {job.id}")

    # Wait for completion
    result = await client.wait(job.id, timeout=30)
    print(f"Job completed: {result.success}")

asyncio.run(main())

Features

• Async/await support - Built on aiohttp for high performance
• Sync API available - Use GopherQueueSync for synchronous code
• Batch submission - Submit up to 1000 jobs atomically
• Long-polling wait - Efficiently wait for job completion
• SSE events - Real-time job status updates
• Type hints - Full type annotation support
• API key auth - Secure API access

API Reference

Client Options

from gopherqueue import GopherQueue

client = GopherQueue(
    url="http://localhost:8080",
    api_key="your-api-key",       # Optional API key
    timeout=30,                     # Request timeout in seconds
    max_connections=100,            # Connection pool size
)

Submit Job

job = await client.submit(
    job_type="email",
    payload={"to": "[e-mail]"},
    priority=1,                    # 0=Critical, 1=High, 2=Normal, 3=Low, 4=Bulk
    delay="5m",                    # Delay before execution
    timeout="30m",                 # Max execution time
    max_attempts=3,                # Retry attempts
    idempotency_key="unique-key",  # Deduplication
    tags={"env": "prod"},          # Metadata
)

Batch Submit

results = await client.submit_batch([
    {"type": "email", "payload": {"to": "[e-mail]"}},
    {"type": "email", "payload": {"to": "[e-mail]"}},
], atomic=True)  # All-or-nothing

print(f"Accepted: {results.accepted}, Rejected: {results.rejected}")

Wait for Job

result = await client.wait(job.id, timeout=60)
if result.completed:
    if result.success:
        print(f"Output: {result.result}")
    else:
        print(f"Error: {result.result.error}")

Get Job Status

job = await client.get(job_id)
print(f"State: {job.state}, Progress: {job.progress}%")

List Jobs

jobs = await client.list(state="running", type="email", limit=100)
for job in jobs:
    print(f"{job.id}: {job.state}")

Cancel Job

job = await client.cancel(job_id, reason="No longer needed", force=True)

Retry Failed Job

job = await client.retry(job_id, reset_attempts=True)

SSE Events

async for event in client.events(job_id="*"):  # Subscribe to all jobs
    print(f"Event: {event.type}, Job: {event.data.id}")

Synchronous API

from gopherqueue import GopherQueueSync

client = GopherQueueSync("http://localhost:8080")

job = client.submit("email", {"to": "[e-mail]"})
result = client.wait(job.id, timeout=30)

License

MIT License