These docs are for PubNub 4.0 for Python V4 which is our latest and greatest! For the docs of the older versions of the SDK, please check PubNub 3.0 for Python, PubNub 3.0 for Python-Tornado and PubNub 3.0 for Python-Twisted.
If you have questions about the PubNub for Python SDK, please contact us at email@example.com.
Requires that the
When enabled via the PubNub Admin Console, the Stream Controller feature provides PubNub developers the ability to efficiently subscribe to multiple channels via Channel Multiplexing (MXing) and Channel Groups.
Channel and Channel Group names are UTF-8 compatible. Name length is limited to 64, and prohibited chars in a channel group are:
Channel Multiplexing enables developers to subscribe to up to 50 channels (not within a channel group) over a single TCP socket. On mobile devices, its easy to realize the network bandwidth and battery power savings gained from channel multiplexing.
These code samples build off code defined in the Publish and Subscribe tutorial, so before proceeding, be sure you have completed that tutorial first.
The examples below demonstrate how to subscribe and unsubscribe from multiple channels with a single call. The use of callbacks will give you a way to know when your operations complete successfully or with errors.
a.*you will get all messages for
a.x. The wildcarded
*portion refers to any portion of the channel string name after the
3 levels (2 dots) of wildcarding is supported, e.g.:
Channel Groups allows PubNub developers to bundle thousands of channels into a
group that can be identified by name. These Channel Groups can then be subscribed to, receiving data from the many backend-channels the channel group contains.
When building with channel-groups, you may create an unlimited number of these uniquely named channel groups, each with up to 2000 channels in them. Up to 10 channel groups may be subscribed to per PubNub instance. The below diagram depicts this design pattern and default limits:
As an example, for a group chat application, the channel group name would describe the conversation, and the channel names would be the chat audience's channels.
For a user
work are the chat room names (channel groups) and the channels are the contacts (channels), your design may look something like this:
- rajat : family : wife
- rajat : family : daughter
- rajat : family : son
- rajat : friends : pandu
- rajat : friends : craig
- rajat : friends : stephen
- rajat : work : pandu
- rajat : work : stephen
- rajat : work : sergey
Given the above design pattern
work are the 3 channel groups, which each contain a handful of channels in different combinations such as wife, son, pandu, craig, stephen, etc.
Similarly for user
mychats is the chat room name (channel group) and the channels
general-m-keyboard-presence, your design may look something like this:
- alex : mychats : general-a-messages
- alex : mychats : general-a-keyboard-presence
- alex : mychats : general-j-messages
- alex : mychats : general-j-keyboard-presence
- alex : mychats : general-m-messages
- alex : mychats : general-m-keyboard-presence
Please contact firstname.lastname@example.org if you feel this design pattern and/or default limits will not accommodate your application's design.
Each Channel Group and associated channel(s) is identified by a unique name. These names may be a string of up to 64 Unicode characters, excluding reserved characters:
Before you use a channel group, you must first add a channel to it. Channels can be added from either a client-side (mobile phone, web page), or a server-side (Java, Ruby, Python) device.
For our example, lets create a chat application around channel groups. Each channel group will contain the members' topic channels for the group. The following steps will demonstrate:
- Defining the Channel Group
- Adding Channels to a Channel Group
- Subscribing to the Channel Group
- Unsubscribing to the Channel Group
- Receiving Channel Group Presence Messages
- Removing Channels from a Channel Group
- Listing all Channels in a Channel Group
- Removing a Channel from a Channel Group
We'll implicitly define a channel group called
We'll add the channel
wife to the channel group
pubnub.add_channel_to_channel_group()\ .channel_group(channel_group)\ .channels("wife")\ .sync()
Continuing creation of the CG, we add the son and daughter channels to this channel group as well.
pubnub.add_channel_to_channel_group()\ .channel_group(channel_group)\ .channels(["son", "daughter"])\ .sync()
Now that we've added some channels to our CG, we need to subscribe to it. When a message arrives published to any of the channel group members, the message will arrive via the m variable in the message callback. The c variable will contain the source channel name.
To enable receiving Presence messages for the CG, just add
-pnpres suffix to the channel name in the
channelGroupSubscribe function :
We'll learn more about using PubNub Presence features in the Presence tutorial.
Lets assume that our
son no longer wants to be part of the
family chat app, because he is getting irritated with his sister's comments. To remove his channel from the group, we'd just call the following method:
pubnub.remove_channel_from_channel_group().\ channels(["son", "daughter"]).\ channel_group("channel_group").\ sync()
If he had permissions to remove his sister from the group, he probably would just do that instead, but if PAM was implemented, we could make it so that he only has permissions to either add or remove himself to the group, not add or remove others. We'll discuss PAM in more detail in the PAM, SSL, and AES256 Message Encryption tutorial.
To get a list of all the channels defined within a channel group, call the following method. In this example, we dump all the channels within
To remove a Channel Group by name, use the following method: