tableauserverclient 0.33__py3-none-any.whl → 0.35__py3-none-any.whl

tableauserverclient/server/request_options.py

@@ -1,4 +1,5 @@
 import sys
+from typing import Optional
 
 from typing_extensions import Self
 
@@ -9,12 +10,12 @@ import logging
 from tableauserverclient.helpers.logging import logger
 
 
-class RequestOptionsBase(object):
+class RequestOptionsBase:
     # This method is used if server api version is below 3.7 (2020.1)
     def apply_query_params(self, url):
         try:
             params = self.get_query_params()
-            params_list = ["{}={}".format(k, v) for (k, v) in params.items()]
+            params_list = [f"{k}={v}" for (k, v) in params.items()]
 
             logger.debug("Applying options to request: <%s(%s)>", self.__class__.__name__, ",".join(params_list))
 
@@ -22,15 +23,74 @@ class RequestOptionsBase(object):
                 url, existing_params = url.split("?")
                 params_list.append(existing_params)
 
-            return "{0}?{1}".format(url, "&".join(params_list))
+            return "{}?{}".format(url, "&".join(params_list))
         except NotImplementedError:
             raise
 
-    def get_query_params(self):
-        raise NotImplementedError()
+
+# If it wasn't a breaking change, I'd rename it to QueryOptions
+"""
+This class manages options can be used when querying content on the server
+"""
 
 
 class RequestOptions(RequestOptionsBase):
+    """
+    This class is used to manage the options that can be used when querying content on the server.
+    Optionally initialize with a page number and page size to control the number of items returned.
+
+    Additionally, you can add sorting and filtering options to the request.
+
+    The `sort` and `filter` options are set-like objects, so you can only add a field once. If you add the same field
+    multiple times, only the last one will be used.
+
+    The list of fields that can be sorted on or filtered by can be found in the `Field`
+    class contained within this class.
+
+    Parameters
+    ----------
+    pagenumber: int, optional
+        The page number to start the query on. Default is 1.
+
+    pagesize: int, optional
+        The number of items to return per page. Default is 100. Can also read
+        from the environment variable `TSC_PAGE_SIZE`
+    """
+
+    def __init__(self, pagenumber=1, pagesize=None):
+        self.pagenumber = pagenumber
+        self.pagesize = pagesize or config.PAGE_SIZE
+        self.sort = set()
+        self.filter = set()
+        # This is private until we expand all of our parsers to handle the extra fields
+        self._all_fields = False
+
+    def get_query_params(self) -> dict:
+        params = {}
+        if self.sort and len(self.sort) > 0:
+            sort_options = (str(sort_item) for sort_item in self.sort)
+            ordered_sort_options = sorted(sort_options)
+            params["sort"] = ",".join(ordered_sort_options)
+        if len(self.filter) > 0:
+            filter_options = (str(filter_item) for filter_item in self.filter)
+            ordered_filter_options = sorted(filter_options)
+            params["filter"] = ",".join(ordered_filter_options)
+        if self._all_fields:
+            params["fields"] = "_all_"
+        if self.pagenumber:
+            params["pageNumber"] = self.pagenumber
+        if self.pagesize:
+            params["pageSize"] = self.pagesize
+        return params
+
+    def page_size(self, page_size):
+        self.pagesize = page_size
+        return self
+
+    def page_number(self, page_number):
+        self.pagenumber = page_number
+        return self
+
     class Operator:
         Equals = "eq"
         GreaterThan = "gt"
@@ -41,6 +101,7 @@ class RequestOptions(RequestOptionsBase):
         Has = "has"
         CaseInsensitiveEquals = "cieq"
 
+    # These are fields in the REST API
     class Field:
         Args = "args"
         AuthenticationType = "authenticationType"
@@ -83,6 +144,7 @@ class RequestOptions(RequestOptionsBase):
         NotificationType = "notificationType"
         OwnerDomain = "ownerDomain"
         OwnerEmail = "ownerEmail"
+        OwnerId = "ownerId"
         OwnerName = "ownerName"
         ParentProjectId = "parentProjectId"
         Priority = "priority"
@@ -109,68 +171,93 @@ class RequestOptions(RequestOptionsBase):
         UpdatedAt = "updatedAt"
         UserCount = "userCount"
         UserId = "userId"
+        ViewId = "viewId"
         ViewUrlName = "viewUrlName"
         WorkbookDescription = "workbookDescription"
+        WorkbookId = "workbookId"
         WorkbookName = "workbookName"
 
     class Direction:
         Desc = "desc"
         Asc = "asc"
 
-    def __init__(self, pagenumber=1, pagesize=None):
-        self.pagenumber = pagenumber
-        self.pagesize = pagesize or config.PAGE_SIZE
-        self.sort = set()
-        self.filter = set()
 
-        # This is private until we expand all of our parsers to handle the extra fields
-        self._all_fields = False
+"""
+These options can be used by methods that are fetching data exported from a specific content item
+"""
 
-    def page_size(self, page_size):
-        self.pagesize = page_size
-        return self
 
-    def page_number(self, page_number):
-        self.pagenumber = page_number
-        return self
+class _DataExportOptions(RequestOptionsBase):
+    def __init__(self, maxage: int = -1):
+        super().__init__()
+        self.view_filters: list[tuple[str, str]] = []
+        self.view_parameters: list[tuple[str, str]] = []
+        self.max_age: Optional[int] = maxage
+        """
+        This setting will affect the contents of the workbook as they are exported.
+        Valid language values are tableau-supported languages like de, es, en
+        If no locale is specified, the default locale for that language will be used
+        """
+        self.language: Optional[str] = None
+
+    @property
+    def max_age(self) -> int:
+        return self._max_age
+
+    @max_age.setter
+    @property_is_int(range=(0, 240), allowed=[-1])
+    def max_age(self, value):
+        self._max_age = value
 
     def get_query_params(self):
         params = {}
-        if self.pagenumber:
-            params["pageNumber"] = self.pagenumber
-        if self.pagesize:
-            params["pageSize"] = self.pagesize
-        if len(self.sort) > 0:
-            sort_options = (str(sort_item) for sort_item in self.sort)
-            ordered_sort_options = sorted(sort_options)
-            params["sort"] = ",".join(ordered_sort_options)
-        if len(self.filter) > 0:
-            filter_options = (str(filter_item) for filter_item in self.filter)
-            ordered_filter_options = sorted(filter_options)
-            params["filter"] = ",".join(ordered_filter_options)
-        if self._all_fields:
-            params["fields"] = "_all_"
+        if self.max_age != -1:
+            params["maxAge"] = self.max_age
+        if self.language:
+            params["language"] = self.language
+
+        self._append_view_filters(params)
         return params
 
+    def vf(self, name: str, value: str) -> Self:
+        """Apply a filter based on a column within the view.
+        Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'
 
-class _FilterOptionsBase(RequestOptionsBase):
-    """Provide a basic implementation of adding view filters to the url"""
+        For more detail see: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views
 
-    def __init__(self):
-        self.view_filters = []
-        self.view_parameters = []
+        Parameters
+        ----------
+        name: str
+            The name of the column to filter on
 
-    def get_query_params(self):
-        raise NotImplementedError()
+        value: str
+            The value to filter on
 
-    def vf(self, name: str, value: str) -> Self:
-        """Apply a filter to the view for a filter that is a normal column
-        within the view."""
+        Returns
+        -------
+        Self
+            The current object
+        """
         self.view_filters.append((name, value))
         return self
 
     def parameter(self, name: str, value: str) -> Self:
-        """Apply a filter based on a parameter within the workbook."""
+        """Apply a filter based on a parameter within the workbook.
+        Note that when filtering on a boolean type field, the only valid values are 'true' and 'false'
+
+        Parameters
+        ----------
+        name: str
+            The name of the parameter to filter on
+
+        value: str
+            The value to filter on
+
+        Returns
+        -------
+        Self
+            The current object
+        """
         self.view_parameters.append((name, value))
         return self
 
@@ -181,82 +268,142 @@ class _FilterOptionsBase(RequestOptionsBase):
             params[name] = value
 
 
-class CSVRequestOptions(_FilterOptionsBase):
-    def __init__(self, maxage=-1):
-        super(CSVRequestOptions, self).__init__()
-        self.max_age = maxage
+class _ImagePDFCommonExportOptions(_DataExportOptions):
+    def __init__(self, maxage=-1, viz_height=None, viz_width=None):
+        super().__init__(maxage=maxage)
+        self.viz_height = viz_height
+        self.viz_width = viz_width
 
     @property
-    def max_age(self):
-        return self._max_age
+    def viz_height(self):
+        return self._viz_height
 
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value):
-        self._max_age = value
+    @viz_height.setter
+    @property_is_int(range=(0, sys.maxsize), allowed=(None,))
+    def viz_height(self, value):
+        self._viz_height = value
 
-    def get_query_params(self):
-        params = {}
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
+    @property
+    def viz_width(self):
+        return self._viz_width
+
+    @viz_width.setter
+    @property_is_int(range=(0, sys.maxsize), allowed=(None,))
+    def viz_width(self, value):
+        self._viz_width = value
+
+    def get_query_params(self) -> dict:
+        params = super().get_query_params()
+
+        # XOR. Either both are None or both are not None.
+        if (self.viz_height is None) ^ (self.viz_width is None):
+            raise ValueError("viz_height and viz_width must be specified together")
+
+        if self.viz_height is not None:
+            params["vizHeight"] = self.viz_height
+
+        if self.viz_width is not None:
+            params["vizWidth"] = self.viz_width
 
-        self._append_view_filters(params)
         return params
 
 
-class ExcelRequestOptions(_FilterOptionsBase):
-    def __init__(self, maxage: int = -1) -> None:
-        super().__init__()
-        self.max_age = maxage
+class CSVRequestOptions(_DataExportOptions):
+    """
+    Options that can be used when exporting a view to CSV. Set the maxage to control the age of the data exported.
+    Filters to the underlying data can be applied using the `vf` and `parameter` methods.
 
-    @property
-    def max_age(self) -> int:
-        return self._max_age
+    Parameters
+    ----------
+    maxage: int, optional
+        The maximum age of the data to export. Shortest possible duration is 1
+        minute. No upper limit. Default is -1, which means no limit.
+    """
 
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value: int) -> None:
-        self._max_age = value
+    extension = "csv"
 
-    def get_query_params(self):
-        params = {}
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
 
-        self._append_view_filters(params)
-        return params
+class ExcelRequestOptions(_DataExportOptions):
+    """
+    Options that can be used when exporting a view to Excel. Set the maxage to control the age of the data exported.
+    Filters to the underlying data can be applied using the `vf` and `parameter` methods.
+
+    Parameters
+    ----------
+    maxage: int, optional
+        The maximum age of the data to export. Shortest possible duration is 1
+        minute. No upper limit. Default is -1, which means no limit.
+    """
+
+    extension = "xlsx"
+
+
+class ImageRequestOptions(_ImagePDFCommonExportOptions):
+    """
+    Options that can be used when exporting a view to an image. Set the maxage to control the age of the data exported.
+    Filters to the underlying data can be applied using the `vf` and `parameter` methods.
+
+    Parameters
+    ----------
+    imageresolution: str, optional
+        The resolution of the image to export. Valid values are "high" or None. Default is None.
+        Image width and actual pixel density are determined by the display context
+        of the image. Aspect ratio is always preserved. Set the value to "high" to
+        ensure maximum pixel density.
+
+    maxage: int, optional
+        The maximum age of the data to export. Shortest possible duration is 1
+        minute. No upper limit. Default is -1, which means no limit.
+
+    viz_height: int, optional
+        The height of the viz in pixels. If specified, viz_width must also be specified.
+
+    viz_width: int, optional
+        The width of the viz in pixels. If specified, viz_height must also be specified.
+
+    """
 
+    extension = "png"
 
-class ImageRequestOptions(_FilterOptionsBase):
     # if 'high' isn't specified, the REST API endpoint returns an image with standard resolution
     class Resolution:
         High = "high"
 
-    def __init__(self, imageresolution=None, maxage=-1):
-        super(ImageRequestOptions, self).__init__()
+    def __init__(self, imageresolution=None, maxage=-1, viz_height=None, viz_width=None):
+        super().__init__(maxage=maxage, viz_height=viz_height, viz_width=viz_width)
         self.image_resolution = imageresolution
-        self.max_age = maxage
-
-    @property
-    def max_age(self):
-        return self._max_age
-
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value):
-        self._max_age = value
 
     def get_query_params(self):
-        params = {}
+        params = super().get_query_params()
         if self.image_resolution:
             params["resolution"] = self.image_resolution
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
-        self._append_view_filters(params)
         return params
 
 
-class PDFRequestOptions(_FilterOptionsBase):
+class PDFRequestOptions(_ImagePDFCommonExportOptions):
+    """
+    Options that can be used when exporting a view to PDF. Set the maxage to control the age of the data exported.
+    Filters to the underlying data can be applied using the `vf` and `parameter` methods.
+
+    Parameters
+    ----------
+    page_type: str, optional
+        The page type of the PDF to export. Valid values are accessible via the `PageType` class.
+
+    orientation: str, optional
+        The orientation of the PDF to export. Valid values are accessible via the `Orientation` class.
+
+    maxage: int, optional
+        The maximum age of the data to export. Shortest possible duration is 1
+        minute. No upper limit. Default is -1, which means no limit.
+
+    viz_height: int, optional
+        The height of the viz in pixels. If specified, viz_width must also be specified.
+
+    viz_width: int, optional
+        The width of the viz in pixels. If specified, viz_height must also be specified.
+    """
+
     class PageType:
         A3 = "a3"
         A4 = "a4"
@@ -278,61 +425,16 @@ class PDFRequestOptions(_FilterOptionsBase):
         Landscape = "landscape"
 
     def __init__(self, page_type=None, orientation=None, maxage=-1, viz_height=None, viz_width=None):
-        super(PDFRequestOptions, self).__init__()
+        super().__init__(maxage=maxage, viz_height=viz_height, viz_width=viz_width)
         self.page_type = page_type
         self.orientation = orientation
-        self.max_age = maxage
-        self.viz_height = viz_height
-        self.viz_width = viz_width
-
-    @property
-    def max_age(self):
-        return self._max_age
-
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value):
-        self._max_age = value
-
-    @property
-    def viz_height(self):
-        return self._viz_height
 
-    @viz_height.setter
-    @property_is_int(range=(0, sys.maxsize), allowed=(None,))
-    def viz_height(self, value):
-        self._viz_height = value
-
-    @property
-    def viz_width(self):
-        return self._viz_width
-
-    @viz_width.setter
-    @property_is_int(range=(0, sys.maxsize), allowed=(None,))
-    def viz_width(self, value):
-        self._viz_width = value
-
-    def get_query_params(self):
-        params = {}
+    def get_query_params(self) -> dict:
+        params = super().get_query_params()
         if self.page_type:
             params["type"] = self.page_type
 
         if self.orientation:
             params["orientation"] = self.orientation
 
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
-
-        # XOR. Either both are None or both are not None.
-        if (self.viz_height is None) ^ (self.viz_width is None):
-            raise ValueError("viz_height and viz_width must be specified together")
-
-        if self.viz_height is not None:
-            params["vizHeight"] = self.viz_height
-
-        if self.viz_width is not None:
-            params["vizWidth"] = self.viz_width
-
-        self._append_view_filters(params)
-
         return params

tableauserverclient/server/server.py

@@ -58,11 +58,68 @@ minimum_supported_server_version = "2.3"
 default_server_version = "2.4"  # first version that dropped the legacy auth endpoint
 
 
-class Server(object):
+class Server:
+    """
+    In the Tableau REST API, the server (https://MY-SERVER/) is the base or core
+    of the URI that makes up the various endpoints or methods for accessing
+    resources on the server (views, workbooks, sites, users, data sources, etc.)
+    The TSC library provides a Server class that represents the server. You
+    create a server instance to sign in to the server and to call the various
+    methods for accessing resources.
+
+    The Server class contains the attributes that represent the server on
+    Tableau Server. After you create an instance of the Server class, you can
+    sign in to the server and call methods to access all of the resources on the
+    server.
+
+    Parameters
+    ----------
+    server_address : str
+        Specifies the address of the Tableau Server or Tableau Cloud (for
+        example, https://MY-SERVER/).
+
+    use_server_version : bool
+        Specifies the version of the REST API to use (for example, '2.5'). When
+        you use the TSC library to call methods that access Tableau Server, the
+        version is passed to the endpoint as part of the URI
+        (https://MY-SERVER/api/2.5/). Each release of Tableau Server supports
+        specific versions of the REST API. New versions of the REST API are
+        released with Tableau Server. By default, the value of version is set to
+        '2.3', which corresponds to Tableau Server 10.0. You can view or set
+        this value. You might need to set this to a different value, for
+        example, if you want to access features that are supported by the server
+        and a later version of the REST API. For more information, see REST API
+        Versions.
+
+    Examples
+    --------
+    >>> import tableauserverclient as TSC
+
+    >>> # create a instance of server
+    >>> server = TSC.Server('https://MY-SERVER')
+
+    >>> # sign in, etc.
+
+    >>> # change the REST API version to match the server
+    >>> server.use_server_version()
+
+    >>> # or change the REST API version to match a specific version
+    >>> # for example, 2.8
+    >>> # server.version = '2.8'
+
+    """
+
     class PublishMode:
+        """
+        Enumerates the options that specify what happens when you publish a
+        workbook or data source. The options are Overwrite, Append, or
+        CreateNew.
+        """
+
         Append = "Append"
         Overwrite = "Overwrite"
         CreateNew = "CreateNew"
+        Replace = "Replace"
 
     def __init__(self, server_address, use_server_version=False, http_options=None, session_factory=None):
         self._auth_token = None
@@ -130,7 +187,7 @@ class Server(object):
             raise ValueError("Server connection settings not valid", req_ex)
 
     def __repr__(self):
-        return "<TableauServerClient [Connection: {}, {}]>".format(self.baseurl, self.server_info.serverInfo)
+        return f"<TableauServerClient [Connection: {self.baseurl}, {self.server_info.serverInfo}]>"
 
     def add_http_options(self, options_dict: dict):
         try:
@@ -142,7 +199,7 @@ class Server(object):
             # expected errors on invalid input:
             # 'set' object has no attribute 'keys', 'list' object has no attribute 'keys'
             # TypeError: cannot convert dictionary update sequence element #0 to a sequence (input is a tuple)
-            raise ValueError("Invalid http options given: {}".format(options_dict))
+            raise ValueError(f"Invalid http options given: {options_dict}")
 
     def clear_http_options(self):
         self._http_options = dict()
@@ -151,12 +208,14 @@ class Server(object):
         self._site_id = None
         self._user_id = None
         self._auth_token = None
+        self._site_url = None
         self._session = self._session_factory()
 
-    def _set_auth(self, site_id, user_id, auth_token):
+    def _set_auth(self, site_id, user_id, auth_token, site_url=None):
         self._site_id = site_id
         self._user_id = user_id
         self._auth_token = auth_token
+        self._site_url = site_url
 
     def _get_legacy_version(self):
         # the serverInfo call was introduced in 2.4, earlier than that we have this different call
@@ -176,15 +235,15 @@ class Server(object):
             old_version = self.version
             version = self.server_info.get().rest_api_version
         except ServerInfoEndpointNotFoundError as e:
-            logger.info("Could not get version info from server: {}{}".format(e.__class__, e))
+            logger.info(f"Could not get version info from server: {e.__class__}{e}")
             version = self._get_legacy_version()
         except EndpointUnavailableError as e:
-            logger.info("Could not get version info from server: {}{}".format(e.__class__, e))
+            logger.info(f"Could not get version info from server: {e.__class__}{e}")
             version = self._get_legacy_version()
         except Exception as e:
-            logger.info("Could not get version info from server: {}{}".format(e.__class__, e))
+            logger.info(f"Could not get version info from server: {e.__class__}{e}")
             version = None
-        logger.info("versions: {}, {}".format(version, old_version))
+        logger.info(f"versions: {version}, {old_version}")
         return version or old_version
 
     def use_server_version(self):
@@ -201,12 +260,12 @@ class Server(object):
 
     def assert_at_least_version(self, comparison: str, reason: str):
         if not self.check_at_least_version(comparison):
-            error = "{} is not available in API version {}. Requires {}".format(reason, self.version, comparison)
+            error = f"{reason} is not available in API version {self.version}. Requires {comparison}"
             raise EndpointUnavailableError(error)
 
     @property
     def baseurl(self):
-        return "{0}/api/{1}".format(self._server_address, str(self.version))
+        return f"{self._server_address}/api/{str(self.version)}"
 
     @property
     def namespace(self):
@@ -226,6 +285,13 @@ class Server(object):
             raise NotSignedInError(error)
         return self._site_id
 
+    @property
+    def site_url(self):
+        if self._site_url is None:
+            error = "Missing site URL. You must sign in first."
+            raise NotSignedInError(error)
+        return self._site_url
+
     @property
     def user_id(self):
         if self._user_id is None:

tableauserverclient/server/sort.py

@@ -1,7 +1,21 @@
-class Sort(object):
+class Sort:
+    """
+    Used with request options (RequestOptions) where you can filter and sort on
+    the results returned from the server.
+
+    Parameters
+    ----------
+    field : str
+        Sets the field to sort on. The fields are defined in the RequestOption class.
+
+    direction : str
+        The direction to sort, either ascending (Asc) or descending (Desc). The
+        options are defined in the RequestOptions.Direction class.
+    """
+
     def __init__(self, field, direction):
         self.field = field
         self.direction = direction
 
     def __str__(self):
-        return "{0}:{1}".format(self.field, self.direction)
+        return f"{self.field}:{self.direction}"