Merge branch 'release/3.0.0'

filestack · Jul 16, 2019 · ef0c3cf · ef0c3cf
2 parents 0a0b6e5 + 7a7b5f7
commit ef0c3cf
Show file tree

Hide file tree

Showing 75 changed files with 1,948 additions and 2,005 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,3 +8,5 @@ tests/data/test_download.jpg
 .coverage
 .idea
 .venv
+
+docs/build/*
diff --git a/.travis.yml b/.travis.yml
@@ -1,10 +1,11 @@
+dist: xenial
 language: python
 
 python:
-  - "2.7"
-  - "3.4"
   - "3.5"
   - "3.6"
+  - "3.7"
+  - "3.8-dev"
 
 install:
   - pip install -r requirements.txt

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Filestack-Python Changelog
 
+### 3.0.0 (July 16th, 2019)
+- Dropped support for Python 2.7
+- client.upload() now handles local files and file-like objects, accepts keyword arguments only
+- client.upload_url() handles external url uploads
+- Please see [API Reference](https://filestack-python.readthedocs.io) to learn more
+
 ### 2.8.1 (July 3th, 2019)
 - Fixed store params in external url upload
 

diff --git a/README.md b/README.md
@@ -4,15 +4,18 @@
   <a href="http://travis-ci.org/filestack/filestack-python">
     <img src="https://img.shields.io/travis/filestack/filestack-python.svg">
   </a>
-  <a href="https://pypi.python.org/pypi/filestack-python/2.3.1">
+  <a href="https://pypi.python.org/pypi/filestack-python">
     <img src="https://img.shields.io/pypi/v/filestack-python.svg">
   </a>
+    <img src="https://img.shields.io/pypi/pyversions/filestack-python.svg">
 </p>
 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.
 
 ## Resources
 
-* [API Reference](https://filestack.github.io/filestack-python)
+To learn more about this SDK, please visit our API Reference
+
+* [API Reference](https://filestack-python.readthedocs.io)
 
 ## Installing
 
@@ -28,49 +31,53 @@ or directly from GitHub
 pip install git+https://github.com/filestack/filestack-python.git
 ```
 
-## Usage
+## Quickstart
 
 The Filestack SDK allows you to upload and handle filelinks using two main classes: Client and Filelink.
 
-### Uploading New File with Client
+### Uploading files with `filestack.Client`
 ``` python
 from filestack import Client
-client = Client("<YOUR_API_KEY>")
+client = Client('<YOUR_API_KEY>')
 
-params = {'mimetype': 'image/png'}
-new_filelink = client.upload(filepath="path/to/file", params=params)
+new_filelink = client.upload(filepath='path/to/file')
 print(new_filelink.url)
 ```
-Uploading local files will use Filestack's multipart upload by default. To disable, just set the argument to false.
 
-```python
-new_filelink = client.upload(filepath="path/to/file", multipart=False)
-```
 #### Uploading files using Filestack Intelligent Ingestion
 To upload files using Filestack Intelligent Ingestion, simply add `intelligent=True` argument
 ```python
-new_filelink = client.upload(filepath="path/to/file", intelligent=True)
+new_filelink = client.upload(filepath='path/to/file', intelligent=True)
 ```
 FII always uses multipart uploads. In case of network issues, it will dynamically split file parts into smaller chunks (sacrificing upload speed in favour of upload reliability).
 
-### Create Filelink using Existing Handle
+### Working with Filelinks
+Filelink objects can by created by uploading new files, or by initializing `filestack.Filelink` with already existing file handle
 ```python
-from filestack import Filelink
-new_filelink = Filelink("<YOUR_HANDLE>")
+from filestack import Filelink, Client
+
+client = Client('<APIKEY>')
+filelink = client.upload(filepath='path/to/file')
+filelink.url  # 'https://cdn.filestackcontent.com/FILE_HANDLE
+
+# work with previously uploaded file
+filelink = Filelink('FILE_HANDLE')
 ```
 
 ### Basic Filelink Functions
 
-With a Filelink, you can download to a local path or get the content of a file. You can also delete or overwrite files if you have security enabled on your account.
+With a Filelink, you can download to a local path or get the content of a file. You can also perform various transformations.
 
 ```python
 file_content = new_filelink.get_content()
 
-response = new_filelink.download("/path/to/file")
+size_in_bytes = new_filelink.download('/path/to/file')
+
+filelink.overwrite(filepath='path/to/new/file')
 
-filelink.overwrite(filepath="path/to/new/file")
+filelink.resize(width=400).flip()
 
-response = filelink.delete()
+filelink.delete()
 ```
 
 ### Transformations
@@ -81,7 +88,7 @@ You can chain transformations on both Filelinks and external URLs. Storing trans
 transform = client.transform_external('http://<SOME_URL>')
 new_filelink = transform.resize(width=500, height=500).flip().enhance().store()
 
-filelink = Filelink("<YOUR_HANDLE">)
+filelink = Filelink('<YOUR_HANDLE'>)
 new_filelink = filelink.resize(width=500, height=500).flip().enhance().store()
 ```
 
@@ -113,40 +120,55 @@ filelink = av_object.to_filelink()
 
 ### Security Objects
 
-Security is set on Client or Filelink classes upon instantiation.
+Security is set on Client or Filelink classes upon instantiation and is used to sign all API calls.
 
 ```python
-from filestack import security
+from filestack import Security
 
-json_policy = {"expiry": 253381964415}
-security = security(json_policy, '<YOUR_APP_SECRET>')
-client = Client("<YOUR_API_KEY", security=security)
+policy = {'expiry': 253381964415}  # 'expiry' is the only required key
+security = Security(policy, '<YOUR_APP_SECRET>')
+client = Client('<YOUR_API_KEY', security=security)
 
 # new Filelink object inherits security and will use for all calls
-new_filelink = client.upload(filepath="path/to/file")
+new_filelink = client.upload(filepath='path/to/file')
+
+# you can also provide Security objects explicitly for some methods
+size_in_bytes = filelink.download(security=security)
+```
+
+You can also retrieve security details straight from the object:
+```python
+>>> policy = {'expiry': 253381964415, 'call': ['read']}
+>>> security = Security(policy, 'SECURITY-SECRET')
+>>> security.policy_b64
+'eyJjYWxsIjogWyJyZWFkIl0sICJleHBpcnkiOiAyNTMzODE5NjQ0MTV9'
+>>> security.signature
+'f61fa1effb0638ab5b6e208d5d2fd9343f8557d8a0bf529c6d8542935f77bb3c'
 ```
 
 ### Webhook verification
 
-You can use `Client.verify_webhook_signature` method to make sure that the webhooks you receive are sent by Filestack.
+You can use `filestack.helpers.verify_webhook_signature` method to make sure that the webhooks you receive are sent by Filestack.
 
 ```python
-from filestack import Client
+from filestack.helpers import verify_webhook_signature
 
 # webhook_data is raw content you receive
 webhook_data = b'{"action": "fp.upload", "text": {"container": "some-bucket", "url": "https://cdn.filestackcontent.com/Handle", "filename": "filename.png", "client": "Computer", "key": "key_filename.png", "type": "image/png", "size": 1000000}, "id": 50006}'
 
-resp = Client.verify_webhook_signature(
-    '<YOUR_WEBHOOK_SECRET>', webhook_data,
-    {'FS-Signature': '<SIGNATURE-FROM-REQUEST-HEADERS>', 'FS-Timestamp': '<TIMESTAMP-FROM-REQUEST-HEADERS>'}
+result, details = verify_webhook_signature(
+    '<YOUR_WEBHOOK_SECRET>',
+    webhook_data,
+    {
+      'FS-Signature': '<SIGNATURE-FROM-REQUEST-HEADERS>',
+      'FS-Timestamp': '<TIMESTAMP-FROM-REQUEST-HEADERS>'
+    }
 )
 
-if not resp['valid'] and resp['error'] is None:
-    raise Exception('Webhook signature is invalid')
-elif resp['error']:
-    print('Please check input params: {}'.format(resp['error']))
-else:
+if result is True:
     print('Webhook is valid and was generated by Filestack')
+else:
+    raise Exception(details['error'])
 ```
 
 ## Versioning

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-2.8.1
+3.0.0
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/asset-manifest.json b/docs/asset-manifest.json
diff --git a/docs/data.json b/docs/data.json
diff --git a/docs/favicon.ico b/docs/favicon.ico
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/intro.md b/docs/intro.md
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/manifest.json b/docs/manifest.json
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,4 @@
+Sphinx==2.1.2
+sphinx-rtd-theme==0.4.3
+trafaret==1.2.0
+requests==2.22.0
diff --git a/docs/service-worker.js b/docs/service-worker.js
diff --git a/docs/source/_static/img/filestack_logo.svg b/docs/source/_static/img/filestack_logo.svg
diff --git a/docs/source/_static/img/fs_logo.png b/docs/source/_static/img/fs_logo.png
diff --git a/docs/source/_static/img/logo-fs-bright.png b/docs/source/_static/img/logo-fs-bright.png
diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst
@@ -0,0 +1,34 @@
+API Reference
+=============
+
+Client
+------
+
+.. autoclass:: filestack.Client
+   :special-members: __init__
+   :members:
+
+
+Filelink
+--------
+
+.. autoclass:: filestack.Filelink
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
+
+Security
+--------------
+
+.. autoclass:: filestack.Security
+   :special-members: __init__
+   :members:
+
+
+Transformation
+--------------
+
+.. autoclass:: filestack.Transformation
+   :members:
+   :inherited-members: