relayway 0.2.0

Python SDK for background job processing via Relayway API

relayway

Python SDK for enqueueing background jobs via the RelayWay API.

Installation

pip install .

Configuration

Set environment variables (or use a .env file):

export RELAYWAY_API_KEY="sk_xxx"              # Your RelayWay API key
export RELAYWAY_WEBHOOK_SECRET="whsec_xxx"     # Shared secret for webhook auth
export RELAYWAY_BASE_URL="https://api.relayway.io"  # RelayWay API URL
export RELAYWAY_ORIGIN="https://myapp.com"     # Your app's public URL

Quick start

from fastapi import FastAPI
from relayway import background, relayway_router

app = FastAPI()
app.include_router(relayway_router)

@background(name="send-email")
def send_email(to: str, subject: str) -> dict:
    send_actual_email(to, subject)
    return {"sent": True}

# Call the function — it enqueues instead of executing locally
result = await send_email("[e-mail]", "Welcome!")
print(result)  # {"id": "task-abc", "status": "pending"}

How it works

1. Registration — @background() registers your function in the SDK's internal registry.
2. Enqueue — Calling the function sends the arguments as a task payload to the RelayWay API.
3. Execution — The RelayWay worker picks up the task and POSTs to your app at /relayway/webhook/{name}. The router verifies the HMAC signature, looks up your function, and calls it with the original arguments.
4. Response — The function's return value is sent back to the worker.

API reference

@background(name="my-func")

Decorator that marks a function for background execution.

• name — unique identifier (defaults to func.__name__). The worker calls back to /relayway/webhook/{name}.

relayway_router

A FastAPI APIRouter you mount on your app. Provides the webhook endpoint:

• POST /relayway/webhook/{name} — worker callback, HMAC-protected.

Run tests

uv run --group dev pytest -q