File Sharing API for Python-Asyncio SDK

Use the Files API to upload and share files up to 5 MB. Common use cases include social apps that share images and healthcare apps that share medical records.

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.

For details on the method that publishes the file message, see Publish file message.

Method(s)

1pubnub.send_file()
2    .channel(channel) \
3    .file_name(file_name) \
4    .message(message) \
5    .should_store(should_store) \
6    .ttl(ttl) \
7    .file_object(file_object) \
8    .cipher_key(cipher_key) \
9    .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 used to encrypt uploaded data. If not provided, the cipherKey in PNConfiguration is used if configured.
ttl Type: Integer Default: n/a	How long the message should be stored in the channel's storage.
should_store Type: Boolean Default: True	Whether to store the published file message in the channel history.
message Type: Dictionary Default: n/a	Message to send along with the file to the specified channel.
meta Type: Dictionary Default: n/a	Metadata object that can be used with the filtering capability.

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.

1import asyncio
2import os
3from pubnub.pnconfiguration import PNConfiguration
4from pubnub.pubnub_asyncio import PubNubAsyncio
5from pubnub.exceptions import PubNubException
6

7

8async def send_file(pubnub: PubNubAsyncio):
9    try:
10        with open("knights_of_ni.jpg", "rb") as fd:
11            # Send a file with additional options
12            envelope = await pubnub.send_file() \
13                .channel("test_channel") \
14                .file_name("knights_of_ni.jpg") \
15                .message({"test_message": "test"}) \
16                .should_store(True) \
17                .ttl(222) \
18                .file_object(fd) \
19                .cipher_key("secret") \
20                .future()
21

22            if envelope.status.is_error():
23                print("Error sending file")
24            else:
25                print(f"File sent successfully: {envelope.result.name}")
26

27    except PubNubException as e:
28        print(f"Error: {e}")
29    except FileNotFoundError:
30        print("File not found, please check the file path")
31

32

33if __name__ == "__main__":
34    loop = asyncio.new_event_loop()
35    asyncio.set_event_loop(loop)
36

37    # Configuration for PubNub instance
38    pn_config = PNConfiguration()
39    pn_config.subscribe_key = os.getenv('SUBSCRIBE_KEY', 'demo')
40    pn_config.publish_key = os.getenv('PUBLISH_KEY', 'demo')
41    pn_config.user_id = "my_custom_user_id"
42

43    pubnub = PubNubAsyncio(pn_config)
44

45    try:
46        loop.run_until_complete(send_file(pubnub))
47    finally:
48        loop.run_until_complete(pubnub.stop())
49        loop.close()

show all 49 lines

Returns

The send_file() operation returns a PNSendFileResult with 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 a list of files uploaded to a channel.

Method(s)

1pubnub.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 dataset. Used for forward pagination to fetch the next page and continue from where you left off.

Sample code

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

Returns

The list_files() operation returns a PNGetFilesResult with 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 uploaded file.
size	String	Size of the uploaded file.
created	String	Time of creation.

Get file URL

Generate a URL to download a file from the target channel.

Method(s)

1pubnub.get_file_url() \
2    .channel(String) \
3    .file_id(String) \
4    .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

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

Returns

The get_file_url() operation returns a PNGetFileDownloadURLResult with the following property:

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

Download file

Download a file from the specified channel.

Method(s)

1pubnub.download_file() \
2    .channel(String) \
3    .file_id(String) \
4    .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 used to decrypt downloaded data. If not provided, the SDK uses the cipher_key from the PNConfiguration.

Sample code

1download_envelope = await pubnub.download_file().\
2    channel("test_channel").\
3    file_id("fileId").\
4    file_name("knights_of_ni.jpg").future()

Returns

The download_file() operation returns a PNDownloadFileResult with the following property:

Property Name	Type	Description
data	bytes	Python bytes object.

Delete file

Delete a file from the specified channel.

Method(s)

1pubnub.delete_file() \
2    .channel(String) \
3    .file_id(String) \
4    .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

1envelope = await pubnub.delete_file().\
2    channel("test_channel").\
3    file_id("fileId").\
4    file_name("knights_of_ni.jpg").future()

Returns

The delete_file() operation returns a PNDeleteFileResult with 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)

1pubnub.publish_file_message() \
2    .channel(String) \
3    .meta(Dictionary) \
4    .message(Dictionary) \
5    .file_id(String) \
6    .file_name(String) \
7    .should_store(Boolean) \
8    .ttl(Integer)

* required

Parameter	Description
channel * Type: String Default: n/a	Name of the channel to publish the 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	Metadata object that can be used with the filtering capability.
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 set on your key.
ttl Type: Integer Default: 0	How long the message is stored in the channel's history. If not specified, defaults to the key set's retention value.

Sample code

1envelope = await pubnub.publish_file_message().\
2    channel("test_channel").\
3    meta({"test": "test"}).\
4    message({"test_message": "test"}).\
5    file_id("fileID").\
6    file_name("knights_of_ni.jpg").\
7    ttl(22).future()

Returns

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

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