Memberships API for PubNub Python SDK

Python version support

Python SDK versions 5.0.0 and higher no longer support Python v2.7 and the Twisted and Tornado frameworks. If you require support for any of these, use SDK version 4.8.1.

Note that PubNub will stop supporting versions of Python lower than 3.7 by the end of 2021.

PubNub allows you to store the relation between Users and Spaces through Memberships. Using the Memberships API, you can track and display all available User-to-Space and Space-to-User associations and provide additional details about the type of relation a User and the Space have, like, for example, being an administrator of the Space.

Enable Memberships API

To enable Memberships API:

TODO

Fetch User Memberships

Returns memberships for the specified User optionally including custom fields.

Method(s)

pubnub.fetch_memberships(). 
    user_id(str).
    limit(int).
    page(PNPage Object).
    filter(str).
    include_total_count(bool).
    include_custom(bool).
    include_space_details(SpaceDetailsLevel?) TODO

Parameter	Type	Required	Default	Description
user_id	str	yes		User to fetch memberships of.
limit	int	No	N/A TODO	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.
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_space_details	TODO	TODO	TODO	TODO

Basic Usage

Synchronous:

pubnub.fetch_memberships().\
            user_id("Neo")\
            limit(10).\
            page(None).\
            include_total_count(True).\
            include_custom(True).\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.fetch_memberships().\
            user_id("Neo")\
            limit(10).\
            page(None).\
            include_total_count(True).\
            include_custom(True).\
            pn_async(callback)

Returns

The fetch_memberships() operation returns a PNFetchUsersResult which contains the following properties:

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

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

TODO

Key	Description
id	User ID.
name	Name associated with User object
type	Category used to classify the purpose of a User
status	Condition the User is in
externalId	External ID associated with User object
profileUrl	Profile URL associated with User object
email	Email address associated with User object
custom	Custom object associated with User object in form of dictionary containing string to string pairs

Fetch Space Memberships

Returns memberships for the specified Space optionally including custom fields.

Method(s)

pubnub.fetch_memberships(). 
    space_id(str).
    limit(int).
    page(PNPage Object).
    filter(str).
    include_total_count(bool).
    include_custom(bool).
    include_space_details(SpaceDetailsLevel?) TODO

Parameter	Type	Required	Default	Description
space_id	str	yes		Space to fetch memberships of.
limit	int	No	N/A TODO	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.
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_space_details	TODO	TODO	TODO	TODO

Basic Usage

Synchronous:

pubnub.fetch_memberships().\
            space_id("Real World")\
            limit(10).\
            page(None).\
            include_total_count(True).\
            include_custom(True).\
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.fetch_memberships().\
            space_id("Real World")\
            limit(10).\
            page(None).\
            include_total_count(True).\
            include_custom(True).\
            pn_async(callback)

Returns

The fetch_memberships() operation returns a PNFetchUsersResult which contains the following properties:

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

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

TODO

Key	Description
id	User ID.
name	Name associated with User object
type	Category used to classify the purpose of a User
status	Condition the User is in
externalId	External ID associated with User object
profileUrl	Profile URL associated with User object
email	Email address associated with User object
custom	Custom object associated with User object in form of dictionary containing string to string pairs

Add User Memberships

Adds memberships for the specified User.

Method(s)

pubnub.add_memberships().
    TODO

Parameter	Type	Required	Default	Description
spaceIdsWithCustomsTODO	List	Yes		List of Space IDs to add the User the membership to. The list can contain strings (spaceId only) or objects which can include custom data, for example: { id: "my-space-3", custom: { owner: "PubNubUser" } }
userIdTODO	String	Optional	current userId	User to add the membership to. If not supplied then current user's userId is used.

Basic Usage

TODO

Returns

The add_memberships() operation returns a TODO which contains the following properties:

TODO

Property Name	Type	Description
status	PNStatus	Status of the operation

Add Space Memberships

Adds memberships for the specified Space.

Method(s)

pubnub.add_memberships().
    TODO

Parameter	Type	Required	Default	Description
spaceIdsWithCustomsTODO	List	Yes		List of Space IDs to add the User the membership to. The list can contain strings (spaceId only) or objects which can include custom data, for example: { id: "my-space-3", custom: { owner: "PubNubUser" } }
userIdTODO	String	Optional	current userId	User to add the membership to. If not supplied then current user's userId is used.

Basic Usage

TODO

Returns

The add_memberships() operation returns a TODO which contains the following properties:

TODO

Property Name	Type	Description
status	PNStatus	Status of the operation

Update User Memberships

Updates memberships for the specified User.

Method(s)

pubnub.update_memberships()
TODO

Parameter	Type	Required	Default	Description
spaceIdsWithCustomsTODO	List	Yes		Array of spaces to update the memberships to. Array can contain strings (space name only) or objects which can include custom data, for example: { id: "my-space-3", custom: { owner: "PubNubUser" } }.
userIdTODO	String	Optional	current userId	Unique user identifier. If not supplied then current user's userId is used.

Basic Usage

TODO

Returns

The update_memberships() operation returns a TODO which contains the following properties:

TODO

Property Name	Type	Description
status	PNStatus	Status of the operation

Update Space Memberships

Updates memberships for the specified Space.

Method(s)

pubnub.update_memberships()
TODO

Parameter	Type	Required	Default	Description
spaceIdsWithCustomsTODO	List	Yes		Array of spaces to update the memberships to. Array can contain strings (space name only) or objects which can include custom data, for example: { id: "my-space-3", custom: { owner: "PubNubUser" } }.
userIdTODO	String	Optional	current userId	Unique user identifier. If not supplied then current user's userId is used.

Basic Usage

TODO

Returns

The update_memberships() operation returns a TODO which contains the following properties:

TODO

Property Name	Type	Description
status	PNStatus	Status of the operation

Remove User Memberships

Removes memberships from the specified User.

Method(s)

pubnub.remove_memberships().
TODO

Parameter	Type	Required	Default	Description
space_idsTODO	List	Yes		Spaces to remove the user from.
user_idTODO	String	Yes	current user_id	Unique user identifier. If not supplied then current user's user_id is used.

Basic Usage

Synchronous:

TODO

Asynchronous:

TODO

Returns

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

Property Name	Type	Description
status	PNStatus	Status of the operation

Remove Space Memberships

Removes memberships from the specified Space.

Method(s)

Method(s)

pubnub.remove_memberships().
TODO

Parameter	Type	Required	Default	Description
space_idsTODO	List	Yes		Spaces to remove the user from.
user_idTODO	String	Yes	current user_id	Unique user identifier. If not supplied then current user's user_id is used.

Basic Usage

Synchronous:

TODO

Asynchronous:

TODO

Returns

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

Property Name	Type	Description
status	PNStatus	Status of the operation

Events

PubNub sends out system-wide events when Memberships, Spaces/Channels, and Users are created, updated, or removed. You can choose to receive these events to trigger additional logic.

Enabling/Disabling events

You can configure whether events are generated in the Admin Portal.

Receive Membership events

To receive Membership events on, for example, matrix channel:

1. Subscribe to the channel:

TODO

1. Add a dedicated Memberships listener:

TODO

Membership created or updated event

The following is the structure of the Membership create/update event:

TODO

Membership removed event

The following is the structure of the remove event:

TODO