From 2b28091386dc4b3597b56b773254056185b0c6e0 Mon Sep 17 00:00:00 2001 From: Devendra Date: Wed, 25 Jun 2014 23:01:13 +0530 Subject: [#73858464] adding sphinx docs --- docs/build/html/index.html | 1555 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1555 insertions(+) create mode 100644 docs/build/html/index.html (limited to 'docs/build/html/index.html') diff --git a/docs/build/html/index.html b/docs/build/html/index.html new file mode 100644 index 0000000..e183435 --- /dev/null +++ b/docs/build/html/index.html @@ -0,0 +1,1555 @@ + + + + + + + + Welcome to PubNub’s documentation! — PubNub 3.5.2 documentation + + + + + + + + + + + +
+

Navigation

+ +
+ +
+
+
+
+ +
+

Welcome to PubNub’s documentation!

+
+
    +
+
+
+

Pubnub

+
+
+class Pubnub.Pubnub(publish_key, subscribe_key, secret_key=None, cipher_key=None, auth_key=None, ssl_on=False, origin='pubsub.pubnub.com', uuid=None, pooling=True, pres_uuid=None)
+
+
+audit(channel=None, auth_key=None, callback=None, error=None)
+

Method for fetching permissions from pubnub servers.

+

This method provides a mechanism to reveal existing PubNub Access Manager attributes +for any combination of subscribe_key, channel and auth_key.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to return PAM +attributes optionally in combination with auth_key. +If channel is not specified, results for all channels +associated with subscribe_key are returned. +If auth_key is not specified, it is possible to return +results for a comma separated list of channels.
+
auth_key: (string) (optional)
+
Specifies the auth_key to return PAM attributes for. +If only a single channel is specified, it is possible to return +results for a comma separated list of auth_keys.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response +{

+
+

“message”:”Success”, +“payload”:{

+
+
+
“channels”:{
+
+
“my_channel”:{
+
“auths”:{“my_ro_authkey”:{“r”:1,”w”:0}, +“my_rw_authkey”:{“r”:0,”w”:1}, +“my_admin_authkey”:{“r”:1,”w”:1}
+
+

}

+
+
+

}

+
+

},

+
+

}

+
+
+

Usage:

+
+
pubnub.audit (‘my_channel’); # Sync Mode
+
+ +
+
+decrypt(message)
+

Method for decrypting data.

+

This method takes ciphertext as input and returns decrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be decrypted.
+
Returns:
+
Returns decrypted message if cipher key is set
+
+
+ +
+
+encrypt(message)
+

Method for encrypting data.

+

This method takes plaintext as input and returns encrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be encrypted.
+
Returns:
+
Returns encrypted message if cipher key is set
+
+
+ +
+
+grant(channel=None, auth_key=False, read=True, write=True, ttl=5, callback=None, error=None)
+

Method for granting permissions.

+

This function establishes subscribe and/or write permissions for +PubNub Access Manager (PAM) by setting the read or write attribute +to true. A grant with read or write set to false (or not included) +will revoke any previous grants with read or write set to true.

+
+
Permissions can be applied to any one of three levels:
+
    +
  1. Application level privileges are based on subscribe_key applying to all associated channels.
    2. +
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
    3. +
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
    4. +
+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to grant permissions to. +If channel is not specified, the grant applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to grant permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
read: (boolean) (default: True)
+
Read permissions are granted by setting to True. +Read permissions are removed by setting to False.
+
write: (boolean) (default: True)
+
Write permissions are granted by setting to true. +Write permissions are removed by setting to false.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_ro_authkey”:{“r”:1,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+here_now(channel, callback=None, error=None)
+

Get here now data.

+

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.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies the channel name to return occupancy results. +If channel is not provided, here_now will return data for all channels.
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
Optional variable. An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Sync Mode: list +Async Mode: None

+

Response Format:

+

The here_now() method returns a list of uuid s currently subscribed to the channel.

+

uuids:[“String”,”String”, ... ,”String”] - List of UUIDs currently subscribed to the channel.

+

occupancy: Number - Total current occupancy of the channel.

+

Example Response: +{

+
+

occupancy: 4, +uuids: [

+
+
‘123123234t234f34fq3dq’, +‘143r34f34t34fq34q34q3’, +‘23f34d3f4rq34r34rq23q’, +‘w34tcw45t45tcw435tww3’,
+

]

+
+

}

+
+
+
+ +
+
+history(channel, count=100, reverse=False, start=None, end=None, callback=None, error=None)
+

This method fetches historical messages of a channel.

+

PubNub Storage/Playback Service provides real-time access to an unlimited +history for all messages published to PubNub. Stored messages are replicated +across multiple availability zones in several geographical data center +locations. Stored messages can be encrypted with AES-256 message encryption +ensuring that they are not readable while stored on PubNub’s network.

+

It is possible to control how messages are returned and in what order, +for example you can:

+
+

Return messages in the order newest to oldest (default behavior).

+

Return messages in the order oldest to newest by setting reverse to true.

+

Page through results by providing a start or end time token.

+

Retrieve a “slice” of the time line by providing both a start and end time token.

+

Limit the number of messages to a specific quantity using the count parameter.

+
+
+
Args:
+
+
channel: (string)
+
Specifies channel to return history messages from
+
count: (int) (default: 100)
+
Specifies the number of historical messages to return
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a list in sync mode i.e. when callback argument is not given

+
+
Sample Response:
+
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
+
+
+
+
+ +
+
+presence(channel, callback, error=None)
+

Subscribe to presence data on a channel.

+
+
Only works in async mode
+
+
Args:
+

channel: Channel name ( string ) on which to publish message +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
None
+
+
+ +
+
+publish(channel, message, callback=None, error=None)
+

Publishes data on a channel.

+

The publish() method is used to send a message to all subscribers of a channel. +To publish a message you must first specify a valid publish_key at initialization. +A successfully published message is replicated across the PubNub Real-Time Network +and sent simultaneously to all subscribed clients on a channel.

+
+
Messages in transit can be secured from potential eavesdroppers with SSL/TLS by
+

setting ssl to True during initialization.

+

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key +during initialization.

+
+
Args:
+
+
channel: (string)
+
Specifies channel name to publish messages to.
+
message: (string/int/double/dict/list)
+
Message to be published
+
callback: (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
+
+
Returns:
+

Sync Mode : list +Async Mode : None

+

The function returns the following formatted response:

+
+
[ Number, “Status”, “Time Token”]
+

The output below demonstrates the response to a successful call:

+
+
[1,”Sent”,”13769558699541401”]
+
+
+
+ +
+
+revoke(channel=None, auth_key=None, ttl=1, callback=None, error=None)
+

Method for revoking permissions.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to revoke permissions to. +If channel is not specified, the revoke applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to revoke permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_authkey”:{“r”:0,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+subscribe(channels, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)
+

Subscribe to data on a channel.

+

This function causes the client to create an open TCP socket to the +PubNub Real-Time Network and begin listening for messages on a specified channel. +To subscribe to a channel the client must send the appropriate subscribe_key at +initialization.

+

Only works in async mode

+
+
Args:
+
+
channel: (string/list)
+
Specifies the channel to subscribe to. It is possible to specify +multiple channels as a comma separated list or andarray.
+
callback: (function)
+
This callback is called on receiving a message from the channel.
+
error: (function) (optional)
+
This callback is called on an error event
+
connect: (function) (optional)
+
This callback is called on a successful connection to the PubNub cloud
+
disconnect: (function) (optional)
+
This callback is called on client disconnect from the PubNub cloud
+
reconnect: (function) (optional)
+
This callback is called on successfully re-connecting to the PubNub cloud
+
+
+
Returns:
+
None
+
+
+ +
+
+time(callback=None)
+

This function will return a 17 digit precision Unix epoch.

+

Args:

+
+
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
+
Returns:
+

Returns a 17 digit number in sync mode i.e. when callback argument is not given

+
+
Sample:
+
13769501243685161
+
+
+
+
+ +
+
+unsubscribe(channel)
+
+
Subscribe to presence data on a channel.
+
Only works in async mode
+
Args:
+

channel: Channel name ( string ) on which to publish message +message: Message to be published ( String / int / double / dict / list ). +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
Returns a list in sync mode i.e. when callback argument is not given
+
+
+ +
+ +
+
+

PubnubTwisted

+
+
+class Pubnub.PubnubTwisted(publish_key, subscribe_key, secret_key=None, cipher_key=None, auth_key=None, ssl_on=False, origin='pubsub.pubnub.com')
+
+
+audit(channel=None, auth_key=None, callback=None, error=None)
+

Method for fetching permissions from pubnub servers.

+

This method provides a mechanism to reveal existing PubNub Access Manager attributes +for any combination of subscribe_key, channel and auth_key.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to return PAM +attributes optionally in combination with auth_key. +If channel is not specified, results for all channels +associated with subscribe_key are returned. +If auth_key is not specified, it is possible to return +results for a comma separated list of channels.
+
auth_key: (string) (optional)
+
Specifies the auth_key to return PAM attributes for. +If only a single channel is specified, it is possible to return +results for a comma separated list of auth_keys.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response +{

+
+

“message”:”Success”, +“payload”:{

+
+
+
“channels”:{
+
+
“my_channel”:{
+
“auths”:{“my_ro_authkey”:{“r”:1,”w”:0}, +“my_rw_authkey”:{“r”:0,”w”:1}, +“my_admin_authkey”:{“r”:1,”w”:1}
+
+

}

+
+
+

}

+
+

},

+
+

}

+
+
+

Usage:

+
+
pubnub.audit (‘my_channel’); # Sync Mode
+
+ +
+
+decrypt(message)
+

Method for decrypting data.

+

This method takes ciphertext as input and returns decrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be decrypted.
+
Returns:
+
Returns decrypted message if cipher key is set
+
+
+ +
+
+encrypt(message)
+

Method for encrypting data.

+

This method takes plaintext as input and returns encrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be encrypted.
+
Returns:
+
Returns encrypted message if cipher key is set
+
+
+ +
+
+grant(channel=None, auth_key=False, read=True, write=True, ttl=5, callback=None, error=None)
+

Method for granting permissions.

+

This function establishes subscribe and/or write permissions for +PubNub Access Manager (PAM) by setting the read or write attribute +to true. A grant with read or write set to false (or not included) +will revoke any previous grants with read or write set to true.

+
+
Permissions can be applied to any one of three levels:
+
    +
  1. Application level privileges are based on subscribe_key applying to all associated channels.
    2. +
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
    3. +
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
    4. +
+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to grant permissions to. +If channel is not specified, the grant applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to grant permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
read: (boolean) (default: True)
+
Read permissions are granted by setting to True. +Read permissions are removed by setting to False.
+
write: (boolean) (default: True)
+
Write permissions are granted by setting to true. +Write permissions are removed by setting to false.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_ro_authkey”:{“r”:1,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+here_now(channel, callback=None, error=None)
+

Get here now data.

+

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.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies the channel name to return occupancy results. +If channel is not provided, here_now will return data for all channels.
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
Optional variable. An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Sync Mode: list +Async Mode: None

+

Response Format:

+

The here_now() method returns a list of uuid s currently subscribed to the channel.

+

uuids:[“String”,”String”, ... ,”String”] - List of UUIDs currently subscribed to the channel.

+

occupancy: Number - Total current occupancy of the channel.

+

Example Response: +{

+
+

occupancy: 4, +uuids: [

+
+
‘123123234t234f34fq3dq’, +‘143r34f34t34fq34q34q3’, +‘23f34d3f4rq34r34rq23q’, +‘w34tcw45t45tcw435tww3’,
+

]

+
+

}

+
+
+
+ +
+
+history(channel, count=100, reverse=False, start=None, end=None, callback=None, error=None)
+

This method fetches historical messages of a channel.

+

PubNub Storage/Playback Service provides real-time access to an unlimited +history for all messages published to PubNub. Stored messages are replicated +across multiple availability zones in several geographical data center +locations. Stored messages can be encrypted with AES-256 message encryption +ensuring that they are not readable while stored on PubNub’s network.

+

It is possible to control how messages are returned and in what order, +for example you can:

+
+

Return messages in the order newest to oldest (default behavior).

+

Return messages in the order oldest to newest by setting reverse to true.

+

Page through results by providing a start or end time token.

+

Retrieve a “slice” of the time line by providing both a start and end time token.

+

Limit the number of messages to a specific quantity using the count parameter.

+
+
+
Args:
+
+
channel: (string)
+
Specifies channel to return history messages from
+
count: (int) (default: 100)
+
Specifies the number of historical messages to return
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a list in sync mode i.e. when callback argument is not given

+
+
Sample Response:
+
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
+
+
+
+
+ +
+
+presence(channel, callback, error=None)
+

Subscribe to presence data on a channel.

+
+
Only works in async mode
+
+
Args:
+

channel: Channel name ( string ) on which to publish message +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
None
+
+
+ +
+
+publish(channel, message, callback=None, error=None)
+

Publishes data on a channel.

+

The publish() method is used to send a message to all subscribers of a channel. +To publish a message you must first specify a valid publish_key at initialization. +A successfully published message is replicated across the PubNub Real-Time Network +and sent simultaneously to all subscribed clients on a channel.

+
+
Messages in transit can be secured from potential eavesdroppers with SSL/TLS by
+

setting ssl to True during initialization.

+

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key +during initialization.

+
+
Args:
+
+
channel: (string)
+
Specifies channel name to publish messages to.
+
message: (string/int/double/dict/list)
+
Message to be published
+
callback: (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
+
+
Returns:
+

Sync Mode : list +Async Mode : None

+

The function returns the following formatted response:

+
+
[ Number, “Status”, “Time Token”]
+

The output below demonstrates the response to a successful call:

+
+
[1,”Sent”,”13769558699541401”]
+
+
+
+ +
+
+revoke(channel=None, auth_key=None, ttl=1, callback=None, error=None)
+

Method for revoking permissions.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to revoke permissions to. +If channel is not specified, the revoke applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to revoke permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_authkey”:{“r”:0,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+subscribe(channels, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)
+

Subscribe to data on a channel.

+

This function causes the client to create an open TCP socket to the +PubNub Real-Time Network and begin listening for messages on a specified channel. +To subscribe to a channel the client must send the appropriate subscribe_key at +initialization.

+

Only works in async mode

+
+
Args:
+
+
channel: (string/list)
+
Specifies the channel to subscribe to. It is possible to specify +multiple channels as a comma separated list or andarray.
+
callback: (function)
+
This callback is called on receiving a message from the channel.
+
error: (function) (optional)
+
This callback is called on an error event
+
connect: (function) (optional)
+
This callback is called on a successful connection to the PubNub cloud
+
disconnect: (function) (optional)
+
This callback is called on client disconnect from the PubNub cloud
+
reconnect: (function) (optional)
+
This callback is called on successfully re-connecting to the PubNub cloud
+
+
+
Returns:
+
None
+
+
+ +
+
+time(callback=None)
+

This function will return a 17 digit precision Unix epoch.

+

Args:

+
+
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
+
Returns:
+

Returns a 17 digit number in sync mode i.e. when callback argument is not given

+
+
Sample:
+
13769501243685161
+
+
+
+
+ +
+
+unsubscribe(channel)
+
+
Subscribe to presence data on a channel.
+
Only works in async mode
+
Args:
+

channel: Channel name ( string ) on which to publish message +message: Message to be published ( String / int / double / dict / list ). +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
Returns a list in sync mode i.e. when callback argument is not given
+
+
+ +
+ +
+
+

PubnubTornado

+
+
+class Pubnub.PubnubTornado(publish_key, subscribe_key, secret_key=False, cipher_key=False, auth_key=False, ssl_on=False, origin='pubsub.pubnub.com')
+
+
+audit(channel=None, auth_key=None, callback=None, error=None)
+

Method for fetching permissions from pubnub servers.

+

This method provides a mechanism to reveal existing PubNub Access Manager attributes +for any combination of subscribe_key, channel and auth_key.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to return PAM +attributes optionally in combination with auth_key. +If channel is not specified, results for all channels +associated with subscribe_key are returned. +If auth_key is not specified, it is possible to return +results for a comma separated list of channels.
+
auth_key: (string) (optional)
+
Specifies the auth_key to return PAM attributes for. +If only a single channel is specified, it is possible to return +results for a comma separated list of auth_keys.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response +{

+
+

“message”:”Success”, +“payload”:{

+
+
+
“channels”:{
+
+
“my_channel”:{
+
“auths”:{“my_ro_authkey”:{“r”:1,”w”:0}, +“my_rw_authkey”:{“r”:0,”w”:1}, +“my_admin_authkey”:{“r”:1,”w”:1}
+
+

}

+
+
+

}

+
+

},

+
+

}

+
+
+

Usage:

+
+
pubnub.audit (‘my_channel’); # Sync Mode
+
+ +
+
+decrypt(message)
+

Method for decrypting data.

+

This method takes ciphertext as input and returns decrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be decrypted.
+
Returns:
+
Returns decrypted message if cipher key is set
+
+
+ +
+
+encrypt(message)
+

Method for encrypting data.

+

This method takes plaintext as input and returns encrypted data. +This need not be called directly as enncryption/decryption is +taken care of transparently by Pubnub class if cipher key is +provided at time of initializing pubnub object

+
+
Args:
+
message: Message to be encrypted.
+
Returns:
+
Returns encrypted message if cipher key is set
+
+
+ +
+
+grant(channel=None, auth_key=False, read=True, write=True, ttl=5, callback=None, error=None)
+

Method for granting permissions.

+

This function establishes subscribe and/or write permissions for +PubNub Access Manager (PAM) by setting the read or write attribute +to true. A grant with read or write set to false (or not included) +will revoke any previous grants with read or write set to true.

+
+
Permissions can be applied to any one of three levels:
+
    +
  1. Application level privileges are based on subscribe_key applying to all associated channels.
    2. +
  2. Channel level privileges are based on a combination of subscribe_key and channel name.
    3. +
  3. User level privileges are based on the combination of subscribe_key, channel and auth_key.
    4. +
+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to grant permissions to. +If channel is not specified, the grant applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to grant permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
read: (boolean) (default: True)
+
Read permissions are granted by setting to True. +Read permissions are removed by setting to False.
+
write: (boolean) (default: True)
+
Write permissions are granted by setting to true. +Write permissions are removed by setting to false.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_ro_authkey”:{“r”:1,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+here_now(channel, callback=None, error=None)
+

Get here now data.

+

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.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies the channel name to return occupancy results. +If channel is not provided, here_now will return data for all channels.
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
Optional variable. An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Sync Mode: list +Async Mode: None

+

Response Format:

+

The here_now() method returns a list of uuid s currently subscribed to the channel.

+

uuids:[“String”,”String”, ... ,”String”] - List of UUIDs currently subscribed to the channel.

+

occupancy: Number - Total current occupancy of the channel.

+

Example Response: +{

+
+

occupancy: 4, +uuids: [

+
+
‘123123234t234f34fq3dq’, +‘143r34f34t34fq34q34q3’, +‘23f34d3f4rq34r34rq23q’, +‘w34tcw45t45tcw435tww3’,
+

]

+
+

}

+
+
+
+ +
+
+history(channel, count=100, reverse=False, start=None, end=None, callback=None, error=None)
+

This method fetches historical messages of a channel.

+

PubNub Storage/Playback Service provides real-time access to an unlimited +history for all messages published to PubNub. Stored messages are replicated +across multiple availability zones in several geographical data center +locations. Stored messages can be encrypted with AES-256 message encryption +ensuring that they are not readable while stored on PubNub’s network.

+

It is possible to control how messages are returned and in what order, +for example you can:

+
+

Return messages in the order newest to oldest (default behavior).

+

Return messages in the order oldest to newest by setting reverse to true.

+

Page through results by providing a start or end time token.

+

Retrieve a “slice” of the time line by providing both a start and end time token.

+

Limit the number of messages to a specific quantity using the count parameter.

+
+
+
Args:
+
+
channel: (string)
+
Specifies channel to return history messages from
+
count: (int) (default: 100)
+
Specifies the number of historical messages to return
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a list in sync mode i.e. when callback argument is not given

+
+
Sample Response:
+
[[“Pub1”,”Pub2”,”Pub3”,”Pub4”,”Pub5”],13406746729185766,13406746845892666]
+
+
+
+
+ +
+
+presence(channel, callback, error=None)
+

Subscribe to presence data on a channel.

+
+
Only works in async mode
+
+
Args:
+

channel: Channel name ( string ) on which to publish message +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
None
+
+
+ +
+
+publish(channel, message, callback=None, error=None)
+

Publishes data on a channel.

+

The publish() method is used to send a message to all subscribers of a channel. +To publish a message you must first specify a valid publish_key at initialization. +A successfully published message is replicated across the PubNub Real-Time Network +and sent simultaneously to all subscribed clients on a channel.

+
+
Messages in transit can be secured from potential eavesdroppers with SSL/TLS by
+

setting ssl to True during initialization.

+

Published messages can also be encrypted with AES-256 simply by specifying a cipher_key +during initialization.

+
+
Args:
+
+
channel: (string)
+
Specifies channel name to publish messages to.
+
message: (string/int/double/dict/list)
+
Message to be published
+
callback: (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
+
+
Returns:
+

Sync Mode : list +Async Mode : None

+

The function returns the following formatted response:

+
+
[ Number, “Status”, “Time Token”]
+

The output below demonstrates the response to a successful call:

+
+
[1,”Sent”,”13769558699541401”]
+
+
+
+ +
+
+revoke(channel=None, auth_key=None, ttl=1, callback=None, error=None)
+

Method for revoking permissions.

+
+
Args:
+
+
channel: (string) (optional)
+
Specifies channel name to revoke permissions to. +If channel is not specified, the revoke applies to all +channels associated with the subscribe_key. If auth_key +is not specified, it is possible to grant permissions to +multiple channels simultaneously by specifying the channels +as a comma separated list.
+
auth_key: (string) (optional)
+
Specifies auth_key to revoke permissions to. +It is possible to specify multiple auth_keys as comma +separated list in combination with a single channel name. +If auth_key is provided as the special-case value “null” +(or included in a comma-separated list, eg. “null,null,abc”), +a new auth_key will be generated and returned for each “null” value.
+
ttl: (int) (default: 1440 i.e 24 hrs)
+
Time in minutes for which granted permissions are valid. +Max is 525600 , Min is 1. +Setting ttl to 0 will apply the grant indefinitely.
+
callback: (function) (optional)
+
A callback method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado
+
error: (function) (optional)
+
An error method can be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+

Returns a dict in sync mode i.e. when callback argument is not given +The dict returned contains values with keys ‘message’ and ‘payload’

+

Sample Response: +{

+
+

“message”:”Success”, +“payload”:{

+
+

“ttl”:5, +“auths”:{

+
+
“my_authkey”:{“r”:0,”w”:0}
+

}, +“subscribe_key”:”my_subkey”, +“level”:”user”, +“channel”:”my_channel”

+
+

}

+
+

}

+
+
+
+ +
+
+subscribe(channels, callback, error=None, connect=None, disconnect=None, reconnect=None, sync=False)
+

Subscribe to data on a channel.

+

This function causes the client to create an open TCP socket to the +PubNub Real-Time Network and begin listening for messages on a specified channel. +To subscribe to a channel the client must send the appropriate subscribe_key at +initialization.

+

Only works in async mode

+
+
Args:
+
+
channel: (string/list)
+
Specifies the channel to subscribe to. It is possible to specify +multiple channels as a comma separated list or andarray.
+
callback: (function)
+
This callback is called on receiving a message from the channel.
+
error: (function) (optional)
+
This callback is called on an error event
+
connect: (function) (optional)
+
This callback is called on a successful connection to the PubNub cloud
+
disconnect: (function) (optional)
+
This callback is called on client disconnect from the PubNub cloud
+
reconnect: (function) (optional)
+
This callback is called on successfully re-connecting to the PubNub cloud
+
+
+
Returns:
+
None
+
+
+ +
+
+time(callback=None)
+

This function will return a 17 digit precision Unix epoch.

+

Args:

+
+
+
callback: (optional)
+
A callback method should be passed to the method. +If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
+
Returns:
+

Returns a 17 digit number in sync mode i.e. when callback argument is not given

+
+
Sample:
+
13769501243685161
+
+
+
+
+ +
+
+unsubscribe(channel)
+
+
Subscribe to presence data on a channel.
+
Only works in async mode
+
Args:
+

channel: Channel name ( string ) on which to publish message +message: Message to be published ( String / int / double / dict / list ). +callback: A callback method should be passed to the method.

+
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
error: Optional variable. An error method can be passed to the method.
+
If set, the api works in async mode. +Required argument when working with twisted or tornado .
+
+
+
Returns:
+
Returns a list in sync mode i.e. when callback argument is not given
+
+
+ +
+ +
+
+
+

Indices and tables

+ +
+ + +
+
+
+
+
+

Table Of Contents

+ + +

This Page

+ + + +
+
+
+
+
+

Navigation

+ +
+
+ © Copyright 2014, PubNub Inc.. + Created using Sphinx 1.2.2. +
+ + \ No newline at end of file -- cgit v1.2.3