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

tableauserverclient/server/endpoint/tasks_endpoint.py

@@ -31,6 +31,24 @@ class Tasks(Endpoint):
     def get(
         self, req_options: Optional["RequestOptions"] = None, task_type: str = TaskItem.Type.ExtractRefresh
     ) -> tuple[list[TaskItem], PaginationItem]:
+        """
+        Returns information about tasks on the specified site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#list_extract_refresh_tasks
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Options for the request, such as filtering, sorting, and pagination.
+
+        task_type : str, optional
+            The type of task to query. See TaskItem.Type for possible values.
+
+        Returns
+        -------
+        tuple[list[TaskItem], PaginationItem]
+
+        """
         if task_type == TaskItem.Type.DataAcceleration:
             self.parent_srv.assert_at_least_version("3.8", "Data Acceleration Tasks")
 
@@ -45,6 +63,20 @@ class Tasks(Endpoint):
 
     @api(version="2.6")
     def get_by_id(self, task_id: str) -> TaskItem:
+        """
+        Returns information about the specified task.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get_extract_refresh_task
+
+        Parameters
+        ----------
+        task_id : str
+            The ID of the task to query.
+
+        Returns
+        -------
+        TaskItem
+        """
         if not task_id:
             error = "No Task ID provided"
             raise ValueError(error)
@@ -59,6 +91,21 @@ class Tasks(Endpoint):
 
     @api(version="3.19")
     def create(self, extract_item: TaskItem) -> TaskItem:
+        """
+        Creates a custom schedule for an extract refresh on Tableau Cloud. For
+        Tableau Server, use the Schedules endpoint to create a schedule.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_cloud_extract_refresh_task
+
+        Parameters
+        ----------
+        extract_item : TaskItem
+            The extract refresh task to create.
+
+        Returns
+        -------
+        TaskItem
+        """
         if not extract_item:
             error = "No extract refresh provided"
             raise ValueError(error)
@@ -70,6 +117,20 @@ class Tasks(Endpoint):
 
     @api(version="2.6")
     def run(self, task_item: TaskItem) -> bytes:
+        """
+        Runs the specified extract refresh task.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#run_extract_refresh_task
+
+        Parameters
+        ----------
+        task_item : TaskItem
+            The task to run.
+
+        Returns
+        -------
+        bytes
+        """
         if not task_item.id:
             error = "Task item missing ID."
             raise MissingRequiredFieldError(error)
@@ -86,6 +147,23 @@ class Tasks(Endpoint):
     # Delete 1 task by id
     @api(version="3.6")
     def delete(self, task_id: str, task_type: str = TaskItem.Type.ExtractRefresh) -> None:
+        """
+        Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_extract_refresh_task
+
+        Parameters
+        ----------
+        task_id : str
+            The ID of the task to delete.
+
+        task_type : str, default TaskItem.Type.ExtractRefresh
+            The type of task to query. See TaskItem.Type for possible values.
+
+        Returns
+        -------
+        None
+        """
         if task_type == TaskItem.Type.DataAcceleration:
             self.parent_srv.assert_at_least_version("3.8", "Data Acceleration Tasks")
 

tableauserverclient/server/endpoint/views_endpoint.py

@@ -1,6 +1,7 @@
 import logging
 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.permissions_endpoint import _PermissionsEndpoint
@@ -25,6 +26,12 @@ if TYPE_CHECKING:
 
 
 class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
+    """
+    The Tableau Server Client provides methods for interacting with view
+    resources, or endpoints. These methods correspond to the endpoints for views
+    in the Tableau Server REST API.
+    """
+
     def __init__(self, parent_srv):
         super().__init__(parent_srv)
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
@@ -42,6 +49,24 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
     def get(
         self, req_options: Optional["RequestOptions"] = None, usage: bool = False
     ) -> tuple[list[ViewItem], PaginationItem]:
+        """
+        Returns the list of views on the site. Paginated endpoint.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_views_for_site
+
+        Parameters
+        ----------
+        req_options: Optional[RequestOptions], default None
+            The request options for the request. These options can include
+            parameters such as page size and sorting.
+
+        usage: bool, default False
+            If True, includes usage statistics in the response.
+
+        Returns
+        -------
+        views: tuple[list[ViewItem], PaginationItem]
+        """
         logger.info("Querying all views on site")
         url = self.baseurl
         if usage:
@@ -53,6 +78,23 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="3.1")
     def get_by_id(self, view_id: str, usage: bool = False) -> ViewItem:
+        """
+        Returns the details of a specific view.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#get_view
+
+        Parameters
+        ----------
+        view_id: str
+            The view ID.
+
+        usage: bool, default False
+            If True, includes usage statistics in the response.
+
+        Returns
+        -------
+        view_item: ViewItem
+        """
         if not view_id:
             error = "View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -65,6 +107,24 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="2.0")
     def populate_preview_image(self, view_item: ViewItem) -> None:
+        """
+        Populates a preview image for the specified view.
+
+        This method gets the preview image (thumbnail) for the specified view
+        item. The method uses the id and workbook_id fields to query the preview
+        image. The method populates the preview_image for the view.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_view_with_preview
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to populate the preview image.
+
+        Returns
+        -------
+        None
+        """
         if not view_item.id or not view_item.workbook_id:
             error = "View item missing ID or workbook ID."
             raise MissingRequiredFieldError(error)
@@ -83,6 +143,27 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="2.5")
     def populate_image(self, view_item: ViewItem, req_options: Optional["ImageRequestOptions"] = None) -> None:
+        """
+        Populates the image of the specified view.
+
+        This method uses the id field to query the image, and populates the
+        image content as the image field.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_view_image
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to populate the image.
+
+        req_options: Optional[ImageRequestOptions], default None
+            Optional request options for the request. These options can include
+            parameters such as image resolution and max age.
+
+        Returns
+        -------
+        None
+        """
         if not view_item.id:
             error = "View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -101,6 +182,26 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="2.7")
     def populate_pdf(self, view_item: ViewItem, req_options: Optional["PDFRequestOptions"] = None) -> None:
+        """
+        Populates the PDF content of the specified view.
+
+        This method populates a PDF with image(s) of the view you specify.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_view_pdf
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to populate the PDF.
+
+        req_options: Optional[PDFRequestOptions], default None
+            Optional request options for the request. These options can include
+            parameters such as orientation and paper size.
+
+        Returns
+        -------
+        None
+        """
         if not view_item.id:
             error = "View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -119,6 +220,27 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="2.7")
     def populate_csv(self, view_item: ViewItem, req_options: Optional["CSVRequestOptions"] = None) -> None:
+        """
+        Populates the CSV data of the specified view.
+
+        This method uses the id field to query the CSV data, and populates the
+        data as the csv field.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_view_data
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to populate the CSV data.
+
+        req_options: Optional[CSVRequestOptions], default None
+            Optional request options for the request. These options can include
+            parameters such as view filters and max age.
+
+        Returns
+        -------
+        None
+        """
         if not view_item.id:
             error = "View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -137,6 +259,27 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="3.8")
     def populate_excel(self, view_item: ViewItem, req_options: Optional["ExcelRequestOptions"] = None) -> None:
+        """
+        Populates the Excel data of the specified view.
+
+        This method uses the id field to query the Excel data, and populates the
+        data as the Excel field.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#download_view_excel
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to populate the Excel data.
+
+        req_options: Optional[ExcelRequestOptions], default None
+            Optional request options for the request. These options can include
+            parameters such as view filters and max age.
+
+        Returns
+        -------
+        None
+        """
         if not view_item.id:
             error = "View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -155,18 +298,66 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="3.2")
     def populate_permissions(self, item: ViewItem) -> None:
+        """
+        Returns a list of permissions for the specific view.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_view_permissions
+
+        Parameters
+        ----------
+        item: ViewItem
+            The view item for which to populate the permissions.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.populate(item)
 
     @api(version="3.2")
-    def update_permissions(self, resource, rules):
+    def update_permissions(self, resource: ViewItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
+        """ """
         return self._permissions.update(resource, rules)
 
     @api(version="3.2")
-    def delete_permission(self, item, capability_item):
+    def delete_permission(self, item: ViewItem, capability_item: PermissionsRule) -> None:
+        """
+        Deletes permission to the specified view (also known as a sheet) for a
+        Tableau Server user or group.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_view_permission
+
+        Parameters
+        ----------
+        item: ViewItem
+            The view item for which to delete the permission.
+
+        capability_item: PermissionsRule
+            The permission rule to delete.
+
+        Returns
+        -------
+        None
+        """
         return self._permissions.delete(item, capability_item)
 
     # Update view. Currently only tags can be updated
     def update(self, view_item: ViewItem) -> ViewItem:
+        """
+        Updates the tags for the specified view. All other fields are managed
+        through the WorkbookItem object.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#add_tags_to_view
+
+        Parameters
+        ----------
+        view_item: ViewItem
+            The view item for which to update tags.
+
+        Returns
+        -------
+        ViewItem
+        """
         if not view_item.id:
             error = "View item missing ID. View must be retrieved from server first."
             raise MissingRequiredFieldError(error)
@@ -178,14 +369,64 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
 
     @api(version="1.0")
     def add_tags(self, item: Union[ViewItem, str], tags: Union[Iterable[str], str]) -> set[str]:
+        """
+        Adds tags to the specified view.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#add_tags_to_view
+
+        Parameters
+        ----------
+        item: Union[ViewItem, str]
+            The view item or view ID to which to add tags.
+
+        tags: Union[Iterable[str], str]
+            The tags to add to the view.
+
+        Returns
+        -------
+        set[str]
+
+        """
         return super().add_tags(item, tags)
 
     @api(version="1.0")
     def delete_tags(self, item: Union[ViewItem, str], tags: Union[Iterable[str], str]) -> None:
+        """
+        Deletes tags from the specified view.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#delete_tags_from_view
+
+        Parameters
+        ----------
+        item: Union[ViewItem, str]
+            The view item or view ID from which to delete tags.
+
+        tags: Union[Iterable[str], str]
+            The tags to delete from the view.
+
+        Returns
+        -------
+        None
+        """
         return super().delete_tags(item, tags)
 
     @api(version="1.0")
     def update_tags(self, item: ViewItem) -> None:
+        """
+        Updates the tags for the specified view. Any changes to the tags must
+        be made by editing the tags attribute of the view item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#add_tags_to_view
+
+        Parameters
+        ----------
+        item: ViewItem
+            The view item for which to update tags.
+
+        Returns
+        -------
+        None
+        """
         return super().update_tags(item)
 
     def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[ViewItem]:

tableauserverclient/server/endpoint/webhooks_endpoint.py

@@ -23,6 +23,21 @@ class Webhooks(Endpoint):
 
     @api(version="3.6")
     def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[WebhookItem], PaginationItem]:
+        """
+        Returns a list of all webhooks on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#list_webhooks_for_site
+
+        Parameters
+        ----------
+        req_options : Optional[RequestOptions]
+            Filter and sorting options for the request.
+
+        Returns
+        -------
+        tuple[list[WebhookItem], PaginationItem]
+            A tuple of the list of webhooks and pagination item
+        """
         logger.info("Querying all Webhooks on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -32,6 +47,21 @@ class Webhooks(Endpoint):
 
     @api(version="3.6")
     def get_by_id(self, webhook_id: str) -> WebhookItem:
+        """
+        Returns information about a specified Webhook.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#get_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to query.
+
+        Returns
+        -------
+        WebhookItem
+            An object containing information about the webhook.
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)
@@ -42,6 +72,20 @@ class Webhooks(Endpoint):
 
     @api(version="3.6")
     def delete(self, webhook_id: str) -> None:
+        """
+        Deletes a specified webhook.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to delete.
+
+        Returns
+        -------
+        None
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)
@@ -51,6 +95,21 @@ class Webhooks(Endpoint):
 
     @api(version="3.6")
     def create(self, webhook_item: WebhookItem) -> WebhookItem:
+        """
+        Creates a new webhook on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_webhook
+
+        Parameters
+        ----------
+        webhook_item : WebhookItem
+            The webhook item to create.
+
+        Returns
+        -------
+        WebhookItem
+            An object containing information about the created webhook
+        """
         url = self.baseurl
         create_req = RequestFactory.Webhook.create_req(webhook_item)
         server_response = self.post_request(url, create_req)
@@ -61,6 +120,24 @@ class Webhooks(Endpoint):
 
     @api(version="3.6")
     def test(self, webhook_id: str):
+        """
+        Tests the specified webhook. Sends an empty payload to the configured
+        destination URL of the webhook and returns the response from the server.
+        This is useful for testing, to ensure that things are being sent from
+        Tableau and received back as expected.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#test_webhook
+
+        Parameters
+        ----------
+        webhook_id : str
+            The ID of the webhook to test.
+
+        Returns
+        -------
+        XML Response
+
+        """
         if not webhook_id:
             error = "Webhook ID undefined."
             raise ValueError(error)

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -118,7 +118,7 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         return WorkbookItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     @api(version="2.8")
-    def refresh(self, workbook_item: Union[WorkbookItem, str]) -> JobItem:
+    def refresh(self, workbook_item: Union[WorkbookItem, str], incremental: bool = False) -> JobItem:
         """
         Refreshes the extract of an existing workbook.
 
@@ -126,6 +126,8 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         ----------
         workbook_item : WorkbookItem | str
             The workbook item or workbook ID.
+        incremental: bool
+            Whether to do a full refresh or incremental refresh of the extract data
 
         Returns
         -------
@@ -134,8 +136,8 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         """
         id_ = getattr(workbook_item, "id", workbook_item)
         url = f"{self.baseurl}/{id_}/refresh"
-        empty_req = RequestFactory.Empty.empty_req()
-        server_response = self.post_request(url, empty_req)
+        refresh_req = RequestFactory.Task.refresh_req(incremental)
+        server_response = self.post_request(url, refresh_req)
         new_job = JobItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return new_job
 
@@ -280,7 +282,7 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         if include_view_acceleration_status:
             url += "?includeViewAccelerationStatus=True"
 
-        update_req = RequestFactory.Workbook.update_req(workbook_item)
+        update_req = RequestFactory.Workbook.update_req(workbook_item, self.parent_srv)
         server_response = self.put_request(url, update_req)
         logger.info(f"Updated workbook item (ID: {workbook_item.id})")
         updated_workbook = copy.copy(workbook_item)

tableauserverclient/server/pager.py

@@ -27,6 +27,30 @@ class Pager(Iterable[T]):
     (users in a group, views in a workbook, etc) by passing a different endpoint.
 
     Will loop over anything that returns (list[ModelItem], PaginationItem).
+
+    Will make a copy of the `RequestOptions` object passed in so it can be reused.
+
+    Makes a call to the Server for each page of items, then yields each item in the list.
+
+    Parameters
+    ----------
+    endpoint: CallableEndpoint[T] or Endpoint[T]
+        The endpoint to call to get the items. Can be a callable or an Endpoint object.
+        Expects a tuple of (list[T], PaginationItem) to be returned.
+
+    request_opts: RequestOptions, optional
+        The request options to pass to the endpoint. If not provided, will use default RequestOptions.
+        Filters, sorts, page size, starting page number, etc can be set here.
+
+    Yields
+    ------
+    T
+        The items returned from the endpoint.
+
+    Raises
+    ------
+    ValueError
+        If the endpoint is not a callable or an Endpoint object.
     """
 
     def __init__(

tableauserverclient/server/request_factory.py

@@ -958,9 +958,15 @@ class WorkbookRequest:
             views_element = ET.SubElement(workbook_element, "views")
             for view_name in workbook_item.hidden_views:
                 _add_hiddenview_element(views_element, view_name)
+
+        if workbook_item.thumbnails_user_id is not None:
+            workbook_element.attrib["thumbnailsUserId"] = workbook_item.thumbnails_user_id
+        elif workbook_item.thumbnails_group_id is not None:
+            workbook_element.attrib["thumbnailsGroupId"] = workbook_item.thumbnails_group_id
+
         return ET.tostring(xml_request)
 
-    def update_req(self, workbook_item):
+    def update_req(self, workbook_item, parent_srv: Optional["Server"] = None):
         xml_request = ET.Element("tsRequest")
         workbook_element = ET.SubElement(xml_request, "workbook")
         if workbook_item.name:
@@ -973,6 +979,12 @@ class WorkbookRequest:
         if workbook_item.owner_id:
             owner_element = ET.SubElement(workbook_element, "owner")
             owner_element.attrib["id"] = workbook_item.owner_id
+        if (
+            workbook_item.description is not None
+            and parent_srv is not None
+            and parent_srv.check_at_least_version("3.21")
+        ):
+            workbook_element.attrib["description"] = workbook_item.description
         if workbook_item._views is not None:
             views_element = ET.SubElement(workbook_element, "views")
             for view in workbook_item.views:
@@ -1105,6 +1117,13 @@ class TaskRequest:
         # Send an empty tsRequest
         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)
+
     @_tsrequest_wrapped
     def create_extract_req(self, xml_request: ET.Element, extract_item: "TaskItem") -> bytes:
         extract_element = ET.SubElement(xml_request, "extractRefresh")