Python-asyncio Files API Reference for Realtime Apps
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
inPNConfiguration
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 inchannel
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 thePNConfiguration
.
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. |