tableauserverclient 0.36__py3-none-any.whl → 0.38__py3-none-any.whl

tableauserverclient/server/endpoint/users_endpoint.py

@@ -87,7 +87,7 @@ class Users(QuerysetEndpoint[UserItem]):
 
         if req_options is None:
             req_options = RequestOptions()
-        req_options._all_fields = True
+        req_options.all_fields = True
 
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -381,10 +381,15 @@ class Users(QuerysetEndpoint[UserItem]):
 
     # Get workbooks for user
     @api(version="2.0")
-    def populate_workbooks(self, user_item: UserItem, req_options: Optional[RequestOptions] = None) -> None:
+    def populate_workbooks(
+        self, user_item: UserItem, req_options: Optional[RequestOptions] = None, owned_only: bool = False
+    ) -> None:
         """
         Returns information about the workbooks that the specified user owns
-        and has Read (view) permissions for.
+        or has Read (view) permissions for. If owned_only is set to True,
+        only the workbooks that the user owns are returned. If owned_only is
+        set to False, all workbooks that the user has Read (view) permissions
+        for are returned.
 
         This method retrieves the workbook information for the specified user.
         The REST API is designed to return only the information you ask for
@@ -402,6 +407,10 @@ class Users(QuerysetEndpoint[UserItem]):
         req_options : Optional[RequestOptions]
             Optional request options to filter and sort the results.
 
+        owned_only : bool, default=False
+            If True, only the workbooks that the user owns are returned.
+            If False, all workbooks that the user has Read (view) permissions
+
         Returns
         -------
         None
@@ -423,14 +432,22 @@ class Users(QuerysetEndpoint[UserItem]):
             raise MissingRequiredFieldError(error)
 
         def wb_pager():
-            return Pager(lambda options: self._get_wbs_for_user(user_item, options), req_options)
+            def func(req_options):
+                return self._get_wbs_for_user(user_item, req_options, owned_only=owned_only)
+
+            return Pager(func, req_options)
 
         user_item._set_workbooks(wb_pager)
 
     def _get_wbs_for_user(
-        self, user_item: UserItem, req_options: Optional[RequestOptions] = None
+        self,
+        user_item: UserItem,
+        req_options: Optional[RequestOptions] = None,
+        owned_only: bool = False,
     ) -> tuple[list[WorkbookItem], PaginationItem]:
         url = f"{self.baseurl}/{user_item.id}/workbooks"
+        if owned_only:
+            url += "?ownedBy=true"
         server_response = self.get_request(url, req_options)
         logger.info(f"Populated workbooks for user (ID: {user_item.id})")
         workbook_item = WorkbookItem.from_response(server_response.content, self.parent_srv.namespace)

tableauserverclient/server/endpoint/views_endpoint.py

@@ -3,7 +3,7 @@ from contextlib import closing
 
 from tableauserverclient.models.permissions_item import PermissionsRule
 from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
-from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
+from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError, UnsupportedAttributeError
 from tableauserverclient.server.endpoint.permissions_endpoint import _PermissionsEndpoint
 from tableauserverclient.server.endpoint.resource_tagger import TaggingMixin
 from tableauserverclient.server.query import QuerySet
@@ -171,6 +171,10 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
         def image_fetcher():
             return self._get_view_image(view_item, req_options)
 
+        if not self.parent_srv.check_at_least_version("3.23") and req_options is not None:
+            if req_options.viz_height or req_options.viz_width:
+                raise UnsupportedAttributeError("viz_height and viz_width are only supported in 3.23+")
+
         view_item._set_image(image_fetcher)
         logger.info(f"Populated image for view (ID: {view_item.id})")
 

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -11,7 +11,11 @@ from tableauserverclient.models.permissions_item import PermissionsRule
 from tableauserverclient.server.query import QuerySet
 
 from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api, parameter_added_in
-from tableauserverclient.server.endpoint.exceptions import InternalServerError, MissingRequiredFieldError
+from tableauserverclient.server.endpoint.exceptions import (
+    InternalServerError,
+    MissingRequiredFieldError,
+    UnsupportedAttributeError,
+)
 from tableauserverclient.server.endpoint.permissions_endpoint import _PermissionsEndpoint
 from tableauserverclient.server.endpoint.resource_tagger import TaggingMixin
 
@@ -34,7 +38,7 @@ from collections.abc import Iterable, Sequence
 
 if TYPE_CHECKING:
     from tableauserverclient.server import Server
-    from tableauserverclient.server.request_options import RequestOptions
+    from tableauserverclient.server.request_options import RequestOptions, PDFRequestOptions, PPTXRequestOptions
     from tableauserverclient.models import DatasourceItem
     from tableauserverclient.server.endpoint.schedules_endpoint import AddResponse
 
@@ -136,7 +140,7 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         """
         id_ = getattr(workbook_item, "id", workbook_item)
         url = f"{self.baseurl}/{id_}/refresh"
-        refresh_req = RequestFactory.Task.refresh_req(incremental)
+        refresh_req = RequestFactory.Task.refresh_req(incremental, self.parent_srv)
         server_response = self.post_request(url, refresh_req)
         new_job = JobItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return new_job
@@ -472,11 +476,12 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         connections = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
         return connections
 
-    # Get the pdf of the entire workbook if its tabs are enabled, pdf of the default view if its tabs are disabled
     @api(version="3.4")
-    def populate_pdf(self, workbook_item: WorkbookItem, req_options: Optional["RequestOptions"] = None) -> None:
+    def populate_pdf(self, workbook_item: WorkbookItem, req_options: Optional["PDFRequestOptions"] = None) -> None:
         """
-        Populates the PDF for the specified workbook item.
+        Populates the PDF for the specified workbook item. Get the pdf of the
+        entire workbook if its tabs are enabled, pdf of the default view if its
+        tabs are disabled.
 
         This method populates a PDF with image(s) of the workbook view(s) you
         specify.
@@ -488,7 +493,7 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         workbook_item : WorkbookItem
             The workbook item to populate the PDF for.
 
-        req_options : RequestOptions, optional
+        req_options : PDFRequestOptions, optional
             (Optional) You can pass in request options to specify the page type
             and orientation of the PDF content, as well as the maximum age of
             the PDF rendered on the server. See PDFRequestOptions class for more
@@ -510,17 +515,26 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         def pdf_fetcher() -> bytes:
             return self._get_wb_pdf(workbook_item, req_options)
 
+        if not self.parent_srv.check_at_least_version("3.23") and req_options is not None:
+            if req_options.view_filters or req_options.view_parameters:
+                raise UnsupportedAttributeError("view_filters and view_parameters are only supported in 3.23+")
+
+            if req_options.viz_height or req_options.viz_width:
+                raise UnsupportedAttributeError("viz_height and viz_width are only supported in 3.23+")
+
         workbook_item._set_pdf(pdf_fetcher)
         logger.info(f"Populated pdf for workbook (ID: {workbook_item.id})")
 
-    def _get_wb_pdf(self, workbook_item: WorkbookItem, req_options: Optional["RequestOptions"]) -> bytes:
+    def _get_wb_pdf(self, workbook_item: WorkbookItem, req_options: Optional["PDFRequestOptions"]) -> bytes:
         url = f"{self.baseurl}/{workbook_item.id}/pdf"
         server_response = self.get_request(url, req_options)
         pdf = server_response.content
         return pdf
 
     @api(version="3.8")
-    def populate_powerpoint(self, workbook_item: WorkbookItem, req_options: Optional["RequestOptions"] = None) -> None:
+    def populate_powerpoint(
+        self, workbook_item: WorkbookItem, req_options: Optional["PPTXRequestOptions"] = None
+    ) -> None:
         """
         Populates the PowerPoint for the specified workbook item.
 
@@ -561,7 +575,7 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         workbook_item._set_powerpoint(pptx_fetcher)
         logger.info(f"Populated powerpoint for workbook (ID: {workbook_item.id})")
 
-    def _get_wb_pptx(self, workbook_item: WorkbookItem, req_options: Optional["RequestOptions"]) -> bytes:
+    def _get_wb_pptx(self, workbook_item: WorkbookItem, req_options: Optional["PPTXRequestOptions"]) -> bytes:
         url = f"{self.baseurl}/{workbook_item.id}/powerpoint"
         server_response = self.get_request(url, req_options)
         pptx = server_response.content

tableauserverclient/server/query.py

@@ -208,6 +208,42 @@ class QuerySet(Iterable[T], Sized):
             self.request_options.pagesize = kwargs["page_size"]
         return self
 
+    def fields(self: Self, *fields: str) -> Self:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be used in addition to the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        self.request_options.fields |= set(fields) | set(("_default_"))
+        return self
+
+    def only_fields(self: Self, *fields: str) -> Self:
+        """
+        Add fields to the request options. If no fields are provided, the
+        default fields will be used. If fields are provided, the default fields
+        will be replaced by the provided fields.
+
+        Parameters
+        ----------
+        fields : str
+            The fields to include in the request options.
+
+        Returns
+        -------
+        QuerySet
+        """
+        self.request_options.fields |= set(fields)
+        return self
+
     @staticmethod
     def _parse_shorthand_filter(key: str) -> tuple[str, str]:
         tokens = key.split("__", 1)

tableauserverclient/server/request_factory.py

@@ -913,6 +913,8 @@ class UserRequest:
             user_element.attrib["authSetting"] = user_item.auth_setting
         if password:
             user_element.attrib["password"] = password
+        if user_item.idp_configuration_id is not None:
+            user_element.attrib["idpConfigurationId"] = user_item.idp_configuration_id
         return ET.tostring(xml_request)
 
     def add_req(self, user_item: UserItem) -> bytes:
@@ -929,6 +931,9 @@ class UserRequest:
 
         if user_item.auth_setting:
             user_element.attrib["authSetting"] = user_item.auth_setting
+
+        if user_item.idp_configuration_id is not None:
+            user_element.attrib["idpConfigurationId"] = user_item.idp_configuration_id
         return ET.tostring(xml_request)
 
 
@@ -1118,11 +1123,17 @@ class TaskRequest:
         pass
 
     @_tsrequest_wrapped
-    def refresh_req(self, xml_request: ET.Element, incremental: bool = False) -> bytes:
-        task_element = ET.SubElement(xml_request, "extractRefresh")
-        if incremental:
-            task_element.attrib["incremental"] = "true"
-        return ET.tostring(xml_request)
+    def refresh_req(
+        self, xml_request: ET.Element, incremental: bool = False, parent_srv: Optional["Server"] = None
+    ) -> Optional[bytes]:
+        if parent_srv is not None and parent_srv.check_at_least_version("3.25"):
+            task_element = ET.SubElement(xml_request, "extractRefresh")
+            if incremental:
+                task_element.attrib["incremental"] = "true"
+            return ET.tostring(xml_request)
+        elif incremental:
+            raise ValueError("Incremental refresh is only supported in 3.25+")
+        return None
 
     @_tsrequest_wrapped
     def create_extract_req(self, xml_request: ET.Element, extract_item: "TaskItem") -> bytes:

tableauserverclient/server/request_options.py

@@ -1,5 +1,6 @@
 import sys
 from typing import Optional
+import warnings
 
 from typing_extensions import Self
 
@@ -62,8 +63,21 @@ class RequestOptions(RequestOptionsBase):
         self.pagesize = pagesize or config.PAGE_SIZE
         self.sort = set()
         self.filter = set()
+        self.fields = set()
         # This is private until we expand all of our parsers to handle the extra fields
-        self._all_fields = False
+        self.all_fields = False
+
+    @property
+    def _all_fields(self) -> bool:
+        return self.all_fields
+
+    @_all_fields.setter
+    def _all_fields(self, value):
+        warnings.warn(
+            "Directly setting _all_fields is deprecated, please use the all_fields property instead.",
+            DeprecationWarning,
+        )
+        self.all_fields = value
 
     def get_query_params(self) -> dict:
         params = {}
@@ -75,12 +89,14 @@ class RequestOptions(RequestOptionsBase):
             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:
+        if self.all_fields:
             params["fields"] = "_all_"
         if self.pagenumber:
             params["pageNumber"] = self.pagenumber
         if self.pagesize:
             params["pageSize"] = self.pagesize
+        if self.fields:
+            params["fields"] = ",".join(self.fields)
         return params
 
     def page_size(self, page_size):
@@ -181,6 +197,116 @@ class RequestOptions(RequestOptionsBase):
         Desc = "desc"
         Asc = "asc"
 
+    class SelectFields:
+        class Common:
+            All = "_all_"
+            Default = "_default_"
+
+        class ContentsCounts:
+            ProjectCount = "contentsCounts.projectCount"
+            ViewCount = "contentsCounts.viewCount"
+            DatasourceCount = "contentsCounts.datasourceCount"
+            WorkbookCount = "contentsCounts.workbookCount"
+
+        class Datasource:
+            ContentUrl = "datasource.contentUrl"
+            ID = "datasource.id"
+            Name = "datasource.name"
+            Type = "datasource.type"
+            Description = "datasource.description"
+            CreatedAt = "datasource.createdAt"
+            UpdatedAt = "datasource.updatedAt"
+            EncryptExtracts = "datasource.encryptExtracts"
+            IsCertified = "datasource.isCertified"
+            UseRemoteQueryAgent = "datasource.useRemoteQueryAgent"
+            WebPageURL = "datasource.webpageUrl"
+            Size = "datasource.size"
+            Tag = "datasource.tag"
+            FavoritesTotal = "datasource.favoritesTotal"
+            DatabaseName = "datasource.databaseName"
+            ConnectedWorkbooksCount = "datasource.connectedWorkbooksCount"
+            HasAlert = "datasource.hasAlert"
+            HasExtracts = "datasource.hasExtracts"
+            IsPublished = "datasource.isPublished"
+            ServerName = "datasource.serverName"
+
+        class Favorite:
+            Label = "favorite.label"
+            ParentProjectName = "favorite.parentProjectName"
+            TargetOwnerName = "favorite.targetOwnerName"
+
+        class Group:
+            ID = "group.id"
+            Name = "group.name"
+            DomainName = "group.domainName"
+            UserCount = "group.userCount"
+            MinimumSiteRole = "group.minimumSiteRole"
+
+        class Job:
+            ID = "job.id"
+            Status = "job.status"
+            CreatedAt = "job.createdAt"
+            StartedAt = "job.startedAt"
+            EndedAt = "job.endedAt"
+            Priority = "job.priority"
+            JobType = "job.jobType"
+            Title = "job.title"
+            Subtitle = "job.subtitle"
+
+        class Owner:
+            ID = "owner.id"
+            Name = "owner.name"
+            FullName = "owner.fullName"
+            SiteRole = "owner.siteRole"
+            LastLogin = "owner.lastLogin"
+            Email = "owner.email"
+
+        class Project:
+            ID = "project.id"
+            Name = "project.name"
+            Description = "project.description"
+            CreatedAt = "project.createdAt"
+            UpdatedAt = "project.updatedAt"
+            ContentPermissions = "project.contentPermissions"
+            ParentProjectID = "project.parentProjectId"
+            TopLevelProject = "project.topLevelProject"
+            Writeable = "project.writeable"
+
+        class User:
+            ExternalAuthUserId = "user.externalAuthUserId"
+            ID = "user.id"
+            Name = "user.name"
+            SiteRole = "user.siteRole"
+            LastLogin = "user.lastLogin"
+            FullName = "user.fullName"
+            Email = "user.email"
+            AuthSetting = "user.authSetting"
+
+        class View:
+            ID = "view.id"
+            Name = "view.name"
+            ContentUrl = "view.contentUrl"
+            CreatedAt = "view.createdAt"
+            UpdatedAt = "view.updatedAt"
+            Tags = "view.tags"
+            SheetType = "view.sheetType"
+            Usage = "view.usage"
+
+        class Workbook:
+            ID = "workbook.id"
+            Description = "workbook.description"
+            Name = "workbook.name"
+            ContentUrl = "workbook.contentUrl"
+            ShowTabs = "workbook.showTabs"
+            Size = "workbook.size"
+            CreatedAt = "workbook.createdAt"
+            UpdatedAt = "workbook.updatedAt"
+            SheetCount = "workbook.sheetCount"
+            HasExtracts = "workbook.hasExtracts"
+            Tags = "workbook.tags"
+            WebpageUrl = "workbook.webpageUrl"
+            DefaultViewId = "workbook.defaultViewId"
+
 
 """
 These options can be used by methods that are fetching data exported from a specific content item
@@ -385,6 +511,8 @@ 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.
 
+    vf and parameter filters are only supported in API version 3.23 and later.
+
     Parameters
     ----------
     page_type: str, optional
@@ -438,3 +566,35 @@ class PDFRequestOptions(_ImagePDFCommonExportOptions):
             params["orientation"] = self.orientation
 
         return params
+
+
+class PPTXRequestOptions(RequestOptionsBase):
+    """
+    Options that can be used when exporting a view to PPTX. Set the maxage to control the age of the data exported.
+
+    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.
+    """
+
+    def __init__(self, maxage=-1):
+        super().__init__()
+        self.max_age = maxage
+
+    @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.max_age != -1:
+            params["maxAge"] = self.max_age
+
+        return params

tableauserverclient/server/server.py

@@ -2,6 +2,7 @@ from tableauserverclient.helpers.logging import logger
 
 import requests
 import urllib3
+import ssl
 
 from defusedxml.ElementTree import fromstring, ParseError
 from packaging.version import Version
@@ -91,6 +92,13 @@ class Server:
         and a later version of the REST API. For more information, see REST API
         Versions.
 
+    http_options : dict, optional
+        Additional options to pass to the requests library when making HTTP requests.
+
+    session_factory : callable, optional
+        A factory function that returns a requests.Session object. If not provided,
+        requests.session is used.
+
     Examples
     --------
     >>> import tableauserverclient as TSC
@@ -107,6 +115,16 @@ class Server:
     >>> # for example, 2.8
     >>> # server.version = '2.8'
 
+    >>> # if connecting to an older Tableau Server with weak DH keys (Python 3.12+ only)
+    >>> server.configure_ssl(allow_weak_dh=True)  # Note: reduces security
+
+    Notes
+    -----
+    When using Python 3.12 or later with older versions of Tableau Server, you may encounter
+    SSL errors related to weak Diffie-Hellman keys. This is because newer Python versions
+    enforce stronger security requirements. You can temporarily work around this using
+    configure_ssl(allow_weak_dh=True), but this reduces security and should only be used
+    as a temporary measure until the server can be upgraded.
     """
 
     class PublishMode:
@@ -125,6 +143,7 @@ class Server:
         self._auth_token = None
         self._site_id = None
         self._user_id = None
+        self._ssl_context = None
 
         # TODO: this needs to change to default to https, but without breaking existing code
         if not server_address.startswith("http://") and not server_address.startswith("https://"):
@@ -313,3 +332,26 @@ class Server:
 
     def is_signed_in(self):
         return self._auth_token is not None
+
+    def configure_ssl(self, *, allow_weak_dh=False):
+        """Configure SSL/TLS settings for the server connection.
+
+        Parameters
+        ----------
+        allow_weak_dh : bool, optional
+            If True, allows connections to servers with DH keys that are considered too small by modern Python versions.
+            WARNING: This reduces security and should only be used as a temporary workaround.
+        """
+        if allow_weak_dh:
+            logger.warning(
+                "WARNING: Allowing weak Diffie-Hellman keys. This reduces security and should only be used temporarily."
+            )
+            self._ssl_context = ssl.create_default_context()
+            # Allow weak DH keys by setting minimum key size to 512 bits (default is 1024 in Python 3.12+)
+            self._ssl_context.set_dh_parameters(min_key_bits=512)
+            self.add_http_options({"verify": self._ssl_context})
+        else:
+            self._ssl_context = None
+            # Remove any custom SSL context if we're reverting to default settings
+            if "verify" in self._http_options:
+                del self._http_options["verify"]

{tableauserverclient-0.36.dist-info → tableauserverclient-0.38.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: tableauserverclient
-Version: 0.36
+Version: 0.38
 Summary: A Python module for working with the Tableau Server REST API.
 Author-email: Tableau <github@tableau.com>
 License: The MIT License (MIT)
@@ -50,6 +50,7 @@ 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"
+Dynamic: license-file
 
 # Tableau Server Client (Python)