Spaces API for PubNub Python SDK

A Space is where online interactions within a given business domain happen. A Space may, for example, be an abstract representation of your home (for IoT device purposes), a chat channel about football (in chat applications), or a multiplayer game instance.

Enable Spaces API

To enable the Spaces API, set the PN_ENABLE_ENTITIES environment variable to True.

Fetch Spaces

Returns a paginated list of Spaces, optionally including custom fields for each.

Method(s)

pubnub.fetchSpaces()
        .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.fetchSpaces(). \
            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.fetchSpaces(). \
            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 fetchSpaces() operation returns a PNGFetchSpacesResult which contains the following properties:

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

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

Key	Description
id	Space id
name	Name associated with the Space metadata object.
space_status	Condition the Space is in.
space_type	Category used to classify the purpose of the Space.
description	Description associated with the Space metadata object.
custom	Custom object associated with the Space metadata object in form of dictionary containing string to string pairs.

Fetch Space

Returns metadata for the specified Space, optionally including custom fields for each.

Method(s)

pubnub.fetchSpace(space_id: str)
    .include_custom(bool)

Parameter	Type	Required	Default	Description
space_id	str	yes		Space ID
include_custom	bool	No	False	Whether to include the custom object in the fetch response

Basic Usage

Synchronous:

pubnub.fetch_space('some_space_id'). \
    include_custom(True). \
    sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.fetch_space('some_space_id'). \
        include_custom(True). \
        pn_async(callback)

Returns

The fetchSpace() operation returns a PNFetchSpaceResult which contains the following properties:

Property Name	Type	Description
data	{}	Dictionary containing Space metadata
status	PNStatus	Status of the operation

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

Key	Description
id	Space metadata id
name	Name associated with the Space metadata object
status	Condition the Space is in.
type	Category used to classify the purpose of the Space.
description	Description associated with the Space metadata object
custom	Custom object associated with the Space metadata object in form of dictionary containing string to string pairs

Create Space

Create metadata for the Space in the database, optionally including custom fields for each.

Method(s)

pubnub.create_space(space_id: str)
        .name(str)
        .description(str)
        .custom(dict)
        .space_status(str)
        .space_type(str)

Parameter	Type	Required	Default	Description
space_id	str	yes		Space ID.
name	str	No	N/A	Name of the Space.
description	str	No	N/A	Description of the Space.
custom	Map<String, Object>	No	N/A	Any object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
space_status	str	Optional	None	Condition the Space is in.
space_type	str	Optional	None	Category used to classify the purpose of the Space.

Basic Usage

Synchronous:

pubnub.create_space("my-space") \
    .include_custom(True) \
    .name("Space Name") \
    .description("Description") \
    .custom({ "key1": "val1", "key2": "val2" }) \
    .space_status("active") \
    .space_type("Group Chat") \
    .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.create_space("my-space") \
    .include_custom(True) \
    .name("Space Name") \
    .description("Description") \
    .custom({ "key1": "val1", "key2": "val2" }) \
    .space_status("active") \
    .space_type("Group Chat") \
    .pn_async(callback)

Returns

The createSpace() operation returns a PNCreateSpaceResult which contains the following properties:

Property Name	Type	Description
data	{}	Dictionary containing Space metadata
status	PNStatus	Status of the operation

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

Key	Description
id	Space metadata id
name	Name associated with the Space metadata object
status	Condition the Space is in.
type	Category used to classify the purpose of the Space.
description	Description associated with the Space metadata object
custom	Custom object associated with the Space metadata object in form of dictionary containing string to string pairs

Update Space

Update existing metadata for the Space in the database, optionally including custom fields for each.

Method(s)

pubnub.update_space(space_id: str)
    .name(str)
    .description(str)
    .custom(dict)
    .space_status(str)
    .space_type(str)

Parameter	Type	Required	Default	Description
space_id	str	yes		Space ID.
name	str	No	N/A	Name of the Space.
description	str	No	N/A	Description of the Space.
custom	Map<String, Object>	No	N/A	Any object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
space_status	str	Optional	None	Condition the Space is in.
space_type	str	Optional	None	Category used to classify the purpose of the Space.

Basic Usage

Synchronous:

pubnub.update_space("my-space") \
    .include_custom(True) \
    .name("Space Name") \
    .description("Description") \
    .custom({ "key1": "val1", "key2": "val2" }) \
    .space_status("active") \
    .space_type("Group Chat") \
    .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.update_space("my-space") \
    .include_custom(True) \
    .name("Space Name") \
    .description("Description") \
    .custom({ "key1": "val1", "key2": "val2" }) \
    .space_status("active") \
    .space_type("Group Chat") \
    .pn_async(callback)

Returns

The update_space() operation returns a PNUpdateSpaceResult 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	Space metadata ID.
name	Name associated with the Space metadata object.
space_status	Condition the Space is in.
space_type	Category used to classify the purpose of the Space.
description	Description associated with the Space metadata object.
custom	Custom object associated with the Space metadata object in form of dictionary containing string to string pairs.

Remove Space

Removes the metadata from a specified Space.

Method(s)

pubnub.remove_space(space_id: str)

Parameter	Type	Required	Default	Description
space_id	str	yes		Space ID.

Basic Usage

Synchronous:

pubnub.remove_space("my-space") \
    .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_space("my-space") \
    .pn_async(callback)

Returns

The remove_space() operation returns a PNRemoveSpaceResult which contains the following properties:

Property Name	Type	Description
status	PNStatus	Status of the operation