Filestack Logo Docs homepage

Python SDK

Documentation

The full source code can be found on GitHub. For more information about this SDK, please see Python API Reference.

Installation

Install filestack package with pip

pip install --upgrade filestack-python

or directly from GitHub

pip install git+https://github.com/filestack/filestack-python.git

If you don’t have pip installed you can install it by running this command:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

You can also install Filestack SDK from source code with:

python setup.py install

Requirements

Since version 3.0.0 of this SDK, we support Python 3.5+.

If you’re still using an older version of Python (e.g., 2.7), you can install older SDK releases, but please remember it’s in maitenance mode only.

pip install "filestack-python<3.0.0"

Configuration

The library needs to be configured with your API key which is available in your Filestack Developer Portal.

Initializing Filestack Client

from filestack import Client
client = Client(YOUR_API_KEY)

Security

Security may be required for certain API requests, such as overwrite and delete, or if security has been enabled for the application.

One way of using Security is to pass it as an argument on when initializing Client or Filelink classes.

from filestack import Security

policy = {"expiry": 253381964415}
security = Security(policy, YOUR_APP_SECRET)
client = Client(YOUR_API_KEY, security=security)

You can also pass security objects when making API requests

from filestack import Security, Client, Filelink
upload_only_policy = {
    "expiry": 1572390000, "call": ["pick"]
}

security = Security(upload_only_policy, YOUR_APP_SECRET)

client = Client(YOUR_API_KEY)
client.upload("/path/to/image.jpg", security=security)

read_only_policy = {
    "expiry": 1572390000, "call": ["read"]
}
flink = Filelink(FILE_HANDLE)
security = Security(read_only_policy, YOUR_APP_SECRET)
flink.signed_url(security=security)

Usage

Upload from file

store_params = {
    "mimetype": "image/png"
}
new_filelink = client.upload(filepath="path/to/file", store_params=store_params)
print(new_filelink.url)  # 'https://cdn.filestackcontent.com/FILE_HANDLE'

You can also upload file-like objects and any byte content

import io

content = b'bytes-in-memory'
new_filelink = client.upload(file_obj=io.BytesIO(content))

Uploading local files will use Filestack’s multipart upload.

Upload from url

store_params = {
    "filename": "image_from_url.jpg"
}
new_filelink = client.upload_url("https://URL_TO_FILE", store_params=store_params)

Intelligent Ingestion

To upload files using Filestack Intelligent Ingestion, simply add intelligent=True argument

new_filelink = client.upload(filepath="path/to/file", intelligent=True)

Intelligent Ingestion always uses multipart uploads. In case of network issues, it will dynamically split file parts into smaller chunks.

You can create a Filelink object from existing handle.

from filestack import Filelink
filelink = Filelink(YOUR_HANDLE)

With a Filelink, you can perform File API operations. You can download files to a local path:

size_in_bytes = new_filelink.download("/save/file/here")

Get content of a file.

file_content = new_filelink.get_content()

Overwrite it. This action requires security

filelink.overwrite(filepath="path/to/new/file")

Or delete it. This action requires security

filelink.delete()

Transformations

You can chain Processing API transformations on Filelinks, External URLs and Storage Aliases. Storing transformations will return a new Filelink object.

transform = client.transform_external("http://<SOME_URL>")
new_filelink = transform.resize(width=500, height=500).flip().enhance().store()

filelink = Filelink(YOUR_HANDLE)
new_filelink = filelink.resize(width=500, height=500).flip().enhance().store()

You can also retrieve the transformation url at any point.

transform_candidate = client.transform_external("http://<SOME_URL>")
transform = transform_candidate.resize(width=500, height=500).flip().enhance()
print(transform.url)

Audio/Video Convert

Audio and video conversion works just like any transformation, except it returns an instance of class AudioVisual, which allows you to check the status of your video conversion, as well as get its UUID and timestamp.

av_object = filelink.av_convert(width=100, height=100)
while (av_object.status != "completed"):
    print(av_object.status)
    print(av_object.uuid)
    print(av_object.timestamp)

The status property calls the API to check its current status, and you can call to_filelink() once video is complete (this function checks its status first and will fail if not completed yet).

filelink = av_object.to_filelink()