Add annotation for endpoints to indicate minimum supported API version

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

tableauserverclient/server/endpoint/exceptions.py

@@ -28,3 +28,7 @@ class MissingRequiredFieldError(Exception):
 
 class ServerInfoEndpointNotFoundError(Exception):
     pass
+
+
+class EndpointUnavailableError(Exception):
+    pass