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 |