File Sharing API for Python SDK

You can upload and share files up to 5 MB on PubNub. Common uses include sharing images in chat apps and documents in healthcare.

When you upload a file to a channel, PubNub stores it with your key. Subscribers on that channel receive a file event with the file ID, file name, and an optional description.

Request execution and return values

You can decide whether to perform the Python SDK operations synchronously or asynchronously.

.sync() returns an Envelope object, which has two fields: Envelope.result, whose type differs for each API, and Envelope.status of type PnStatus.
```
pubnub.publish() \
    .channel("myChannel") \
    .message("Hello from PubNub Python SDK") \
    .sync()
```

.pn_async(callback) returns None and passes the values of Envelope.result and Envelope.status to a callback you must define beforehand.

def my_callback_function(result, status):
    print(f'TT: {result.timetoken}, status: {status.category.name}')

pubnub.publish() \
    .channel("myChannel") \
    .message("Hello from PubNub Python SDK") \
    .pn_async(my_callback_function)

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)

pubnub.send_file() \
    .channel(String) \
    .file_name(String) \
    .message(Dictionary) \
    .should_store(Boolean) \
    .ttl(Integer) \
    .file_object(Python Object File or bytes) \
    .meta(Dictionary) \
    .custom_message_type(String)

* 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.
`message` Type: Dictionary Default: n/a	Message to send along with the file to the specified `channel`.
`should_store` Type: Boolean Default: `True`	Whether to store the published `file message` in the `channel` history.
`ttl` Type: Integer Default: n/a	How long the message should be stored in the channel's storage.
`file_object` * Type: bytes or Python file object Default: n/a	Input stream with file content.
`meta` Type: Dictionary Default: n/a	Metadata object which can be used with the filtering ability.
`custom_message_type` Type: String Default: n/a	A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes `-` and underscores `_` are allowed. The value cannot start with special characters or the string `pn_` or `pn-`. Examples: `text`, `action`, `poll`.

Deprecated parameter

The cipher_key parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass cipher_key as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

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.

Builder Pattern
Named Arguments

import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
from pubnub.exceptions import PubNubException


def send_file(pubnub: PubNub, file_path: str, channel: str):
    try:
        with open(file_path, 'rb') as sample_file:
            response = pubnub.send_file() \
                .channel(channel) \
                .file_name("sample.gif") \
                .message({"test_message": "test"}) \
                .file_object(sample_file) \
                .sync()
show all 39 lines

import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub
from pubnub.exceptions import PubNubException


def send_file(pubnub: PubNub, file_path: str, channel: str):
    try:
        with open(file_path, 'rb') as sample_file:
            response = pubnub.send_file(
                channel=channel,
                file_name="sample.gif",
                file_object=sample_file,
                message="Hey, it's gif not jif",
                custom_message_type="file-message"
show all 41 lines

Returns

Returns an Envelope.

Field	Type	Description
result	`PNSendFileResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNSendFileResult

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)

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

Builder Pattern
Named Arguments

file_list_response = pubnub.list_files(channel="ch1", limit=10, next="xyz...abc").sync()
print(f"Found {len(file_list_response.result.data)} files:")

for file_data in file_list_response.result.data:
    print(f"  {file_data['name']} with id: {file_data['id']}")

Returns

Returns an Envelope.

Field	Type	Description
result	`PNGetFilesResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNGetFilesResult

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 a URL to download a file from the 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

Builder Pattern
Named Arguments

download_url = pubnub.get_file_url(channel="ch1",
                                   file_id=file_data['id'],
                                   file_data['name']) \
    .sync()

print(f'  Download url: {download_url.result.file_url}')

Returns

Returns an Envelope.

Field	Type	Description
result	`PNGetFileDownloadURLResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNGetFileDownloadURLResult

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)

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.

Deprecated parameter

Sample code

Builder Pattern
Named Arguments

download_url = pubnub.download_file(channel="ch1",
                                    file_id=file_data['id'],
                                    file_data['name']) \
    .sync()

fw = open(f"{os.getcwd()}/{file_data['name']}", 'wb')
fw.write(download_file.result.data)

print(f"File saved as {os.getcwd()}/{file_data['name']}")

Returns

Returns an Envelope.

Field	Type	Description
result	`PNDownloadFileResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNDownloadFileResult

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

Delete file

Delete a file from the 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

Builder Pattern
Named Arguments

pubnub.delete_file(channel="ch1",
                   file_id=file_data['id'],
                   file_data['name']) \
    .sync()

print(f"File deleted")

Returns

Returns an Envelope.

Field	Type	Description
result	`PNDeleteFileResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNDeleteFileResult

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) \
    .custom_message_type(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.
`meta` Type: Dictionary Default: n/a	Metadata object which can be used with the filtering ability.
`message` Type: Dictionary Default: n/a	The payload.
`file_id` * Type: String Default: n/a	Unique identifier of the file.
`custom_message_type` Type: String Default: n/a	A case-sensitive, alphanumeric string from 3 to 50 characters describing the business-specific label or category of the message. Dashes `-` and underscores `_` are allowed. The value cannot start with special characters or the string `pn_` or `pn-`. Examples: `text`, `action`, `poll`.
`file_name` * Type: String Default: n/a	Name of the file.
`should_store` Type: Boolean Default: `True`	Whether to store this message in history. Set to `False` to not store it. By default, messages are stored according to the retention policy set on your key.
`ttl` Type: Int 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

Builder Pattern
Named Arguments

# synchronous:
envelope = pubnub.publish_file_message() \
    .channel("test_channel") \
    .meta({"test": "test"}) \
    .message({"test_message": "test"}) \
    .custom_message_type("file-message") \
    .file_id("fileID") \
    .file_name("knights_of_ni.jpg") \
    .ttl(22) \
    .sync()

# multithreaded asynchronous:
def callback(response, status):
    pass

show all 24 lines

envelope = pubnub.publish_file_message(channel="test_channel",
                                       message="Bring me a shrubbery",
                                       file_id="fileID",
                                       file_name="knights_of_ni.jpg",
                                       custom_message_type="file-message",
                                       meta={"nice": True, "expensive": False},
                                       ttl=22) \
    .sync()

Returns

Returns an Envelope.

Field	Type	Description
result	`PNPublishFileMessageResult`	A detailed object containing the result of the operation.
status	`PNStatus`	A status object with additional information.

PNPublishFileMessageResult

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.

Request execution and return values

Send file​

Method(s)​

Deprecated parameter

Sample code​

Reference code

Returns​

PNSendFileResult​

List channel files​

Method(s)​

Sample code​

Returns​

PNGetFilesResult​

Get file URL​

Method(s)​

Sample code​

Returns​

PNGetFileDownloadURLResult​

Download file​

Method(s)​

Deprecated parameter

Sample code​

Returns​

PNDownloadFileResult​

Delete file​

Method(s)​

Sample code​

Returns​

PNDeleteFileResult​

Publish file message​

Method(s)​

Sample code​

Returns​

PNPublishFileMessageResult​

Send file

Method(s)

Sample code

Returns

PNSendFileResult

List channel files

Method(s)

Sample code

Returns

PNGetFilesResult

Get file URL

Method(s)

Sample code

Returns

PNGetFileDownloadURLResult

Download file

Method(s)

Sample code

Returns

PNDownloadFileResult

Delete file

Method(s)

Sample code

Returns

PNDeleteFileResult

Publish file message

Method(s)

Sample code

Returns

PNPublishFileMessageResult