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)
ParameterTypeRequiredDefaultDescription
limitIntegerNoN/AThe maximum number of objects to retrieve at a time.
pagePNPageNoN/AThe paging object used for pagination.
filterStringNoN/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_countBooleanNoFalseRequest totalCount to be included in paginated response, which is omitted by default.
include_customBooleanNoFalseWhether to include the custom object in the fetch response.
include_statusBooleanNoTrueWhether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_typeBooleanNoTrueWhether 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 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
statusUser status value
typeUser 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)
ParameterTypeRequiredDefaultDescription
uuidStringNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
include_customBooleanNoFalseWhether to include the custom object in the fetch response.
include_statusBooleanNoTrueWhether to include the status field in the fetch response, which is included by default.
include_typeBooleanNoTrueWhether 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 NameTypeDescription
dataDictionary 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
statusStatus value associated with UUID object
typeType value associated with UUID object
customCustom 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)
ParameterTypeRequiredDefaultDescription
uuidStringNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
set_nameStringNoN/ADisplay name for the user.
set_statusStringNoN/AUser status. Max. 50 characters.
set_typeStringNoN/AUser type. Max. 50 characters.
external_idStringNoN/AUser's identifier in an external system.
profile_urlStringNoN/AThe URL of the user's profile picture.
emailStringNoN/AThe user's email address.
customAnyNoN/AAny object of key-value pairs with supported data types. App Context filtering language doesn’t support filtering by custom properties.
include_customBooleanNoFalseWhether 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 NameTypeDescription
dataDictionary 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
statusUser status
typeUser type
customCustom 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)
ParameterTypeRequiredDefaultDescription
uuidStringNopubnub.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

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)
ParameterTypeRequiredDefaultDescription
limitIntegerNo100The maximum number of objects to retrieve at a time.
pagePNPageNoN/AThe paging object used for pagination.
filterStringNoN/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_countBooleanNoFalseRequest totalCount to be included in paginated response, which is omitted by default.
include_customBooleanNoFalseWhether to include the custom object in the fetch response.
include_statusBooleanNoTrueWhether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_typeBooleanNoTrueWhether 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 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
statusChannel status value
typeChannel type value
customCustom 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)
ParameterTypeRequiredDefaultDescription
channelstryesChannel name
include_customboolOptionalFalseWhether to include the custom object in the fetch response.
include_statusBooleanNoTrueWhether to include the status field in the fetch response. Setting this to False will prevent this value from being returned.
include_typeBooleanNoTrueWhether 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 NameTypeDescription
dataDictionary 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
statusChannel status value
typeChannel type value
customCustom 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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel ID.
set_nameStringNoN/AName of the channel.
set_statusStringNoN/AChannel status. Max. 50 characters.
set_typeStringNoN/AChannel type. Max. 50 characters.
descriptionStringNoN/ADescription of a channel.
customMap<String, Object>NoN/AAny object of key-value pairs with supported data types. App Context filtering language doesn’t support filtering by custom properties.
include_customBooleanNoFalseWhether 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 NameTypeDescription
dataDictionary 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
statusChannels status value
typeChannels type value
customCustom 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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel 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

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)
ParameterTypeRequiredDefaultDescription
uuidStringOptionalpubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitIntegerOptional100The maximum number of objects to retrieve at a time
pagePNPageOptionalN/AThe paging object used for pagination
filterStringOptionalN/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_countBooleanOptionalFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customBooleanOptionalFalseWhether to include the custom object in the fetch response
include_channelIntegerOptionalN/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
dataList 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

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)
ParameterTypeRequiredDefaultDescription
channelMemberships[PNChannelMembership]yesCollection of PNChannelMembership to add to membership
uuidStringNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterStringNoN/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_countBooleanNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response
include_channelIntegerNoN/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
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 NameTypeDescription
dataList 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

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)
ParameterTypeRequiredDefaultDescription
channel_memberships[PNChannelMembership]yesList of channels (as PNChannelMembership) to remove from membership.
uuidStringNopubnub.configuration.uuidUnique UUID Metadata identifier.
If not supplied, then UUID from configuration will be used.
limitIntegerNo100The maximum number of objects to retrieve at a time.
pagePNPageNoN/AThe paging object used for pagination.
filterStringNoN/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_countBooleanNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response.
include_channelIntegerNoN/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
dataList 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

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)
ParameterTypeRequiredDefaultDescription
uuidStringNopubnub.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
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNonullThe paging object used for pagination
filterStringNonullExpression 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_countBooleanNofalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customBooleanNofalseWhether to include the custom object in the fetch response
include_channelIntegerNoN/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
dataList 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

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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel name
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterStringNoN/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_countBooleanNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response
include_uuidIntegerNoN/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

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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel name
uuids[PNUUID]yesList of members PNUUID to add to channel
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNonullThe paging object used for pagination
filterStringNonullExpression 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_countBooleanNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response
include_uuidIntegerNoN/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
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 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

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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel name
uuids[PNUUID]yesList of members (as PNUUID) to remove from channel
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterStringNoN/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_countBooleanNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response
include_uuidIntegerNoN/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

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)
ParameterTypeRequiredDefaultDescription
channelStringyesChannel name
set[PNUUID]yesList of members PNUUID to add to channel
remove[PNUUID]yesList of members PNUUID to remove from channel
limitIntegerNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterStringNoN/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_countBooleanNoFalseRequest include_total_count to be included in paginated response, which is omitted by default
include_customBooleanNoFalseWhether to include the custom object in the fetch response
include_uuidIntegerNoN/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
Last updated on