File Sharing API for 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

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, send_file internally calls the publish_file_message method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

Method(s)

pubnub.send_file()
    .channel(channel) \
    .file_name(file_name) \
    .message(message) \
    .should_store(should_store) \
    .ttl(ttl) \
    .file_object(file_object) \
    .cipher_key(cipher_key) \
    .future()

* required

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

Sample code

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

import asyncio
import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub_asyncio import PubNubAsyncio
from pubnub.exceptions import PubNubException


async def send_file(pubnub: PubNubAsyncio):
    try:
        with open("knights_of_ni.jpg", "rb") as fd:
            # Send a file with additional options
            envelope = await pubnub.send_file() \
                .channel("test_channel") \
                .file_name("knights_of_ni.jpg") \
                .message({"test_message": "test"}) \
show all 49 lines

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

Retrieve list of files uploaded to Channel.

Method(s)

pubnub.list_files().channel(String)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Channel to get the list of files.
`limit` Type: Int Default: n/a	The number of elements to return.
`next` Type: String Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.

Sample code

envelope = await pubnub.list_files().channel("test_channel").limit(10).next("XYZ....ABC").future()

Returns

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

Property Name	Type	Description
`next`	String	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
`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

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

Method(s)

pubnub.get_file_url() \
    .channel(String) \
    .file_id(String) \
    .file_name(String)

* required

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

Sample code

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

Download file from specified Channel.

Method(s)

pubnub.download_file() \
    .channel(String) \
    .file_id(String) \
    .file_name(String)

* required

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

Sample code

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

Delete file from specified Channel.

Method(s)

pubnub.delete_file() \
    .channel(String) \
    .file_id(String) \
    .file_name(String)

* required

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

Sample code

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

Publish the uploaded file message to a specified channel.

This method is called internally by send_file as part of the file-sending process to publish the message with the file (already uploaded in a storage service) on a channel.

This message includes the file's unique identifier and name elements, which are needed to construct download links and inform channel subscribers that the file is available for download.

You can call this method when send_file fails and returns the status.operation === PNPublishFileMessageOperation error. In that case, you can use the data from the status object to try again and use publish_file_message to manually resend a file message to a channel without repeating the upload step.

Method(s)

pubnub.publish_file_message() \
    .channel(String) \
    .meta(Dictionary) \
    .message(Dictionary) \
    .file_id(String) \
    .file_name(String) \
    .should_store(Boolean) \
    .ttl(Integer)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Name of `channel` to publish file message.
`file_name` * Type: String Default: n/a	Name of the file.
`file_id` * Type: String Default: n/a	Unique identifier of the file.
`message` Type: Dictionary Default: n/a	The payload.
`meta` Type: Dictionary Default: n/a	Meta data object which can be used with the filtering ability.
`should_store` Type: Boolean Default: `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` Type: Integer Default: `0`	How long the message should be stored in the channel's history. If not specified, defaults to the key set's retention value.

Sample code

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.

Send file​

Method(s)​

Sample code​

Reference code

Returns​

List channel files​

Method(s)​

Sample code​

Returns​

Get file URL​

Method(s)​

Sample code​

Returns​

Download file​

Method(s)​

Sample code​

Returns​

Delete file​

Method(s)​

Sample code​

Returns​

Publish file message​

Method(s)​

Sample code​

Returns​

Send file

Method(s)

Sample code

Returns

List channel files

Method(s)

Sample code

Returns

Get file URL

Method(s)

Sample code

Returns

Download file

Method(s)

Sample code

Returns

Delete file

Method(s)

Sample code

Returns

Publish file message

Method(s)

Sample code

Returns