filestack-python

This is the official Python SDK for Filestack - API and content management system that makes it easy to add powerful file uploading and transformation capabilities to any web or mobile application.

from filestack import Client

cli = Client('<FILESTACK APIKEY>')
filelink = cli.upload(filepath='/path/to/image.jpg')
print(filelink.url)  # => 'https://cdn.filestackcontent.com/<FILE_HANDLE>'

Table of Contents

Installation & Quickstart

filestack-python can be installed from PyPI:

$ pip install filestack-python

or directly from GitHub:

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

To upload a file, all you need to do is to create an instance of filestack.Client with your Filestack API Key and use the upload() method:

1
2
3
4
from filestack import Client

cli = Client('<FILESTACK_APIKEY>')
filelink = cli.upload(filepath='path/to/video.mp4')

Proceed Uploading files to section to learn more about file uploaing options.

Uploading files

Filestack Python SDK allows you to uploads local files, file-like objects and files from external urls.

Local files

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from filestack import Client

cli = Client('<FILESTACK_APIKEY>')
filelink = cli.upload(filepath='path/to/video.mp4')

# upload to non-default storage provider under specific path
store_params = {
    'location': 'gcs',  # Google Cloud Storage
    'path': 'folder/subfolder/video_file.mpg'
}
filelink = cli.upload(filepath='path/to/video.mp4', store_params=store_params)

File-like objects

1
2
3
4
5
from filestack import Client

cli = Client('<FILESTACK_APIKEY>')
with open('path/to/video.mp4', 'rb') as f:
    filelink = cli.upload(file_obj=f)

To upload in-memory bytes:

1
2
3
4
5
6
7
import io
from filestack import Client

bytes_to_upload = b'content'

cli = Client('<FILESTACK_APIKEY>')
filelink = cli.upload(file_obj=io.BytesIO(bytes_to_upload))

External urls

1
2
3
4
from filestack import Client

cli = Client('<FILESTACK_APIKEY>')
filelink = cli.upload_url(url='https://f4fcdn.eu/wp-content/uploads/2018/06/krakowmain.jpg')

Store params

Each upload function shown above takes a store_params argument which is a Python dictionary with following keys (all are optional):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
store_params = {
    'filename': 'string',
    'location': 'string',
    'path': 'string',
    'container': 'string',
    'mimetype': 'string',
    'region': 'string',
    'access': 'string',
    'base64decode': True|False,
    'workflows': ['workflow-id-1', 'workflow-id-2'],
    'upload_tags': {
        'key': 'value',
        'key2': 'value'
    }
}
  • filename - name for the stored file
  • location - storage provider to be used
  • path - the path to store the file within the specified container
  • container - the bucket or container (folder) in which to store the file (does not apply when storing to Dropbox)
  • mimetype - mime type that should be stored in file’s metadata
  • region - storage region (applies to S3 only)
  • access - should the file be stored as "public" or "private" (applies to S3 only)
  • base64decode - indicates if content should be decoded before it is stored
  • workflows - IDs of Filestack Workflows that should be triggered after upload
  • upload_tags - set of key: value pairs that will be returned with webhook for particular upload

API Reference

Client

class filestack.Client(apikey, storage='S3', security=None)

This class is responsible for uploading files (creating Filelinks), converting external urls to Transformation objects, taking url screenshots and returning zipped files (multiple Filelinks).

In order to create a client instance, pass in your Filestack API key. You can also specify which storage should be used for your uploads and provide a Security object to sign all your API calls.

>>> from filestack import Client, Security
>>> security = Security(policy={'expiry': 1594200833}, secret='YOUR APP SECRET')
>>> cli = Client('<FILESTACK_APIKEY>', storage='gcs', security=security)
__init__(apikey, storage='S3', security=None)
Parameters:
  • apikey (str) – your Filestack API key
  • storage (str) – default storage to be used for uploads (one of S3, gcs, dropbox, azure)
  • security (filestack.Security) – Security object that will be used by default for all API calls
transform_external(external_url)

Turns an external URL into a Filestack Transformation object

>>> t_obj = client.transform_external('https://image.url')
>>> t_obj.resize(width=800)  # now you can do this
Parameters:external_url (str) – file URL
Returns:filestack.Transformation
upload(*, filepath=None, file_obj=None, store_params=None, intelligent=False, security=None)

Uploads local file or file-like object.

Parameters:
  • filepath (str) – path to file
  • file_obj (io.BytesIO or similar) – file-like object
  • store_params (dict) – store parameters to be used during upload
  • intelligent (bool) – upload file using Filestack Intelligent Ingestion.
  • security (filestack.Security) – Security object that will be used for this API call
Returns:

new Filelink object
Return type:

filestack.Filelink

Note

This method accepts keyword arguments only. Out of filepath and file_obj only one should be provided.

upload_url(url, store_params=None, security=None)

Uploads file from external url

Parameters:
  • url (str) – file URL
  • store_params (dict) – store parameters to be used during upload
  • security (filestack.Security) – Security object that will be used for this API call
Returns:

new Filelink object
Return type:

filestack.Filelink
urlscreenshot(url, agent=None, mode=None, width=None, height=None, delay=None)

Takes a ‘screenshot’ of the given URL

Parameters:
  • url (str) – website URL
  • agent (str) – one of: "desktop" "mobile"
  • mode (str) – one of: "all" "window"
  • width (int) – screen width
  • height (int) – screen height
Returns:

filestack.Transformation
zip(destination_path, files, security=None)

Takes array of handles and downloads a compressed ZIP archive to provided path

Parameters:
  • destination_path (str) – path where the ZIP file should be stored
  • file (list) – list of filelink handles and/or URLs
  • security (filestack.Security) – Security object that will be used for this API call
Returns:

ZIP archive size in bytes
Return type:

int

Security

class filestack.Security(policy, secret)

Security objects are used to sign API calls. To learn more about Filestack Security, please visit https://www.filestack.com/docs/concepts/security

>>> sec = Security({'expiry': 1562763146, 'call': ['read']}, 'SECURITY-SECRET')
>>> sec.policy
{'expiry': 1562763146, 'call': ['read']}
>>> sec.policy_b64
'eyJjYWxsIjogWyJyZWFkIl0sICJleHBpcnkiOiAxNTYyNzYzMTQ2fQ=='
>>> sec.signature
'89f1325dca54cfce976163fb692bb266f28129525b8c6bb0eeadf4b7d450e2f0'
__init__(policy, secret)
Parameters:
  • policy (dict) – policy to be used
  • secret (str) – your application secret
as_url_string()

Returns the security part of signed urls

Returns:url part in the form of security=p:<encoded policy>,s:<signature>
Return type:str

Transformation

class filestack.Transformation(apikey=None, handle=None, external_url=None, security=None)

Transformation objects represent the result of image transformation performed on Filelinks or other Transformations (as they can be chained). Unless explicitly stored, no Filelinks are created when image transformations are performed.

>>> from filestack import Filelink
>>> transformation= Filelink('sm9IEXAMPLEQuzfJykmA').resize(width=800)
>>> transformation.url
'https://cdn.filestackcontent.com/resize=width:800/sm9IEXAMPLEQuzfJykmA'
>>> new_filelink = transformation.store()
>>> new_filelink.url
'https://cdn.filestackcontent.com/NEW_HANDLE'
download(path, security=None)

Downloads a file to the given local path and returns the size of the downloaded file if successful

get_content(security=None)

Returns the raw byte content of a given object

Returns:file content
Return type:bytes
ocr(security=None)

Performs OCR on current object (image)

Parameters:security (filestack.Security) – Security object that will be used to run OCR
Returns:dictionary containing OCR data
Return type:dict
sfw(security=None)

Performs Safe for Work detection on current object (image).

Parameters:security (filestack.Security) – Security object that will be used to perform image tagging
Returns:dictionary containing SFW result
Return type:dict
signed_url(security=None)

Returns object’s URL signed using security object

>>> filelink.url
'https://cdn.filestackcontent.com/security=p:<encoded_policy>,s:<signature>/FILE_HANDLE'
>>> transformation.url
'https://cdn.filestackcontent.com/resize=width:800/security=p:<encoded_policy>,s:<signature>/FILE_HANDLE'
Parameters:security (filestack.Security) – Security object that will be used to sign url
Returns:object’s signed URL
Return type:str
store(filename=None, location=None, path=None, container=None, region=None, access=None, base64decode=None, workflows=None)

Stores current object as a new filestack.Filelink.

Parameters:
  • filename (str) – name for the stored file
  • location (str) – your storage location, one of: "s3" "azure" "dropbox" "rackspace" "gcs"
  • container (str) – the bucket or container (folder) in which to store the file (does not apply when storing to Dropbox)
  • path (str) – the path to store the file within the specified container
  • region (str) – your storage region (applies to S3 only)
  • access (str) – "public" or "private" (applies to S3 only)
  • base64decode (bool) – indicates if content should be decoded before it is stored
  • workflows (list) –

    IDs of Filestack Workflows that should be triggered after upload
Returns:

new Filelink object
Return type:

filestack.Filelink
tags(security=None)

Performs image tagging operation on current object (image)

Parameters:security (filestack.Security) – Security object that will be used to perform image tagging
Returns:dictionary containing image tags
Return type:dict
property url

Returns object’s URL

>>> filelink.url
'https://cdn.filestackcontent.com/FILE_HANDLE'
>>> transformation.url
'https://cdn.filestackcontent.com/resize=width:800/FILE_HANDLE'
Returns:object’s URL
Return type:str