tableauserverclient 0.38__py3-none-any.whl → 0.40__py3-none-any.whl

tableauserverclient/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
 
@@ -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"):
@@ -569,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/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]:
         """

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -30,9 +30,12 @@ from tableauserverclient.models import WorkbookItem, ConnectionItem, ViewItem, P
 from tableauserverclient.server import RequestFactory
 
 from typing import (
+    Literal,
     Optional,
     TYPE_CHECKING,
+    TypeVar,
     Union,
+    overload,
 )
 from collections.abc import Iterable, Sequence
 
@@ -325,16 +328,92 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         logger.info(f"Updated workbook item (ID: {workbook_item.id} & connection item {connection_item.id})")
         return connection
 
+    # Update workbook_connections
+    @api(version="3.26")
+    def update_connections(
+        self,
+        workbook_item: WorkbookItem,
+        connection_luids: Iterable[str],
+        authentication_type: str,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        embed_password: Optional[bool] = None,
+    ) -> list[ConnectionItem]:
+        """
+        Bulk updates one or more workbook connections by LUID, including authenticationType, username, password, and embedPassword.
+
+        Parameters
+        ----------
+        workbook_item : WorkbookItem
+            The workbook item containing the connections.
+
+        connection_luids : Iterable of str
+            The connection LUIDs to update.
+
+        authentication_type : str
+            The authentication type to use (e.g., 'AD Service Principal').
+
+        username : str, optional
+            The username to set (e.g., client ID for keypair auth).
+
+        password : str, optional
+            The password or secret to set.
+
+        embed_password : bool, optional
+            Whether to embed the password.
+
+        Returns
+        -------
+        Iterable of str
+            The connection LUIDs that were updated.
+        """
+
+        url = f"{self.baseurl}/{workbook_item.id}/connections"
+
+        request_body = RequestFactory.Workbook.update_connections_req(
+            connection_luids,
+            authentication_type,
+            username=username,
+            password=password,
+            embed_password=embed_password,
+        )
+
+        # Send request
+        server_response = self.put_request(url, request_body)
+        connection_items = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)
+        updated_ids: list[str] = [conn.id for conn in connection_items]
+
+        logger.info(f"Updated connections for workbook {workbook_item.id}: {', '.join(updated_ids)}")
+        return connection_items
+
+    T = TypeVar("T", bound=FileObjectW)
+
+    @overload
+    def download(
+        self,
+        workbook_id: str,
+        filepath: T,
+        include_extract: bool = True,
+    ) -> T: ...
+
+    @overload
+    def download(
+        self,
+        workbook_id: str,
+        filepath: Optional[FilePath] = None,
+        include_extract: bool = True,
+    ) -> str: ...
+
     # Download workbook contents with option of passing in filepath
     @api(version="2.0")
     @parameter_added_in(no_extract="2.5")
     @parameter_added_in(include_extract="2.5")
     def download(
         self,
-        workbook_id: str,
-        filepath: Optional[PathOrFileW] = None,
-        include_extract: bool = True,
-    ) -> PathOrFileW:
+        workbook_id,
+        filepath=None,
+        include_extract=True,
+    ):
         """
         Downloads a workbook to the specified directory (optional).
 
@@ -683,6 +762,30 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         """
         return self._permissions.delete(item, capability_item)
 
+    @overload
+    def publish(
+        self,
+        workbook_item: WorkbookItem,
+        file: PathOrFileR,
+        mode: str,
+        connections: Optional[Sequence[ConnectionItem]],
+        as_job: Literal[False],
+        skip_connection_check: bool,
+        parameters=None,
+    ) -> WorkbookItem: ...
+
+    @overload
+    def publish(
+        self,
+        workbook_item: WorkbookItem,
+        file: PathOrFileR,
+        mode: str,
+        connections: Optional[Sequence[ConnectionItem]],
+        as_job: Literal[True],
+        skip_connection_check: bool,
+        parameters=None,
+    ) -> JobItem: ...
+
     @api(version="2.0")
     @parameter_added_in(as_job="3.0")
     @parameter_added_in(connections="2.8")
@@ -919,15 +1022,27 @@ class Workbooks(QuerysetEndpoint[WorkbookItem], TaggingMixin[WorkbookItem]):
         revisions = RevisionItem.from_response(server_response.content, self.parent_srv.namespace, workbook_item)
         return revisions
 
+    T = TypeVar("T", bound=FileObjectW)
+
+    @overload
+    def download_revision(
+        self, workbook_id: str, revision_number: Optional[str], filepath: T, include_extract: bool
+    ) -> T: ...
+
+    @overload
+    def download_revision(
+        self, workbook_id: str, revision_number: Optional[str], filepath: Optional[FilePath], include_extract: bool
+    ) -> str: ...
+
     # Download 1 workbook revision by revision number
     @api(version="2.3")
     def download_revision(
         self,
-        workbook_id: str,
-        revision_number: Optional[str],
-        filepath: Optional[PathOrFileW] = None,
-        include_extract: bool = True,
-    ) -> PathOrFileW:
+        workbook_id,
+        revision_number,
+        filepath,
+        include_extract=True,
+    ):
         """
         Downloads a workbook revision to the specified directory (optional).