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

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.

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
ParameterDescription
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 which should be sent along with file to specified channel.
should_store
Type: Boolean
Default:
True
Whether PubNub published file message should be stored in channel history.
ttl
Type: Integer
Default:
n/a
How long message should be stored in 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
Meta data 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.

Basic Usage


Returns

The send_file() operation returns an Envelope which contains the following fields:

FieldTypeDescription
result
PNSendFileResult
A detailed object containing the result of the operation.
status
PNStatus
A status object with additional information.

PNSendFileResult

Property NameTypeDescription
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
ParameterDescription
channel *
Type: String
Default:
n/a
Channel to get the list of files.

Basic Usage


Returns

The list_files() operation returns an Envelope which contains the following fields:

FieldTypeDescription
result
PNGetFilesResult
A detailed object containing the result of the operation.
status
PNStatus
A status object with additional information.

PNGetFilesResult

Property NameTypeDescription
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.
prev
String
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
count
Int
Number of files returned.
data
List
List of channel files.

data contains the following properties:

Property NameTypeDescription
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
ParameterDescription
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.

Basic Usage


Returns

The get_file_url() operation returns an Envelope which contains the following fields:

FieldTypeDescription
result
PNGetFileDownloadURLResult
A detailed object containing the result of the operation.
status
PNStatus
A status object with additional information.

PNGetFileDownloadURLResult

Property NameTypeDescription
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
ParameterDescription
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

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.

Basic Usage


Returns

The download_file() operation returns an Envelope which contains the following fields:

FieldTypeDescription
result
PNDownloadFileResult
A detailed object containing the result of the operation.
status
PNStatus
A status object with additional information.

PNDownloadFileResult

Property NameTypeDescription
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
ParameterDescription
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.

Basic Usage


Returns

The download_file() operation returns an Envelope which contains the following fields:

FieldTypeDescription
result
PNDeleteFileResult
A detailed object containing the result of the operation.
status
PNStatus
A status object with additional information.

PNDeleteFileResult

Property NameTypeDescription
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
ParameterDescription
channel *
Type: String
Default:
n/a
Name of channel to publish file message.
meta
Type: Dictionary
Default:
n/a
Meta data 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
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: 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.

Basic Usage

# 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

Returns

The publish_file_message() operation returns an Envelope which contains the following fields:

FieldTypeDescription
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 NameTypeDescription
timestamp
String
The timetoken at which the message was published.
Last updated on