File Sharing API for PubNub 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
Description
Upload file / data to specified channel.
Method(s)
pubnub.send_file(). channel(str). file_name(str). message(dict). should_store(bool). ttl(int). file_object(Python Object File or bytes). cipher_key(str)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
channel | String | Yes | Channel for the file. | |
file_name | String | Yes | Name of the file to send. | |
file_object | bytes or Python file object | Yes | Input stream with file content. | |
cipherKey | String | Optional | PNConfiguration#cipherKey | Key to be used to encrypt uploaded data. If not provided, cipherKey in PNConfiguration will be used, if provided. |
ttl | Integer | Optional | How long message should be stored in channel's storage. | |
should_store | Boolean | Optional | True | Whether PubNub published file message should be stored in channel history. |
message | Dict | Optional | Message which should be sent along with file to specified channel. | |
meta | Dict | Optional | Meta data object which can be used with the filtering ability. |
Basic Usage
with open("knights_of_ni.jpg", "rb") as fd:
envelope = await pubnub.send_file().\
channel("test_channel").\
file_name("knights_of_ni.jpg").\
message({"test_message": "test"}).\
should_store(True).\
ttl(222).\
file_object(fd).\
cipher_key("secret").future()
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
Description
Retrieve list of files uploaded to Channel.
Method(s)
pubnub.list_files().channel(str)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
channel | String | Yes | Channel to get the list of files. |
Basic Usage
envelope = await pubnub.list_files().channel("test_channel").future()
Returns
The list_file() operation returns a PNGetFilesResult which contains the following properties:
| Property Name | Type | Description |
|---|---|---|
next | String | Cursor bookmark for fetching the next page. |
prev | String | Cursor bookmark for fetching the previous page. |
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
Description
Generate URL which can be used to download file from target Channel.
Method(s)
pubnub.get_file_url(). channel(str). file_id(str). file_name(str)
| 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
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
Description
Download file from specified Channel.
Method(s)
pubnub.download_file(). channel(str). file_id(str). file_name(str)
| 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. |
cipher_key | String | Optional | Key to be used to decrypt downloaded data. If a key is not provided, the SDK uses the cipher_key from the PNConfiguration. |
Basic Usage
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
Description
Delete file from specified Channel.
Method(s)
pubnub.delete_file(). channel(str). file_id(str). file_name(str)
| 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
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
Description
Publish file message from specified Channel.
Method(s)
pubnub.publish_file_message(). channel(str). meta(dict). message(dict). file_id(str). file_name(str). should_store(bool). ttl(int)
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
channel | String | Yes | Name of channel to publish file message. | |
file_name | String | Yes | Name of the file. | |
file_id | String | Yes | Unique identifier of the file. | |
message | Dict | Optional | The payload. | |
meta | Dict | Optional | Meta data object which can be used with the filtering ability. | |
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
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. |