App Context API for PubNub Python SDK

This page describes App Context (formerly Objects v2). To upgrade from Objects v1, refer to the migration guide.

App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to easily store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases.

PubNub also triggers events when object data is set or removed from the database. Clients can receive these events in real time and update their front-end application accordingly.

User

Get Metadata for all Users

Returns a paginated list of UUID metadata objects, optionally including the custom data object for each.

Method(s)

To Get All UUID Metadata you can use the following method(s) in the Python SDK:

pubnub.get_all_uuid_metadata() \
        .limit(Integer) \
        .page(PNPage Object) \
        .filter(String) \
        .sort(List<PNSortKey>) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_status(Boolean) \
        .include_type(Boolean)

Parameter	Type	Required	Default	Description
limit	Integer	No	N/A	The maximum number of objects to retrieve at a time.
page	PNPage	No	N/A	The paging object used for pagination.
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	List<PNSortKey>	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}.
include_total_count	Boolean	No	False	Request totalCount to be included in paginated response, which is omitted by default.
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.
include_status	Boolean	No	True	Whether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_type	Boolean	No	True	Whether to include the type field in the fetch response. Setting this to False will prevent this value from being returned.

Basic Usage

Synchronous:

pubnub.get_all_uuid_metadata().\
            include_custom(True).\
            limit(10).\
            include_total_count(True).\
            sort(PNSortKey.asc(PNSortKeyValue.ID), PNSortKey.desc(PNSortKeyValue.UPDATED)).\
            page(None).\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_all_uuid_metadata().\
            include_custom(True).\
            limit(10).\
            include_total_count(True).\
            sort(PNSortKey.asc(PNSortKeyValue.ID), PNSortKey.desc(PNSortKeyValue.UPDATED)).\
            page(None).\
            pn_async(callback)

Returns

The get_all_uuid_metadata() operation returns a PNGetAllUUIDMetadataResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing UUID metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with UUID metadata.

Key	Description
id	UUID
name	Name associated with UUID object
externalId	External ID associated with UUID object
profileUrl	Profile URL associated with UUID object
email	Email address associated with UUID object
custom	Custom object associated with UUID object in form of dictionary containing string to string pairs
status	User status value
type	User type value

Get User Metadata

Returns metadata for the specified UUID, optionally including its custom data object.

Method(s)

To Get UUID Metadata you can use the following method(s) in the Python SDK:

pubnub.get_uuid_metadata() \
        .uuid(String) \
        .include_custom(Boolean)

Parameter	Type	Required	Default	Description
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.
include_status	Boolean	No	True	Whether to include the status field in the fetch response, which is included by default.
include_type	Boolean	No	True	Whether to include the type field in the fetch response, which is included by default.

Basic Usage

Synchronous:

pubnub.get_uuid_metadata().\
            include_custom(True).\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_uuid_metadata().\
            include_custom(True).\
            pn_async(callback)

Returns

The get_uuid_metadata() operation returns a PNGetUUIDMetadataResult which contains the following properties:

Property Name	Type	Description
data		Dictionary containing UUID metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with UUID metadata.

Key	Description
id	UUID
name	Name associated with UUID object
externalId	External ID associated with UUID object
profileUrl	Profile URL associated with UUID object
email	Email address associated with UUID object
status	Status value associated with UUID object
type	Type value associated with UUID object
custom	Custom object associated with UUID object in form of dictionary containing string to string pairs

Set User Metadata

Set metadata for a UUID in the database, optionally including its custom data object.

Method(s)

To Set UUID Metadata you can use the following method(s) in the Python SDK:

pubnub.set_uuid_metadata() \
        .uuid(String) \
        .set_name(String) \
        .set_status(String) \
        .set_type(String) \
        .external_id(String) \
        .profile_url(String) \
        .email(String) \
        .custom(Dictionary) \
        .include_custom(Boolean)

Parameter	Type	Required	Default	Description
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
set_name	String	No	N/A	Display name for the user.
set_status	String	No	N/A	User status. Max. 50 characters.
set_type	String	No	N/A	User type. Max. 50 characters.
external_id	String	No	N/A	User's identifier in an external system.
profile_url	String	No	N/A	The URL of the user's profile picture.
email	String	No	N/A	The user's email address.
custom	Any	No	N/A	Any object of key-value pairs with supported data types. App Context filtering language doesn’t support filtering by custom properties.
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Basic Usage

Synchronous:

pubnub.set_uuid_metadata() \
            .include_custom(True) \
            .uuid("Some UUID") \
            .set_name("Some Name") \
            .set_status("Active") \
            .set_type("User") \
            .email("test@example.com") \
            .profile_url("http://example.com") \
            .external_id("1234567890") \
            .custom({"key1": "val1", "key2": "val2"}) \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.set_uuid_metadata() \
            .include_custom(True) \
            .uuid("Some UUID") \
            .set_name("Some Name") \
            .set_status("Active") \
            .set_type("User") \
            .email("test@example.com") \
            .profile_url("http://example.com") \
            .external_id("1234567890") \
            .custom({"key1": "val1", "key2": "val2"}) \
            pn_async(callback)

Returns

The set_uuid_metadata() operation returns a PNSetUUIDMetadataResult which contains the following properties:

Property Name	Type	Description
data		Dictionary containing UUID metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with UUID metadata.

Key	Description
id	UUID
name	Name associated with UUID object
externalId	External ID associated with UUID object
profileUrl	Profile URL associated with UUID object
email	Email address associated with UUID object
status	User status
type	User type
custom	Custom object associated with UUID object in form of dictionary containing string to string pairs

Remove User Metadata

Removes the metadata from a specified UUID.

Method(s)

To Remove UUID Metadata you can use the following method(s) in the Python SDK:

pubnub.remove_uuid_metadata()
        .uuid(String)

Parameter	Type	Required	Default	Description
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.

Basic Usage

Synchronous:

pubnub.remove_uuid_metadata().\
            uuid("Some UUID").sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_uuid_metadata().\
            uuid("Some UUID").pn_async(callback)

Returns

The remove_uuid_metadata() operation returns a PNRemoveUUIDMetadataResult which contains the following properties:

Property Name	Type	Description
status	PNStatus	Status of the operation

Channel

Get Metadata for all Channels

Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each.

Method(s)

To Get All Channel Metadata you can use the following method(s) in the Python SDK:

pubnub.get_all_channel_metadata() \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean)

Parameter	Type	Required	Default	Description
limit	Integer	No	100	The maximum number of objects to retrieve at a time.
page	PNPage	No	N/A	The paging object used for pagination.
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	[PNSortKey]	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}.
include_total_count	Boolean	No	False	Request totalCount to be included in paginated response, which is omitted by default.
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.
include_status	Boolean	No	True	Whether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_type	Boolean	No	True	Whether to include the type field in the fetch response. Setting this to False will prevent this value from being returned.

Basic Usage

Synchronous:

pubnub.get_all_channel_metadata().\
            include_custom(True).\
            limit(10).\
            include_total_count(True).\
            sort(PNSortKey.asc(PNSortKeyValue.ID), PNSortKey.desc(PNSortKeyValue.UPDATED)).\
            page(None).\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_all_channel_metadata().\
            include_custom(True).\
            limit(10).\
            include_total_count(True).\
            sort(PNSortKey.asc(PNSortKeyValue.ID), PNSortKey.desc(PNSortKeyValue.UPDATED)).\
            page(None).\
            pn_async(callback)

Returns

The get_all_uuid_metadata() operation returns a PNGetAllChannelMetadataResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing channel metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with channel metadata.

Key	Description
id	Channel metadata ID
name	Name associated with channel metadata object
description	Description associated with channel metadata object
status	Channel status value
type	Channel type value
custom	Custom object associated with channel metadata object in form of dictionary containing string to string pairs

Get Channel Metadata

Returns metadata for the specified channel, optionally including its custom data object.

Method(s)

To Get Channel Metadata you can use the following method(s) in the Python SDK:

pubnub.get_channel_metadata() \
        .channel(String) \
        .include_custom(Boolean)

Parameter	Type	Required	Default	Description
channel	str	yes		Channel name
include_custom	bool	Optional	False	Whether to include the custom object in the fetch response.
include_status	Boolean	No	True	Whether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_type	Boolean	No	True	Whether to include the type field in the fetch response. Setting this to False will prevent this value from being returned.

Basic Usage

Synchronous:

pubnub.get_channel_metadata().\
            include_custom(True).\
            channel("channel").\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_channel_metadata().\
            include_custom(True).\
            channel("channel").\
            pn_async(callback)

Returns

The get_channel_metadata() operation returns a PNGetChannelMetadataResult which contains the following properties:

Property Name	Type	Description
data		Dictionary containing channel metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with channel metadata.

Key	Description
id	Channel metadata ID
name	Name associated with channel metadata object
description	Description associated with channel metadata object
status	Channel status value
type	Channel type value
custom	Custom object associated with channel metadata object in form of dictionary containing string to string pairs

Set Channel Metadata

Set metadata for a channel in the database, optionally including its custom data object.

Method(s)

To Set Channel Metadata you can use the following method(s) in the Python SDK:

pubnub.set_channel_metadata() \
        .channel(String) \
        .set_name(String) \
        .set_status(String) \
        .set_type(String) \
        .description(String) \
        .custom(Dictionary) \
        .include_custom(Boolean)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel ID.
set_name	String	No	N/A	Name of the channel.
set_status	String	No	N/A	Channel status. Max. 50 characters.
set_type	String	No	N/A	Channel type. Max. 50 characters.
description	String	No	N/A	Description of a channel.
custom	Map<String, Object>	No	N/A	Any object of key-value pairs with supported data types. App Context filtering language doesn’t support filtering by custom properties.
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.

API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Basic Usage

Synchronous:

pubnub.set_channel_metadata() \
            .include_custom(True) \
            .channel("channel id") \
            .set_name("Channel Name") \
            .set_status("Archived") \
            .set_type("Archived") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.set_channel_metadata() \
            .include_custom(True) \
            .channel("channel id") \
            .set_name("Channel Name") \
            .set_status("Archived") \
            .set_type("Archived") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .pn_async(callback)

Returns

The set_channel_metadata() operation returns a PNSetChannelMetadataResult which contains the following properties:

Property Name	Type	Description
data		Dictionary containing channel metadata
status	PNStatus	Status of the operation

Where each element in data list contains dictionary with channel metadata.

Key	Description
id	channel metadata id
name	Name associated with channel metadata object
description	Description associated with channel metadata object
status	Channels status value
type	Channels type value
custom	Custom object associated with channel metadata object in form of dictionary containing string to string pairs

Remove Channel Metadata

Removes the metadata from a specified channel.

Method(s)

To Remove Channel Metadata you can use the following method(s) in the Python SDK:

pubnub.remove_channel_metadata() \
        .channel(String)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel name

Basic Usage

Synchronous:

pubnub.remove_channel_metadata() \
            .channel("channel id") \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_channel_metadata() \
            .channel("channel id") \
            .pn_async(callback)

Returns

The remove_channel_metadata() operation returns a PNRemoveChannelMetadataResult which contains the following properties:

Property Name	Type	Description
status	PNStatus	Status of the operation

Channel Memberships

Get Channel Memberships

The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions.

Method(s)

To Get Channel Memberships you can use the following method(s) in the Python SDK:

pubnub.get_memberships() \
        .uuid(String) \
        .limit(Integer) \
        .page(PNPage Object) \
        .filter(String) \
        .sort(* PNSortKey Object) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_channel(Integer)

Parameter	Type	Required	Default	Description
uuid	String	Optional	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
limit	Integer	Optional	100	The maximum number of objects to retrieve at a time
page	PNPage	Optional	N/A	The paging object used for pagination
filter	String	Optional	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	Optional	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	Optional	False	Request totalCount to be included in paginated response, which is omitted by default
include_custom	Boolean	Optional	False	Whether to include the custom object in the fetch response
include_channel	Integer	Optional	N/A	The level of channel details to return in the membership. Possible values are defined as constants in ChannelIncludeEndpoint: ChannelIncludeEndpoint.CHANNEL and ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.get_memberships().\
            include_custom(True).\
            include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM).\
            uuid("Some UUID").sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_memberships().\
            include_custom(True).\
            include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM).\
            uuid("Some UUID").pn_async(callback)

Returns

The get_memberships() operation returns a PNGetMembershipsResult which contains the following properties:

Property Name	Type	Description
data		List of dictionaries containing memberships metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
channel	Dictionary containing channel metadata (id, name, description, custom)
custom	Custom object associated with membership in form of dictionary containing string to string pairs

Set Channel Memberships

Set channel memberships for a UUID.

Method(s)

To Set Channel Memberships you can use the following method(s) in the Python SDK:

pubnub.set_memberships() \
        .channel_memberships([PNChannelMembership]) \
        .uuid(String) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSort Object) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_channel(Integer)

Parameter	Type	Required	Default	Description
channelMemberships	[PNChannelMembership]	yes		Collection of PNChannelMembership to add to membership
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	N/A	The paging object used for pagination
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request totalCount to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response
include_channel	Integer	No	N/A	The level of channel details to return in the membership. Possible values are defined as constants in ChannelIncludeEndpoint: ChannelIncludeEndpoint.CHANNEL and ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM

API limits

To learn about the maximum length of parameters used to set channel membership metadata, refer to REST API docs.

Basic Usage

Synchronous:

some_channel = "somechannel"
        some_channel_with_custom = "somechannel_with_custom"

        pubnub.set_channel_metadata()\
            .channel(some_channel)\
            .set_name("some name")\
            .sync()

        custom_1 = {
            "key3": "val1",
            "key4": "val2"}
        pubnub.set_channel_metadata() \
            .channel(some_channel_with_custom) \
            .set_name("some name with custom") \
            .custom(custom_1) \

show all 33 lines

Asynchronous:

def callback(response, status):
    pass

some_channel = "somechannel"
        some_channel_with_custom = "somechannel_with_custom"

        pubnub.set_channel_metadata()\
            .channel(some_channel)\
            .set_name("some name")\
            .sync()

        custom_1 = {
            "key3": "val1",
            "key4": "val2"}
        pubnub.set_channel_metadata() \

show all 36 lines

Returns

The set_memberships() operation returns a PNSetMembershipsResult which contains the following properties:

Property Name	Type	Description
data		List of dictionaries containing memberships metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
channel	Dictionary containing channel metadata (id, name, description, custom)
custom	Custom object associated with membership in form of dictionary containing string to string pairs

Remove Channel Memberships

Remove channel memberships for a UUID.

Method(s)

To Remove Channel Memberships you can use the following method(s) in the Python SDK:

pubnub.remove_memberships() \
        .channel_memberships([PNChannelMembership]) \
        .uuid(String) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSort) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_channel(Integer)

Parameter	Type	Required	Default	Description
channel_memberships	[PNChannelMembership]	yes		List of channels (as PNChannelMembership) to remove from membership.
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
limit	Integer	No	100	The maximum number of objects to retrieve at a time.
page	PNPage	No	N/A	The paging object used for pagination.
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request totalCount to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response.
include_channel	Integer	No	N/A	The level of channel details to return in the membership. Possible values are defined as constants in ChannelIncludeEndpoint: ChannelIncludeEndpoint.CHANNEL and ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.remove_memberships()\
            .uuid("some_uuid")\
            .channel_memberships([PNChannelMembership.channel(some_channel)])\
            .include_custom(True)\
            .include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM)\
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_memberships()\
            .uuid("some_uuid")\
            .channel_memberships([PNChannelMembership.channel(some_channel)])\
            .include_custom(True)\
            .include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM)\
            .pn_async(callback)

Returns

The remove_memberships() operation returns a PNRemoveMembershipsResult which contains the following properties:

Property Name	Type	Description
data		List of dictionaries containing memberships metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
channel	Dictionary containing channel metadata (id, name, description, custom)
custom	Custom object associated with membership in form of dictionary containing string to string pairs

Manage Channel Memberships

Manage a user's channel memberships.

Method(s)

To Manage Channel Memberships you can use the following method(s) in the Python SDK:

pubnub.manage_memberships() \
        .uuid(String) \
        .set([PNChannelMembership>]) \
        .remove([PNChannelMembership]) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_channel(Integer)

Parameter	Type	Required	Default	Description
uuid	String	No	pubnub.configuration.uuid	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
set	[PNChannelMembership]	yes		List of members PNChannelMembership to add to channel
remove	[PNChannelMembership]	yes		List of members PNChannelMembership to remove from channel
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	null	The paging object used for pagination
filter	String	No	null	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	false	Request include_total_count to be included in paginated response, which is omitted by default
include_custom	Boolean	No	false	Whether to include the custom object in the fetch response
include_channel	Integer	No	N/A	The level of channel details to return in the membership. Possible values are defined as constants in ChannelIncludeEndpoint: ChannelIncludeEndpoint.CHANNEL and ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.manage_memberships() \
            .uuid("some_uuid") \
            .set([PNChannelMembership.channel(some_channel)]) \
            .remove([PNChannelMembership.channel(some_channel_with_custom)]) \
            .include_custom(True) \
            .include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM) \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.manage_memberships() \
            .uuid("some_uuid") \
            .set([PNChannelMembership.channel(some_channel)]) \
            .remove([PNChannelMembership.channel(some_channel_with_custom)]) \
            .include_custom(True) \
            .include_channel(ChannelIncludeEndpoint.CHANNEL_WITH_CUSTOM) \
            .pn_async(callback)

Returns

The manage_memberships() operation returns a PNManageMembershipsResult which contains the following properties:

Property Name	Type	Description
data		List of dictionaries containing memberships metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
channel	Dictionary containing channel metadata (id, name, description, custom)
custom	Custom object associated with membership in form of dictionary containing string to string pairs

Channel Members

Get Channel Members

The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database.

Method(s)

To Get Channel Members you can use the following method(s) in the Python SDK:

pubnub.get_channel_members() \
        .channel(String) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_uuid(Integer)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel name
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	N/A	The paging object used for pagination
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request include_total_count to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response
include_uuid	Integer	No	N/A	The level of uuid metadata details to return in the channel member. Possible values are defined as constants in UUIDIncludeEndpoint: UUIDIncludeEndpoint.UUID and UUIDIncludeEndpoint.UUID_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.get_channel_members().\
            channel("channel").\
            include_custom(True).\
            include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM).sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.get_channel_members().\
            channel("channel").\
            include_custom(True).\
            include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM).pn_async()

Returns

The get_channel_members() operation returns a PNGetChannelMembersResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing channel members metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
uuid	Dictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
custom	Custom object associated with channel member in form of dictionary containing string to string pairs

Set Channel Members

This method sets members in a channel.

Method(s)

To Set Channel Members you can use the following method(s) in the Python SDK:

pubnub.set_channel_members() \
        .channel(String) \
        .uuids([PNUUID object]) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_uuid(Integer)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel name
uuids	[PNUUID]	yes		List of members PNUUID to add to channel
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	null	The paging object used for pagination
filter	String	No	null	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request include_total_count to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response
include_uuid	Integer	No	N/A	The level of uuid metadata details to return in the channel member. Possible values are defined as constants in UUIDIncludeEndpoint: UUIDIncludeEndpoint.UUID and UUIDIncludeEndpoint.UUID_WITH_CUSTOM

API limits

To learn about the maximum length of parameters used to set channel members metadata, refer to REST API docs.

Basic Usage

Synchronous:

pubnub.set_uuid_metadata()\
            .uuid(some_uuid)\
            .set_name("some name")\
            .sync()

custom_1 = {
    "key3": "val1",
    "key4": "val2"}
pubnub.set_uuid_metadata() \
    .uuid(some_uuid_with_custom) \
    .set_name("some name with custom") \
    .custom(custom_1) \
    .sync()

uuids_to_set = [

show all 24 lines

Asynchronous:

def callback(response, status):
    pass

pubnub.set_uuid_metadata()\
            .uuid(some_uuid)\
            .set_name("some name")\
            .sync()

custom_1 = {
    "key3": "val1",
    "key4": "val2"}
pubnub.set_uuid_metadata() \
    .uuid(some_uuid_with_custom) \
    .set_name("some name with custom") \
    .custom(custom_1) \

show all 27 lines

Returns

The set_channel_members() operation returns a PNSetChannelMembersResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing channel members metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
uuid	Dictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
custom	Custom object associated with channel member in form of dictionary containing string to string pairs

Remove Channel Members

Remove members from a Channel.

Method(s)

To Remove Channel Members you can use the following method(s) in the Python SDK:

pubnub.remove_channel_members() \
        .channel(String) \
        .uuids([PNUUID]) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .includeUUID(Integer)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel name
uuids	[PNUUID]	yes		List of members (as PNUUID) to remove from channel
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	N/A	The paging object used for pagination
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request include_total_count to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response
include_uuid	Integer	No	N/A	The level of uuid metadata details to return in the channel member. Possible values are defined as constants in UUIDIncludeEndpoint: UUIDIncludeEndpoint.UUID and UUIDIncludeEndpoint.UUID_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.remove_channel_members()\
            .channel("channel id")\
            .uuids([PNUUID.uuid(some_uuid)])\
            .include_custom(True)\
            .include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM)\
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_channel_members()\
            .channel("channel id")\
            .uuids([PNUUID.uuid(some_uuid)])\
            .include_custom(True)\
            .include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM).pn_async()

Returns

The remove_channel_members() operation returns a PNRemoveChannelMembersResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing channel members metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
uuid	Dictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
custom	Custom object associated with channel member in form of dictionary containing string to string pairs

Manage Channel Members

Manage the members of a channel.

Method(s)

To Manage Channel Members you can use the following method(s) in the Python SDK:

pubnub.manage_channel_members() \
        .channel(String) \
        .set([PNUUID]) \
        .remove([PNUUID]) \
        .limit(Integer) \
        .page(PNPage) \
        .filter(String) \
        .sort(* PNSortKey) \
        .include_total_count(Boolean) \
        .include_custom(Boolean) \
        .include_uuid(Integer)

Parameter	Type	Required	Default	Description
channel	String	yes		Channel name
set	[PNUUID]	yes		List of members PNUUID to add to channel
remove	[PNUUID]	yes		List of members PNUUID to remove from channel
limit	Integer	No	100	The maximum number of objects to retrieve at a time
page	PNPage	No	N/A	The paging object used for pagination
filter	String	No	N/A	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort	PNSortKey	No	N/A	List of properties to sort by. Available options are id, name, and updated. Use asc or desc to specify sort direction. For example: {name: 'asc'}
include_total_count	Boolean	No	False	Request include_total_count to be included in paginated response, which is omitted by default
include_custom	Boolean	No	False	Whether to include the custom object in the fetch response
include_uuid	Integer	No	N/A	The level of uuid metadata details to return in the channel member. Possible values are defined as constants in UUIDIncludeEndpoint: UUIDIncludeEndpoint.UUID and UUIDIncludeEndpoint.UUID_WITH_CUSTOM

Basic Usage

Synchronous:

pubnub.manage_channel_members()\
            .channel("channel id")\
            .set([PNUUID.uuid(some_uuid)])\
            .remove([PNUUID.uuid(some_uuid_with_custom)])\
            .include_custom(True)\
            .include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM)\
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.pubnub.manage_channel_members()\
            .channel("channel id")\
            .set([PNUUID.uuid(some_uuid)])\
            .remove([PNUUID.uuid(some_uuid_with_custom)])\
            .include_custom(True)\
            .include_uuid(UUIDIncludeEndpoint.UUID_WITH_CUSTOM)\
            .pn_async(callback)

Returns

The manage_channel_members() operation returns a PNManageChannelMembersResult which contains the following properties:

Property Name	Type	Description
data	[]	List of dictionaries containing channel members metadata
status	PNStatus	Status of the operation
total_count	int	Total count of results (if include_total_count was set)
prev	PNPage.Previous	PNPage instance to be used if further requests
next	PNPage.Next	PNPage instance to be used if further requests

Where each element in data list contains dictionary with membership metadata.

Key	Description
uuid	Dictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
custom	Custom object associated with channel member in form of dictionary containing string to string pairs

PNChannelMembership class

PNChannelMembership is a utility class that exposes two factory methods: channel(channel) constructs a channel membership, and channel_with_custom(channelId, custom) constructs a channel membership with additional custom metadata.

class PNChannelMembership:
    __metaclass__ = ABCMeta

    def __init__(self, channel):
        self._channel = channel

    @staticmethod
    def channel(channel):
        return JustChannel(channel)

    @staticmethod
    def channel_with_custom(channel, custom):
        return ChannelWithCustom(channel, custom)

show all 24 lines

PNUUID class

PNUUID is a utility class that exposes two factory methods: uuid(uuid) constructs a UUID, and uuid_with_custom(channel_id, custom) constructs a UUID with additional custom metadata.

class PNUUID:
    __metaclass__ = ABCMeta

    def __init__(self, uuid):
        self._uuid = uuid

    @staticmethod
    def uuid(uuid):
        return JustUUID(uuid)

    @staticmethod
    def uuid_with_custom(uuid, custom):
        return UUIDWithCustom(uuid, custom)

show all 24 lines

App Context Filtering Language Definition

The filtering language for App Context is similar to the stream filtering language.

Note the following:

• Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.
• Custom properties must have the same type as the value used in the expression; it's an error to compare a custom property of one type to a value of another type.
• App Context that don't have the referenced custom property at all are excluded regardless of the operator or value used in the expression. The null value can be used to filter out objects that do or don't have the referenced custom property.
• The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.
• Values used with LIKE must be encoded just like any other string value. Thus, to escape an asterisk, the raw value must contain \\*.
• The entire expression must be URL-encoded when used in the query string.

Custom property filtering

You can't filter by custom properties.

<expression>           ::= <and_expression> ( "||" <and_expression> )*
<and_expression>       ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition>     ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path>        ::= <property_name> ( "." <property_name> )*
<property_name>        ::= <identifier> | "[" <string> "]"
<value>                ::= <string> | <number> | "true" | "false" | "null"

Tokens

<identifier>           ::=  <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator>  ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string>               ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
 | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
 | <unicode_char> - <double_quote> - "\" )* <double_quote>

show all 26 lines

Sample Object Filtering Expressions

The following simple expression returns results whose custom property named public is equal to Boolean true.

custom.public == true

The following date/time comparison returns results that were modified on or after August 31, 2019 (UTC):

updated >= "2019-08-31T00:00:00Z"

The following compound expression returns results that don't have a description, but do have a non-empty custom label or description property:

description == null && (custom.label != "" || custom.description != "")

The following wildcard expression returns results whose name starts with the letter X:

name LIKE 'X*'

The following escaped wildcard expression returns results whose name contains an asterisk (*):

name LIKE '*\\**'