Azure Web PubSub Client Library for Python

1.1.0 verified Fri May 01 auth: no python

The Azure Web PubSub Client Library for Python (v1.1.0) enables real-time messaging between clients and a Web PubSub service instance. It supports reliable WebSocket connections, group joins, event handlers, and reconnection. Released under the Azure SDK for Python monorepo, it follows a stable release cadence with regular updates.

pip install azure-messaging-webpubsubclient

Common errors

error ImportError: cannot import name 'WebPubSubClient' from 'azure.messaging.webpubsub' ↓

cause Incorrect import path; the correct package is azure.messaging.webpubsubclient.

fix

Use: from azure.messaging.webpubsubclient import WebPubSubClient

error AttributeError: 'WebPubSubClient' object has no attribute 'on' ↓

cause The 'on' method was renamed to 'subscribe' in version 1.0.0.

fix

Use client.subscribe(event, handler) instead.

error TypeError: __init__() got an unexpected keyword argument 'credential' ↓

cause The constructor expects either 'connection_string' or 'credential' as a WebPubSubClientCredential object, not a raw credential.

fix

Create a WebPubSubClientCredential object first: from azure.messaging.webpubsubclient.models import WebPubSubClientCredential; credential = WebPubSubClientCredential(...); client = WebPubSubClient(credential=credential)

Warnings

breaking In version 1.0.0, the client API was redesigned. The old synchronous methods (e.g., send_message) were replaced with an async-first pattern. If you were using preview versions (0.x), your code will break. ↓

fix Update to 1.1.0 and adapt to async usage if needed, or use the sync wrapper.

deprecated The 'on' method for event handlers is deprecated in favor of the 'subscribe' method. The old pattern is still supported but will be removed in a future version. ↓

fix Use client.subscribe(event, handler) instead of client.on(event, handler).

gotcha The client does not automatically reconnect if the server closes the WebSocket with a non-retriable status code. Users must implement their own reconnection logic or use the built-in auto-reconnect utility. ↓

fix Set up reconnect options when creating the client, e.g., WebPubSubClient(connection_string=..., reconnect_retry_total=3).

Imports

WebPubSubClient

wrong

from azure.messaging.webpubsub import WebPubSubClient

correct

from azure.messaging.webpubsubclient import WebPubSubClient

The package is azure-messaging-webpubsubclient, not azure-messaging-webpubsub.

WebPubSubClientCredential

from azure.messaging.webpubsubclient.models import WebPubSubClientCredential

Wrong import path leads to ImportError.

Quickstart

Minimal setup to connect to Azure Web PubSub using a connection string.

import os
from azure.messaging.webpubsubclient import WebPubSubClient
from azure.messaging.webpubsubclient.models import WebPubSubClientCredential

connection_string = os.environ.get('WEBPUBSUB_CONNECTION_STRING', '')
client = WebPubSubClient(connection_string=connection_string)
client.open()
# ... use client
client.close()