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

tableauserverclient/server/endpoint/projects_endpoint.py

@@ -20,6 +20,11 @@ from tableauserverclient.helpers.logging import logger
 
 
 class Projects(QuerysetEndpoint[ProjectItem]):
+    """
+    The project methods are based upon the endpoints for projects in the REST
+    API and operate on the ProjectItem class.
+    """
+
     def __init__(self, parent_srv: "Server") -> None:
         super().__init__(parent_srv)
 
@@ -32,6 +37,23 @@ class Projects(QuerysetEndpoint[ProjectItem]):
 
     @api(version="2.0")
     def get(self, req_options: Optional["RequestOptions"] = None) -> tuple[list[ProjectItem], PaginationItem]:
+        """
+        Retrieves all projects on the site. The endpoint is paginated and can
+        be filtered using the req_options parameter.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#query_projects
+
+        Parameters
+        ----------
+        req_options : RequestOptions | None, default None
+            The request options to filter the projects. The default is None.
+
+        Returns
+        -------
+        tuple[list[ProjectItem], PaginationItem]
+            Returns a tuple containing a list of ProjectItem objects and a
+            PaginationItem object.
+        """
         logger.info("Querying all projects on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -41,6 +63,25 @@ class Projects(QuerysetEndpoint[ProjectItem]):
 
     @api(version="2.0")
     def delete(self, project_id: str) -> None:
+        """
+        Deletes a single project on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#delete_project
+
+        Parameters
+        ----------
+        project_id : str
+            The unique identifier for the project.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the project ID is not defined, an error is raised.
+        """
         if not project_id:
             error = "Project ID undefined."
             raise ValueError(error)
@@ -50,6 +91,36 @@ class Projects(QuerysetEndpoint[ProjectItem]):
 
     @api(version="2.0")
     def update(self, project_item: ProjectItem, samples: bool = False) -> ProjectItem:
+        """
+        Modify the project settings.
+
+        You can use this method to update the project name, the project
+        description, or the project permissions. To specify the site, create a
+        TableauAuth instance using the content URL for the site (site_id), and
+        sign in to that site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#update_project
+
+        Parameters
+        ----------
+        project_item : ProjectItem
+            The project item object must include the project ID. The values in
+            the project item override the current project settings.
+
+        samples : bool
+            Set to True to include sample workbooks and data sources in the
+            project. The default is False.
+
+        Returns
+        -------
+        ProjectItem
+            Returns the updated project item.
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the project item is missing the ID, an error is raised.
+        """
         if not project_item.id:
             error = "Project item missing ID."
             raise MissingRequiredFieldError(error)
@@ -64,6 +135,32 @@ class Projects(QuerysetEndpoint[ProjectItem]):
 
     @api(version="2.0")
     def create(self, project_item: ProjectItem, samples: bool = False) -> ProjectItem:
+        """
+        Creates a project on the specified site.
+
+        To create a project, you first create a new instance of a ProjectItem
+        and pass it to the create method. To specify the site to create the new
+        project, create a TableauAuth instance using the content URL for the
+        site (site_id), and sign in to that site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_projects.htm#create_project
+
+        Parameters
+        ----------
+        project_item : ProjectItem
+            Specifies the properties for the project. The project_item is the
+            request package. To create the request package, create a new
+            instance of ProjectItem.
+
+        samples : bool
+            Set to True to include sample workbooks and data sources in the
+            project. The default is False.
+
+        Returns
+        -------
+        ProjectItem
+            Returns the new project item.
+        """
         params = {"params": {RequestOptions.Field.PublishSamples: samples}}
         url = self.baseurl
         if project_item._samples:
@@ -76,136 +173,639 @@ class Projects(QuerysetEndpoint[ProjectItem]):
 
     @api(version="2.0")
     def populate_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the project permissions, parses and stores the returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_project_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with permissions.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.populate(item)
 
     @api(version="2.0")
     def update_permissions(self, item: ProjectItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
+        """
+        Updates the permissions for the specified project item. The rules
+        provided are expected to be a complete list of the permissions for the
+        project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
+
         return self._permissions.update(item, rules)
 
     @api(version="2.0")
     def delete_permission(self, item: ProjectItem, rules: list[PermissionsRule]) -> None:
+        """
+        Deletes the specified permissions from the project item.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_project_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete permissions from.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._permissions.delete(item, rules)
 
     @api(version="2.1")
     def populate_workbook_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default workbook permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default workbook permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Workbook)
 
     @api(version="2.1")
     def populate_datasource_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default datasource permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default datasource permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Datasource)
 
     @api(version="3.2")
     def populate_metric_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default metric permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default metric permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Metric)
 
     @api(version="3.4")
     def populate_datarole_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default datarole permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default datarole permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Datarole)
 
     @api(version="3.4")
     def populate_flow_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default flow permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default flow permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Flow)
 
     @api(version="3.4")
     def populate_lens_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default lens permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default lens permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Lens)
 
     @api(version="3.23")
     def populate_virtualconnection_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default virtualconnections permissions, parses and stores
+        the returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default virtual connection
+            permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.VirtualConnection)
 
     @api(version="3.23")
     def populate_database_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default database permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default database permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Database)
 
     @api(version="3.23")
     def populate_table_default_permissions(self, item: ProjectItem) -> None:
+        """
+        Queries the default table permissions, parses and stores the
+        returned the permissions.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#query_default_permissions
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to populate with default table permissions.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.populate_default_permissions(item, Resource.Table)
 
     @api(version="2.1")
     def update_workbook_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default workbook permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default workbook permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Workbook)
 
     @api(version="2.1")
     def update_datasource_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default datasource permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default datasource permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Datasource)
 
     @api(version="3.2")
     def update_metric_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default metric permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default metric permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Metric)
 
     @api(version="3.4")
     def update_datarole_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default datarole permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default datarole permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Datarole)
 
     @api(version="3.4")
     def update_flow_default_permissions(self, item: ProjectItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
+        """
+        Add or updates the default flow permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default flow permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Flow)
 
     @api(version="3.4")
     def update_lens_default_permissions(self, item: ProjectItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
+        """
+        Add or updates the default lens permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default lens permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Lens)
 
     @api(version="3.23")
     def update_virtualconnection_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default virtualconnection permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default virtualconnection permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.VirtualConnection)
 
     @api(version="3.23")
     def update_database_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default database permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default database permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Database)
 
     @api(version="3.23")
     def update_table_default_permissions(
         self, item: ProjectItem, rules: list[PermissionsRule]
     ) -> list[PermissionsRule]:
+        """
+        Add or updates the default table permissions for the specified.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#replace_default_permissions_for_content
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to update default table permissions for.
+
+        rules : list[PermissionsRule]
+            The list of permissions rules to update the project with.
+
+        Returns
+        -------
+        list[PermissionsRule]
+            Returns the updated list of permissions rules.
+        """
         return self._default_permissions.update_default_permissions(item, rules, Resource.Table)
 
     @api(version="2.1")
     def delete_workbook_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default workbook permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Workbook)
 
     @api(version="2.1")
     def delete_datasource_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default datasource permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Datasource)
 
     @api(version="3.2")
     def delete_metric_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default workbook permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Metric)
 
     @api(version="3.4")
     def delete_datarole_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default datarole permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Datarole)
 
     @api(version="3.4")
     def delete_flow_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default flow permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Flow)
 
     @api(version="3.4")
     def delete_lens_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default lens permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Lens)
 
     @api(version="3.23")
     def delete_virtualconnection_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default virtualconnection permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.VirtualConnection)
 
     @api(version="3.23")
     def delete_database_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default database permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Database)
 
     @api(version="3.23")
     def delete_table_default_permissions(self, item: ProjectItem, rule: PermissionsRule) -> None:
+        """
+        Deletes the specified default permission rule from the project.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_permissions.htm#delete_default_permission
+
+        Parameters
+        ----------
+        item : ProjectItem
+            The project item to delete default table permissions from.
+
+        rule : PermissionsRule
+            The permissions rule to delete from the project.
+
+        Returns
+        -------
+        None
+        """
         self._default_permissions.delete_default_permission(item, rule, Resource.Table)
 
     def filter(self, *invalid, page_size: Optional[int] = None, **kwargs) -> QuerySet[ProjectItem]: