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

Send file

Upload file / data to specified channel.

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)

Parameter	Type	Required	Default	Description
channel	String	Yes		Channel for the file.
file_name	String	Yes		Name of the file to send.
message	Dictionary	Optional		Message which should be sent along with file to specified channel.
should_store	Boolean	Optional	True	Whether PubNub published file message should be stored in channel history.
ttl	Integer	Optional		How long message should be stored in channel's storage.
file_object	bytes or Python file object	Yes		Input stream with file content.
meta	Dictionary	Optional		Meta data object which can be used with the filtering ability.

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

# synchronous
with open("knights_of_ni.jpg", "rb") as fd:
    envelope = pubnub.send_file() \
        .channel("test_channel") \
        .file_name("knights_of_ni.jpg") \
        .message({"test_message": "test"}) \
        .file_object(fd) \
        .sync()

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

with open("knights_of_ni.jpg", "rb") as fd:
    pubnub.send_file() \

show all 20 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)

Parameter	Type	Required	Default	Description
channel	String	Yes		Channel to get the list of files.

Basic Usage

# synchronous
pubnub.list_files() \
    .channel("test_channel") \
    .sync()

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

pubnub.list_files() \
    .channel("test_channel") \
    .pn_async(callback)

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.
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 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)

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

Basic Usage

# Synchronous:
envelope = pubnub.get_file_url().\
        channel("test_channel").\
        file_id("fileID").\
        file_name("knights_of_ni.jpg").sync()

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

pubnub.get_file_url().\
        channel("test_channel").\
        file_id("fileID").\
        file_name("knights_of_ni.jpg").pn_async(callback)

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)

Parameter	Type	Required	Description
channel	String	Yes	Name of channel to which the file has been uploaded.
file_name	String	Yes	Name under which the uploaded file is stored.
file_id	String	Yes	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

# synchronous:
download_envelope = pubnub.download_file().\
        channel("test_channel").\
        file_id("fileId").\
        file_name("knights_of_ni.jpg").sync()

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

pubnub.download_file().\
        channel("test_channel").\
        file_id("fileID").\
        file_name("knights_of_ni.jpg").pn_async(callback)

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)

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

Basic Usage

# synchronous:
envelope = pubnub.delete_file().\
        channel("test_channel").\
        file_id("fileId").\
        file_name("knights_of_ni.jpg").sync()

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

pubnub.delete_file().\
        channel("test_channel").\
        file_id("fileId").\
        file_name("knights_of_ni.jpg").pn_async(callback)

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 file message from specified Channel.

Method(s)

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

Parameter	Type	Required	Default	Description
channel	String	Yes		Name of channel to publish file message.
meta	Dictionary	Optional		Meta data object which can be used with the filtering ability.
message	Dictionary	Optional		The payload.
file_id	String	Yes		Unique identifier of the file.
file_name	String	Yes		Name of the file.
should_store	Boolean	Optional	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	Int	Optional	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"}).\
        file_id("fileID").\
    file_name("knights_of_ni.jpg").\
        ttl(22).sync()

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

pubnub.publish_file_message().\
        channel("test_channel").\

show all 20 lines

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.