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

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
@@ -11,7 +12,8 @@ from tableauserverclient.models import ViewItem, PaginationItem
 
 from tableauserverclient.helpers.logging import logger
 
-from typing import Iterable, Iterator, List, Optional, Set, Tuple, TYPE_CHECKING, Union
+from typing import Optional, TYPE_CHECKING, Union
+from collections.abc import Iterable, Iterator
 
 if TYPE_CHECKING:
     from tableauserverclient.server.request_options import (
@@ -24,23 +26,47 @@ 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(Views, self).__init__(parent_srv)
+        super().__init__(parent_srv)
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
 
     # Used because populate_preview_image functionaliy requires workbook endpoint
     @property
     def siteurl(self) -> str:
-        return "{0}/sites/{1}".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}"
 
     @property
     def baseurl(self) -> str:
-        return "{0}/views".format(self.siteurl)
+        return f"{self.siteurl}/views"
 
     @api(version="2.2")
     def get(
         self, req_options: Optional["RequestOptions"] = None, usage: bool = False
-    ) -> Tuple[List[ViewItem], PaginationItem]:
+    ) -> 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:
@@ -52,11 +78,28 @@ 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)
-        logger.info("Querying single view (ID: {0})".format(view_id))
-        url = "{0}/{1}".format(self.baseurl, view_id)
+        logger.info(f"Querying single view (ID: {view_id})")
+        url = f"{self.baseurl}/{view_id}"
         if usage:
             url += "?includeUsageStatistics=true"
         server_response = self.get_request(url)
@@ -64,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)
@@ -72,16 +133,37 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
             return self._get_preview_for_view(view_item)
 
         view_item._set_preview_image(image_fetcher)
-        logger.info("Populated preview image for view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated preview image for view (ID: {view_item.id})")
 
     def _get_preview_for_view(self, view_item: ViewItem) -> bytes:
-        url = "{0}/workbooks/{1}/views/{2}/previewImage".format(self.siteurl, view_item.workbook_id, view_item.id)
+        url = f"{self.siteurl}/workbooks/{view_item.workbook_id}/views/{view_item.id}/previewImage"
         server_response = self.get_request(url)
         image = server_response.content
         return image
 
     @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)
@@ -90,16 +172,36 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
             return self._get_view_image(view_item, req_options)
 
         view_item._set_image(image_fetcher)
-        logger.info("Populated image for view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated image for view (ID: {view_item.id})")
 
     def _get_view_image(self, view_item: ViewItem, req_options: Optional["ImageRequestOptions"]) -> bytes:
-        url = "{0}/{1}/image".format(self.baseurl, view_item.id)
+        url = f"{self.baseurl}/{view_item.id}/image"
         server_response = self.get_request(url, req_options)
         image = server_response.content
         return image
 
     @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)
@@ -108,16 +210,37 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
             return self._get_view_pdf(view_item, req_options)
 
         view_item._set_pdf(pdf_fetcher)
-        logger.info("Populated pdf for view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated pdf for view (ID: {view_item.id})")
 
     def _get_view_pdf(self, view_item: ViewItem, req_options: Optional["PDFRequestOptions"]) -> bytes:
-        url = "{0}/{1}/pdf".format(self.baseurl, view_item.id)
+        url = f"{self.baseurl}/{view_item.id}/pdf"
         server_response = self.get_request(url, req_options)
         pdf = server_response.content
         return pdf
 
     @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)
@@ -126,16 +249,37 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
             return self._get_view_csv(view_item, req_options)
 
         view_item._set_csv(csv_fetcher)
-        logger.info("Populated csv for view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated csv for view (ID: {view_item.id})")
 
     def _get_view_csv(self, view_item: ViewItem, req_options: Optional["CSVRequestOptions"]) -> Iterator[bytes]:
-        url = "{0}/{1}/data".format(self.baseurl, view_item.id)
+        url = f"{self.baseurl}/{view_item.id}/data"
 
         with closing(self.get_request(url, request_object=req_options, parameters={"stream": True})) as server_response:
             yield from server_response.iter_content(1024)
 
     @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)
@@ -144,28 +288,76 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
             return self._get_view_excel(view_item, req_options)
 
         view_item._set_excel(excel_fetcher)
-        logger.info("Populated excel for view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated excel for view (ID: {view_item.id})")
 
     def _get_view_excel(self, view_item: ViewItem, req_options: Optional["ExcelRequestOptions"]) -> Iterator[bytes]:
-        url = "{0}/{1}/crosstab/excel".format(self.baseurl, view_item.id)
+        url = f"{self.baseurl}/{view_item.id}/crosstab/excel"
 
         with closing(self.get_request(url, request_object=req_options, parameters={"stream": True})) as server_response:
             yield from server_response.iter_content(1024)
 
     @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)
@@ -176,15 +368,65 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
         return view_item
 
     @api(version="1.0")
-    def add_tags(self, item: Union[ViewItem, str], tags: Union[Iterable[str], str]) -> Set[str]:
+    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/virtual_connections_endpoint.py

@@ -1,7 +1,8 @@
 from functools import partial
 import json
 from pathlib import Path
-from typing import Iterable, List, Optional, Set, TYPE_CHECKING, Tuple, Union
+from typing import Optional, TYPE_CHECKING, Union
+from collections.abc import Iterable
 
 from tableauserverclient.models.connection_item import ConnectionItem
 from tableauserverclient.models.pagination_item import PaginationItem
@@ -28,7 +29,7 @@ class VirtualConnections(QuerysetEndpoint[VirtualConnectionItem], TaggingMixin):
         return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/virtualConnections"
 
     @api(version="3.18")
-    def get(self, req_options: Optional[RequestOptions] = None) -> Tuple[List[VirtualConnectionItem], PaginationItem]:
+    def get(self, req_options: Optional[RequestOptions] = None) -> tuple[list[VirtualConnectionItem], PaginationItem]:
         server_response = self.get_request(self.baseurl, req_options)
         pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
         virtual_connections = VirtualConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
@@ -44,7 +45,7 @@ class VirtualConnections(QuerysetEndpoint[VirtualConnectionItem], TaggingMixin):
 
     def _get_virtual_database_connections(
         self, virtual_connection: VirtualConnectionItem, req_options: Optional[RequestOptions] = None
-    ) -> Tuple[List[ConnectionItem], PaginationItem]:
+    ) -> tuple[list[ConnectionItem], PaginationItem]:
         server_response = self.get_request(f"{self.baseurl}/{virtual_connection.id}/connections", req_options)
         connections = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
         pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
@@ -83,7 +84,7 @@ class VirtualConnections(QuerysetEndpoint[VirtualConnectionItem], TaggingMixin):
     @api(version="3.23")
     def get_revisions(
         self, virtual_connection: VirtualConnectionItem, req_options: Optional[RequestOptions] = None
-    ) -> Tuple[List[RevisionItem], PaginationItem]:
+    ) -> tuple[list[RevisionItem], PaginationItem]:
         server_response = self.get_request(f"{self.baseurl}/{virtual_connection.id}/revisions", req_options)
         pagination_item = PaginationItem.from_response(server_response.content, self.parent_srv.namespace)
         revisions = RevisionItem.from_response(server_response.content, self.parent_srv.namespace, virtual_connection)
@@ -159,7 +160,7 @@ class VirtualConnections(QuerysetEndpoint[VirtualConnectionItem], TaggingMixin):
     @api(version="3.23")
     def add_tags(
         self, virtual_connection: Union[VirtualConnectionItem, str], tags: Union[Iterable[str], str]
-    ) -> Set[str]:
+    ) -> set[str]:
         return super().add_tags(virtual_connection, tags)
 
     @api(version="3.23")

tableauserverclient/server/endpoint/webhooks_endpoint.py

@@ -6,7 +6,7 @@ from tableauserverclient.models import WebhookItem, PaginationItem
 
 from tableauserverclient.helpers.logging import logger
 
-from typing import List, Optional, TYPE_CHECKING, Tuple
+from typing import Optional, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from ..server import Server
@@ -15,14 +15,29 @@ if TYPE_CHECKING:
 
 class Webhooks(Endpoint):
     def __init__(self, parent_srv: "Server") -> None:
-        super(Webhooks, self).__init__(parent_srv)
+        super().__init__(parent_srv)
 
     @property
     def baseurl(self) -> str:
-        return "{0}/sites/{1}/webhooks".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/webhooks"
 
     @api(version="3.6")
-    def get(self, req_options: Optional["RequestOptions"] = None) -> Tuple[List[WebhookItem], PaginationItem]:
+    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,39 +47,101 @@ 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)
-        logger.info("Querying single webhook (ID: {0})".format(webhook_id))
-        url = "{0}/{1}".format(self.baseurl, webhook_id)
+        logger.info(f"Querying single webhook (ID: {webhook_id})")
+        url = f"{self.baseurl}/{webhook_id}"
         server_response = self.get_request(url)
         return WebhookItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     @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)
-        url = "{0}/{1}".format(self.baseurl, webhook_id)
+        url = f"{self.baseurl}/{webhook_id}"
         self.delete_request(url)
-        logger.info("Deleted single webhook (ID: {0})".format(webhook_id))
+        logger.info(f"Deleted single webhook (ID: {webhook_id})")
 
     @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)
         new_webhook = WebhookItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
-        logger.info("Created new webhook (ID: {0})".format(new_webhook.id))
+        logger.info(f"Created new webhook (ID: {new_webhook.id})")
         return new_webhook
 
     @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)
-        url = "{0}/{1}/test".format(self.baseurl, webhook_id)
+        url = f"{self.baseurl}/{webhook_id}/test"
         testOutcome = self.get_request(url)
-        logger.info("Testing webhook (ID: {0} returned {1})".format(webhook_id, testOutcome))
+        logger.info(f"Testing webhook (ID: {webhook_id} returned {testOutcome})")
         return testOutcome