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

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)

Parameter	Type	Required	Default	Description
`limit`	`int`	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`	`str`	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`	`bool`	No	`False`	Request `totalCount` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether 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 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

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)

Parameter	Type	Required	Default	Description
`uuid`	`str`	No	`pubnub.configuration.uuid`	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
`include_custom`	`bool`	No	`False`	Whether 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 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
`custom`	Custom 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)

Parameter	Type	Required	Default	Description
`uuid`	`str`	No	`pubnub.configuration.uuid`	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
`set_name`	`str`	No	N/A	Display name for the user, up to 200 characters.
`external_id`	`str`	No	N/A	User's identifier in an external system.
`profile_url`	`str`	No	N/A	The URL of the user's profile picture.
`email`	`str`	No	N/A	The user's email address. Maximum 80 characters.
`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`	`bool`	No	`False`	Whether 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 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
`custom`	Custom 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)

Parameter	Type	Required	Default	Description
`uuid`	`str`	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

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)

Parameter	Type	Required	Default	Description
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `totalCount` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether 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 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
`custom`	Custom 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)

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

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
`custom`	Custom 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)

Parameter	Type	Required	Default	Description
`channel`	`str`	yes		Channel ID.
`name`	`str`	No	N/A	Name of the channel.
`description`	`str`	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`	`bool`	No	`False`	Whether 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 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
`custom`	Custom 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)

Parameter	Type	Required	Default	Description
`channel`	`str`	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

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)

Parameter	Type	Required	Default	Description
`uuid`	`str`	Optional	`pubnub.configuration.uuid`	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
`limit`	`int`	Optional	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	Optional	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	Optional	`False`	Request `totalCount` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	Optional	`False`	Whether to include the `custom` object in the fetch response
`include_channel`	`int`	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

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)

Parameter	Type	Required	Default	Description
`channelMemberships`	`[PNChannelMembership]`	yes		Collection of `PNChannelMembership` to add to membership
`uuid`	`str`	No	`pubnub.configuration.uuid`	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `totalCount` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response
`include_channel`	`int`	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:

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

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)

Parameter	Type	Required	Default	Description
`channel_memberships`	`[PNChannelMembership]`	yes		List of channels (as `PNChannelMembership`) to remove from membership.
`uuid`	`str`	No	`pubnub.configuration.uuid`	Unique UUID Metadata identifier. If not supplied, then UUID from configuration will be used.
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time.
`page`	`PNPage`	No	N/A	The paging object used for pagination.
`filter`	`str`	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`	`bool`	No	`False`	Request `totalCount` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response.
`include_channel`	`int`	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

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)

Parameter	Type	Required	Default	Description
`uuid`	`str`	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`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	`null`	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`false`	Request `include_total_count` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`false`	Whether to include the `custom` object in the fetch response
`include_channel`	`int`	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

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)

Parameter	Type	Required	Default	Description
`channel`	`str`	yes		Channel name
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `include_total_count` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response
`include_uuid`	`int`	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

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)

Parameter	Type	Required	Default	Description
`channel`	`str`	yes		Channel name
`uuids`	`[PNUUID]`	yes		List of members `PNUUID` to add to channel
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	`null`	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `include_total_count` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response
`include_uuid`	`int`	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.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

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)

Parameter	Type	Required	Default	Description
`channel`	`str`	yes		Channel name
`uuids`	`[PNUUID]`	yes		List of members (as `PNUUID`) to remove from channel
`limit`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `include_total_count` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response
`include_uuid`	`int`	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

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)

Parameter	Type	Required	Default	Description
`channel`	`str`	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`	`int`	No	100	The maximum number of objects to retrieve at a time
`page`	`PNPage`	No	N/A	The paging object used for pagination
`filter`	`str`	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`	`bool`	No	`False`	Request `include_total_count` to be included in paginated response, which is omitted by default
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response
`include_uuid`	`int`	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 '*\\**'

User​

Get Metadata for all Users​

Description​

Method(s)​

Basic Usage​

Returns​

Get User Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Set User Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Remove User Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Channel​

Get Metadata for all Channels​

Description​

Method(s)​

Basic Usage​

Returns​

Get Channel Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Set Channel Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Remove Channel Metadata​

Description​

Method(s)​

Basic Usage​

Returns​

Channel Memberships​

Get Channel Memberships​

Description​

Method(s)​

Basic Usage​

Returns​

Set Channel Memberships​

Description​

Method(s)​

Basic Usage​

Returns​

Remove Channel Memberships​

Description​

Method(s)​

Basic Usage​

Returns​

Manage Channel Memberships​

Description​

Method(s)​

Basic Usage​

Returns​

Channel Members​

Get Channel Members​

Description​

Method(s)​

Basic Usage​

Returns​

Set Channel Members​

Description​

Method(s)​

Basic Usage​

Returns​

Remove Channel Members​

Description​

Method(s)​

Basic Usage​

Returns​

Manage Channel Members​

User

Get Metadata for all Users

Description

Method(s)

Basic Usage

Returns

Get User Metadata

Description

Method(s)

Basic Usage

Returns

Set User Metadata

Description

Method(s)

Basic Usage

Returns

Remove User Metadata

Description

Method(s)

Basic Usage

Returns

Channel

Get Metadata for all Channels

Description

Method(s)

Basic Usage

Returns

Get Channel Metadata

Description

Method(s)

Basic Usage

Returns

Set Channel Metadata

Description

Method(s)

Basic Usage

Returns

Remove Channel Metadata

Description

Method(s)

Basic Usage

Returns

Channel Memberships

Get Channel Memberships

Description

Method(s)

Basic Usage

Returns

Set Channel Memberships

Description

Method(s)

Basic Usage

Returns

Remove Channel Memberships

Description

Method(s)

Basic Usage

Returns

Manage Channel Memberships

Description

Method(s)

Basic Usage

Returns

Channel Members

Get Channel Members

Description

Method(s)

Basic Usage

Returns

Set Channel Members

Description

Method(s)

Basic Usage

Returns

Remove Channel Members

Description

Method(s)

Basic Usage

Returns

Manage Channel Members