Download with extract_only and parameter checking (#143)

* Add a new decorator that checks parameters against the version. Used with the @api decorator.
* Add extract_only flags to workbooks and data sources, protected behind v2.5 flag

Author: t8y8

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -1,4 +1,4 @@
-from .endpoint import Endpoint, api
+from .endpoint import Endpoint, api, parameter_added_in
 from .exceptions import MissingRequiredFieldError
 from .fileuploads_endpoint import Fileuploads
 from .resource_tagger import _ResourceTagger
@@ -70,11 +70,16 @@ def delete(self, datasource_id):
 
     # Download 1 datasource by id
     @api(version="2.0")
-    def download(self, datasource_id, filepath=None):
+    @parameter_added_in(version="2.5", parameters=['extract_only'])
+    def download(self, datasource_id, filepath=None, extract_only=False):
         if not datasource_id:
             error = "Datasource ID undefined."
             raise ValueError(error)
         url = "{0}/{1}/content".format(self.baseurl, datasource_id)
+
+        if extract_only:
+            url += "?includeExtract=False"
+
         with closing(self.get_request(url, parameters={'stream': True})) as server_response:
             _, params = cgi.parse_header(server_response.headers['Content-Disposition'])
             filename = os.path.basename(params['filename'])

tableauserverclient/server/endpoint/endpoint.py

@@ -107,3 +107,37 @@ def wrapper(self, *args, **kwargs):
             return func(self, *args, **kwargs)
         return wrapper
     return _decorator
+
+
+def parameter_added_in(version, parameters):
+    '''Annotate minimum versions for new parameters or request options on an endpoint.
+
+    The api decorator documents when an endpoint was added, this decorator annotates
+    keyword arguments on endpoints that may control functionality added after an endpoint was introduced.
+
+    The REST API will ignore invalid parameters in most cases, so this raises a warning instead of throwing
+    an exception
+
+    Example:
+    >>> @api(version="2.0")
+    >>> @parameter_added_in(version="2.5", parameters=['extract_only'])
+    >>> def download(self, workbook_id, filepath=None, extract_only=False):
+    >>>     ...
+    '''
+    def _decorator(func):
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            params = set(parameters)
+            invalid_params = params & set(kwargs)
+
+            if invalid_params:
+                import warnings
+                server_version = Version(self.parent_srv.version or "0.0")
+                minimum_supported = Version(version)
+                if server_version < minimum_supported:
+                    error = "The parameter(s) {!r} are not available in {} and will be ignored. Added in {}".format(
+                        invalid_params, server_version, minimum_supported)
+                    warnings.warn(error)
+            return func(self, *args, **kwargs)
+        return wrapper
+    return _decorator

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -1,4 +1,4 @@
-from .endpoint import Endpoint, api
+from .endpoint import Endpoint, api, parameter_added_in
 from .exceptions import MissingRequiredFieldError
 from .fileuploads_endpoint import Fileuploads
 from .resource_tagger import _ResourceTagger
@@ -76,12 +76,16 @@ def update(self, workbook_item):
 
     # Download workbook contents with option of passing in filepath
     @api(version="2.0")
-    def download(self, workbook_id, filepath=None):
+    @parameter_added_in(version="2.5", parameters=['extract_only'])
+    def download(self, workbook_id, filepath=None, extract_only=False):
         if not workbook_id:
             error = "Workbook ID undefined."
             raise ValueError(error)
         url = "{0}/{1}/content".format(self.baseurl, workbook_id)
 
+        if extract_only:
+            url += "?includeExtract=False"
+
         with closing(self.get_request(url, parameters={"stream": True})) as server_response:
             _, params = cgi.parse_header(server_response.headers['Content-Disposition'])
             filename = os.path.basename(params['filename'])

test/test_datasource.py

@@ -164,6 +164,19 @@ def test_download(self):
             self.assertTrue(os.path.exists(file_path))
         os.remove(file_path)
 
+    def test_download_extract_only(self):
+        # Pretend we're 2.5 for 'extract_only'
+        self.server.version = "2.5"
+        self.baseurl = self.server.datasources.baseurl
+
+        with requests_mock.mock() as m:
+            m.get(self.baseurl + '/9dbd2263-16b5-46e1-9c43-a76bb8ab65fb/content?includeExtract=False',
+                  headers={'Content-Disposition': 'name="tableau_datasource"; filename="Sample datasource.tds"'},
+                  complete_qs=True)
+            file_path = self.server.datasources.download('9dbd2263-16b5-46e1-9c43-a76bb8ab65fb', extract_only=True)
+            self.assertTrue(os.path.exists(file_path))
+        os.remove(file_path)
+
     def test_update_missing_id(self):
         single_datasource = TSC.DatasourceItem('test', 'ee8c6e70-43b6-11e6-af4f-f7b0d8e20760')
         self.assertRaises(TSC.MissingRequiredFieldError, self.server.datasources.update, single_datasource)

test/test_workbook.py

@@ -170,6 +170,20 @@ def test_download(self):
             self.assertTrue(os.path.exists(file_path))
         os.remove(file_path)
 
+    def test_download_extract_only(self):
+        # Pretend we're 2.5 for 'extract_only'
+        self.server.version = "2.5"
+        self.baseurl = self.server.workbooks.baseurl
+
+        with requests_mock.mock() as m:
+            m.get(self.baseurl + '/1f951daf-4061-451a-9df1-69a8062664f2/content?includeExtract=False',
+                  headers={'Content-Disposition': 'name="tableau_workbook"; filename="RESTAPISample.twbx"'},
+                  complete_qs=True)
+            # Technically this shouldn't download a twbx, but we are interested in the qs, not the file
+            file_path = self.server.workbooks.download('1f951daf-4061-451a-9df1-69a8062664f2', extract_only=True)
+            self.assertTrue(os.path.exists(file_path))
+        os.remove(file_path)
+
     def test_download_missing_id(self):
         self.assertRaises(ValueError, self.server.workbooks.download, '')