Python-Tornado Presence API Reference for Realtime Apps
Python version support
Python SDK versions 5.0.0 and higher no longer support Python v2.7 and the Twisted and Tornado frameworks. If you require support for any of these, use SDK version 4.8.1.
Note that PubNub will stop supporting versions of Python lower than 3.7 by the end of 2021.
Presence enables you to track the online and offline status of users and devices in real time, as well as store custom state information. Presence provides authoritative information on:
- When a user has joined or left a channel
- Who, and how many, users are subscribed to a particular channel
- Which channel(s) an individual user is subscribed to
- Associated state information for these users
Learn more about our Presence feature here.
Here Now
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the here_now()
function in your application.
Method(s)
To call Here Now
you can use the following method(s) in the Python-Tornado SDK:
pubnub.here_now().channels(String|List|Tuple).channel_groups(String|List|Tuple).include_state(Boolean).include_uuids(Boolean)
Parameter Type Required Defaults Description channels
String | List | Tuple Optional The channels
to get the here now details.channel_groups
String | List | Tuple Optional The channel groups
to get the here now details.include_state
Boolean Optional False
If True
, the response will include the presence states of the users for channels/channelGroups.include_uuids
Boolean Optional True
If True
, the response will include the UUIDs of the connected clients.
Basic Usage
Get a list of UUIDs subscribed to channel:
envelope = yield pubnub.here_now()\
.channels(['cool_channel1', 'cool_channel2'])\
.include_uuids(True)\
.future()
if envelope.status.is_error():
# handle error
return
for channel_data in envelope.result.channels:
print("---")
print("channel: %s" % channel_data.channel_name)
print("occupancy: %s" % channel_data.occupancy)
print("occupants: %s" % channel_data.channel_name)
for occupant in channel_data.occupants:
print("uuid: %s, state: %s" % (occupant.uuid, occupant.state))
Returns
The here_now()
operation returns a PNHereNowResult
which contains the following fields:
Field | Type | Description |
---|---|---|
total_channels | Int | Total channels . |
total_occupancy | Int | Total occupancy |
channels | Dict | A dict with values of PNHereNowChannelData for each channel. See PNHereNowChannelData for more details. |
PNHereNowChannelData:
Field | Type | Description |
---|---|---|
channel_name | String | channel name. |
occupancy | Int | occupancy of the channel . |
occupants | List | A list of PNHereNowOccupantData , see PNHereNowOccupantData for more details. |
PNHereNowOccupantData:
Field | Type | Description |
---|---|---|
uuid | String | uuid of the user. |
state | Dict | state of the user. |
Other Examples
- Returning State: Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-envelope = yield pubnub.here_now().channels("my_channel").\ include_uuids(True).include_state(True).future()
{ total_channels: 1, channels: [{ channel_name: "my_channel", occupancy: 1, occupants: [{ uuid: "myUuid1" state: { "abcd": { "age": 15 } } }] }], total_occupancy: 1 }
- Return Occupancy Only: Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return only the
occupancy
information for a single channel by specifying the channel and settingUUIDs
to false:envelope = yield pubnub.here_now().channels("my_channel").\ include_uuids(False).include_state(False).future()
{ total_channels: 1, channels: [{ channel_name: "my_channel", occupancy: 3, occupants: [] }], total_occupancy: 3 }
- Returning UUIDs and occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return the list of
UUIDs
andoccupancy
for allchannels
by omitting the channel:envelope = yield pubnub.here_now().include_uuids(True).include_state(False).future()
{ total_channels: 2, channels: [ { channel_name: "my_channel", occupancy: 1, occupants: [{ uuid: "data01", state: None }] }, { occupancy: 2, occupants: [{ uuid: "jason01", state: None }] } ], total_occupancy: 3 }
- Return Occupancy for all channels: Requires Presence add-onRequires that the Presence add-on is enabled with Global Here Now checked for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return only the
occupancy
information(Global Here Now)
by omitting thechannel name
envelope = yield pubnub.here_now()\ .include_state(True)\ .include_uuids(True)\ .future()
{ total_channels: 1, channels: [{ channel_name: "my_channel", occupancy: 3, occupants: [] }], total_occupancy: 3 }
-
envelope = yield pubnub.here_now().channel_groups(['cg1', 'cg2', 'cg3']).\ include_uuids(True).include_state(True).future()
{ total_channels: 1, channels: [ { channel_name: "my_channel", occupancy: 1, occupants: [{ uuid: "143r34f34t34fq34q34q3", state: None }] }, { occupancy: 1, occupants: [{ uuid: "123123234t234f34fq3dq", state: None }] }, { occupancy: 1, occupants: [{ uuid: "23f34d3f4rq34r34rq23q", state: None }] }, { occupancy: 1, occupants: [{ uuid: "w34tcw45t45tcw435tww3", state: None }] } ], total_occupancy: 4 }
Where Now
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
You can obtain information about the current list of channels to which a UUID is subscribed to by calling the where_now()
function in your application.
Note
If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.
Method(s)
To call where_now()
you can use the following method(s) in the Python-Tornado SDK:
pubnub.where_now().uuid(String)
Parameter Type Required Description uuid
String Optional uuid
to get info on.
Basic Usage
You simply need to define the uuid
and the callback
function to be used to send the data to as in the example below.
Get a list of channels a UUID is subscribed to:
envelope = yield pubnub.where_now().future()
Returns
The where_now()
operation returns a PNWhereNowResult
which contains the following fields:
Field | Type | Description |
---|---|---|
channels | List | The list of channels where the UUID is present. |
Other Examples
Obtain information about the current list of channels of some other UUID
envelope = yield pubnub.where_now().uuid('some-other-uuid').future()
User State
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
The state API is used to set/get key/value pairs specific to a subscriber uuid
.
State information is supplied as a JSON object of key/value pairs.
Important
Presence state must be expressed as a dict
. When calling set_state
, be sure to supply an initialized dict
which can be serialized.
Method(s)
pubnub.set_state().channels(String|List|Tuple).channel_groups(String|List|Tuple).state(Dict)
Parameter Type Required Description channels
String | List | Tuple Optional channels
to setstate
.channel_groups
String | List | Tuple Optional channel groups
to setstate
.state
Dict Optional state
to set.
pubnub.get_state().channels(String|List|Tuple).channel_groups(String|List|Tuple).uuid(String)
Parameter Type Required Description channels
String | List | Tuple Optional channels
to getstate
.channel_groups
String | List | Tuple Optional channel groups
to getstate
.uuid
String Optional uuid
to get state on.
Basic Usage
my_state = {
'age': 20
}
envelope = yield pubnub.set_state().channels(['ch1', 'ch2', 'ch3']).state(my_state).future()
envelope = yield pubnub.get_state().channels(['ch1', 'ch2', 'ch3']).uuid('such_uuid').future()
Returns
The set_state() operation returns a PNSetStateResult which contains the following fields:
Field | Type | Description |
---|---|---|
state | Dict | dict of UUIDs and the user states. |
The get_state() operation returns a PNGetStateResult which contains the following fields:
Field | Type | Description |
---|---|---|
channels | Dict | dict of channels and the user states. |