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

tableauserverclient/server/endpoint/custom_views_endpoint.py

@@ -1,18 +1,29 @@
 import io
 import logging
 import os
+from contextlib import closing
 from pathlib import Path
-from typing import List, Optional, Tuple, Union
+from typing import Optional, Union, TYPE_CHECKING
+from collections.abc import Iterator
 
-from tableauserverclient.config import BYTES_PER_MB, FILESIZE_LIMIT_MB
+from tableauserverclient.config import BYTES_PER_MB, config
 from tableauserverclient.filesys_helpers import get_file_object_size
 from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
 from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
 from tableauserverclient.models import CustomViewItem, PaginationItem
-from tableauserverclient.server import RequestFactory, RequestOptions, ImageRequestOptions
+from tableauserverclient.server import (
+    RequestFactory,
+    RequestOptions,
+    ImageRequestOptions,
+    PDFRequestOptions,
+    CSVRequestOptions,
+)
 
 from tableauserverclient.helpers.logging import logger
 
+if TYPE_CHECKING:
+    from tableauserverclient.server.query import QuerySet
+
 """
 Get a list of custom views on a site
 get the details of a custom view
@@ -33,29 +44,41 @@ io_types_w = (io.BufferedWriter, io.BytesIO)
 
 class CustomViews(QuerysetEndpoint[CustomViewItem]):
     def __init__(self, parent_srv):
-        super(CustomViews, self).__init__(parent_srv)
+        super().__init__(parent_srv)
 
     @property
     def baseurl(self) -> str:
-        return "{0}/sites/{1}/customviews".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/customviews"
 
     @property
     def expurl(self) -> str:
         return f"{self.parent_srv._server_address}/api/exp/sites/{self.parent_srv.site_id}/customviews"
 
-    """
-    If the request has no filter parameters: Administrators will see all custom views. 
-        Other users will see only custom views that they own.
-    If the filter parameters include ownerId: Users will see only custom views that they own.
-    If the filter parameters include viewId and/or workbookId, and don't include ownerId:
-        Users will see those custom views that they have Write and WebAuthoring permissions for.
-    If site user visibility is not set to Limited, the Users will see those custom views that are "public",
-     meaning the value of their shared attribute is true.
-    If site user visibility is set to Limited, ????
-    """
-
     @api(version="3.18")
-    def get(self, req_options: Optional["RequestOptions"] = None) -> Tuple[List[CustomViewItem], PaginationItem]:
+    def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[CustomViewItem], PaginationItem]:
+        """
+        Get a list of custom views on a site.
+
+        If the request has no filter parameters: Administrators will see all custom views.
+            Other users will see only custom views that they own.
+        If the filter parameters include ownerId: Users will see only custom views that they own.
+        If the filter parameters include viewId and/or workbookId, and don't include ownerId:
+            Users will see those custom views that they have Write and WebAuthoring permissions for.
+        If site user visibility is not set to Limited, the Users will see those custom views that are "public",
+         meaning the value of their shared attribute is true.
+        If site user visibility is set to Limited, ????
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#list_custom_views
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Filtering options for the request, by default None
+
+        Returns
+        -------
+        tuple[list[CustomViewItem], PaginationItem]
+        """
         logger.info("Querying all custom views on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -65,16 +88,50 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
 
     @api(version="3.18")
     def get_by_id(self, view_id: str) -> Optional[CustomViewItem]:
+        """
+        Get the details of a specific custom view.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#get_custom_view
+
+        Parameters
+        ----------
+        view_id : str
+
+        Returns
+        -------
+        Optional[CustomViewItem]
+        """
         if not view_id:
             error = "Custom view item missing ID."
             raise MissingRequiredFieldError(error)
-        logger.info("Querying custom view (ID: {0})".format(view_id))
-        url = "{0}/{1}".format(self.baseurl, view_id)
+        logger.info(f"Querying custom view (ID: {view_id})")
+        url = f"{self.baseurl}/{view_id}"
         server_response = self.get_request(url)
         return CustomViewItem.from_response(server_response.content, self.parent_srv.namespace)
 
     @api(version="3.18")
     def populate_image(self, view_item: CustomViewItem, req_options: Optional["ImageRequestOptions"] = None) -> None:
+        """
+        Populate the image of a custom view.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#get_custom_view_image
+
+        Parameters
+        ----------
+        view_item : CustomViewItem
+
+        req_options : ImageRequestOptions, optional
+            Options to customize the image returned, by default None
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the view_item is missing an ID
+        """
         if not view_item.id:
             error = "Custom View item missing ID."
             raise MissingRequiredFieldError(error)
@@ -83,20 +140,111 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
             return self._get_view_image(view_item, req_options)
 
         view_item._set_image(image_fetcher)
-        logger.info("Populated image for custom view (ID: {0})".format(view_item.id))
+        logger.info(f"Populated image for custom view (ID: {view_item.id})")
 
     def _get_view_image(self, view_item: CustomViewItem, 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
 
-    """
-    Not yet implemented: pdf or csv exports
-    """
+    @api(version="3.23")
+    def populate_pdf(self, custom_view_item: CustomViewItem, req_options: Optional["PDFRequestOptions"] = None) -> None:
+        """
+        Populate the PDF of a custom view.
+
+        Parameters
+        ----------
+        custom_view_item : CustomViewItem
+            The custom view item to populate the PDF for.
+
+        req_options : PDFRequestOptions, optional
+            Options to customize the PDF returned, by default None
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the custom view item is missing an ID
+        """
+        if not custom_view_item.id:
+            error = "Custom View item missing ID."
+            raise MissingRequiredFieldError(error)
+
+        def pdf_fetcher():
+            return self._get_custom_view_pdf(custom_view_item, req_options)
+
+        custom_view_item._set_pdf(pdf_fetcher)
+        logger.info(f"Populated pdf for custom view (ID: {custom_view_item.id})")
+
+    def _get_custom_view_pdf(
+        self, custom_view_item: CustomViewItem, req_options: Optional["PDFRequestOptions"]
+    ) -> bytes:
+        url = f"{self.baseurl}/{custom_view_item.id}/pdf"
+        server_response = self.get_request(url, req_options)
+        pdf = server_response.content
+        return pdf
+
+    @api(version="3.23")
+    def populate_csv(self, custom_view_item: CustomViewItem, req_options: Optional["CSVRequestOptions"] = None) -> None:
+        """
+        Populate the CSV of a custom view.
+
+        Parameters
+        ----------
+        custom_view_item : CustomViewItem
+            The custom view item to populate the CSV for.
+
+        req_options : CSVRequestOptions, optional
+            Options to customize the CSV returned, by default None
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the custom view item is missing an ID
+        """
+        if not custom_view_item.id:
+            error = "Custom View item missing ID."
+            raise MissingRequiredFieldError(error)
+
+        def csv_fetcher():
+            return self._get_custom_view_csv(custom_view_item, req_options)
+
+        custom_view_item._set_csv(csv_fetcher)
+        logger.info(f"Populated csv for custom view (ID: {custom_view_item.id})")
+
+    def _get_custom_view_csv(
+        self, custom_view_item: CustomViewItem, req_options: Optional["CSVRequestOptions"]
+    ) -> Iterator[bytes]:
+        url = f"{self.baseurl}/{custom_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.18")
     def update(self, view_item: CustomViewItem) -> Optional[CustomViewItem]:
+        """
+        Updates the name, owner, or shared status of a custom view.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#update_custom_view
+
+        Parameters
+        ----------
+        view_item : CustomViewItem
+            The custom view item to update.
+
+        Returns
+        -------
+        Optional[CustomViewItem]
+            The updated custom view item.
+        """
         if not view_item.id:
             error = "Custom view item missing ID."
             raise MissingRequiredFieldError(error)
@@ -105,24 +253,64 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
             return view_item
 
         # Update the custom view owner or name
-        url = "{0}/{1}".format(self.baseurl, view_item.id)
+        url = f"{self.baseurl}/{view_item.id}"
         update_req = RequestFactory.CustomView.update_req(view_item)
         server_response = self.put_request(url, update_req)
-        logger.info("Updated custom view (ID: {0})".format(view_item.id))
+        logger.info(f"Updated custom view (ID: {view_item.id})")
         return CustomViewItem.from_response(server_response.content, self.parent_srv.namespace)
 
     # Delete 1 view by id
     @api(version="3.19")
     def delete(self, view_id: str) -> None:
+        """
+        Deletes a single custom view by ID.
+
+        Rest API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#delete_custom_view
+
+        Parameters
+        ----------
+        view_id : str
+            The ID of the custom view to delete.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the view_id is not provided.
+        """
         if not view_id:
             error = "Custom View ID undefined."
             raise ValueError(error)
-        url = "{0}/{1}".format(self.baseurl, view_id)
+        url = f"{self.baseurl}/{view_id}"
         self.delete_request(url)
-        logger.info("Deleted single custom view (ID: {0})".format(view_id))
+        logger.info(f"Deleted single custom view (ID: {view_id})")
 
     @api(version="3.21")
     def download(self, view_item: CustomViewItem, file: PathOrFileW) -> PathOrFileW:
+        """
+        Download the definition of a custom view as json. The file parameter can
+        be a file path or a file object. If a file path is provided, the file
+        will be written to that location. If a file object is provided, the file
+        will be written to that object.
+
+        May contain sensitive information.
+
+        Parameters
+        ----------
+        view_item : CustomViewItem
+            The custom view item to download.
+
+        file : PathOrFileW
+            The file path or file object to write the custom view to.
+
+        Returns
+        -------
+        PathOrFileW
+            The file path or file object that the custom view was written to.
+        """
         url = f"{self.expurl}/{view_item.id}/content"
         server_response = self.get_request(url)
         if isinstance(file, io_types_w):
@@ -136,6 +324,25 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
 
     @api(version="3.21")
     def publish(self, view_item: CustomViewItem, file: PathOrFileR) -> Optional[CustomViewItem]:
+        """
+        Publish a custom view to Tableau Server. The file parameter can be a
+        file path or a file object. If a file path is provided, the file will be
+        read from that location. If a file object is provided, the file will be
+        read from that object.
+
+        Parameters
+        ----------
+        view_item : CustomViewItem
+            The custom view item to publish.
+
+        file : PathOrFileR
+            The file path or file object to read the custom view from.
+
+        Returns
+        -------
+        Optional[CustomViewItem]
+            The published custom view item.
+        """
         url = self.expurl
         if isinstance(file, io_types_r):
             size = get_file_object_size(file)
@@ -144,7 +351,7 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
         else:
             raise ValueError("File path or file object required for publishing custom view.")
 
-        if size >= FILESIZE_LIMIT_MB * BYTES_PER_MB:
+        if size >= config.FILESIZE_LIMIT_MB * BYTES_PER_MB:
             upload_session_id = self.parent_srv.fileuploads.upload(file)
             url = f"{url}?uploadSessionId={upload_session_id}"
             xml_request, content_type = RequestFactory.CustomView.publish_req_chunked(view_item)
@@ -163,3 +370,25 @@ class CustomViews(QuerysetEndpoint[CustomViewItem]):
 
         server_response = self.post_request(url, xml_request, content_type)
         return CustomViewItem.from_response(server_response.content, self.parent_srv.namespace)
+
+    def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> "QuerySet[CustomViewItem]":
+        """
+        Queries the Tableau Server for items using the specified filters. Page
+        size can be specified to limit the number of items returned in a single
+        request. If not specified, the default page size is 100. Page size can
+        be an integer between 1 and 1000.
+
+        No positional arguments are allowed. All filters must be specified as
+        keyword arguments. If you use the equality operator, you can specify it
+        through <field_name>=<value>. If you want to use a different operator,
+        you can specify it through <field_name>__<operator>=<value>. Field
+        names can either be in snake_case or camelCase.
+
+        This endpoint supports the following fields and operators:
+
+        view_id=...
+        workbook_id=...
+        owner_id=...
+        """
+
+        return super().filter(*invalid, page_size=page_size, **kwargs)

tableauserverclient/server/endpoint/data_acceleration_report_endpoint.py

@@ -10,14 +10,14 @@ from tableauserverclient.helpers.logging import logger
 
 class DataAccelerationReport(Endpoint):
     def __init__(self, parent_srv):
-        super(DataAccelerationReport, self).__init__(parent_srv)
+        super().__init__(parent_srv)
 
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
         self._default_permissions = _DefaultPermissionsEndpoint(parent_srv, lambda: self.baseurl)
 
     @property
     def baseurl(self):
-        return "{0}/sites/{1}/dataAccelerationReport".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/dataAccelerationReport"
 
     @api(version="3.8")
     def get(self, req_options=None):

tableauserverclient/server/endpoint/data_alert_endpoint.py

@@ -7,7 +7,7 @@ from tableauserverclient.models import DataAlertItem, PaginationItem, UserItem
 
 from tableauserverclient.helpers.logging import logger
 
-from typing import List, Optional, TYPE_CHECKING, Tuple, Union
+from typing import Optional, TYPE_CHECKING, Union
 
 
 if TYPE_CHECKING:
@@ -17,14 +17,14 @@ if TYPE_CHECKING:
 
 class DataAlerts(Endpoint):
     def __init__(self, parent_srv: "Server") -> None:
-        super(DataAlerts, self).__init__(parent_srv)
+        super().__init__(parent_srv)
 
     @property
     def baseurl(self) -> str:
-        return "{0}/sites/{1}/dataAlerts".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/dataAlerts"
 
     @api(version="3.2")
-    def get(self, req_options: Optional["RequestOptions"] = None) -> Tuple[List[DataAlertItem], PaginationItem]:
+    def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[DataAlertItem], PaginationItem]:
         logger.info("Querying all dataAlerts on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -38,8 +38,8 @@ class DataAlerts(Endpoint):
         if not dataAlert_id:
             error = "dataAlert ID undefined."
             raise ValueError(error)
-        logger.info("Querying single dataAlert (ID: {0})".format(dataAlert_id))
-        url = "{0}/{1}".format(self.baseurl, dataAlert_id)
+        logger.info(f"Querying single dataAlert (ID: {dataAlert_id})")
+        url = f"{self.baseurl}/{dataAlert_id}"
         server_response = self.get_request(url)
         return DataAlertItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
@@ -55,9 +55,9 @@ class DataAlerts(Endpoint):
             error = "Dataalert ID undefined."
             raise ValueError(error)
         # DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id/users/user-id
-        url = "{0}/{1}".format(self.baseurl, dataAlert_id)
+        url = f"{self.baseurl}/{dataAlert_id}"
         self.delete_request(url)
-        logger.info("Deleted single dataAlert (ID: {0})".format(dataAlert_id))
+        logger.info(f"Deleted single dataAlert (ID: {dataAlert_id})")
 
     @api(version="3.2")
     def delete_user_from_alert(self, dataAlert: Union[DataAlertItem, str], user: Union[UserItem, str]) -> None:
@@ -80,9 +80,9 @@ class DataAlerts(Endpoint):
             error = "User ID undefined."
             raise ValueError(error)
         # DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id/users/user-id
-        url = "{0}/{1}/users/{2}".format(self.baseurl, dataAlert_id, user_id)
+        url = f"{self.baseurl}/{dataAlert_id}/users/{user_id}"
         self.delete_request(url)
-        logger.info("Deleted User (ID {0}) from dataAlert (ID: {1})".format(user_id, dataAlert_id))
+        logger.info(f"Deleted User (ID {user_id}) from dataAlert (ID: {dataAlert_id})")
 
     @api(version="3.2")
     def add_user_to_alert(self, dataAlert_item: DataAlertItem, user: Union[UserItem, str]) -> UserItem:
@@ -98,10 +98,10 @@ class DataAlerts(Endpoint):
         if not user_id:
             error = "User ID undefined."
             raise ValueError(error)
-        url = "{0}/{1}/users".format(self.baseurl, dataAlert_item.id)
+        url = f"{self.baseurl}/{dataAlert_item.id}/users"
         update_req = RequestFactory.DataAlert.add_user_to_alert(dataAlert_item, user_id)
         server_response = self.post_request(url, update_req)
-        logger.info("Added user (ID {0}) to dataAlert item (ID: {1})".format(user_id, dataAlert_item.id))
+        logger.info(f"Added user (ID {user_id}) to dataAlert item (ID: {dataAlert_item.id})")
         added_user = UserItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return added_user
 
@@ -111,9 +111,9 @@ class DataAlerts(Endpoint):
             error = "Dataalert item missing ID."
             raise MissingRequiredFieldError(error)
 
-        url = "{0}/{1}".format(self.baseurl, dataAlert_item.id)
+        url = f"{self.baseurl}/{dataAlert_item.id}"
         update_req = RequestFactory.DataAlert.update_req(dataAlert_item)
         server_response = self.put_request(url, update_req)
-        logger.info("Updated dataAlert item (ID: {0})".format(dataAlert_item.id))
+        logger.info(f"Updated dataAlert item (ID: {dataAlert_item.id})")
         updated_dataAlert = DataAlertItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return updated_dataAlert

tableauserverclient/server/endpoint/databases_endpoint.py

@@ -1,5 +1,6 @@
 import logging
-from typing import Union, Iterable, Set
+from typing import Union
+from collections.abc import Iterable
 
 from tableauserverclient.server.endpoint.default_permissions_endpoint import _DefaultPermissionsEndpoint
 from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
@@ -15,7 +16,7 @@ from tableauserverclient.helpers.logging import logger
 
 class Databases(Endpoint, TaggingMixin):
     def __init__(self, parent_srv):
-        super(Databases, self).__init__(parent_srv)
+        super().__init__(parent_srv)
 
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
         self._default_permissions = _DefaultPermissionsEndpoint(parent_srv, lambda: self.baseurl)
@@ -23,7 +24,7 @@ class Databases(Endpoint, TaggingMixin):
 
     @property
     def baseurl(self):
-        return "{0}/sites/{1}/databases".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/databases"
 
     @api(version="3.5")
     def get(self, req_options=None):
@@ -40,8 +41,8 @@ class Databases(Endpoint, TaggingMixin):
         if not database_id:
             error = "database ID undefined."
             raise ValueError(error)
-        logger.info("Querying single database (ID: {0})".format(database_id))
-        url = "{0}/{1}".format(self.baseurl, database_id)
+        logger.info(f"Querying single database (ID: {database_id})")
+        url = f"{self.baseurl}/{database_id}"
         server_response = self.get_request(url)
         return DatabaseItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
@@ -50,9 +51,9 @@ class Databases(Endpoint, TaggingMixin):
         if not database_id:
             error = "Database ID undefined."
             raise ValueError(error)
-        url = "{0}/{1}".format(self.baseurl, database_id)
+        url = f"{self.baseurl}/{database_id}"
         self.delete_request(url)
-        logger.info("Deleted single database (ID: {0})".format(database_id))
+        logger.info(f"Deleted single database (ID: {database_id})")
 
     @api(version="3.5")
     def update(self, database_item):
@@ -60,10 +61,10 @@ class Databases(Endpoint, TaggingMixin):
             error = "Database item missing ID."
             raise MissingRequiredFieldError(error)
 
-        url = "{0}/{1}".format(self.baseurl, database_item.id)
+        url = f"{self.baseurl}/{database_item.id}"
         update_req = RequestFactory.Database.update_req(database_item)
         server_response = self.put_request(url, update_req)
-        logger.info("Updated database item (ID: {0})".format(database_item.id))
+        logger.info(f"Updated database item (ID: {database_item.id})")
         updated_database = DatabaseItem.from_response(server_response.content, self.parent_srv.namespace)[0]
         return updated_database
 
@@ -78,10 +79,10 @@ class Databases(Endpoint, TaggingMixin):
             return self._get_tables_for_database(database_item)
 
         database_item._set_tables(column_fetcher)
-        logger.info("Populated tables for database (ID: {0}".format(database_item.id))
+        logger.info(f"Populated tables for database (ID: {database_item.id}")
 
     def _get_tables_for_database(self, database_item):
-        url = "{0}/{1}/tables".format(self.baseurl, database_item.id)
+        url = f"{self.baseurl}/{database_item.id}/tables"
         server_response = self.get_request(url)
         tables = TableItem.from_response(server_response.content, self.parent_srv.namespace)
         return tables
@@ -127,7 +128,7 @@ class Databases(Endpoint, TaggingMixin):
         self._data_quality_warnings.clear(item)
 
     @api(version="3.9")
-    def add_tags(self, item: Union[DatabaseItem, str], tags: Iterable[str]) -> Set[str]:
+    def add_tags(self, item: Union[DatabaseItem, str], tags: Iterable[str]) -> set[str]:
         return super().add_tags(item, tags)
 
     @api(version="3.9")