Reword no_extract and update signature of added_in (#144)

`parameter_added_in` got a facelift and now takes keyword arguments, where the value represents the version for that keyword. It looks a little cleaner and makes the checking code much simpler.

Also renamed the `extract_only` to be `no_extract` because it means the opposite of `extract_only`, oops.

Author: t8y8

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -65,14 +65,14 @@ def delete(self, datasource_id):
 
     # Download 1 datasource by id
     @api(version="2.0")
-    @parameter_added_in(version="2.5", parameters=['extract_only'])
-    def download(self, datasource_id, filepath=None, extract_only=False):
+    @parameter_added_in(no_extract='2.5')
+    def download(self, datasource_id, filepath=None, no_extract=False):
         if not datasource_id:
             error = "Datasource ID undefined."
             raise ValueError(error)
         url = "{0}/{1}/content".format(self.baseurl, datasource_id)
 
-        if extract_only:
+        if no_extract:
             url += "?includeExtract=False"
 
         with closing(self.get_request(url, parameters={'stream': True})) as server_response:

tableauserverclient/server/endpoint/endpoint.py

@@ -109,34 +109,38 @@ def wrapper(self, *args, **kwargs):
     return _decorator
 
 
-def parameter_added_in(version, parameters):
+def parameter_added_in(**params):
     '''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
+    an exception.
+
+    Args:
+        Key/value pairs of the form `parameter`=`version`. Kwargs.
+    Raises:
+        UserWarning
+    Returns:
+        None
 
     Example:
     >>> @api(version="2.0")
-    >>> @parameter_added_in(version="2.5", parameters=['extract_only'])
+    >>> @parameter_added_in(no_extract='2.5')
     >>> 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)
+            import warnings
+            server_ver = Version(self.parent_srv.version or "0.0")
+            params_to_check = set(params) & set(kwargs)
+            for p in params_to_check:
+                min_ver = Version(str(params[p]))
+                if server_ver < min_ver:
+                    error = "{!r} not available in {}, it will be ignored. Added in {}".format(p, server_ver, min_ver)
                     warnings.warn(error)
             return func(self, *args, **kwargs)
         return wrapper

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -93,14 +93,14 @@ def update(self, workbook_item):
 
     # Download workbook contents with option of passing in filepath
     @api(version="2.0")
-    @parameter_added_in(version="2.5", parameters=['extract_only'])
-    def download(self, workbook_id, filepath=None, extract_only=False):
+    @parameter_added_in(no_extract='2.5')
+    def download(self, workbook_id, filepath=None, no_extract=False):
         if not workbook_id:
             error = "Workbook ID undefined."
             raise ValueError(error)
         url = "{0}/{1}/content".format(self.baseurl, workbook_id)
 
-        if extract_only:
+        if no_extract:
             url += "?includeExtract=False"
 
         with closing(self.get_request(url, parameters={"stream": True})) as server_response:

test/test_datasource.py

@@ -154,7 +154,7 @@ def test_download_extract_only(self):
             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)
+            file_path = self.server.datasources.download('9dbd2263-16b5-46e1-9c43-a76bb8ab65fb', no_extract=True)
             self.assertTrue(os.path.exists(file_path))
         os.remove(file_path)
 

test/test_workbook.py

@@ -180,7 +180,7 @@ def test_download_extract_only(self):
                   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)
+            file_path = self.server.workbooks.download('1f951daf-4061-451a-9df1-69a8062664f2', no_extract=True)
             self.assertTrue(os.path.exists(file_path))
         os.remove(file_path)