# Azure Web PubSub client library for Python
[Azure Web PubSub](https://aka.ms/awps/doc) is a cloud service that helps developers easily build real-time features in web applications with publish-subscribe patterns at scale.
Any scenario that requires real-time messaging between server and clients or among clients following publish-subscribe patterns can benefit from using Web PubSub. Developers no longer need to poll the server by sending repeated HTTP requests at intervals, which is wasteful and hard-to-scale.
As shown in the diagram below, your clients establish WebSocket connections with your Web PubSub resource. This client library:
- simplifies managing client connections
- simplifies sending messages among clients
- automatically retries after unintended drops of client connection
- reliably deliveries messages in number and in order after recovering from connection drops
Details about the terms used here are described in [key concepts](#key-concepts) section.
_This library is hosted on [pypi][pypi]._
## Getting started
### Currently supported environments
- [Python 3.7+](https://www.python.org/downloads/)
### Prerequisites
- An [Azure subscription][azure_sub].
- A [Web PubSub resource][create_instance]
### 1. Install the `azure-messaging-webpubsubclient` package
```bash
pip install azure-messaging-webpubsubclient
```
### 2. Connect with your Web PubSub resource
A client uses a Client Access URL to connect and authenticate with the service, which follows a pattern of `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`. A client can have a few ways to obtain the Client Access URL. For this quick start, you can copy and paste one from Azure Portal shown below.
As shown in the diagram above, the client has the permissions to send messages to and join a specific group named "_group1_".
```python
from azure.messaging.webpubsubclient import WebPubSubClient
client = WebPubSubClient("<<client-access-url>>")
with client:
# The client can join/leave groups, send/receive messages to and from those groups all in real-time
...
```
### 3. Join groups
Note that a client can only receive messages from groups that it has joined and you need to add a callback to specify the logic when receiving messages.
```python
# ...continues the code snippet from above
# Registers a listener for the event 'group-message' early before joining a group to not miss messages
group_name = "group1";
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message: {e.data}"));
# A client needs to join the group it wishes to receive messages from
client.join_group(groupName);
```
### 4. Send messages to a group
```python
# ...continues the code snippet from above
# Send a message to a joined group
client.send_to_group(group_name, "hello world", WebPubSubDataType.TEXT);
# In the Console tab of your developer tools found in your browser, you should see the message printed there.
```
---
## Examples
### Add callbacks for connected, disconnected and stopped events
####
1. When a client is successfully connected to your Web PubSub resource, the `connected` event is triggered.
```python
client.subscribe(CallbackType.CONNECTED, lambda e: print(f"Connection {e.connection_id} is connected"))
```
2. When a client is disconnected and fails to recover the connection, the `disconnected` event is triggered.
```python
client.subscribe(CallbackType.DISCONNECTED, lambda e: print(f"Connection disconnected: {e.message}"))
```
3. The `stopped` event will be triggered when the client is disconnected *and* the client stops trying to reconnect. This usually happens after the `client.close()` is called, or `auto_reconnect` is disabled or a specified limit to trying to reconnect has reached. If you want to restart the client, you can call `client.open()` in the stopped event.
```python
client.subscribe(CallbackType.STOPPED, lambda : print("Client has stopped"))
```
---
### A client consumes messages from the application server or joined groups
A client can add callbacks to consume messages from your application server or groups. Please note, for `group-message` event the client can _only_ receive group messages that it has joined.
```python
# Registers a listener for the "server-message". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.
client.subscribe(CallbackType.SERVER_MESSAGE, lambda e: print(f"Received message {e.data}"))
# Registers a listener for the "group-message". The callback will be invoked when the client receives a message from the groups it has joined.
client.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f"Received message from {e.group}: {e.data}"))
```
---
### Handle rejoin failure
When a client is disconnected and fails to recover, all group contexts will be cleaned up in your Web PubSub resource. This means when the client reconnects, it needs to rejoin groups. By default, the client has `auto_rejoin_groups` option enabled.
However, you should be aware of `auto_rejoin_groups`'s limitations.
- The client can only rejoin groups that it's originally joined by the client code _not_ by the server side code.
- "rejoin group" operations may fail due to various reasons, e.g. the client doesn't have permission to join the groups. In such cases, you need to add a callback to handle this failure.
```python
# By default auto_rejoin_groups=True. You can disable it by setting to False.
client = WebPubSubClient("<client-access-url>", auto_rejoin_groups=True);
# Registers a listener to handle "rejoin-group-failed" event
client.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f"Rejoin group {e.group} failed: {e.error}"))
```
---
### Operation and retry
By default, the operation such as `client.join_group()`, `client.leave_group()`, `client.send_to_group()`, `client.send_event()` has three retries. You can configure through the key-word arguments. If all retries have failed, an error will be thrown. You can keep retrying by passing in the same `ack_id` as previous retries so that the Web PubSub service can deduplicate the operation.
```python
try:
client.join_group(group_name)
except SendMessageError as e:
client.join_group(group_name, ack_id=e.ack_id)
```
---
### Specify subprotocol
You can change the subprotocol to be used by the client. By default, the client uses `json.reliable.webpubsub.azure.v1`. You can choose to use `json.reliable.webpubsub.azure.v1` or `json.webpubsub.azure.v1`.
```python
from azure.messaging.webpubsubclient.models import WebPubSubProtocolType
# Change to use json.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", protocol_type=WebPubSubProtocolType.JSON);
```
```python
from azure.messaging.webpubsubclient.models import WebPubSubProtocolType
# Change to use json.reliable.webpubsub.azure.v1
const client = new WebPubSubClient("<client-access-url>", protocol_type=WebPubSubProtocolType.JSON_RELIABLE);
```
---
## Key concepts
### Connection
A connection, also known as a client or a client connection, represents an individual WebSocket connection connected to the Web PubSub. When successfully connected, a unique connection ID is assigned to this connection by the Web PubSub. Each `WebPubSubClient` creates its own exclusive connection.
### Recovery
If a client using reliable protocols disconnects, a new WebSocket tries to establish using the connection ID of the lost connection. If the new WebSocket connection is successfully connected, the connection is recovered. Throughout the time a client is disconnected, the service retains the client's context as well as all messages that the client was subscribed to, and when the client recovers, the service will send these messages to the client. If the service returns WebSocket error code `1008` or the recovery attempt lasts more than 30 seconds, the recovery fails.
### Reconnect
Reconnection happens when the client connection drops and fails to recover. Reconnection starts a new connection and the new connection has a new connection ID. Unlike recovery, the service treats the reconnected client as a new client connection. The client connection needs to rejoin groups. By default, the client library rejoins groups after reconnection.
### Hub
A hub is a logical concept for a set of client connections. Usually, you use one hub for one purpose, for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub, and during its lifetime, it belongs to that hub. Different applications can share one Web PubSub by using different hub names.
### Group
A group is a subset of connections to the hub. You can add a client connection to a group, or remove the client connection from the group, anytime you want. For example, when a client joins a chat room, or when a client leaves the chat room, this chat room can be considered to be a group. A client can join multiple groups, and a group can contain multiple clients.
### User
Connections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or multiple browser tabs.
---
## Client Lifetime
Each of the Web PubSub clients is safe to cache and be used as a singleton for the lifetime of the application. The registered event callbacks share the same lifetime with the client. This means you can add or remove callbacks at any time and the registration status will not change after reconnection or the client being stopped.
## Troubleshooting
This library uses the standard [logging](https://docs.python.org/3/library/logging.html) library for logging. If you want detailed `DEBUG` level logging, including payload of request, you can set `logging_enable=True` in client or per-operation
## Next steps
You can also find [more samples here](https://github.com/Azure/azure-webpubsub/tree/main/samples/python).
## Additional resources
- Learn more about client permission, see [permissions](https://learn.microsoft.com/azure/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol#permissions)
- [Product documentation](https://aka.ms/awps/doc)
## Contributing
If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.
[azure_sub]: https://azure.microsoft.com/free/
[create_instance]: https://learn.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance
[pypi]: https://pypi.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk",
"name": "azure-messaging-webpubsubclient",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "azure, azure sdk",
"author": "Microsoft Corporation",
"author_email": "azpysdkhelp@microsoft.com",
"download_url": "https://files.pythonhosted.org/packages/17/03/73f2fff522b333cbbe0f1acba331b38aa5a4e58e95cc3d2c3b345673bc9e/azure-messaging-webpubsubclient-1.1.0.tar.gz",
"platform": null,
"description": "# Azure Web PubSub client library for Python\n\n[Azure Web PubSub](https://aka.ms/awps/doc) is a cloud service that helps developers easily build real-time features in web applications with publish-subscribe patterns at scale.\n\nAny scenario that requires real-time messaging between server and clients or among clients following publish-subscribe patterns can benefit from using Web PubSub. Developers no longer need to poll the server by sending repeated HTTP requests at intervals, which is wasteful and hard-to-scale.\n\nAs shown in the diagram below, your clients establish WebSocket connections with your Web PubSub resource. This client library:\n\n- simplifies managing client connections\n- simplifies sending messages among clients\n- automatically retries after unintended drops of client connection\n- reliably deliveries messages in number and in order after recovering from connection drops\n\n\n\nDetails about the terms used here are described in [key concepts](#key-concepts) section.\n\n_This library is hosted on [pypi][pypi]._\n\n## Getting started\n\n### Currently supported environments\n\n- [Python 3.7+](https://www.python.org/downloads/)\n\n### Prerequisites\n\n- An [Azure subscription][azure_sub].\n- A [Web PubSub resource][create_instance]\n\n### 1. Install the `azure-messaging-webpubsubclient` package\n\n```bash\npip install azure-messaging-webpubsubclient\n```\n\n### 2. Connect with your Web PubSub resource\n\nA client uses a Client Access URL to connect and authenticate with the service, which follows a pattern of `wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>`. A client can have a few ways to obtain the Client Access URL. For this quick start, you can copy and paste one from Azure Portal shown below.\n\n\n\nAs shown in the diagram above, the client has the permissions to send messages to and join a specific group named \"_group1_\". \n\n```python\nfrom azure.messaging.webpubsubclient import WebPubSubClient\n\nclient = WebPubSubClient(\"<<client-access-url>>\")\nwith client:\n # The client can join/leave groups, send/receive messages to and from those groups all in real-time\n ...\n```\n\n### 3. Join groups\n\nNote that a client can only receive messages from groups that it has joined and you need to add a callback to specify the logic when receiving messages.\n\n```python\n# ...continues the code snippet from above\n\n# Registers a listener for the event 'group-message' early before joining a group to not miss messages\ngroup_name = \"group1\";\nclient.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f\"Received message: {e.data}\"));\n\n# A client needs to join the group it wishes to receive messages from\nclient.join_group(groupName);\n```\n\n### 4. Send messages to a group\n\n```python\n# ...continues the code snippet from above\n\n# Send a message to a joined group\nclient.send_to_group(group_name, \"hello world\", WebPubSubDataType.TEXT);\n\n# In the Console tab of your developer tools found in your browser, you should see the message printed there.\n```\n\n---\n## Examples\n### Add callbacks for connected, disconnected and stopped events\n#### \n1. When a client is successfully connected to your Web PubSub resource, the `connected` event is triggered.\n\n```python\nclient.subscribe(CallbackType.CONNECTED, lambda e: print(f\"Connection {e.connection_id} is connected\"))\n```\n\n2. When a client is disconnected and fails to recover the connection, the `disconnected` event is triggered.\n\n```python\nclient.subscribe(CallbackType.DISCONNECTED, lambda e: print(f\"Connection disconnected: {e.message}\"))\n```\n\n3. The `stopped` event will be triggered when the client is disconnected *and* the client stops trying to reconnect. This usually happens after the `client.close()` is called, or `auto_reconnect` is disabled or a specified limit to trying to reconnect has reached. If you want to restart the client, you can call `client.open()` in the stopped event.\n\n```python\nclient.subscribe(CallbackType.STOPPED, lambda : print(\"Client has stopped\"))\n```\n\n---\n### A client consumes messages from the application server or joined groups\n\nA client can add callbacks to consume messages from your application server or groups. Please note, for `group-message` event the client can _only_ receive group messages that it has joined.\n\n```python\n# Registers a listener for the \"server-message\". The callback will be invoked when your application server sends message to the connectionID, to or broadcast to all connections.\nclient.subscribe(CallbackType.SERVER_MESSAGE, lambda e: print(f\"Received message {e.data}\"))\n\n# Registers a listener for the \"group-message\". The callback will be invoked when the client receives a message from the groups it has joined.\nclient.subscribe(CallbackType.GROUP_MESSAGE, lambda e: print(f\"Received message from {e.group}: {e.data}\"))\n```\n\n---\n### Handle rejoin failure\nWhen a client is disconnected and fails to recover, all group contexts will be cleaned up in your Web PubSub resource. This means when the client reconnects, it needs to rejoin groups. By default, the client has `auto_rejoin_groups` option enabled. \n\nHowever, you should be aware of `auto_rejoin_groups`'s limitations. \n- The client can only rejoin groups that it's originally joined by the client code _not_ by the server side code. \n- \"rejoin group\" operations may fail due to various reasons, e.g. the client doesn't have permission to join the groups. In such cases, you need to add a callback to handle this failure.\n\n```python\n# By default auto_rejoin_groups=True. You can disable it by setting to False.\nclient = WebPubSubClient(\"<client-access-url>\", auto_rejoin_groups=True);\n\n# Registers a listener to handle \"rejoin-group-failed\" event\nclient.subscribe(CallbackType.REJOIN_GROUP_FAILED, lambda e: print(f\"Rejoin group {e.group} failed: {e.error}\"))\n```\n\n---\n### Operation and retry\n\nBy default, the operation such as `client.join_group()`, `client.leave_group()`, `client.send_to_group()`, `client.send_event()` has three retries. You can configure through the key-word arguments. If all retries have failed, an error will be thrown. You can keep retrying by passing in the same `ack_id` as previous retries so that the Web PubSub service can deduplicate the operation.\n\n```python\ntry:\n client.join_group(group_name)\nexcept SendMessageError as e:\n client.join_group(group_name, ack_id=e.ack_id)\n```\n\n---\n### Specify subprotocol\n\nYou can change the subprotocol to be used by the client. By default, the client uses `json.reliable.webpubsub.azure.v1`. You can choose to use `json.reliable.webpubsub.azure.v1` or `json.webpubsub.azure.v1`.\n\n```python\nfrom azure.messaging.webpubsubclient.models import WebPubSubProtocolType\n# Change to use json.webpubsub.azure.v1\nconst client = new WebPubSubClient(\"<client-access-url>\", protocol_type=WebPubSubProtocolType.JSON);\n```\n\n```python\nfrom azure.messaging.webpubsubclient.models import WebPubSubProtocolType\n# Change to use json.reliable.webpubsub.azure.v1\nconst client = new WebPubSubClient(\"<client-access-url>\", protocol_type=WebPubSubProtocolType.JSON_RELIABLE);\n```\n\n---\n## Key concepts\n\n### Connection\n\nA connection, also known as a client or a client connection, represents an individual WebSocket connection connected to the Web PubSub. When successfully connected, a unique connection ID is assigned to this connection by the Web PubSub. Each `WebPubSubClient` creates its own exclusive connection.\n\n### Recovery\n\nIf a client using reliable protocols disconnects, a new WebSocket tries to establish using the connection ID of the lost connection. If the new WebSocket connection is successfully connected, the connection is recovered. Throughout the time a client is disconnected, the service retains the client's context as well as all messages that the client was subscribed to, and when the client recovers, the service will send these messages to the client. If the service returns WebSocket error code `1008` or the recovery attempt lasts more than 30 seconds, the recovery fails.\n\n### Reconnect\n\nReconnection happens when the client connection drops and fails to recover. Reconnection starts a new connection and the new connection has a new connection ID. Unlike recovery, the service treats the reconnected client as a new client connection. The client connection needs to rejoin groups. By default, the client library rejoins groups after reconnection.\n\n### Hub\n\nA hub is a logical concept for a set of client connections. Usually, you use one hub for one purpose, for example, a chat hub, or a notification hub. When a client connection is created, it connects to a hub, and during its lifetime, it belongs to that hub. Different applications can share one Web PubSub by using different hub names.\n\n### Group\n\nA group is a subset of connections to the hub. You can add a client connection to a group, or remove the client connection from the group, anytime you want. For example, when a client joins a chat room, or when a client leaves the chat room, this chat room can be considered to be a group. A client can join multiple groups, and a group can contain multiple clients.\n\n### User\n\nConnections to Web PubSub can belong to one user. A user might have multiple connections, for example when a single user is connected across multiple devices or multiple browser tabs.\n\n---\n## Client Lifetime\n\nEach of the Web PubSub clients is safe to cache and be used as a singleton for the lifetime of the application. The registered event callbacks share the same lifetime with the client. This means you can add or remove callbacks at any time and the registration status will not change after reconnection or the client being stopped.\n\n## Troubleshooting\n\nThis library uses the standard [logging](https://docs.python.org/3/library/logging.html) library for logging. If you want detailed `DEBUG` level logging, including payload of request, you can set `logging_enable=True` in client or per-operation\n\n## Next steps\n\nYou can also find [more samples here](https://github.com/Azure/azure-webpubsub/tree/main/samples/python).\n\n## Additional resources\n\n- Learn more about client permission, see [permissions](https://learn.microsoft.com/azure/azure-web-pubsub/reference-json-reliable-webpubsub-subprotocol#permissions)\n\n- [Product documentation](https://aka.ms/awps/doc)\n\n## Contributing\n\nIf you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.\n\n[azure_sub]: https://azure.microsoft.com/free/\n[create_instance]: https://learn.microsoft.com/azure/azure-web-pubsub/howto-develop-create-instance\n[pypi]: https://pypi.org/\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Microsoft Azure Web PubSub Client Library for Python",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/Azure/azure-sdk-for-python/tree/main/sdk"
},
"split_keywords": [
"azure",
" azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a63dac08b9d650d85a56e223d26d4efc3f3b93114f1b002046b95b167917fda8",
"md5": "bbba55014547cf44386ce8e5e898d588",
"sha256": "d1eef163e99b47a3e222d6a192dc3bcd83ae9343fa8a1e1242046edf6acae663"
},
"downloads": -1,
"filename": "azure_messaging_webpubsubclient-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bbba55014547cf44386ce8e5e898d588",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38666,
"upload_time": "2024-05-06T09:28:20",
"upload_time_iso_8601": "2024-05-06T09:28:20.663393Z",
"url": "https://files.pythonhosted.org/packages/a6/3d/ac08b9d650d85a56e223d26d4efc3f3b93114f1b002046b95b167917fda8/azure_messaging_webpubsubclient-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "170373f2fff522b333cbbe0f1acba331b38aa5a4e58e95cc3d2c3b345673bc9e",
"md5": "4add904e50ff1da51b13b24d00f92bc6",
"sha256": "73fe2fd3a37c4b8cd4e788197e77fdeed9aab8681fb3bf293fd5b25cff789e4c"
},
"downloads": -1,
"filename": "azure-messaging-webpubsubclient-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4add904e50ff1da51b13b24d00f92bc6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 47561,
"upload_time": "2024-05-06T09:28:18",
"upload_time_iso_8601": "2024-05-06T09:28:18.675149Z",
"url": "https://files.pythonhosted.org/packages/17/03/73f2fff522b333cbbe0f1acba331b38aa5a4e58e95cc3d2c3b345673bc9e/azure-messaging-webpubsubclient-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 09:28:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-messaging-webpubsubclient"
}
JSON
