Spaces 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.

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.

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
`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`	Optional	`False`	Whether to include the `custom` object in the fetch response

Basic Usage

Synchronous:

pubnub.fetch_space(). \
            include_custom(True). \
            space_id("my-space"). \
            sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.fetch_space(). \
            include_custom(True). \
            space_id("my-space"). \
            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
`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 a Space in the database, optionally including custom fields for each.

Method(s)

pubnub.create_space()
        .space_id(str)
        .name(str)
        .description(str)
        .custom(dict)
        .include_custom(bool)

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 a 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.
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response.

Basic Usage

Synchronous:

pubnub.create_space() \
            .include_custom(True) \
            .space_id("my-space") \
            .set_name("Space Name") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.create_space() \
            .include_custom(True) \
            .space_id("my-space") \
            .set_name("Space Name") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .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
`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 a Space in the database, optionally including custom fields for each.

Method(s)

pubnub.update_space()
        .space_id(str)
        .name(str)
        .description(str)
        .custom(dict)
        .include_custom(bool)

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 a 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.
`include_custom`	`bool`	No	`False`	Whether to include the `custom` object in the fetch response.

Basic Usage

Synchronous:

pubnub.update_space() \
            .include_custom(True) \
            .space_id("my-space") \
            .set_name("Space Name") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.update_space() \
            .include_custom(True) \
            .space_id("my-space") \
            .set_name("Space Name") \
            .description("Description") \
            .custom({ "key1": "val1", "key2": "val2" }) \
            .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.
`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() \
            .space_id("my-space") \
            .sync()

Asynchronous:

def callback(response, status):
    pass

pubnub.remove_space() \
            .space_id("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