tableauserverclient 0.37__py3-none-any.whl → 0.39__py3-none-any.whl

{tableauserverclient/server → server}/endpoint/tables_endpoint.py

@@ -1,7 +1,8 @@
 import logging
-from typing import Union
+from typing import Optional, Union, TYPE_CHECKING
 from collections.abc import Iterable
 
+from tableauserverclient.models.permissions_item import PermissionsRule
 from tableauserverclient.server.endpoint.dqw_endpoint import _DataQualityWarningEndpoint
 from tableauserverclient.server.endpoint.endpoint import api, Endpoint
 from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError
@@ -12,6 +13,10 @@ from tableauserverclient.models import TableItem, ColumnItem, PaginationItem
 from tableauserverclient.server.pager import Pager
 
 from tableauserverclient.helpers.logging import logger
+from tableauserverclient.server.request_options import RequestOptions
+
+if TYPE_CHECKING:
+    from tableauserverclient.models import DQWItem, PermissionsRule
 
 
 class Tables(Endpoint, TaggingMixin[TableItem]):
@@ -22,11 +27,29 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         self._data_quality_warnings = _DataQualityWarningEndpoint(self.parent_srv, "table")
 
     @property
-    def baseurl(self):
+    def baseurl(self) -> str:
         return f"{self.parent_srv.baseurl}/sites/{self.parent_srv.site_id}/tables"
 
     @api(version="3.5")
-    def get(self, req_options=None):
+    def get(self, req_options: Optional[RequestOptions] = None) -> tuple[list[TableItem], PaginationItem]:
+        """
+        Get information about all tables on the site. Endpoint is paginated, and
+        will return a default of 100 items per page. Use the `req_options`
+        parameter to customize the request.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_tables
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Options to customize the request. If not provided, defaults to None.
+
+        Returns
+        -------
+        tuple[list[TableItem], PaginationItem]
+            A tuple containing a list of TableItem objects and a PaginationItem
+            object.
+        """
         logger.info("Querying all tables on site")
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -36,7 +59,27 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
 
     # Get 1 table
     @api(version="3.5")
-    def get_by_id(self, table_id):
+    def get_by_id(self, table_id: str) -> TableItem:
+        """
+        Get information about a single table on the site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_table
+
+        Parameters
+        ----------
+        table_id : str
+            The ID of the table to retrieve.
+
+        Returns
+        -------
+        TableItem
+            A TableItem object representing the table.
+
+        Raises
+        ------
+        ValueError
+            If the table ID is not provided.
+        """
         if not table_id:
             error = "table ID undefined."
             raise ValueError(error)
@@ -46,7 +89,24 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return TableItem.from_response(server_response.content, self.parent_srv.namespace)[0]
 
     @api(version="3.5")
-    def delete(self, table_id):
+    def delete(self, table_id: str) -> None:
+        """
+        Delete a single table from the server.
+
+        Parameters
+        ----------
+        table_id : str
+            The ID of the table to delete.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        ValueError
+            If the table ID is not provided.
+        """
         if not table_id:
             error = "Database ID undefined."
             raise ValueError(error)
@@ -55,7 +115,27 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         logger.info(f"Deleted single table (ID: {table_id})")
 
     @api(version="3.5")
-    def update(self, table_item):
+    def update(self, table_item: TableItem) -> TableItem:
+        """
+        Update a table on the server.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_table
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object to update.
+
+        Returns
+        -------
+        TableItem
+            The updated TableItem object.
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the table item is missing an ID.
+        """
         if not table_item.id:
             error = "table item missing ID."
             raise MissingRequiredFieldError(error)
@@ -69,21 +149,46 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
 
     # Get all columns of the table
     @api(version="3.5")
-    def populate_columns(self, table_item, req_options=None):
+    def populate_columns(self, table_item: TableItem, req_options: Optional[RequestOptions] = None) -> None:
+        """
+        Populate the columns of a table item. Sets a fetcher function to
+        retrieve the columns when needed.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#query_columns
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object to populate columns for.
+
+        req_options : RequestOptions, optional
+            Options to customize the request. If not provided, defaults to None.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        MissingRequiredFieldError
+            If the table item is missing an ID.
+        """
         if not table_item.id:
             error = "Table item missing ID. table must be retrieved from server first."
             raise MissingRequiredFieldError(error)
 
         def column_fetcher():
             return Pager(
-                lambda options: self._get_columns_for_table(table_item, options),
+                lambda options: self._get_columns_for_table(table_item, options),  # type: ignore
                 req_options,
             )
 
         table_item._set_columns(column_fetcher)
         logger.info(f"Populated columns for table (ID: {table_item.id}")
 
-    def _get_columns_for_table(self, table_item, req_options=None):
+    def _get_columns_for_table(
+        self, table_item: TableItem, req_options: Optional[RequestOptions] = None
+    ) -> tuple[list[ColumnItem], PaginationItem]:
         url = f"{self.baseurl}/{table_item.id}/columns"
         server_response = self.get_request(url, req_options)
         columns = ColumnItem.from_response(server_response.content, self.parent_srv.namespace)
@@ -91,7 +196,25 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return columns, pagination_item
 
     @api(version="3.5")
-    def update_column(self, table_item, column_item):
+    def update_column(self, table_item: TableItem, column_item: ColumnItem) -> ColumnItem:
+        """
+        Update the description of a column in a table.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_column
+
+        Parameters
+        ----------
+        table_item : TableItem
+            The TableItem object representing the table.
+
+        column_item : ColumnItem
+            The ColumnItem object representing the column to update.
+
+        Returns
+        -------
+        ColumnItem
+            The updated ColumnItem object.
+        """
         url = f"{self.baseurl}/{table_item.id}/columns/{column_item.id}"
         update_req = RequestFactory.Column.update_req(column_item)
         server_response = self.put_request(url, update_req)
@@ -101,31 +224,31 @@ class Tables(Endpoint, TaggingMixin[TableItem]):
         return column
 
     @api(version="3.5")
-    def populate_permissions(self, item):
+    def populate_permissions(self, item: TableItem) -> None:
         self._permissions.populate(item)
 
     @api(version="3.5")
-    def update_permissions(self, item, rules):
+    def update_permissions(self, item: TableItem, rules: list[PermissionsRule]) -> list[PermissionsRule]:
         return self._permissions.update(item, rules)
 
     @api(version="3.5")
-    def delete_permission(self, item, rules):
+    def delete_permission(self, item: TableItem, rules: list[PermissionsRule]) -> None:
         return self._permissions.delete(item, rules)
 
     @api(version="3.5")
-    def populate_dqw(self, item):
+    def populate_dqw(self, item: TableItem) -> None:
         self._data_quality_warnings.populate(item)
 
     @api(version="3.5")
-    def update_dqw(self, item, warning):
+    def update_dqw(self, item: TableItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.update(item, warning)
 
     @api(version="3.5")
-    def add_dqw(self, item, warning):
+    def add_dqw(self, item: TableItem, warning: "DQWItem") -> list["DQWItem"]:
         return self._data_quality_warnings.add(item, warning)
 
     @api(version="3.5")
-    def delete_dqw(self, item):
+    def delete_dqw(self, item: TableItem) -> None:
         self._data_quality_warnings.clear(item)
 
     @api(version="3.9")

{tableauserverclient/server → server}/endpoint/users_endpoint.py

@@ -1,14 +1,19 @@
+from collections.abc import Iterable
 import copy
+import csv
+import io
+import itertools
 import logging
 from typing import Optional
+import warnings
 
 from tableauserverclient.server.query import QuerySet
 
-from .endpoint import QuerysetEndpoint, api
-from .exceptions import MissingRequiredFieldError, ServerResponseError
+from tableauserverclient.server.endpoint.endpoint import QuerysetEndpoint, api
+from tableauserverclient.server.endpoint.exceptions import MissingRequiredFieldError, ServerResponseError
 from tableauserverclient.server import RequestFactory, RequestOptions
-from tableauserverclient.models import UserItem, WorkbookItem, PaginationItem, GroupItem
-from ..pager import Pager
+from tableauserverclient.models import UserItem, WorkbookItem, PaginationItem, GroupItem, JobItem
+from tableauserverclient.server.pager import Pager
 
 from tableauserverclient.helpers.logging import logger
 
@@ -87,7 +92,7 @@ class Users(QuerysetEndpoint[UserItem]):
 
         if req_options is None:
             req_options = RequestOptions()
-        req_options._all_fields = True
+        req_options.all_fields = True
 
         url = self.baseurl
         server_response = self.get_request(url, req_options)
@@ -344,7 +349,34 @@ class Users(QuerysetEndpoint[UserItem]):
 
     # Add new users to site. This does not actually perform a bulk action, it's syntactic sugar
     @api(version="2.0")
-    def add_all(self, users: list[UserItem]):
+    def add_all(self, users: list[UserItem]) -> tuple[list[UserItem], list[UserItem]]:
+        """
+        Syntactic sugar for calling users.add multiple times. This method has
+        been deprecated in favor of using the bulk_add which accomplishes the
+        same task in one API call.
+
+        .. deprecated:: v0.41.0
+            `add_all` will be removed as its functionality is replicated via
+            the `bulk_add` method.
+
+        Parameters
+        ----------
+        users: list[UserItem]
+           A list of UserItem objects to add to the site. Each UserItem object
+           will be passed to the `add` method individually.
+
+        Returns
+        -------
+        tuple[list[UserItem], list[UserItem]]
+            The first element of the tuple is a list of UserItem objects that
+            were successfully added to the site. The second element is a list
+            of UserItem objects that failed to be added to the site.
+
+        Warnings
+        --------
+        This method is deprecated. Use the `bulk_add` method instead.
+        """
+        warnings.warn("This method is deprecated, use bulk_add method instead.", DeprecationWarning)
         created = []
         failed = []
         for user in users:
@@ -357,8 +389,143 @@ class Users(QuerysetEndpoint[UserItem]):
 
     # helping the user by parsing a file they could have used to add users through the UI
     # line format: Username [required], password, display name, license, admin, publish
+    @api(version="3.15")
+    def bulk_add(self, users: Iterable[UserItem]) -> JobItem:
+        """
+        When adding users in bulk, the server will return a job item that can be used to track the progress of the
+        operation. This method will return the job item that was created when the users were added.
+
+        For each user, name is required, and other fields are optional. If connected to activte directory and
+        the user name is not unique across domains, then the domain attribute must be populated on
+        the UserItem.
+
+        The user's display name is read from the fullname attribute.
+
+        Email is optional, but if provided, it must be a valid email address.
+
+        If auth_setting is not provided, and idp_configuration_id is None, then
+        default is ServerDefault.
+
+        If site_role is not provided, the default is Unlicensed.
+
+        Password is optional, and only used if the server is using local
+        authentication. If using any other authentication method, the password
+        should not be provided.
+
+        Details about administrator level and publishing capability are
+        inferred from the site_role.
+
+        If the user belongs to a different IDP configuration, the UserItem's
+        idp_configuration_id attribute must be set to the IDP configuration ID
+        that the user belongs to.
+
+        Parameters
+        ----------
+        users: Iterable[UserItem]
+            An iterable of UserItem objects to add to the site. See above for
+            what fields are required and optional.
+
+        Returns
+        -------
+        JobItem
+            The job that is started for adding the users in bulk.
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+        >>> server = TSC.Server('http://localhost')
+        >>> # Login to the server
+
+        >>> # Create a list of UserItem objects to add to the site
+        >>> users = [
+        >>>    TSC.UserItem(name="user1", site_role="Unlicensed"),
+        >>>    TSC.UserItem(name="user2", site_role="Explorer"),
+        >>>    TSC.UserItem(name="user3", site_role="Creator"),
+        >>> ]
+
+        >>> # Set the domain name for the users
+        >>> for user in users:
+        >>>     user.domain_name = "example.com"
+
+        >>> # Add the users to the site
+        >>> job = server.users.bulk_add(users)
+
+        """
+        url = f"{self.baseurl}/import"
+        # Allow for iterators to be passed into the function
+        csv_users, xml_users = itertools.tee(users, 2)
+        csv_content = create_users_csv(csv_users)
+
+        xml_request, content_type = RequestFactory.User.import_from_csv_req(csv_content, xml_users)
+        server_response = self.post_request(url, xml_request, content_type)
+        return JobItem.from_response(server_response.content, self.parent_srv.namespace).pop()
+
+    @api(version="3.15")
+    def bulk_remove(self, users: Iterable[UserItem]) -> None:
+        """
+        Remove multiple users from the site. The users are identified by their
+        domain and name. The users are removed in bulk, so the server will not
+        return a job item to track the progress of the operation nor a response
+        for each user that was removed.
+
+        Parameters
+        ----------
+        users: Iterable[UserItem]
+            An iterable of UserItem objects to remove from the site. Each
+            UserItem object should have the domain and name attributes set.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+        >>> server = TSC.Server('http://localhost')
+        >>> # Login to the server
+
+        >>> # Find the users to remove
+        >>> example_users = server.users.filter(domain_name="example.com")
+        >>> server.users.bulk_remove(example_users)
+        """
+        url = f"{self.baseurl}/delete"
+        csv_content = remove_users_csv(users)
+        request, content_type = RequestFactory.User.delete_csv_req(csv_content)
+        server_response = self.post_request(url, request, content_type)
+        return None
+
     @api(version="2.0")
     def create_from_file(self, filepath: str) -> tuple[list[UserItem], list[tuple[UserItem, ServerResponseError]]]:
+        """
+        Syntactic sugar for calling users.add multiple times. This method has
+        been deprecated in favor of using the bulk_add which accomplishes the
+        same task in one API call.
+
+        .. deprecated:: v0.41.0
+            `add_all` will be removed as its functionality is replicated via
+            the `bulk_add` method.
+
+        Parameters
+        ----------
+        filepath: str
+            The path to the CSV file containing the users to add to the site.
+            The file is read in line by line and each line is passed to the
+            `add` method.
+
+        Returns
+        -------
+        tuple[list[UserItem], list[tuple[UserItem, ServerResponseError]]]
+            The first element of the tuple is a list of UserItem objects that
+            were successfully added to the site. The second element is a list
+            of tuples where the first element is the UserItem object that failed
+            to be added to the site and the second element is the ServerResponseError
+            that was raised when attempting to add the user.
+
+        Warnings
+        --------
+        This method is deprecated. Use the `bulk_add` method instead.
+        """
+        warnings.warn("This method is deprecated, use bulk_add instead", DeprecationWarning)
         created = []
         failed = []
         if not filepath.find("csv"):
@@ -381,10 +548,15 @@ class Users(QuerysetEndpoint[UserItem]):
 
     # Get workbooks for user
     @api(version="2.0")
-    def populate_workbooks(self, user_item: UserItem, req_options: Optional[RequestOptions] = None) -> None:
+    def populate_workbooks(
+        self, user_item: UserItem, req_options: Optional[RequestOptions] = None, owned_only: bool = False
+    ) -> None:
         """
         Returns information about the workbooks that the specified user owns
-        and has Read (view) permissions for.
+        or has Read (view) permissions for. If owned_only is set to True,
+        only the workbooks that the user owns are returned. If owned_only is
+        set to False, all workbooks that the user has Read (view) permissions
+        for are returned.
 
         This method retrieves the workbook information for the specified user.
         The REST API is designed to return only the information you ask for
@@ -402,6 +574,10 @@ class Users(QuerysetEndpoint[UserItem]):
         req_options : Optional[RequestOptions]
             Optional request options to filter and sort the results.
 
+        owned_only : bool, default=False
+            If True, only the workbooks that the user owns are returned.
+            If False, all workbooks that the user has Read (view) permissions
+
         Returns
         -------
         None
@@ -423,14 +599,22 @@ class Users(QuerysetEndpoint[UserItem]):
             raise MissingRequiredFieldError(error)
 
         def wb_pager():
-            return Pager(lambda options: self._get_wbs_for_user(user_item, options), req_options)
+            def func(req_options):
+                return self._get_wbs_for_user(user_item, req_options, owned_only=owned_only)
+
+            return Pager(func, req_options)
 
         user_item._set_workbooks(wb_pager)
 
     def _get_wbs_for_user(
-        self, user_item: UserItem, req_options: Optional[RequestOptions] = None
+        self,
+        user_item: UserItem,
+        req_options: Optional[RequestOptions] = None,
+        owned_only: bool = False,
     ) -> tuple[list[WorkbookItem], PaginationItem]:
         url = f"{self.baseurl}/{user_item.id}/workbooks"
+        if owned_only:
+            url += "?ownedBy=true"
         server_response = self.get_request(url, req_options)
         logger.info(f"Populated workbooks for user (ID: {user_item.id})")
         workbook_item = WorkbookItem.from_response(server_response.content, self.parent_srv.namespace)
@@ -552,3 +736,105 @@ class Users(QuerysetEndpoint[UserItem]):
         """
 
         return super().filter(*invalid, page_size=page_size, **kwargs)
+
+
+def create_users_csv(users: Iterable[UserItem]) -> bytes:
+    """
+    Create a CSV byte string from an Iterable of UserItem objects. The CSV will
+    have the following columns, and no header row:
+
+    - Username
+    - Password
+    - Display Name
+    - License
+    - Admin Level
+    - Publish capability
+    - Email
+
+    Parameters
+    ----------
+    users: Iterable[UserItem]
+        An iterable of UserItem objects to create the CSV from.
+
+    Returns
+    -------
+    bytes
+        A byte string containing the CSV data.
+    """
+    with io.StringIO() as output:
+        writer = csv.writer(output, quoting=csv.QUOTE_MINIMAL)
+        for user in users:
+            site_role = user.site_role or "Unlicensed"
+            if site_role == "ServerAdministrator":
+                license = "Creator"
+                admin_level = "System"
+            elif site_role.startswith("SiteAdministrator"):
+                admin_level = "Site"
+                license = site_role.replace("SiteAdministrator", "")
+            else:
+                license = site_role
+                admin_level = ""
+
+            if any(x in site_role for x in ("Creator", "Admin", "Publish")):
+                publish = 1
+            else:
+                publish = 0
+
+            writer.writerow(
+                (
+                    f"{user.domain_name}\\{user.name}" if user.domain_name else user.name,
+                    getattr(user, "password", ""),
+                    user.fullname,
+                    license,
+                    admin_level,
+                    publish,
+                    user.email,
+                )
+            )
+        output.seek(0)
+        result = output.read().encode("utf-8")
+    return result
+
+
+def remove_users_csv(users: Iterable[UserItem]) -> bytes:
+    """
+    Create a CSV byte string from an Iterable of UserItem objects. This function
+    only consumes the domain and name attributes of the UserItem objects. The
+    CSV will have space for the following columns, though only the first column
+    will be populated, and no header row:
+
+    - Username
+    - Password
+    - Display Name
+    - License
+    - Admin Level
+    - Publish capability
+    - Email
+
+    Parameters
+    ----------
+    users: Iterable[UserItem]
+        An iterable of UserItem objects to create the CSV from.
+
+    Returns
+    -------
+    bytes
+        A byte string containing the CSV data.
+    """
+    with io.StringIO() as output:
+        writer = csv.writer(output, quoting=csv.QUOTE_MINIMAL)
+        for user in users:
+            writer.writerow(
+                (
+                    f"{user.domain_name}\\{user.name}" if user.domain_name else user.name,
+                    None,
+                    None,
+                    None,
+                    None,
+                    None,
+                    None,
+                )
+            )
+        output.seek(0)
+        result = output.read().encode("utf-8")
+    return result

{tableauserverclient/server → server}/endpoint/views_endpoint.py

@@ -371,6 +371,29 @@ class Views(QuerysetEndpoint[ViewItem], TaggingMixin[ViewItem]):
         # Returning view item to stay consistent with datasource/view update functions
         return view_item
 
+    @api(version="3.27")
+    def delete(self, view: ViewItem | str) -> None:
+        """
+        Deletes a view in a workbook. If you delete the only view in a workbook,
+        the workbook is deleted. Can be used to remove hidden views when
+        republishing or migrating to a different environment.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#delete_view
+
+        Parameters
+        ----------
+        view: ViewItem | str
+            The ViewItem or the luid for the view to be deleted.
+
+        Returns
+        -------
+        None
+        """
+        id_ = getattr(view, "id", view)
+        self.delete_request(f"{self.baseurl}/{id_}")
+        logger.info(f"View({id_}) deleted.")
+        return None
+
     @api(version="1.0")
     def add_tags(self, item: Union[ViewItem, str], tags: Union[Iterable[str], str]) -> set[str]:
         """