Quickstart

Client is the main interface of the library. It can be used to to connect to CometD servers, and to send and receive messages.

Connecting

After creating a Client object the open() method should be called to establish a connection with the server. The connection is closed and the session is terminated by calling the close() method.

client = Client("http://example.com/cometd")
await client.open()
# send and receive messsages...
await client.close()

Client objects can be also used as asynchronous context managers.

async with Client("http://example.com/cometd") as client:
    # send and receive messsages...

Channels

A channel is a string that looks like a URL path such as /foo/bar, /meta/connect or /service/chat.

The Bayeux specification defines three types of channels: meta channels, service channels and broadcast channels.

A channel that starts with /meta/ is a meta channel, a channel that starts with /service/ is a service channel, and all other channels are broadcast channels.

Meta channels

Meta channels provide to applications information about the Bayeux protocol, they are handled by the client internally, the users of the client shouldn’t send or receive messages from these channels.

Service channels

Applications create service channels, which are used in the case of request/response style of communication between client and server (as opposed to the publish/subscribe style of communication of broadcast channels, see below). A server directly responds to messages sent to these channels, the sent message is not broadcasted to any other client.

Broadcast channels

Applications also create broadcast channels, which have the semantic of a messaging topic and are used in the case of the publish/subscribe style of communication, where one sender wants to broadcast information to multiple clients.

Subscriptions

In order to receive messages from broadcast channels a client must subscribe to these channels first.

await client.subscribe("/chat/demo")

If you no longer want to receive messages from one of the channels you’re subscribed to then you must unsubscribe from the channel.

await client.unsubscribe("/chat/demo")

The current set of subscriptions can be obtained from the Client.subscriptions attribute.

Receiving messages

To receive messages broadcasted by the server after subscribing to these channels the receive() method should be used.

message = await client.receive()

The receive() method will wait until a message is received or it will raise a TransportTimeoutError in case the connection is lost with the server and the client can’t re-establish the connection or a ServerError if the connection gets closed by the server.

The client can also be used as an asynchronous iterator in a for loop to wait for incoming messages.

async for message in client:
    # process message

Sending messages

To send messages to service or broadcast channels the publish() method can be used.

data = {"foo": "bar"}
response = await client.publish("/foo/bar", data)