Metadata API for PubNub Python SDK

This page describes the new Objects v2. To upgrade from Objects v1, refer to the migration guide.

Objects provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use Objects 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

Description

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(int).\
page(PNPage Object).\
filter(str).\
sort(*PNSortKey Object).\
include_total_count(bool).\
include_custom(bool)
ParameterTypeRequiredDefaultDescription
limitintNoN/AThe maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortList<PNSortKey>NoN/AList 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_countboolNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response

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 NameTypeDescription
data[]List of dictionaries containing UUID metadata
statusPNStatusStatus of the operation

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

KeyDescription
idUUID
nameName associated with UUID object
externalIdExternal ID associated with UUID object
profileUrlProfile URL associated with UUID object
emailEmail address associated with UUID object
customCustom object associated with UUID object in form of dictionary containing string to string pairs

Get User Metadata

Description

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(str)
.include_custom(bool)
ParameterTypeRequiredDefaultDescription
uuidstrNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
include_customboolNoFalseWhether to include the custom object in the fetch response

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 NameTypeDescription
data{}Dictionary containing UUID metadata
statusPNStatusStatus of the operation

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

KeyDescription
idUUID
nameName associated with UUID object
externalIdExternal ID associated with UUID object
profileUrlProfile URL associated with UUID object
emailEmail address associated with UUID object
customCustom object associated with UUID object in form of dictionary containing string to string pairs

Set User Metadata

Description

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(str).\
set_name(str).\
external_id(str).\
profile_url(str).\
email(str).\
custom(dict).\
include_custom(True)
ParameterTypeRequiredDefaultDescription
uuidstrNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
set_namestrNoN/ADisplay name for the user, up to 200 characters.
external_idstrNoN/AUser's identifier in an external system.
profile_urlstrNoN/AThe URL of the user's profile picture.
emailstrNoN/AThe user's email address. Maximum 80 characters.
customAnyNoN/AAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
include_customboolNoFalseWhether to include the custom object in the fetch response.

Basic Usage

Synchronous:

pubnub.set_uuid_metadata() \
.include_custom(True) \
.uuid("Some UUID") \
.set_name("Soem Name") \
.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("Soem Name") \
.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 NameTypeDescription
data{}Dictionary containing UUID metadata
statusPNStatusStatus of the operation

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

KeyDescription
idUUID
nameName associated with UUID object
externalIdExternal ID associated with UUID object
profileUrlProfile URL associated with UUID object
emailEmail address associated with UUID object
customCustom object associated with UUID object in form of dictionary containing string to string pairs

Remove User Metadata

Description

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(str)
ParameterTypeRequiredDefaultDescription
uuidstrNopubnub.configuration.uuidUnique 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 NameTypeDescription
statusPNStatusStatus of the operation

Channel

Get Metadata for all Channels

Description

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(int)
.page(PNPage)
.filter(str)
.sort(PNSortKey)
.include_total_count(bool)
.include_custom(bool)
ParameterTypeRequiredDefaultDescription
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort[PNSortKey]NoN/AList 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_countboolNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response

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 NameTypeDescription
data[]List of dictionaries containing channel metadata
statusPNStatusStatus of the operation

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

KeyDescription
idchannel metadata id
nameName associated with channel metadata object
descriptionDescription associated with channel metadata object
customCustom object associated with channel metadata object in form of dictionary containing string to string pairs

Get Channel Metadata

Description

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(str)
.include_custom(bool)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
include_customboolOptionalFalseWhether to include the custom object in the fetch response

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 NameTypeDescription
data{}Dictionary containing channel metadata
statusPNStatusStatus of the operation

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

KeyDescription
idchannel metadata id
nameName associated with channel metadata object
descriptionDescription associated with channel metadata object
customCustom object associated with channel metadata object in form of dictionary containing string to string pairs

Set Channel Metadata

Description

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(str)
.set_name(str)
.description(str)
.custom(dict)
.include_custom(bool)
ParameterTypeRequiredDefaultDescription
channelstryesChannel ID.
namestrNoN/AName of the channel.
descriptionstrNoN/ADescription of a channel.
customMap<String, Object>NoN/AAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
include_customboolNoFalseWhether to include the custom object in the fetch response.

Basic Usage

Synchronous:

pubnub.set_channel_metadata() \
.include_custom(True) \
.channel("channel id") \
.set_name("Channel Name") \
.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") \
.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 NameTypeDescription
data{}Dictionary containing channel metadata
statusPNStatusStatus of the operation

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

KeyDescription
idchannel metadata id
nameName associated with channel metadata object
descriptionDescription associated with channel metadata object
customCustom object associated with channel metadata object in form of dictionary containing string to string pairs

Remove Channel Metadata

Description

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(str)
ParameterTypeRequiredDefaultDescription
channelstryesChannel 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 NameTypeDescription
statusPNStatusStatus of the operation

Channel Memberships

Get Channel Memberships

Description

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(str)
.limit(int)
.page(PNPage Object)
.filter(str)
.sort(* PNSortKey Object)
.include_total_count(bool)
.include_custom(bool)
.include_channel(int)
ParameterTypeRequiredDefaultDescription
uuidstrOptionalpubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitintOptional100The maximum number of objects to retrieve at a time
pagePNPageOptionalN/AThe paging object used for pagination
filterstrOptionalN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyOptionalN/AList 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_countboolOptionalFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolOptionalFalseWhether to include the custom object in the fetch response
include_channelintOptionalN/AThe 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 NameTypeDescription
data{}List of dictionaries containing memberships metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
channelDictionary containing channel metadata (id, name, description, custom)
customCustom object associated with membership in form of dictionary containing string to string pairs

Set Channel Memberships

Description

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(str)
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSort Object)
.include_total_count(bool)
.include_custom(bool)
.include_channel(int)
ParameterTypeRequiredDefaultDescription
channelMemberships[PNChannelMembership]yesCollection of PNChannelMembership to add to membership
uuidstrNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response
include_channelintNoN/AThe 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:

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 NameTypeDescription
data{}List of dictionaries containing memberships metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
channelDictionary containing channel metadata (id, name, description, custom)
customCustom object associated with membership in form of dictionary containing string to string pairs

Remove Channel Memberships

Description

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(str)
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSort)
.include_total_count(bool)
.include_custom(bool)
.include_channel(int)
ParameterTypeRequiredDefaultDescription
channel_memberships[PNChannelMembership]yesList of channels (as PNChannelMembership) to remove from membership.
uuidstrNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitintNo100The maximum number of objects to retrieve at a time.
pagePNPageNoN/AThe paging object used for pagination.
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response.
include_channelintNoN/AThe 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 NameTypeDescription
data{}List of dictionaries containing memberships metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
channelDictionary containing channel metadata (id, name, description, custom)
customCustom object associated with membership in form of dictionary containing string to string pairs

Manage Channel Memberships

Description

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(str)
.set([PNChannelMembership>])
.remove([PNChannelMembership])
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSortKey)
.include_total_count(bool)
.include_custom(bool)
.include_channel(int)
ParameterTypeRequiredDefaultDescription
uuidstrNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
set[PNChannelMembership]yesList of members PNChannelMembership to add to channel
remove[PNChannelMembership]yesList of members PNChannelMembership to remove from channel
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNonullThe paging object used for pagination
filterstrNonullExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNofalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customboolNofalseWhether to include the custom object in the fetch response
include_channelintNoN/AThe 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 NameTypeDescription
data{}List of dictionaries containing memberships metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
channelDictionary containing channel metadata (id, name, description, custom)
customCustom object associated with membership in form of dictionary containing string to string pairs

Channel Members

Get Channel Members

Description

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(str)
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSortKey)
.include_total_count(bool)
.include_custom(bool)
.include_uuid(int)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response
include_uuidintNoN/AThe 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 NameTypeDescription
data[]List of dictionaries containing channel members metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
uuidDictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
customCustom object associated with channel member in form of dictionary containing string to string pairs

Set Channel Members

Description

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(str)
.uuids([PNUUID object])
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSortKey)
.include_total_count(bool)
.include_custom(bool)
.include_uuid(int)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
uuids[PNUUID]yesList of members PNUUID to add to channel
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNonullThe paging object used for pagination
filterstrNonullExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response
include_uuidintNoN/AThe 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.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 NameTypeDescription
data[]List of dictionaries containing channel members metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
uuidDictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
customCustom object associated with channel member in form of dictionary containing string to string pairs

Remove Channel Members

Description

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(str)
.uuids([PNUUID])
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSortKey)
.include_total_count(bool)
.include_custom(bool)
.includeUUID(int)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
uuids[PNUUID]yesList of members (as PNUUID) to remove from channel
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response
include_uuidintNoN/AThe 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 NameTypeDescription
data[]List of dictionaries containing channel members metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
uuidDictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
customCustom object associated with channel member in form of dictionary containing string to string pairs

Manage Channel Members

Description

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(str)
.set([PNUUID])
.remove([PNUUID])
.limit(int)
.page(PNPage)
.filter(str)
.sort(* PNSortKey)
.include_total_count(bool)
.include_custom(bool)
.include_uuid(int)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
set[PNUUID]yesList of members PNUUID to add to channel
remove[PNUUID]yesList of members PNUUID to remove from channel
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sortPNSortKeyNoN/AList 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_countboolNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether to include the custom object in the fetch response
include_uuidintNoN/AThe 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 NameTypeDescription
data[]List of dictionaries containing channel members metadata
statusPNStatusStatus of the operation
total_countintTotal count of results (if include_total_count was set)
prevPNPage.PreviousPNPage instance to be used if further requests
nextPNPage.NextPNPage instance to be used if further requests

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

KeyDescription
uuidDictionary containing UUID metadata (id, name, email, externalId, profileUrl, custom)
customCustom 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

Objects Filtering Language Definition

The filtering language for Objects 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.
  • Objects 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 '*\\**'
Last updated on