Files API for PubNub Python SDK
Python version support
Python SDK versions 5.0.0 and higher no longer support Python v2.7 and the Twisted and Tornado frameworks. If you require support for any of these, use SDK version 4.8.1.
Note that PubNub will stop supporting versions of Python lower than 3.7 by the end of 2021.
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
# 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"}).
should_store(True).
ttl(222).
file_object(fd).
cipher_key("secret").sync()
# multithreaded asynchronous
def callback(response, status):
pass
fd = open("knights_of_ni.jpg", "rb") as fd:
pubnub.send_file().
channel("test_channel").
file_name("knights_of_ni.jpg").
message({"test_message": "test"}).
should_store(True).
ttl(222).
file_object(fd.read()).
cipher_key("secret").pn_async(callback)
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
# 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 | 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
# 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").sync()
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
# 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
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
# 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
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
# 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").
meta({"test": "test"}).
message({"test_message": "test"}).
file_id("fileID").
file_name("knights_of_ni.jpg").
ttl(22).pn_async(callback)
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. |