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

Filelink¶

class filestack.Filelink(handle, apikey=None, security=None, upload_response=None)¶

Filelink object represents a file that whas uploaded to Filestack. A filelink object can be created by uploading a file using Client instance, or by initializing Filelink class with a handle (unique id) of already uploaded file.

>>> from filestack import Filelink
>>> flink = Filelink('sm9IEXAMPLEQuzfJykmA')
>>> flink.url
'https://cdn.filestackcontent.com/sm9IEXAMPLEQuzfJykmA'

__init__(handle, apikey=None, security=None, upload_response=None)¶

Parameters:	handle (str) – The path of the file to wrap apikey (str) – Filestack API key that may be required for some API calls security (`filestack.Security`) – Security object that will be used by default for all API calls

delete(apikey=None, security=None)¶

Deletes filelink.

Parameters:	apikey (str) – Filestack API key that will be used for this API call security (`filestack.Security`) – Security object that will be used to delete filelink
Returns:	None

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

metadata(attributes_list=None, security=None)¶

Retrieves filelink’s metadata.

Parameters:	attributes_list (list) – list of attributes that you wish to receive. When not provided, default set of parameters will be returned (may differ depending on your storage settings) security (`filestack.Security`) – Security object that will be used to retrieve metadata

>>> filelink.metadata(['size', 'filename'])
{'filename': 'envelope.jpg', 'size': 171832}

Returns:	A buffered writable file descriptor
Return type:	dict

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

overwrite(*, filepath=None, url=None, file_obj=None, base64decode=False, security=None)¶

Overwrites filelink with new content

Parameters:	filepach (str) – path to file url (str) – file URL file_obj (io.BytesIO or similar) – file-like object base64decode (bool) – indicates if content should be decoded before it is stored security (`filestack.Security`) – Security object that will be used to overwrite filelink

Note

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

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

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