Merge branch 'development' into jac/client-version-header

Author: jacalata

samples/explore_site.py

@@ -0,0 +1,83 @@
+####
+# This script demonstrates how to use the Tableau Server Client
+# to interact with sites.
+####
+
+import argparse
+import logging
+import os.path
+import sys
+
+import tableauserverclient as TSC
+
+
+def main():
+
+    parser = argparse.ArgumentParser(description="Explore site updates by the Server API.")
+    # Common options; please keep those in sync across all samples
+    parser.add_argument("--server", "-s", required=True, help="server address")
+    parser.add_argument("--site", "-S", help="site name")
+    parser.add_argument(
+        "--token-name", "-p", required=True, help="name of the personal access token used to sign into the server"
+    )
+    parser.add_argument(
+        "--token-value", "-v", required=True, help="value of the personal access token used to sign into the server"
+    )
+    parser.add_argument(
+        "--logging-level",
+        "-l",
+        choices=["debug", "info", "error"],
+        default="error",
+        help="desired logging level (set to error by default)",
+    )
+
+    parser.add_argument("--delete")
+    parser.add_argument("--create")
+    parser.add_argument("--url")
+    parser.add_argument("--new_site_name")
+    parser.add_argument("--user_quota")
+    parser.add_argument("--storage_quota")
+    parser.add_argument("--status")
+
+    args = parser.parse_args()
+
+    # Set logging level based on user input, or error by default
+    logging_level = getattr(logging, args.logging_level.upper())
+    logging.basicConfig(level=logging_level)
+
+    # SIGN IN
+    tableau_auth = TSC.PersonalAccessTokenAuth(args.token_name, args.token_value, site_id=args.site)
+    server = TSC.Server(args.server, use_server_version=True)
+    new_site = None
+    with server.auth.sign_in(tableau_auth):
+        current_site = server.sites.get_by_id(server.site_id)
+
+        if args.delete:
+            print("You can only delete the site you are currently in")
+            print("Delete site `{}`?".format(current_site.name))
+            # server.sites.delete(server.site_id)
+
+        elif args.create:
+            new_site = TSC.SiteItem(args.create, args.url or args.create)
+            site_item = server.sites.create(new_site)
+            print(site_item)
+            # to do anything further with the site, you need to log into it
+            # if a PAT is required, that means going to the UI to create one
+
+        else:
+            new_site = current_site
+            print(current_site, "current user quota:", current_site.user_quota)
+            print("Remember, you can only update the site you are currently in")
+            if args.url:
+                new_site.content_url = args.url
+            if args.user_quota:
+                new_site.user_quota = args.user_quota
+            try:
+                updated_site = server.sites.update(new_site)
+                print(updated_site, "new user quota:", updated_site.user_quota)
+            except TSC.ServerResponseError as e:
+                print(e)
+
+
+if __name__ == "__main__":
+    main()

samples/list.py

@@ -59,7 +59,10 @@ def main():
         count = 0
         for resource in TSC.Pager(endpoint.get, options):
             count = count + 1
-            print(resource.id, resource.name)
+            # endpoint.populate_connections(resource)
+            print(resource.name[:18], " ")  # , resource._connections())
+            if count > 100:
+                break
         print("Total: {}".format(count))
 
 

tableauserverclient/datetime_helpers.py

@@ -1,12 +1,12 @@
 import datetime
 
-# This code below is from the python documentation for
-# tzinfo: https://docs.python.org/2.3/lib/datetime-tzinfo.html
 
 ZERO = datetime.timedelta(0)
 HOUR = datetime.timedelta(hours=1)
 
 
+# This class is a concrete implementation of the abstract base class tzinfo
+# docs: https://docs.python.org/2.3/lib/datetime-tzinfo.html
 class UTC(datetime.tzinfo):
     """UTC"""
 

tableauserverclient/models/site_item.py

@@ -1,8 +1,8 @@
 import warnings
 import xml.etree.ElementTree as ET
 
+from distutils.version import Version
 from defusedxml.ElementTree import fromstring
-
 from .property_decorators import (
     property_is_enum,
     property_is_boolean,
@@ -14,7 +14,10 @@
 
 VALID_CONTENT_URL_RE = r"^[a-zA-Z0-9_\-]*$"
 
-from typing import List, Optional, Union
+from typing import List, Optional, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tableauserverclient.server import Server
 
 
 class SiteItem(object):
@@ -23,6 +26,19 @@ class SiteItem(object):
     _tier_explorer_capacity: Optional[int] = None
     _tier_viewer_capacity: Optional[int] = None
 
+    def __str__(self):
+        return (
+            "<"
+            + __name__
+            + ": "
+            + (self.name or "unnamed")
+            + ", "
+            + (self.id or "unknown-id")
+            + ", "
+            + (self.state or "unknown-state")
+            + ">"
+        )
+
     class AdminMode:
         ContentAndUsers: str = "ContentAndUsers"
         ContentOnly: str = "ContentOnly"
@@ -261,18 +277,24 @@ def cataloging_enabled(self) -> bool:
     def cataloging_enabled(self, value: bool):
         self._cataloging_enabled = value
 
+    def is_default(self) -> bool:
+        return self.name.lower() == "default"
+
+    @staticmethod
+    def use_new_flow_settings(parent_srv: "Server") -> bool:
+        return parent_srv is not None and parent_srv.check_at_least_version("3.10")
+
     @property
     def flows_enabled(self) -> bool:
         return self._flows_enabled
 
     @flows_enabled.setter
     @property_is_boolean
     def flows_enabled(self, value: bool) -> None:
+        # Flows Enabled' is not a supported site setting in API Version [3.17].
+        # In Version 3.10+ use the more granular settings 'Editing Flows Enabled' and/or 'Scheduling Flows Enabled'
         self._flows_enabled = value
 
-    def is_default(self) -> bool:
-        return self.name.lower() == "default"
-
     @property
     def editing_flows_enabled(self) -> bool:
         return self._editing_flows_enabled

tableauserverclient/server/endpoint/endpoint.py

@@ -75,7 +75,7 @@ def _make_request(
             logger.debug("request content: {}".format(helpers.strings.redact_xml(content[:1000])))
 
         server_response = method(url, **parameters)
-        self._check_status(server_response)
+        self._check_status(server_response, url)
 
         loggable_response = self.log_response_safely(server_response)
         logger.debug("Server response from {0}:\n\t{1}".format(url, loggable_response))
@@ -85,9 +85,9 @@ def _make_request(
 
         return server_response
 
-    def _check_status(self, server_response):
+    def _check_status(self, server_response, request_url=None):
         if server_response.status_code >= 500:
-            raise InternalServerError(server_response)
+            raise InternalServerError(server_response, request_url)
         elif server_response.status_code not in Success_codes:
             # todo: is an error reliably of content-type application/xml?
             try:
@@ -124,7 +124,7 @@ def get_request(self, url, request_object=None, parameters=None):
         if request_object is not None:
             try:
                 # Query param delimiters don't need to be encoded for versions before 3.7 (2020.1)
-                self.parent_srv.assert_at_least_version("3.7")
+                self.parent_srv.assert_at_least_version("3.7", "Query param encoding")
                 parameters = parameters or {}
                 parameters["params"] = request_object.get_query_params()
             except EndpointUnavailableError:
@@ -194,7 +194,7 @@ def api(version):
     def _decorator(func):
         @wraps(func)
         def wrapper(self, *args, **kwargs):
-            self.parent_srv.assert_at_least_version(version)
+            self.parent_srv.assert_at_least_version(version, "endpoint")
             return func(self, *args, **kwargs)
 
         return wrapper

tableauserverclient/server/endpoint/exceptions.py

@@ -1,7 +1,11 @@
 from defusedxml.ElementTree import fromstring
 
 
-class ServerResponseError(Exception):
+class TableauError(Exception):
+    pass
+
+
+class ServerResponseError(TableauError):
     def __init__(self, code, summary, detail):
         self.code = code
         self.summary = summary
@@ -23,40 +27,41 @@ def from_response(cls, resp, ns):
         return error_response
 
 
-class InternalServerError(Exception):
-    def __init__(self, server_response):
+class InternalServerError(TableauError):
+    def __init__(self, server_response, request_url):
         self.code = server_response.status_code
         self.content = server_response.content
+        self.url = request_url or "server"
 
     def __str__(self):
-        return "\n\nError status code: {0}\n{1}".format(self.code, self.content)
+        return "\n\nInternal error {0} at {1}\n{2}".format(self.code, self.url, self.content)
 
 
-class MissingRequiredFieldError(Exception):
+class MissingRequiredFieldError(TableauError):
     pass
 
 
-class ServerInfoEndpointNotFoundError(Exception):
+class ServerInfoEndpointNotFoundError(TableauError):
     pass
 
 
-class EndpointUnavailableError(Exception):
+class EndpointUnavailableError(TableauError):
     pass
 
 
-class ItemTypeNotAllowed(Exception):
+class ItemTypeNotAllowed(TableauError):
     pass
 
 
-class NonXMLResponseError(Exception):
+class NonXMLResponseError(TableauError):
     pass
 
 
-class InvalidGraphQLQuery(Exception):
+class InvalidGraphQLQuery(TableauError):
     pass
 
 
-class GraphQLError(Exception):
+class GraphQLError(TableauError):
     def __init__(self, error_payload):
         self.error = error_payload
 
@@ -66,7 +71,7 @@ def __str__(self):
         return pformat(self.error)
 
 
-class JobFailedException(Exception):
+class JobFailedException(TableauError):
     def __init__(self, job):
         self.notes = job.notes
         self.job = job
@@ -79,7 +84,7 @@ class JobCancelledException(JobFailedException):
     pass
 
 
-class FlowRunFailedException(Exception):
+class FlowRunFailedException(TableauError):
     def __init__(self, flow_run):
         self.background_job_id = flow_run.background_job_id
         self.flow_run = flow_run

tableauserverclient/server/endpoint/jobs_endpoint.py

@@ -29,7 +29,7 @@ def get(
         if isinstance(job_id, RequestOptionsBase):
             req_options = job_id
 
-        self.parent_srv.assert_at_least_version("3.1")
+        self.parent_srv.assert_at_least_version("3.1", "Jobs.get_by_id(job_id)")
         server_response = self.get_request(self.baseurl, req_options)
         pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
         jobs = BackgroundJobItem.from_response(server_response.content, self.parent_srv.namespace)