amarwave
Official Python client for AmarWave real-time messaging — async, typed, zero boilerplate.
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.0httpx >= 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.