tableauserverclient 0.32__py3-none-any.whl → 0.34__py3-none-any.whl

tableauserverclient/server/request_options.py

@@ -1,19 +1,21 @@
 import sys
+from typing import Optional
 
 from typing_extensions import Self
 
+from tableauserverclient.config import config
 from tableauserverclient.models.property_decorators import property_is_int
 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))
 
@@ -21,15 +23,52 @@ 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):
+    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"
@@ -38,7 +77,9 @@ class RequestOptions(RequestOptionsBase):
         LessThanOrEqual = "lte"
         In = "in"
         Has = "has"
+        CaseInsensitiveEquals = "cieq"
 
+    # These are fields in the REST API
     class Field:
         Args = "args"
         AuthenticationType = "authenticationType"
@@ -115,60 +156,53 @@ class RequestOptions(RequestOptionsBase):
         Desc = "desc"
         Asc = "asc"
 
-    def __init__(self, pagenumber=1, pagesize=100):
-        self.pagenumber = pagenumber
-        self.pagesize = pagesize
-        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 page_size(self, page_size):
-        self.pagesize = page_size
-        return self
+"""
+These options can be used by methods that are fetching data exported from a specific content item
+"""
 
-    def page_number(self, page_number):
-        self.pagenumber = page_number
-        return self
-
-    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_"
-        return params
 
+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
 
-class _FilterOptionsBase(RequestOptionsBase):
-    """Provide a basic implementation of adding view filters to the url"""
+    @property
+    def max_age(self) -> int:
+        return self._max_age
 
-    def __init__(self):
-        self.view_filters = []
-        self.view_parameters = []
+    @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):
-        raise NotImplementedError()
+        params = {}
+        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 to the view for a filter that is a normal column
-        within the view."""
+        """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'"""
         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'"""
         self.view_parameters.append((name, value))
         return self
 
@@ -179,82 +213,73 @@ 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
-
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value):
-        self._max_age = value
+    def viz_height(self):
+        return self._viz_height
 
-    def get_query_params(self):
-        params = {}
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
+    @viz_height.setter
+    @property_is_int(range=(0, sys.maxsize), allowed=(None,))
+    def viz_height(self, value):
+        self._viz_height = value
 
-        self._append_view_filters(params)
-        return params
+    @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
 
-class ExcelRequestOptions(_FilterOptionsBase):
-    def __init__(self, maxage: int = -1) -> None:
-        super().__init__()
-        self.max_age = maxage
+    def get_query_params(self) -> dict:
+        params = super().get_query_params()
 
-    @property
-    def max_age(self) -> int:
-        return 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")
 
-    @max_age.setter
-    @property_is_int(range=(0, 240), allowed=[-1])
-    def max_age(self, value: int) -> None:
-        self._max_age = value
+        if self.viz_height is not None:
+            params["vizHeight"] = self.viz_height
 
-    def get_query_params(self):
-        params = {}
-        if self.max_age != -1:
-            params["maxAge"] = self.max_age
+        if self.viz_width is not None:
+            params["vizWidth"] = self.viz_width
 
-        self._append_view_filters(params)
         return params
 
 
-class ImageRequestOptions(_FilterOptionsBase):
+class CSVRequestOptions(_DataExportOptions):
+    extension = "csv"
+
+
+class ExcelRequestOptions(_DataExportOptions):
+    extension = "xlsx"
+
+
+class ImageRequestOptions(_ImagePDFCommonExportOptions):
+    extension = "png"
+
     # 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):
     class PageType:
         A3 = "a3"
         A4 = "a4"
@@ -276,61 +301,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

@@ -33,6 +33,10 @@ from tableauserverclient.server.endpoint import (
     Metrics,
     Endpoint,
     CustomViews,
+    LinkedTasks,
+    GroupSets,
+    Tags,
+    VirtualConnections,
 )
 from tableauserverclient.server.exceptions import (
     ServerInfoEndpointNotFoundError,
@@ -54,8 +58,64 @@ 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"
@@ -99,6 +159,10 @@ class Server(object):
         self.flow_runs = FlowRuns(self)
         self.metrics = Metrics(self)
         self.custom_views = CustomViews(self)
+        self.linked_tasks = LinkedTasks(self)
+        self.group_sets = GroupSets(self)
+        self.tags = Tags(self)
+        self.virtual_connections = VirtualConnections(self)
 
         self._session = self._session_factory()
         self._http_options = dict()  # must set this before making a server call
@@ -122,7 +186,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:
@@ -134,7 +198,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()
@@ -168,15 +232,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):
@@ -193,12 +257,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):

tableauserverclient/server/sort.py

@@ -1,7 +1,7 @@
-class Sort(object):
+class Sort:
     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}"

{tableauserverclient-0.32.dist-info → tableauserverclient-0.34.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tableauserverclient
-Version: 0.32
+Version: 0.34
 Summary: A Python module for working with the Tableau Server REST API.
 Author-email: Tableau <github@tableau.com>
 License: The MIT License (MIT)
@@ -28,28 +28,28 @@ License: The MIT License (MIT)
 Project-URL: repository, https://github.com/tableau/server-client-python
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.7
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: LICENSE.versioneer
-Requires-Dist: defusedxml >=0.7.1
-Requires-Dist: packaging >=23.1
-Requires-Dist: requests >=2.31
-Requires-Dist: urllib3 ==2.2.2
-Requires-Dist: typing-extensions >=4.0.1
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: packaging>=23.1
+Requires-Dist: requests>=2.32
+Requires-Dist: urllib3<3,>=2.2.2
+Requires-Dist: typing-extensions>=4.0.1
 Provides-Extra: test
-Requires-Dist: black ==23.7 ; extra == 'test'
-Requires-Dist: build ; extra == 'test'
-Requires-Dist: mypy ==1.4 ; extra == 'test'
-Requires-Dist: pytest >=7.0 ; extra == 'test'
-Requires-Dist: pytest-cov ; extra == 'test'
-Requires-Dist: pytest-subtests ; extra == 'test'
-Requires-Dist: requests-mock <2.0,>=1.0 ; extra == 'test'
+Requires-Dist: black==24.8; extra == "test"
+Requires-Dist: build; extra == "test"
+Requires-Dist: mypy==1.4; extra == "test"
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-subtests; extra == "test"
+Requires-Dist: requests-mock<2.0,>=1.0; extra == "test"
 
 # Tableau Server Client (Python)
 
@@ -62,14 +62,14 @@ Use the Tableau Server Client (TSC) library to increase your productivity as you
 * Create users and groups.
 * Query projects, sites, and more.
 
-This repository contains Python source code for the library and sample files showing how to use it. As of May 2022, Python versions 3.7 and up are supported.
+This repository contains Python source code for the library and sample files showing how to use it. As of September 2024, support for Python 3.7 and 3.8 will be dropped - support for older versions of Python aims to match https://devguide.python.org/versions/
 
 To see sample code that works directly with the REST API (in Java, Python, or Postman), visit the [REST API Samples](https://github.com/tableau/rest-api-samples) repo.
 
 For more information on installing and using TSC, see the documentation:
 <https://tableau.github.io/server-client-python/docs/>
  
-
+To contribute, see our [Developer Guide](https://tableau.github.io/server-client-python/docs/dev-guide). A list of all our contributors to date is in [CONTRIBUTORS.md].
 
 ## License
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Ftableau%2Fserver-client-python.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Ftableau%2Fserver-client-python?ref=badge_large)