Files API for PubNub Python-asyncio 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.

Allows users to upload and share files. You can upload any file of up to 5 MB in size. This feature is commonly used in social apps to share images, or in medical apps to share medical records for patients.

When a file is uploaded on a channel, it's stored and managed using a storage service, and associated with your key. Subscribers to that channel receive a file event which contains a file ID, filename, and optional description.

Send file

Description

Upload file / data to specified channel.

Method(s)

pubnub.send_file().  channel(str).  file_name(str).  message(dict).  should_store(bool).  ttl(int).  file_object(Python Object File or bytes).  cipher_key(str)

Parameter	Type	Required	Default	Description
`channel`	String	Yes		Channel for the file.
`file_name`	String	Yes		Name of the file to send.
`file_object`	bytes or Python file object	Yes		Input stream with file content.
`cipherKey`	String	Optional	`PNConfiguration#cipherKey`	Key to be used to encrypt uploaded data. If not provided, `cipherKey` in `PNConfiguration` will be used, if provided.
`ttl`	Integer	Optional		How long message should be stored in channel's storage.
`should_store`	Boolean	Optional	`True`	Whether PubNub published `file message` should be stored in `channel` history.
`message`	Dict	Optional		Message which should be sent along with file to specified `channel`.
`meta`	Dict	Optional		`Meta` data object which can be used with the filtering ability.

Basic Usage

with open("knights_of_ni.jpg", "rb") as fd:
    envelope = await pubnub.send_file().
        channel("test_channel").
        file_name("knights_of_ni.jpg").
        message({"test_message": "test"}).
        should_store(True).
        ttl(222).
        file_object(fd).
        cipher_key("secret").future()

Returns

The send_file() operation returns a PNSendFileResult which contains the following properties:

Property Name	Type	Description
`name`	String	Name of the uploaded file.
`file_id`	String	ID of the uploaded file.
`timestamp`	String	The timetoken at which the message was published.

List channel files

Description

Retrieve list of files uploaded to Channel.

Method(s)

```
pubnub.list_files().channel(str)
```
Parameter Type Required Default Description

channel String Yes Channel to get the list of files.

Parameter	Type	Required	Default	Description
`channel`	String	Yes		Channel to get the list of files.

Basic Usage

envelope = await pubnub.list_files().channel("test_channel").future()

Returns

The list_file() operation returns a PNGetFilesResult which contains the following properties:

Property Name	Type	Description
`next`	String	Cursor bookmark for fetching the next page.
`prev`	String	Cursor bookmark for fetching the previous page.
`count`	Int	Number of files returned.
`data`	List	`List` of channel files.

data contains the following properties:

Property Name	Type	Description
`id`	Long	`Id` of the uploaded file.
`name`	String	`Name` of the upload file.
`size`	String	`Size` of the uploaded file.
`created`	String	Time of creation.

Get File Url

Description

Generate URL which can be used to download file from target Channel.

Method(s)

pubnub.get_file_url().  channel(str).  file_id(str).  file_name(str)

Parameter	Type	Required	Description
`channel`	String	Yes	Name of `channel` to which the file has been uploaded.
`file_name`	String	Yes	Name under which the uploaded file is stored.
`file_id`	String	Yes	Unique identifier for the file, assigned during upload.

Basic Usage

envelope = await pubnub.get_file_url().
    channel("test_channel").
    file_id("d9515cb7-48a7-41a4-9284-f4bf331bc770").
    file_name("knights_of_ni.jpg").future()

Returns

The get_file_url() operation returns a PNGetFileDownloadURLResult which contains the following properties:

Property Name	Type	Description
`file_url`	String	`URL` to be used to download the requested file.

Download file

Description

Download file from specified Channel.

Method(s)

pubnub.download_file().  channel(str).  file_id(str).  file_name(str)

Parameter	Type	Required	Description
`channel`	String	Yes	Name of `channel` to which the file has been uploaded.
`file_name`	String	Yes	Name under which the uploaded file is stored.
`file_id`	String	Yes	Unique identifier for the file, assigned during upload.
`cipher_key`	String	Optional	Key to be used to decrypt downloaded data. If a key is not provided, the SDK uses the `cipher_key` from the `PNConfiguration`.

Basic Usage

download_envelope = await pubnub.download_file().
    channel("test_channel").
    file_id("fileId").
    file_name("knights_of_ni.jpg").future()

Returns

The download_file() operation returns a PNDownloadFileResult which contains the following properties:

Property Name	Type	Description
`data`	bytes	Python bytes object.

Delete file

Description

Delete file from specified Channel.

Method(s)

pubnub.delete_file().  channel(str).  file_id(str).  file_name(str)

Parameter	Type	Required	Description
`channel`	String	Yes	The `channel` from which to delete the file.
`file_id`	String	Yes	Unique identifier of the file to be deleted.
`file_name`	String	Yes	Name of the file to be deleted.

Basic Usage

envelope = await pubnub.delete_file().
    channel("test_channel").
    file_id("fileId").
    file_name("knights_of_ni.jpg").future()

Returns

The delete_file() operation returns a PNDeleteFileResult which contains the following property:

Property Name	Type	Description
`status`	Int	Returns a status code.

Publish file message

Description

Publish file message from specified Channel.

Method(s)

pubnub.publish_file_message().  channel(str).  meta(dict).  message(dict).  file_id(str).  file_name(str).  should_store(bool).  ttl(int)

Parameter	Type	Required	Default	Description
`channel`	String	Yes		Name of `channel` to publish file message.
`file_name`	String	Yes		Name of the file.
`file_id`	String	Yes		Unique identifier of the file.
`message`	Dict	Optional		The payload.
`meta`	Dict	Optional		Meta data object which can be used with the filtering ability.
`should_store`	Boolean	Optional	`True`	Set to `False` to not store this message in history. By default, messages are stored according to the retention policy you set on your key.
`ttl`	Int	Optional	`0`	How long the message should be stored in the channel's history. If not specified, defaults to the key set's retention value.

Basic Usage

envelope = await pubnub.publish_file_message().
    channel("test_channel").
    meta({"test": "test"}).
    message({"test_message": "test"}).
    file_id("fileID").
    file_name("knights_of_ni.jpg").
    ttl(22).future()

Returns

The publish_file_message() operation returns a PNPublishFileMessageResult which contains the following property:

Property Name	Type	Description
`timestamp`	String	The timetoken at which the message was published.