Skip to main content

amarwave

Official Python client for AmarWave real-time messaging — async, typed, zero boilerplate.

PyPI version Python License


Installation

pip install amarwave

Quick Start

import asyncio
from amarwave import AmarWave

async def main():
    aw = AmarWave(
        app_key    = "YOUR_APP_KEY",
        app_secret = "YOUR_APP_SECRET",
    )

    ch = await aw.subscribe("public-chat")
    ch.bind("message", lambda data: print(data["user"], data["text"]))

    await ch.publish("message", {"user": "Ali", "text": "Hello!"})
    await aw.listen()  # keep alive forever

asyncio.run(main())

Configuration

Parameter Type Default Description
app_key str — Your app key (required)
app_secret str "" App secret for HMAC channel auth
cluster str "default" "default" | "eu" | "us" | "ap1" | "ap2"
auth_endpoint str "/broadcasting/auth" Server auth URL for private/presence channels
auth_headers dict {} Headers sent to the auth endpoint
reconnect_delay float 1.0 Base reconnect delay in seconds
max_reconnect_delay float 30.0 Max reconnect delay in seconds
max_retries int 5 Max reconnect attempts (0 = infinite)
activity_timeout float 120.0 Seconds between keepalive pings
pong_timeout float 30.0 Seconds to wait for pong before reconnecting

Clusters

All clusters connect to amarwave.com. The cluster parameter is reserved for future regional routing.

Cluster WebSocket API
default wss://amarwave.com https://amarwave.com
eu wss://amarwave.com https://amarwave.com
us wss://amarwave.com https://amarwave.com
ap1 wss://amarwave.com https://amarwave.com
ap2 wss://amarwave.com https://amarwave.com
aw = AmarWave(app_key="KEY", app_secret="SECRET", cluster="eu")

Channel API

ch = await aw.subscribe("public-chat")

ch.bind("message", handler)           # listen for event
ch.bind_global(lambda e, d: ...)      # listen for all events on this channel
ch.unbind("message", handler)         # remove listener
await ch.publish("message", data)     # publish via HTTP API → bool
await aw.publish("ch", "ev", data)    # top-level publish shortcut

ch.name        # "public-chat"
ch.subscribed  # True when server confirmed subscription

Connection Events

aw.bind("connecting",   lambda _: print("Connecting…"))
aw.bind("connected",    lambda _: print(f"Connected: {aw.socket_id}"))
aw.bind("disconnected", lambda _: print("Disconnected"))
aw.bind("error",        lambda e: print(f"Error: {e}"))

Private & Presence Channels

# Client-side HMAC auth (app_secret required)
aw = AmarWave(app_key="KEY", app_secret="SECRET")
ch = await aw.subscribe("private-orders")    # auto-signed
ch = await aw.subscribe("presence-room-1")  # auto-signed

# Server-side auth (omit app_secret, provide auth_endpoint)
aw = AmarWave(
    app_key       = "KEY",
    auth_endpoint = "https://yourapp.com/api/broadcasting/auth",
    auth_headers  = {"Authorization": f"Bearer {token}"},
)
ch = await aw.subscribe("private-orders")

Django Integration

import asyncio
from amarwave import AmarWave

# One-shot publish from a sync Django view
def notify_user(user_id: int, message: str) -> bool:
    async def _publish() -> bool:
        aw = AmarWave(app_key="KEY", app_secret="SECRET")
        return await aw.publish(f"private-user-{user_id}", "notification", {"message": message})
    return asyncio.run(_publish())

FastAPI Integration

from contextlib import asynccontextmanager
from fastapi import FastAPI
from amarwave import AmarWave

aw = AmarWave(app_key="KEY", app_secret="SECRET")

@asynccontextmanager
async def lifespan(app: FastAPI):
    ch = await aw.subscribe("public-updates")
    ch.bind("message", lambda d: print(d))
    yield
    await aw.disconnect()

app = FastAPI(lifespan=lifespan)

@app.post("/notify")
async def notify(message: str):
    await aw.publish("public-updates", "message", {"text": message})
    return {"ok": True}

Requirements

  • Python 3.10+
  • websockets >= 12.0
  • httpx >= 0.27.0

License

MIT © AmarWave

Metadata

Release files for amarwave 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amarwave 2.0.1
File Size Uploaded Provenance Actions
amarwave-2.0.1.tar.gz 11.1 kB Without provenance Details for amarwave-2.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amarwave 2.0.1
File Interpreter ABI Platform Actions
amarwave-2.0.1-py3-none-any.whl Python 3 none any Details for amarwave-2.0.1-py3-none-any.whl

Total release size: 21.8 kB

Release files / amarwave-2.0.1.tar.gz

Download URL amarwave-2.0.1.tar.gz
Size 11.1 kB
Tags Source
SHA-256 checksum
How to use checksums
ba62e9c4f73b81d98f189881a30d2974259c76f65b361c3c352ff3929317b00e
BLAKE2b-256 checksum
How to use checksums
78e540687d6f5ccf0cbf5a095f595c4c93a9426cc591e73151912d7064644572
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.11

Release files / amarwave-2.0.1-py3-none-any.whl

Download URL amarwave-2.0.1-py3-none-any.whl
Size 10.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca0dcf7919fb6ca138871152ffc423ebaf35bd3baceb2c0d1e28cedaff07ea19
BLAKE2b-256 checksum
How to use checksums
3ee79733e54bdb6993658483c7a2857264587d2149b6b58b959802f2978c6153
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.11

Security for amarwave 2.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page