PubNub LogoDocs
SupportContact SalesLoginTry Our APIs

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)
ParameterTypeRequiredDefaultDescription
limitintNo100The maximum number of objects to retrieve at a time
pagePNPageNoN/AThe paging object used for pagination
filterstrNoN/AExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
sort[PNSortKey]NoN/AList 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_countboolNoFalseRequest totalCount to be included in paginated response, which is omitted by default
include_customboolNoFalseWhether 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 NameTypeDescription
data[]List of dictionaries containing Space metadata
statusPNStatusStatus of the operation

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

KeyDescription
idSpace id
nameName associated with the Space metadata object
descriptionDescription associated with the Space metadata object
customCustom 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)
ParameterTypeRequiredDefaultDescription
space_idstryesSpace ID
include_customboolOptionalFalseWhether 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 NameTypeDescription
data{}Dictionary containing Space metadata
statusPNStatusStatus of the operation

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

KeyDescription
idSpace metadata id
nameName associated with the Space metadata object
descriptionDescription associated with the Space metadata object
customCustom 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)
ParameterTypeRequiredDefaultDescription
space_idstryesSpace ID.
namestrNoN/AName of the Space.
descriptionstrNoN/ADescription of a Space.
customMap<String, Object>NoN/AAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
include_customboolNoFalseWhether 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 NameTypeDescription
data{}Dictionary containing Space metadata
statusPNStatusStatus of the operation

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

KeyDescription
idSpace metadata id
nameName associated with the Space metadata object
descriptionDescription associated with the Space metadata object
customCustom 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)
ParameterTypeRequiredDefaultDescription
space_idstryesSpace ID.
namestrNoN/AName of the Space.
descriptionstrNoN/ADescription of a Space.
customMap<String, Object>NoN/AAny object of key-value pairs with supported data types. Objects filtering language doesn’t support filtering by custom properties.
include_customboolNoFalseWhether 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 NameTypeDescription
data{}Dictionary containing channel metadata
statusPNStatusStatus of the operation

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

KeyDescription
idSpace metadata ID.
nameName associated with the Space metadata object.
descriptionDescription associated with the Space metadata object.
customCustom 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)
ParameterTypeRequiredDefaultDescription
space_idstryesSpace 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 NameTypeDescription
statusPNStatusStatus of the operation
  • Fetch Spaces
  • Fetch Space
  • Create Space
  • Update Space
  • Remove Space
© PubNub Inc. - Privacy Policy