From a590303fa2d6a9fdeeeb17c86d95bc61d35984ce Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Mon, 29 Jan 2024 17:36:53 +0100
Subject: [PATCH 01/13] deactivated flag refactored to filter deactivated
 users.

---
 changelog.d/16874.feature                  |  1 +
 docs/admin_api/user_admin_api.md           |  6 ++-
 synapse/rest/admin/users.py                |  4 +-
 synapse/storage/databases/main/__init__.py |  9 ++--
 tests/rest/admin/test_user.py              | 55 ++++++++++++++++++++--
 5 files changed, 65 insertions(+), 10 deletions(-)
 create mode 100644 changelog.d/16874.feature

diff --git a/changelog.d/16874.feature b/changelog.d/16874.feature
new file mode 100644
index 0000000000..f3f808f182
--- /dev/null
+++ b/changelog.d/16874.feature
@@ -0,0 +1 @@
+Query parameter `deactivated` of [List Accounts](https://matrix-org.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://matrix-org.github.io/synapse/v1.99/usage/administration/admin_api/index.html) refactored, to filter deactivated users in user queries.
\ No newline at end of file
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 9dc600b875..26ca768eeb 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -226,8 +226,10 @@ The following parameters should be set in the URL:
   Defaults to `true` to include guest users. This parameter is not supported when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
 - `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from
   the query. When the flag is absent (the default), **both** admins and non-admins are included in the search results.
-- `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users.
-  Defaults to `false` to exclude deactivated users.
+- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried. 
+  If `false`, deactivated users are excluded from the query. When the flag is absent (the default), 
+  **both** active and deactivated users are included in the 
+  search results.
 - `limit` - string representing a positive integer - Is optional but is used for pagination,
   denoting the maximum number of items to return in this call. Defaults to `100`.
 - `from` - string representing a positive integer - Is optional but used for pagination,
diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index 0229e87f43..ae0c6bbdff 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -72,7 +72,7 @@ class UsersRestServletV2(RestServlet):
     The parameter `user_id` can be used to filter by user id.
     The parameter `name` can be used to filter by user id or display name.
     The parameter `guests` can be used to exclude guest users.
-    The parameter `deactivated` can be used to include deactivated users.
+    The parameter `deactivated` can be used to filter deactivated users.
     The parameter `order_by` can be used to order the result.
     The parameter `not_user_type` can be used to exclude certain user types.
     The parameter `locked` can be used to include locked users.
@@ -118,7 +118,7 @@ async def on_GET(self, request: SynapseRequest) -> Tuple[int, JsonDict]:
                 errcode=Codes.INVALID_PARAM,
             )
 
-        deactivated = parse_boolean(request, "deactivated", default=False)
+        deactivated = parse_boolean(request, "deactivated")
         locked = parse_boolean(request, "locked", default=False)
         admins = parse_boolean(request, "admins")
 
diff --git a/synapse/storage/databases/main/__init__.py b/synapse/storage/databases/main/__init__.py
index 394985d87f..bf779587d9 100644
--- a/synapse/storage/databases/main/__init__.py
+++ b/synapse/storage/databases/main/__init__.py
@@ -176,7 +176,7 @@ async def get_users_paginate(
         user_id: Optional[str] = None,
         name: Optional[str] = None,
         guests: bool = True,
-        deactivated: bool = False,
+        deactivated: Optional[bool] = None,
         admins: Optional[bool] = None,
         order_by: str = UserSortOrder.NAME.value,
         direction: Direction = Direction.FORWARDS,
@@ -232,8 +232,11 @@ def get_users_paginate_txn(
             if not guests:
                 filters.append("is_guest = 0")
 
-            if not deactivated:
-                filters.append("deactivated = 0")
+            if deactivated is not None:
+                if deactivated:
+                    filters.append("deactivated = 1")
+                else:
+                    filters.append("deactivated = 0")
 
             if not locked:
                 filters.append("locked IS FALSE")
diff --git a/tests/rest/admin/test_user.py b/tests/rest/admin/test_user.py
index 9265854223..5722c157b2 100644
--- a/tests/rest/admin/test_user.py
+++ b/tests/rest/admin/test_user.py
@@ -503,7 +503,7 @@ def test_all_users(self) -> None:
 
         channel = self.make_request(
             "GET",
-            self.url + "?deactivated=true",
+            self.url,
             {},
             access_token=self.admin_user_tok,
         )
@@ -982,6 +982,55 @@ def test_filter_admins(self) -> None:
         self.assertEqual(1, channel.json_body["total"])
         self.assertFalse(channel.json_body["users"][0]["admin"])
 
+    def test_filter_deactivated_users(self) -> None:
+        """
+        Tests whether the various values of the query parameter `deactivated` lead to the
+        expected result set.
+        """
+
+        # Register an additional non admin user
+        user_id = self.register_user("user", "pass", admin=False)
+
+        # Deactivate that user, requesting erasure.
+        deactivate_account_handler = self.hs.get_deactivate_account_handler()
+        self.get_success(
+            deactivate_account_handler.deactivate_account(
+                user_id, erase_data=True, requester=create_requester(user_id)
+            )
+        )
+
+        # Query all users
+        channel = self.make_request(
+            "GET",
+            f"{self.url}",
+            access_token=self.admin_user_tok,
+        )
+
+        self.assertEqual(200, channel.code, channel.result)
+        self.assertEqual(2, channel.json_body["total"])
+
+        # Query deactivated users
+        channel = self.make_request(
+            "GET",
+            f"{self.url}?deactivated=true",
+            access_token=self.admin_user_tok,
+        )
+
+        self.assertEqual(200, channel.code, channel.result)
+        self.assertEqual(1, channel.json_body["total"])
+        self.assertEqual("@user:test", channel.json_body["users"][0]["name"])
+
+        # Query deactivated users
+        channel = self.make_request(
+            "GET",
+            f"{self.url}?deactivated=false",
+            access_token=self.admin_user_tok,
+        )
+
+        self.assertEqual(200, channel.code, channel.result)
+        self.assertEqual(1, channel.json_body["total"])
+        self.assertEqual("@admin:test", channel.json_body["users"][0]["name"])
+
     @override_config(
         {
             "experimental_features": {
@@ -1130,7 +1179,7 @@ def test_erasure_status(self) -> None:
         # They should appear in the list users API, marked as not erased.
         channel = self.make_request(
             "GET",
-            self.url + "?deactivated=true",
+            self.url,
             access_token=self.admin_user_tok,
         )
         users = {user["name"]: user for user in channel.json_body["users"]}
@@ -1194,7 +1243,7 @@ def _order_test(
             dir: The direction of ordering to give the server
         """
 
-        url = self.url + "?deactivated=true&"
+        url = self.url + "?"
         if order_by is not None:
             url += "order_by=%s&" % (order_by,)
         if dir is not None and dir in ("b", "f"):

From 9f68a6809bd9c95d5856eb212c63de5cc27d486c Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Thu, 1 Feb 2024 10:16:12 +0100
Subject: [PATCH 02/13] Doclinks in the changelog adjusted.

---
 changelog.d/16874.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelog.d/16874.feature b/changelog.d/16874.feature
index f3f808f182..7192b199cc 100644
--- a/changelog.d/16874.feature
+++ b/changelog.d/16874.feature
@@ -1 +1 @@
-Query parameter `deactivated` of [List Accounts](https://matrix-org.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://matrix-org.github.io/synapse/v1.99/usage/administration/admin_api/index.html) refactored, to filter deactivated users in user queries.
\ No newline at end of file
+Query parameter `deactivated` of [List Accounts](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) refactored, to filter deactivated users in user queries.
\ No newline at end of file

From 0b6e3d6935aaaaca2b353e069eedd19b222184f1 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Fri, 23 Feb 2024 13:34:53 +0100
Subject: [PATCH 03/13] Changed behaviour of query parameter deactivated moved
 to UsersRestServletV3

---
 changelog.d/16874.feature        |  2 +-
 docs/admin_api/user_admin_api.md | 23 ++++++++++++++++++-----
 synapse/rest/admin/__init__.py   |  2 ++
 synapse/rest/admin/users.py      | 15 +++++++++++++--
 tests/rest/admin/test_user.py    |  9 +++++----
 5 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/changelog.d/16874.feature b/changelog.d/16874.feature
index 7192b199cc..3f8ee7095c 100644
--- a/changelog.d/16874.feature
+++ b/changelog.d/16874.feature
@@ -1 +1 @@
-Query parameter `deactivated` of [List Accounts](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) refactored, to filter deactivated users in user queries.
\ No newline at end of file
+Handling of the query parameter `deactivated` in [List Accounts (V3)](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) adjusted, to filter deactivated users in user queries.
\ No newline at end of file
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 26ca768eeb..0a52fe0684 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -163,7 +163,7 @@ Body parameters:
   not be changed. If `null` is given, the user type will be cleared.
   Other allowed options are: `bot` and `support`.
 
-## List Accounts
+## List Accounts (V2)
 
 This API returns all local user accounts.
 By default, the response is ordered by ascending user ID.
@@ -226,10 +226,8 @@ The following parameters should be set in the URL:
   Defaults to `true` to include guest users. This parameter is not supported when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
 - `admins` - Optional flag to filter admins. If `true`, only admins are queried. If `false`, admins are excluded from
   the query. When the flag is absent (the default), **both** admins and non-admins are included in the search results.
-- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried. 
-  If `false`, deactivated users are excluded from the query. When the flag is absent (the default), 
-  **both** active and deactivated users are included in the 
-  search results.
+- `deactivated` - string representing a bool - Is optional and if `true` will **include** deactivated users.
+  Defaults to `false` to exclude deactivated users.
 - `limit` - string representing a positive integer - Is optional but is used for pagination,
   denoting the maximum number of items to return in this call. Defaults to `100`.
 - `from` - string representing a positive integer - Is optional but used for pagination,
@@ -289,6 +287,21 @@ The following fields are returned in the JSON response body:
 
 *Added in Synapse 1.93:* the `locked` query parameter and response field.
 
+
+## List Accounts (V3)
+
+This API returns all local user accounts (see v2). In contrast to v2, the query parameter `deactivated` is handled differently.
+
+```
+GET /_synapse/admin/v3/users
+```
+
+**Parameters**
+- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried.
+  If `false`, deactivated users are excluded from the query. When the flag is absent (the default),
+  **both** active and deactivated users are included in the
+  search results.
+
 ## Query current sessions for a user
 
 This API returns information about the active sessions for a specific user.
diff --git a/synapse/rest/admin/__init__.py b/synapse/rest/admin/__init__.py
index 0e413f02ab..07e0fb71f2 100644
--- a/synapse/rest/admin/__init__.py
+++ b/synapse/rest/admin/__init__.py
@@ -109,6 +109,7 @@
     UserReplaceMasterCrossSigningKeyRestServlet,
     UserRestServletV2,
     UsersRestServletV2,
+    UsersRestServletV3,
     UserTokenRestServlet,
     WhoisRestServlet,
 )
@@ -289,6 +290,7 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
         UserTokenRestServlet(hs).register(http_server)
     UserRestServletV2(hs).register(http_server)
     UsersRestServletV2(hs).register(http_server)
+    UsersRestServletV3(hs).register(http_server)
     UserMediaStatisticsRestServlet(hs).register(http_server)
     LargestRoomsStatistics(hs).register(http_server)
     EventReportDetailRestServlet(hs).register(http_server)
diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index ae0c6bbdff..b6e3499d91 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -72,7 +72,7 @@ class UsersRestServletV2(RestServlet):
     The parameter `user_id` can be used to filter by user id.
     The parameter `name` can be used to filter by user id or display name.
     The parameter `guests` can be used to exclude guest users.
-    The parameter `deactivated` can be used to filter deactivated users.
+    The parameter `deactivated` can be used to include deactivated users.
     The parameter `order_by` can be used to order the result.
     The parameter `not_user_type` can be used to exclude certain user types.
     The parameter `locked` can be used to include locked users.
@@ -118,7 +118,8 @@ async def on_GET(self, request: SynapseRequest) -> Tuple[int, JsonDict]:
                 errcode=Codes.INVALID_PARAM,
             )
 
-        deactivated = parse_boolean(request, "deactivated")
+        deactivated = self.__parse_parameter_deactivated(request)
+
         locked = parse_boolean(request, "locked", default=False)
         admins = parse_boolean(request, "admins")
 
@@ -182,6 +183,16 @@ def _filter(a: attr.Attribute) -> bool:
 
         return HTTPStatus.OK, ret
 
+    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+        return None if parse_boolean(request, "deactivated") else False
+
+
+class UsersRestServletV3(UsersRestServletV2):
+    PATTERNS = admin_patterns("/users$", "v3")
+
+    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+        return parse_boolean(request, "deactivated")
+
 
 class UserRestServletV2(RestServlet):
     PATTERNS = admin_patterns("/users/(?P<user_id>[^/]*)$", "v2")
diff --git a/tests/rest/admin/test_user.py b/tests/rest/admin/test_user.py
index 5722c157b2..54f05f342b 100644
--- a/tests/rest/admin/test_user.py
+++ b/tests/rest/admin/test_user.py
@@ -503,7 +503,7 @@ def test_all_users(self) -> None:
 
         channel = self.make_request(
             "GET",
-            self.url,
+            self.url + "?deactivated=true",
             {},
             access_token=self.admin_user_tok,
         )
@@ -987,6 +987,7 @@ def test_filter_deactivated_users(self) -> None:
         Tests whether the various values of the query parameter `deactivated` lead to the
         expected result set.
         """
+        users_url_v3 = self.url.replace("v2", "v3")
 
         # Register an additional non admin user
         user_id = self.register_user("user", "pass", admin=False)
@@ -1002,7 +1003,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query all users
         channel = self.make_request(
             "GET",
-            f"{self.url}",
+            users_url_v3,
             access_token=self.admin_user_tok,
         )
 
@@ -1012,7 +1013,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query deactivated users
         channel = self.make_request(
             "GET",
-            f"{self.url}?deactivated=true",
+            f"{users_url_v3}?deactivated=true",
             access_token=self.admin_user_tok,
         )
 
@@ -1023,7 +1024,7 @@ def test_filter_deactivated_users(self) -> None:
         # Query deactivated users
         channel = self.make_request(
             "GET",
-            f"{self.url}?deactivated=false",
+            f"{users_url_v3}?deactivated=false",
             access_token=self.admin_user_tok,
         )
 

From 5c305a00f8521ad74a611426241c3303530510c0 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Fri, 23 Feb 2024 13:44:46 +0100
Subject: [PATCH 04/13] Remove empty line.

---
 docs/admin_api/user_admin_api.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 0a52fe0684..70a9638e96 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -287,7 +287,6 @@ The following fields are returned in the JSON response body:
 
 *Added in Synapse 1.93:* the `locked` query parameter and response field.
 
-
 ## List Accounts (V3)
 
 This API returns all local user accounts (see v2). In contrast to v2, the query parameter `deactivated` is handled differently.

From 53a777ae64ac5ee4264887567888edd9c1e59e38 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Fri, 23 Feb 2024 15:39:14 +0100
Subject: [PATCH 05/13] - __parse_parameter_deactivated renamed to
 _parse_parameter_deactivated - 16874.feature: link fixed.

---
 changelog.d/16874.feature        | 2 +-
 docs/admin_api/user_admin_api.md | 5 +++--
 synapse/rest/admin/users.py      | 6 +++---
 tests/rest/admin/test_user.py    | 6 +++---
 4 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/changelog.d/16874.feature b/changelog.d/16874.feature
index 3f8ee7095c..d428b0ae45 100644
--- a/changelog.d/16874.feature
+++ b/changelog.d/16874.feature
@@ -1 +1 @@
-Handling of the query parameter `deactivated` in [List Accounts (V3)](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) adjusted, to filter deactivated users in user queries.
\ No newline at end of file
+Handling of the query parameter `deactivated` in [List Accounts](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) adjusted, to filter deactivated users in user queries.
\ No newline at end of file
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 70a9638e96..a97acd802a 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -163,7 +163,8 @@ Body parameters:
   not be changed. If `null` is given, the user type will be cleared.
   Other allowed options are: `bot` and `support`.
 
-## List Accounts (V2)
+## List Accounts
+### List Accounts (V2)
 
 This API returns all local user accounts.
 By default, the response is ordered by ascending user ID.
@@ -287,7 +288,7 @@ The following fields are returned in the JSON response body:
 
 *Added in Synapse 1.93:* the `locked` query parameter and response field.
 
-## List Accounts (V3)
+### List Accounts (V3)
 
 This API returns all local user accounts (see v2). In contrast to v2, the query parameter `deactivated` is handled differently.
 
diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index b6e3499d91..3ecacc566d 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -118,7 +118,7 @@ async def on_GET(self, request: SynapseRequest) -> Tuple[int, JsonDict]:
                 errcode=Codes.INVALID_PARAM,
             )
 
-        deactivated = self.__parse_parameter_deactivated(request)
+        deactivated = self._parse_parameter_deactivated(request)
 
         locked = parse_boolean(request, "locked", default=False)
         admins = parse_boolean(request, "admins")
@@ -183,14 +183,14 @@ def _filter(a: attr.Attribute) -> bool:
 
         return HTTPStatus.OK, ret
 
-    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+    def _parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
         return None if parse_boolean(request, "deactivated") else False
 
 
 class UsersRestServletV3(UsersRestServletV2):
     PATTERNS = admin_patterns("/users$", "v3")
 
-    def __parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+    def _parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
         return parse_boolean(request, "deactivated")
 
 
diff --git a/tests/rest/admin/test_user.py b/tests/rest/admin/test_user.py
index 54f05f342b..cb208ead57 100644
--- a/tests/rest/admin/test_user.py
+++ b/tests/rest/admin/test_user.py
@@ -503,7 +503,7 @@ def test_all_users(self) -> None:
 
         channel = self.make_request(
             "GET",
-            self.url + "?deactivated=true",
+            f"{self.url}?deactivated=true",
             {},
             access_token=self.admin_user_tok,
         )
@@ -1180,7 +1180,7 @@ def test_erasure_status(self) -> None:
         # They should appear in the list users API, marked as not erased.
         channel = self.make_request(
             "GET",
-            self.url,
+            f"{self.url}?deactivated=true",
             access_token=self.admin_user_tok,
         )
         users = {user["name"]: user for user in channel.json_body["users"]}
@@ -1244,7 +1244,7 @@ def _order_test(
             dir: The direction of ordering to give the server
         """
 
-        url = self.url + "?"
+        url = f"{self.url}?deactivated=true&"
         if order_by is not None:
             url += "order_by=%s&" % (order_by,)
         if dir is not None and dir in ("b", "f"):

From 01af9ab480f890c25a7f3cbbab23d909afe4c308 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Fri, 23 Feb 2024 15:49:24 +0100
Subject: [PATCH 06/13] Linter errors fixed.

---
 synapse/rest/admin/users.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index 3ecacc566d..013ab884a4 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -23,7 +23,7 @@
 import logging
 import secrets
 from http import HTTPStatus
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
 
 import attr
 
@@ -183,14 +183,18 @@ def _filter(a: attr.Attribute) -> bool:
 
         return HTTPStatus.OK, ret
 
-    def _parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+    def _parse_parameter_deactivated(
+        self, request: SynapseRequest
+    ) -> Union[bool, None]:
         return None if parse_boolean(request, "deactivated") else False
 
 
 class UsersRestServletV3(UsersRestServletV2):
     PATTERNS = admin_patterns("/users$", "v3")
 
-    def _parse_parameter_deactivated(self, request: SynapseRequest) -> bool | None:
+    def _parse_parameter_deactivated(
+        self, request: SynapseRequest
+    ) -> Union[bool, None]:
         return parse_boolean(request, "deactivated")
 
 

From bbf65281f6821a1cc12bdd61508c4d3a0d097e5d Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:51:39 +0100
Subject: [PATCH 07/13] Update synapse/rest/admin/users.py

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 synapse/rest/admin/users.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index 013ab884a4..38f6815b6e 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -185,7 +185,7 @@ def _filter(a: attr.Attribute) -> bool:
 
     def _parse_parameter_deactivated(
         self, request: SynapseRequest
-    ) -> Union[bool, None]:
+    ) -> Optional[bool]:
         return None if parse_boolean(request, "deactivated") else False
 
 

From 189e3850b6cddeeb9b71cb29dc589c9d2d7da8b4 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:52:32 +0100
Subject: [PATCH 08/13] Update docs/admin_api/user_admin_api.md

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 docs/admin_api/user_admin_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index a97acd802a..25dbe2844a 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -297,7 +297,7 @@ GET /_synapse/admin/v3/users
 ```
 
 **Parameters**
-- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are queried.
+- `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are returned.
   If `false`, deactivated users are excluded from the query. When the flag is absent (the default),
   **both** active and deactivated users are included in the
   search results.

From 9d0aedee85ac54e7a3abacf9156faa7bcd1c6c26 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:53:14 +0100
Subject: [PATCH 09/13] Update docs/admin_api/user_admin_api.md

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 docs/admin_api/user_admin_api.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 25dbe2844a..9736fe3021 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -299,8 +299,7 @@ GET /_synapse/admin/v3/users
 **Parameters**
 - `deactivated` - Optional flag to filter deactivated users. If `true`, only deactivated users are returned.
   If `false`, deactivated users are excluded from the query. When the flag is absent (the default),
-  **both** active and deactivated users are included in the
-  search results.
+  users are not filtered by deactivation status.
 
 ## Query current sessions for a user
 

From e2ef77b8229147efdc1ec8f48987d6541d91e282 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:54:09 +0100
Subject: [PATCH 10/13] Update synapse/rest/admin/users.py

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 synapse/rest/admin/users.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index 38f6815b6e..fe1c447104 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -186,6 +186,10 @@ def _filter(a: attr.Attribute) -> bool:
     def _parse_parameter_deactivated(
         self, request: SynapseRequest
     ) -> Optional[bool]:
+        """
+        Return None (no filtering) if `deactivated` is `true`, otherwise return `False`
+        (exclude deactivated users from the results).
+        """
         return None if parse_boolean(request, "deactivated") else False
 
 

From c705a1a9a0642f5bbef884d974aef81c0aa82255 Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:54:37 +0100
Subject: [PATCH 11/13] Update tests/rest/admin/test_user.py

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 tests/rest/admin/test_user.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/rest/admin/test_user.py b/tests/rest/admin/test_user.py
index cb208ead57..c5da1e9686 100644
--- a/tests/rest/admin/test_user.py
+++ b/tests/rest/admin/test_user.py
@@ -1021,7 +1021,7 @@ def test_filter_deactivated_users(self) -> None:
         self.assertEqual(1, channel.json_body["total"])
         self.assertEqual("@user:test", channel.json_body["users"][0]["name"])
 
-        # Query deactivated users
+        # Query non-deactivated users
         channel = self.make_request(
             "GET",
             f"{users_url_v3}?deactivated=false",

From 48276fa6571fb78088ec2651d5703715fb28b7ea Mon Sep 17 00:00:00 2001
From: Alexander Fechler <141915399+afechler@users.noreply.github.com>
Date: Mon, 4 Mar 2024 11:55:20 +0100
Subject: [PATCH 12/13] Update changelog.d/16874.feature

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 changelog.d/16874.feature | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelog.d/16874.feature b/changelog.d/16874.feature
index d428b0ae45..6e5afdde3b 100644
--- a/changelog.d/16874.feature
+++ b/changelog.d/16874.feature
@@ -1 +1 @@
-Handling of the query parameter `deactivated` in [List Accounts](https://element-hq.github.io/synapse/v1.99/admin_api/user_admin_api.html#list-accounts) [admin API](https://element-hq.github.io/synapse/v1.99/usage/administration/admin_api/index.html) adjusted, to filter deactivated users in user queries.
\ No newline at end of file
+Add a new [List Accounts v3](https://element-hq.github.io/synapse/v1.103/admin_api/user_admin_api.html#list-accounts-v3) Admin API with improved deactivated user filtering capabilities.
\ No newline at end of file

From 2e85bc2cd387e48c071cecf944e26925ec849a0b Mon Sep 17 00:00:00 2001
From: Alexander Fechler <alexander.fechler@bwi.de>
Date: Mon, 4 Mar 2024 14:47:42 +0100
Subject: [PATCH 13/13] Linting error fixed.

---
 synapse/rest/admin/users.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/synapse/rest/admin/users.py b/synapse/rest/admin/users.py
index fe1c447104..a9645e4af7 100644
--- a/synapse/rest/admin/users.py
+++ b/synapse/rest/admin/users.py
@@ -183,9 +183,7 @@ def _filter(a: attr.Attribute) -> bool:
 
         return HTTPStatus.OK, ret
 
-    def _parse_parameter_deactivated(
-        self, request: SynapseRequest
-    ) -> Optional[bool]:
+    def _parse_parameter_deactivated(self, request: SynapseRequest) -> Optional[bool]:
         """
         Return None (no filtering) if `deactivated` is `true`, otherwise return `False`
         (exclude deactivated users from the results).