docs: docstring updates for bulk add operations

jorwoods · jorwoods · commit 2afca7440f65 · 2024-10-02T18:00:04.000-05:00
diff --git a/tableauserverclient/server/endpoint/users_endpoint.py b/tableauserverclient/server/endpoint/users_endpoint.py
@@ -89,8 +89,34 @@ def add(self, user_item: UserItem) -> 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]):
-        warnings.warn("This method is deprecated, use bulk_add instead", DeprecationWarning)
+    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.34.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:
@@ -127,6 +153,17 @@ def bulk_add(self, users: Iterable[UserItem]) -> JobItem:
 
         Details about administrator level and publishing capability are
         inferred from the site_role.
+
+        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.
         """
         url = f"{self.baseurl}/import"
         # Allow for iterators to be passed into the function
@@ -139,6 +176,22 @@ def bulk_add(self, users: Iterable[UserItem]) -> JobItem:
 
     @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
+        """
         url = f"{self.baseurl}/delete"
         csv_content = remove_users_csv(users)
         request, content_type = RequestFactory.User.delete_csv_req(csv_content)
@@ -147,6 +200,35 @@ def bulk_remove(self, users: Iterable[UserItem]) -> 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.34.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 = []
@@ -268,6 +350,21 @@ def create_users_csv(users: Iterable[UserItem], identity_pool=None) -> bytes:
     - Admin Level
     - Publish capability
     - Email
+
+    Parameters
+    ----------
+    users: Iterable[UserItem]
+        An iterable of UserItem objects to create the CSV from.
+
+    identity_pool: Optional[str]
+        The identity pool to use when adding the users. This parameter is not
+        yet supported in this version of the Tableau Server Client, and should
+        be left as None.
+
+    Returns
+    -------
+    bytes
+        A byte string containing the CSV data.
     """
     if identity_pool is not None:
         raise NotImplementedError("Identity pool is not supported in this version")
@@ -307,6 +404,35 @@ def create_users_csv(users: Iterable[UserItem], identity_pool=None) -> bytes:
 
 
 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.
+
+    identity_pool: Optional[str]
+        The identity pool to use when adding the users. This parameter is not
+        yet supported in this version of the Tableau Server Client, and should
+        be left as None.
+
+    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:
