Files API for PubNub Python-Asyncio SDK

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)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel for the file.
file_nameStringYesName of the file to send.
file_objectbytes or Python file objectYesInput stream with file content.
cipherKeyStringOptionalPNConfiguration#cipherKeyKey to be used to encrypt uploaded data. If not provided, cipherKey in PNConfiguration will be used, if provided.
ttlIntegerOptionalHow long message should be stored in channel's storage.
should_storeBooleanOptionalTrueWhether PubNub published file message should be stored in channel history.
messageDictOptionalMessage which should be sent along with file to specified channel.
metaDictOptionalMeta 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 NameTypeDescription
nameStringName of the uploaded file.
file_idStringID of the uploaded file.
timestampStringThe 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)
ParameterTypeRequiredDefaultDescription
channelStringYesChannel 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 NameTypeDescription
nextStringCursor bookmark for fetching the next page.
prevStringCursor bookmark for fetching the previous page.
countIntNumber of files returned.
dataListList of channel files.

data contains the following properties:

Property NameTypeDescription
idLongId of the uploaded file.
nameStringName of the upload file.
sizeStringSize of the uploaded file.
createdStringTime 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)
ParameterTypeRequiredDescription
channelStringYesName of channel to which the file has been uploaded.
file_nameStringYesName under which the uploaded file is stored.
file_idStringYesUnique 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 NameTypeDescription
file_urlStringURL 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)
ParameterTypeRequiredDescription
channelStringYesName of channel to which the file has been uploaded.
file_nameStringYesName under which the uploaded file is stored.
file_idStringYesUnique identifier for the file, assigned during upload.
cipher_keyStringOptionalKey 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 NameTypeDescription
databytesPython bytes object.

Delete file

Description

Delete file from specified Channel.

Method(s)

pubnub.delete_file().  channel(str).  file_id(str).  file_name(str)
ParameterTypeRequiredDescription
channelStringYesThe channel from which to delete the file.
file_idStringYesUnique identifier of the file to be deleted.
file_nameStringYesName 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 NameTypeDescription
statusIntReturns 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)
ParameterTypeRequiredDefaultDescription
channelStringYesName of channel to publish file message.
file_nameStringYesName of the file.
file_idStringYesUnique identifier of the file.
messageDictOptionalThe payload.
metaDictOptionalMeta data object which can be used with the filtering ability.
should_storeBooleanOptionalTrueSet to False to not store this message in history. By default, messages are stored according to the retention policy you set on your key.
ttlIntOptional0How 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 NameTypeDescription
timestampStringThe timetoken at which the message was published.
Last updated on