Add annotation for endpoints to indicate minimum supported API version (tableau#124)

t8y8 · Russell Hay · commit f7da0db98ac0 · 2017-01-11T11:44:17.000-08:00
* Add annotation for endpoints to indicate minimum supported API version

`endpoint.py` gets a new decorator called `api` that takes a version parameter. This gets normalized and then will check `Server.version` before making the API call. If you are calling an endpoint that is newer than the server version you get a nice error message before it even tries a request against the server!

This can be extended in the future to be more complex (eg building a registry of supported methods, etc) but for now this is a huge usability win rather than throwning a Server-returned 404!

This PR only adds the decorator, actually identifying the minimum for endpoints will be done in a different PR that needs way more manual testing than this did
diff --git a/tableauserverclient/server/endpoint/endpoint.py b/tableauserverclient/server/endpoint/endpoint.py
@@ -1,6 +1,12 @@
-from .exceptions import ServerResponseError
+from .exceptions import ServerResponseError, EndpointUnavailableError
+from functools import wraps
+
 import logging
 
+try:
+    from distutils2.version import NormalizedVersion as Version
+except ImportError:
+    from distutils.version import LooseVersion as Version
 
 logger = logging.getLogger('tableau.endpoint')
 
@@ -69,3 +75,35 @@ def post_request(self, url, xml_request, content_type='text/xml'):
                                   content=xml_request,
                                   auth_token=self.parent_srv.auth_token,
                                   content_type=content_type)
+
+
+def api(version):
+    '''Annotate the minimum supported version for an endpoint.
+
+    Checks the version on the server object and compares normalized versions.
+    It will raise an exception if the server version is > the version specified.
+
+    Args:
+        `version` minimum version that supports the endpoint. String.
+    Raises:
+        EndpointUnavailableError
+    Returns:
+        None
+
+    Example:
+    >>> @api(version="2.3")
+    >>> def get(self, req_options=None):
+    >>>     ...
+    '''
+    def _decorator(func):
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            server_version = Version(self.parent_srv.version)
+            minimum_supported = Version(version)
+            if server_version < minimum_supported:
+                error = "This endpoint is not available in API version {}. Requires {}".format(
+                    server_version, minimum_supported)
+                raise EndpointUnavailableError(error)
+            return func(self, *args, **kwargs)
+        return wrapper
+    return _decorator
diff --git a/tableauserverclient/server/endpoint/exceptions.py b/tableauserverclient/server/endpoint/exceptions.py
@@ -28,3 +28,7 @@ class MissingRequiredFieldError(Exception):
 
 class ServerInfoEndpointNotFoundError(Exception):
     pass
+
+
+class EndpointUnavailableError(Exception):
+    pass
