Add delete_users() bulk deletion method

Author: rsgowman

firebase_admin/_user_mgt.py

@@ -332,6 +332,85 @@ def iterate_all(self):
         return _UserIterator(self)
 
 
+class DeleteUsersResult:
+    """Represents the result of the ``auth.delete_users()`` API."""
+
+    def __init__(self, result, total):
+        """Constructs a DeleteUsersResult.
+
+        Args:
+          result: BatchDeleteAccountsResponse: The proto response, wrapped in a
+              BatchDeleteAccountsResponse instance.
+          total: integer: Total number of deletion attempts.
+        """
+        errors = result.errors
+        self._success_count = total - len(errors)
+        self._failure_count = len(errors)
+        self._errors = errors
+
+    @property
+    def success_count(self):
+        """Returns the number of users that were deleted successfully (possibly
+        zero).
+
+        Users that did not exist prior to calling delete_users() will be
+        considered to be successfully deleted.
+        """
+        return self._success_count
+
+    @property
+    def failure_count(self):
+        """Returns the number of users that failed to be deleted (possibly
+        zero).
+        """
+        return self._failure_count
+
+    @property
+    def errors(self):
+        """A list of ``auth.BatchDeleteErrorInfo`` instances describing the
+        errors that were encountered during the deletion. Length of this list
+        is equal to `failure_count`.
+        """
+        return self._errors
+
+
+class BatchDeleteErrorInfo:
+    """Represents an error that occurred while attempting to delete a batch of
+    users.
+    """
+
+    def __init__(self, err):
+        """Constructs a BatchDeleteErrorInfo instance, corresponding to the
+        json representing the BatchDeleteErrorInfo proto.
+
+        Args:
+            err: A dictionary with 'index', 'local_id' and 'message' fields,
+                representing the BatchDeleteErrorInfo dictionary that's
+                returned by the server.
+        """
+        self.index = err.get('index', 0)
+        self.local_id = err.get('local_id', "")
+        self.message = err.get('message', "")
+
+
+class BatchDeleteAccountsResponse:
+    """Represents the results of a delete_users() call."""
+
+    def __init__(self, errors=None):
+        """Constructs a BatchDeleteAccountsResponse instance, corresponseing to
+        the json representing the BatchDeleteAccountsResponse proto.
+
+        Args:
+            errors: List of dictionaries, with each dictionary representing a
+                BatchDeleteErrorInfo instance as returned by the server. None
+                implies an empty list.
+        """
+        if errors:
+            self.errors = [BatchDeleteErrorInfo(err) for err in errors]
+        else:
+            self.errors = []
+
+
 class ProviderUserInfo(UserInfo):
     """Contains metadata regarding how a user is known by a particular identity provider."""
 
@@ -638,6 +717,45 @@ def delete_user(self, uid):
                 raise _auth_utils.UnexpectedResponseError(
                     'Failed to delete user: {0}.'.format(uid), http_response=http_resp)
 
+    def delete_users(self, uids, force_delete=False):
+        """Deletes the users identified by the specified user ids.
+
+        Args:
+            uids: A list of strings indicating the uids of the users to be deleted.
+                Must have <= 1000 entries.
+            force_delete: Optional parameter that indicates if users should be
+                deleted, even if they're not disabled. Defaults to False.
+
+
+        Returns:
+            BatchDeleteAccountsResponse: Server's proto response, wrapped in a
+                python object.
+
+        Raises:
+            ValueError: If any of the identifiers are invalid or if more than 1000
+                identifiers are specified.
+        """
+        if not uids:
+            return BatchDeleteAccountsResponse()
+
+        if len(uids) > 100:
+            raise ValueError("`uids` paramter must have <= 100 entries.")
+        for uid in uids:
+            _auth_utils.validate_uid(uid, required=True)
+
+        try:
+            body, http_resp = self._client.body_and_response(
+                'post', '/accounts:batchDelete',
+                json={'localIds': uids, 'force': force_delete})
+        except requests.exceptions.RequestException as error:
+            raise _auth_utils.handle_auth_backend_error(error)
+        else:
+            if not isinstance(body, dict):
+                raise _auth_utils.UnexpectedResponseError(
+                    'Unexpected response from server while attempting to delete users.',
+                    http_response=http_resp)
+            return BatchDeleteAccountsResponse(body.get('errors', []))
+
     def import_users(self, users, hash_alg=None):
         """Imports the given list of users to Firebase Auth."""
         try:

firebase_admin/auth.py

@@ -71,6 +71,7 @@
     'create_session_cookie',
     'create_user',
     'delete_user',
+    'delete_users',
     'generate_email_verification_link',
     'generate_password_reset_link',
     'generate_sign_in_with_email_link',
@@ -90,6 +91,7 @@
 ActionCodeSettings = _user_mgt.ActionCodeSettings
 CertificateFetchError = _token_gen.CertificateFetchError
 DELETE_ATTRIBUTE = _user_mgt.DELETE_ATTRIBUTE
+DeleteUsersResult = _user_mgt.DeleteUsersResult
 EmailAlreadyExistsError = _auth_utils.EmailAlreadyExistsError
 ErrorInfo = _user_import.ErrorInfo
 ExpiredIdTokenError = _token_gen.ExpiredIdTokenError
@@ -490,6 +492,41 @@ def delete_user(uid, app=None):
     user_manager.delete_user(uid)
 
 
+def delete_users(uids, force_delete=False, app=None):
+    """Deletes the users specified by the given identifiers.
+
+    Deleting a non-existing user won't generate an error. (i.e. this method is
+    idempotent.) Non-existing users will be considered to be successfully
+    deleted, and will therefore be counted in the
+    DeleteUserResult.success_count value.
+
+    Unless the optional force_delete flag is set to true, only users that are
+    already disabled will be deleted.
+
+    Only a maximum of 1000 identifiers may be supplied. If more than 1000
+    identifiers are supplied, this method will immediately raise a ValueError.
+
+    Args:
+        uids: A list of strings indicating the uids of the users to be deleted.
+            Must have <= 1000 entries.
+        force_delete: Optional parameter that indicates if users should be
+            deleted, even if they're not disabled. Defaults to False.
+        app: An App instance (optional).
+
+    Returns:
+        DeleteUsersResult: The total number of successful/failed deletions, as
+            well as the array of errors that correspond to the failed
+            deletions.
+
+    Raises:
+        ValueError: If any of the identifiers are invalid or if more than 1000
+            identifiers are specified.
+    """
+    user_manager = _get_auth_service(app).user_manager
+    result = user_manager.delete_users(uids, force_delete)
+    return DeleteUsersResult(result, len(uids))
+
+
 def import_users(users, hash_alg=None, app=None):
     """Imports the specified list of users into Firebase Auth.
 

integration/test_auth.py

@@ -408,6 +408,73 @@ def test_delete_user():
     with pytest.raises(auth.UserNotFoundError):
         auth.get_user(user.uid)
 
+
+class TestDeleteUsers:
+    def test_delete_multiple_disabled_users(self):
+        uid1 = auth.create_user(disabled=True).uid
+        uid2 = auth.create_user(disabled=True).uid
+        uid3 = auth.create_user(disabled=True).uid
+
+        delete_users_result = auth.delete_users([uid1, uid2, uid3])
+        assert delete_users_result.success_count == 3
+        assert delete_users_result.failure_count == 0
+        assert len(delete_users_result.errors) == 0
+
+        user_records = auth.get_users(
+            [auth.UidIdentifier(uid1), auth.UidIdentifier(uid2), auth.UidIdentifier(uid3)])
+        assert len(user_records) == 0
+
+    def test_fails_to_delete_enabled_users(self):
+        uid1 = auth.create_user(disabled=False).uid
+        uid2 = auth.create_user(disabled=True).uid
+        uid3 = auth.create_user(disabled=False).uid
+
+        try:
+            delete_users_result = auth.delete_users([uid1, uid2, uid3])
+            assert delete_users_result.success_count == 1
+            assert delete_users_result.failure_count == 2
+            assert len(delete_users_result.errors) == 2
+            assert delete_users_result.errors[0].index == 0
+            assert delete_users_result.errors[0].message.startswith('NOT_DISABLED')
+            assert delete_users_result.errors[1].index == 2
+            assert delete_users_result.errors[1].message.startswith('NOT_DISABLED')
+
+            user_records = auth.get_users(
+                [auth.UidIdentifier(uid1), auth.UidIdentifier(uid2), auth.UidIdentifier(uid3)])
+            assert len(user_records) == 2
+            assert {ur.uid for ur in user_records} == set([uid1, uid3])
+
+        finally:
+            auth.delete_users([uid1, uid3], force_delete=True)
+
+    def test_deletes_enabled_users_when_force_is_true(self):
+        uid1 = auth.create_user(disabled=False).uid
+        uid2 = auth.create_user(disabled=True).uid
+        uid3 = auth.create_user(disabled=False).uid
+
+        delete_users_result = auth.delete_users([uid1, uid2, uid3], force_delete=True)
+        assert delete_users_result.success_count == 3
+        assert delete_users_result.failure_count == 0
+        assert len(delete_users_result.errors) == 0
+
+        user_records = auth.get_users(
+            [auth.UidIdentifier(uid1), auth.UidIdentifier(uid2), auth.UidIdentifier(uid3)])
+        assert len(user_records) == 0
+
+    def test_is_idempotent(self):
+        uid = auth.create_user(disabled=True).uid
+
+        delete_users_result = auth.delete_users([uid])
+        assert delete_users_result.success_count == 1
+        assert delete_users_result.failure_count == 0
+
+        # Delete the user again, ensuring that everything still counts as a
+        # success.
+        delete_users_result = auth.delete_users([uid])
+        assert delete_users_result.success_count == 1
+        assert delete_users_result.failure_count == 0
+
+
 def test_revoke_refresh_tokens(new_user):
     user = auth.get_user(new_user.uid)
     old_valid_after = user.tokens_valid_after_timestamp

tests/test_user_mgt.py

@@ -653,6 +653,47 @@ def test_delete_user_unexpected_response(self, user_mgt_app):
         assert isinstance(excinfo.value, exceptions.UnknownError)
 
 
+class TestDeleteUsers:
+
+    def test_empty_list(self, user_mgt_app):
+        delete_users_result = auth.delete_users([], app=user_mgt_app)
+        assert delete_users_result.success_count == 0
+        assert delete_users_result.failure_count == 0
+        assert len(delete_users_result.errors) == 0
+
+    def test_too_many_identifiers_should_fail(self, user_mgt_app):
+        ids = ['id' + str(i) for i in range(101)]
+        with pytest.raises(ValueError):
+            auth.delete_users(ids, app=user_mgt_app)
+
+    def test_invalid_id_should_fail(self, user_mgt_app):
+        ids = ['too long ' + '.'*128]
+        with pytest.raises(ValueError):
+            auth.delete_users(ids, app=user_mgt_app)
+
+    def test_should_index_errors_correctly_in_results(self, user_mgt_app):
+        _instrument_user_manager(user_mgt_app, 200, """{
+            "errors": [{
+                "index": 0,
+                "localId": "uid1",
+                "message": "NOT_DISABLED : Disable the account before batch deletion."
+            }, {
+                "index": 2,
+                "localId": "uid3",
+                "message": "something awful"
+            }]
+        }""")
+
+        delete_users_result = auth.delete_users(['uid1', 'uid2', 'uid3', 'uid4'], app=user_mgt_app)
+        assert delete_users_result.success_count == 2
+        assert delete_users_result.failure_count == 2
+        assert len(delete_users_result.errors) == 2
+        assert delete_users_result.errors[0].index == 0
+        assert delete_users_result.errors[0].message.startswith('NOT_DISABLED')
+        assert delete_users_result.errors[1].index == 2
+        assert delete_users_result.errors[1].message == 'something awful'
+
+
 class TestListUsers:
 
     @pytest.mark.parametrize('arg', [None, 'foo', list(), dict(), 0, -1, 1001, False])