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

tableauserverclient/server/endpoint/flows_endpoint.py

@@ -5,7 +5,8 @@ import logging
 import os
 from contextlib import closing
 from pathlib import Path
-from typing import Iterable, List, Optional, TYPE_CHECKING, Tuple, Union
+from typing import Optional, TYPE_CHECKING, Union
+from collections.abc import Iterable
 
 from tableauserverclient.helpers.headers import fix_filename
 
@@ -53,18 +54,37 @@ PathOrFileW = Union[FilePath, FileObjectW]
 
 class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
     def __init__(self, parent_srv):
-        super(Flows, self).__init__(parent_srv)
+        super().__init__(parent_srv)
         self._resource_tagger = _ResourceTagger(parent_srv)
         self._permissions = _PermissionsEndpoint(parent_srv, lambda: self.baseurl)
         self._data_quality_warnings = _DataQualityWarningEndpoint(self.parent_srv, "flow")
 
     @property
     def baseurl(self) -> str:
-        return "{0}/sites/{1}/flows".format(self.parent_srv.baseurl, self.parent_srv.site_id)
+        return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/flows"
 
     # Get all flows
     @api(version="3.3")
-    def get(self, req_options: Optional["RequestOptions"] = None) -> Tuple[List[FlowItem], PaginationItem]:
+    def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[FlowItem], PaginationItem]:
+        """
+        Get all flows on site. Returns a tuple of all flow items and pagination item.
+        This method is paginated, and returns one page of items per call. The
+        request options can be used to specify the page number, page size, as
+        well as sorting and filtering options.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flows_for_site
+
+        Parameters
+        ----------
+        req_options: Optional[RequestOptions]
+            An optional Request Options object that can be used to specify
+            sorting, filtering, and pagination options.
+
+        Returns
+        -------
+        tuple[list[FlowItem], PaginationItem]
+            A tuple of a list of flow items and a pagination item.
+        """
         logger.info("Querying all flows on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -75,17 +95,53 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
     # Get 1 flow by id
     @api(version="3.3")
     def get_by_id(self, flow_id: str) -> FlowItem:
+        """
+        Get a single flow by id.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow
+
+        Parameters
+        ----------
+        flow_id: str
+            The id of the flow to retrieve.
+
+        Returns
+        -------
+        FlowItem
+            The flow item that was retrieved.
+        """
         if not flow_id:
             error = "Flow ID undefined."
             raise ValueError(error)
-        logger.info("Querying single flow (ID: {0})".format(flow_id))
-        url = "{0}/{1}".format(self.baseurl, flow_id)
+        logger.info(f"Querying single flow (ID: {flow_id})")
+        url = f"{self.baseurl}/{flow_id}"
         server_response = self.get_request(url)
         return FlowItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     # Populate flow item's connections
     @api(version="3.3")
     def populate_connections(self, flow_item: FlowItem) -> None:
+        """
+        Populate the connections for a flow item. This method will make a
+        request to the Tableau Server to get the connections associated with
+        the flow item and populate the connections property of the flow item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow_connections
+
+        Parameters
+        ----------
+        flow_item: FlowItem
+            The flow item to populate connections for.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the flow item does not have an ID.
+        """
         if not flow_item.id:
             error = "Flow item missing ID. Flow must be retrieved from server first."
             raise MissingRequiredFieldError(error)
@@ -94,10 +150,10 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
             return self._get_flow_connections(flow_item)
 
         flow_item._set_connections(connections_fetcher)
-        logger.info("Populated connections for flow (ID: {0})".format(flow_item.id))
+        logger.info(f"Populated connections for flow (ID: {flow_item.id})")
 
-    def _get_flow_connections(self, flow_item, req_options: Optional["RequestOptions"] = None) -> List[ConnectionItem]:
-        url = "{0}/{1}/connections".format(self.baseurl, flow_item.id)
+    def _get_flow_connections(self, flow_item, req_options: Optional["RequestOptions"] = None) -> list[ConnectionItem]:
+        url = f"{self.baseurl}/{flow_item.id}/connections"
         server_response = self.get_request(url, req_options)
         connections = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
         return connections
@@ -105,20 +161,68 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
     # Delete 1 flow by id
     @api(version="3.3")
     def delete(self, flow_id: str) -> None:
+        """
+        Delete a single flow by id.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#delete_flow
+
+        Parameters
+        ----------
+        flow_id: str
+            The id of the flow to delete.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the flow_id is not defined.
+        """
         if not flow_id:
             error = "Flow ID undefined."
             raise ValueError(error)
-        url = "{0}/{1}".format(self.baseurl, flow_id)
+        url = f"{self.baseurl}/{flow_id}"
         self.delete_request(url)
-        logger.info("Deleted single flow (ID: {0})".format(flow_id))
+        logger.info(f"Deleted single flow (ID: {flow_id})")
 
     # Download 1 flow by id
     @api(version="3.3")
     def download(self, flow_id: str, filepath: Optional[PathOrFileW] = None) -> PathOrFileW:
+        """
+        Download a single flow by id. The flow will be downloaded to the
+        specified file path. If no file path is specified, the flow will be
+        downloaded to the current working directory.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#download_flow
+
+        Parameters
+        ----------
+        flow_id: str
+            The id of the flow to download.
+
+        filepath: Optional[PathOrFileW]
+            The file path to download the flow to. This can be a file path or
+            a file object. If a file object is passed, the flow will be written
+            to the file object. If a file path is passed, the flow will be
+            written to the file path. If no file path is specified, the flow
+            will be downloaded to the current working directory.
+
+        Returns
+        -------
+        PathOrFileW
+            The file path or file object that the flow was downloaded to.
+
+        Raises
+        ------
+        ValueError
+            If the flow_id is not defined.
+        """
         if not flow_id:
             error = "Flow ID undefined."
             raise ValueError(error)
-        url = "{0}/{1}/content".format(self.baseurl, flow_id)
+        url = f"{self.baseurl}/{flow_id}/content"
 
         with closing(self.get_request(url, parameters={"stream": True})) as server_response:
             m = Message()
@@ -137,12 +241,27 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
                         f.write(chunk)
                 return_path = os.path.abspath(download_path)
 
-        logger.info("Downloaded flow to {0} (ID: {1})".format(return_path, flow_id))
+        logger.info(f"Downloaded flow to {return_path} (ID: {flow_id})")
         return return_path
 
     # Update flow
     @api(version="3.3")
     def update(self, flow_item: FlowItem) -> FlowItem:
+        """
+        Updates the flow owner, project, description, and/or tags.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow
+
+        Parameters
+        ----------
+        flow_item: FlowItem
+            The flow item to update.
+
+        Returns
+        -------
+        FlowItem
+            The updated flow item.
+        """
         if not flow_item.id:
             error = "Flow item missing ID. Flow must be retrieved from server first."
             raise MissingRequiredFieldError(error)
@@ -150,28 +269,62 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
         self._resource_tagger.update_tags(self.baseurl, flow_item)
 
         # Update the flow itself
-        url = "{0}/{1}".format(self.baseurl, flow_item.id)
+        url = f"{self.baseurl}/{flow_item.id}"
         update_req = RequestFactory.Flow.update_req(flow_item)
         server_response = self.put_request(url, update_req)
-        logger.info("Updated flow item (ID: {0})".format(flow_item.id))
+        logger.info(f"Updated flow item (ID: {flow_item.id})")
         updated_flow = copy.copy(flow_item)
         return updated_flow._parse_common_elements(server_response.content, self.parent_srv.namespace)
 
     # Update flow connections
     @api(version="3.3")
     def update_connection(self, flow_item: FlowItem, connection_item: ConnectionItem) -> ConnectionItem:
-        url = "{0}/{1}/connections/{2}".format(self.baseurl, flow_item.id, connection_item.id)
+        """
+        Update a connection item for a flow item. This method will update the
+        connection details for the connection item associated with the flow.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow_connection
+
+        Parameters
+        ----------
+        flow_item: FlowItem
+            The flow item that the connection is associated with.
+
+        connection_item: ConnectionItem
+            The connection item to update.
+
+        Returns
+        -------
+        ConnectionItem
+            The updated connection item.
+        """
+        url = f"{self.baseurl}/{flow_item.id}/connections/{connection_item.id}"
 
         update_req = RequestFactory.Connection.update_req(connection_item)
         server_response = self.put_request(url, update_req)
         connection = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
-        logger.info("Updated flow item (ID: {0} & connection item {1}".format(flow_item.id, connection_item.id))
+        logger.info(f"Updated flow item (ID: {flow_item.id} & connection item {connection_item.id}")
         return connection
 
     @api(version="3.3")
     def refresh(self, flow_item: FlowItem) -> JobItem:
-        url = "{0}/{1}/run".format(self.baseurl, flow_item.id)
+        """
+        Runs the flow to refresh the data.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#run_flow_now
+
+        Parameters
+        ----------
+        flow_item: FlowItem
+            The flow item to refresh.
+
+        Returns
+        -------
+        JobItem
+            The job item that was created to refresh the flow.
+        """
+        url = f"{self.baseurl}/{flow_item.id}/run"
         empty_req = RequestFactory.Empty.empty_req()
         server_response = self.post_request(url, empty_req)
         new_job = JobItem.from_response(server_response.content, self.parent_srv.namespace)[0]
@@ -180,8 +333,37 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
     # Publish flow
     @api(version="3.3")
     def publish(
-        self, flow_item: FlowItem, file: PathOrFileR, mode: str, connections: Optional[List[ConnectionItem]] = None
+        self, flow_item: FlowItem, file: PathOrFileR, mode: str, connections: Optional[list[ConnectionItem]] = None
     ) -> FlowItem:
+        """
+        Publishes a flow to the Tableau Server.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#publish_flow
+
+        Parameters
+        ----------
+        flow_item: FlowItem
+            The flow item to publish. This item must have a project_id and name
+            defined.
+
+        file: PathOrFileR
+            The file path or file object to publish. This can be a .tfl or .tflx
+
+        mode: str
+            The publish mode. This can be "Overwrite" or "CreatNew". If the
+            mode is "Overwrite", the flow will be overwritten if it already
+            exists. If the mode is "CreateNew", a new flow will be created with
+            the same name as the flow item.
+
+        connections: Optional[list[ConnectionItem]]
+            A list of connection items to publish with the flow. If the flow
+            contains connections, they must be included in this list.
+
+        Returns
+        -------
+        FlowItem
+            The flow item that was published.
+        """
         if not mode or not hasattr(self.parent_srv.PublishMode, mode):
             error = "Invalid mode defined."
             raise ValueError(error)
@@ -189,7 +371,7 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
         if isinstance(file, (str, os.PathLike)):
             if not os.path.isfile(file):
                 error = "File path does not lead to an existing file."
-                raise IOError(error)
+                raise OSError(error)
 
             filename = os.path.basename(file)
             file_extension = os.path.splitext(filename)[1][1:]
@@ -213,30 +395,30 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
             elif file_type == "xml":
                 file_extension = "tfl"
             else:
-                error = "Unsupported file type {}!".format(file_type)
+                error = f"Unsupported file type {file_type}!"
                 raise ValueError(error)
 
             # Generate filename for file object.
             # This is needed when publishing the flow in a single request
-            filename = "{}.{}".format(flow_item.name, file_extension)
+            filename = f"{flow_item.name}.{file_extension}"
             file_size = get_file_object_size(file)
 
         else:
             raise TypeError("file should be a filepath or file object.")
 
         # Construct the url with the defined mode
-        url = "{0}?flowType={1}".format(self.baseurl, file_extension)
+        url = f"{self.baseurl}?flowType={file_extension}"
         if mode == self.parent_srv.PublishMode.Overwrite or mode == self.parent_srv.PublishMode.Append:
-            url += "&{0}=true".format(mode.lower())
+            url += f"&{mode.lower()}=true"
 
         # Determine if chunking is required (64MB is the limit for single upload method)
         if file_size >= FILESIZE_LIMIT:
-            logger.info("Publishing {0} to server with chunking method (flow over 64MB)".format(filename))
+            logger.info(f"Publishing {filename} to server with chunking method (flow over 64MB)")
             upload_session_id = self.parent_srv.fileuploads.upload(file)
-            url = "{0}&uploadSessionId={1}".format(url, upload_session_id)
+            url = f"{url}&uploadSessionId={upload_session_id}"
             xml_request, content_type = RequestFactory.Flow.publish_req_chunked(flow_item, connections)
         else:
-            logger.info("Publishing {0} to server".format(filename))
+            logger.info(f"Publishing {filename} to server")
 
             if isinstance(file, (str, Path)):
                 with open(file, "rb") as f:
@@ -259,42 +441,175 @@ class Flows(QuerysetEndpoint[FlowItem], TaggingMixin[FlowItem]):
             raise err
         else:
             new_flow = FlowItem.from_response(server_response.content, self.parent_srv.namespace)[0]
-            logger.info("Published {0} (ID: {1})".format(filename, new_flow.id))
+            logger.info(f"Published {filename} (ID: {new_flow.id})")
             return new_flow
 
     @api(version="3.3")
     def populate_permissions(self, item: FlowItem) -> None:
+        """
+        Populate the permissions for a flow item. This method will make a
+        request to the Tableau Server to get the permissions associated with
+        the flow item and populate the permissions property of the flow item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#query_flow_permissions
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to populate permissions for.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.populate(item)
 
     @api(version="3.3")
     def update_permissions(self, item: FlowItem, permission_item: Iterable["PermissionsRule"]) -> None:
+        """
+        Update the permissions for a flow item. This method will update the
+        permissions for the flow item. The permissions must be a list of
+        permissions rules. Will overwrite all existing permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_permissions_for_content
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to update permissions for.
+
+        permission_item: Iterable[PermissionsRule]
+            The permissions rules to update.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.update(item, permission_item)
 
     @api(version="3.3")
     def delete_permission(self, item: FlowItem, capability_item: "PermissionsRule") -> None:
+        """
+        Delete a permission for a flow item. This method will delete only the
+        specified permission for the flow item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#delete_flow_permission
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to delete the permission from.
+
+        capability_item: PermissionsRule
+            The permission to delete.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.delete(item, capability_item)
 
     @api(version="3.5")
     def populate_dqw(self, item: FlowItem) -> None:
+        """
+        Get information about Data Quality Warnings for a flow item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_dqws
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to populate data quality warnings for.
+
+        Returns
+        -------
+        None
+        """
         self._data_quality_warnings.populate(item)
 
     @api(version="3.5")
     def update_dqw(self, item: FlowItem, warning: "DQWItem") -> None:
+        """
+        Update the warning type, status, and message of a data quality warning
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_dqw
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to update data quality warnings for.
+
+        warning: DQWItem
+            The data quality warning to update.
+
+        Returns
+        -------
+        None
+        """
         return self._data_quality_warnings.update(item, warning)
 
     @api(version="3.5")
     def add_dqw(self, item: FlowItem, warning: "DQWItem") -> None:
+        """
+        Add a data quality warning to a flow.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#add_dqw
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to add data quality warnings to.
+
+        warning: DQWItem
+            The data quality warning to add.
+
+        Returns
+        -------
+        None
+        """
         return self._data_quality_warnings.add(item, warning)
 
     @api(version="3.5")
     def delete_dqw(self, item: FlowItem) -> None:
+        """
+        Delete all data quality warnings for a flow.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_dqws
+
+        Parameters
+        ----------
+        item: FlowItem
+            The flow item to delete data quality warnings from.
+
+        Returns
+        -------
+        None
+        """
         self._data_quality_warnings.clear(item)
 
     # a convenience method
     @api(version="3.3")
     def schedule_flow_run(
         self, schedule_id: str, item: FlowItem
-    ) -> List["AddResponse"]:  # actually should return a task
+    ) -> list["AddResponse"]:  # actually should return a task
+        """
+        Schedule a flow to run on an existing schedule.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#add_flow_task_to_schedule
+
+        Parameters
+        ----------
+        schedule_id: str
+            The id of the schedule to add the flow to.
+
+        item: FlowItem
+            The flow item to add to the schedule.
+
+        Returns
+        -------
+        list[AddResponse]
+            The response from the server.
+        """
         return self.parent_srv.schedules.add_to_schedule(schedule_id, flow=item)
 
     def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[FlowItem]: