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