admin filter for user listing

the admin filter is a tri-state, meaning it can filter for admins,
filter for non-admins, and not filter at all.

available since synapse 1.91.0
(https://github.com/matrix-org/synapse/releases/tag/v1.91.0)

fixes #122

References: #122

synadm/api.py

@@ -415,7 +415,7 @@ def __init__(self, log, user, token, base_url, admin_path, timeout, debug,
         self.user = user
 
     def user_list(self, _from, _limit, _guests, _deactivated,
-                  _name, _user_id):
+                  _name, _user_id, _admin=None):
         """List and search users
 
         Args:
@@ -426,19 +426,24 @@ def user_list(self, _from, _limit, _guests, _deactivated,
             _name (string): user name localpart to search for, see Synapse
                 admin API docs for details
             _user_id (string): fully qualified Matrix user ID to search for
+            _admin (bool or None): whether to filter for admins. a None
+                does not filter.
 
         Returns:
             string: JSON string containing the found users
         """
-        return self.query("get", "v2/users", params={
+        params = {
             "from": _from,
             "limit": _limit,
             "guests": (str(_guests).lower() if isinstance(_guests, bool)
                        else None),
             "deactivated": "true" if _deactivated else None,
             "name": _name,
             "user_id": _user_id
-        })
+        }
+        if _admin is not None:
+            params["admins"] = str(_admin).lower()
+        return self.query("get", "v2/users", params=params)
 
     def user_list_paginate(self, _limit, _guests, _deactivated,
                            _name, _user_id, _from="0"):

synadm/cli/user.py

@@ -53,6 +53,16 @@ def user():
 @click.option(
     "--deactivated", "-d", is_flag=True, default=False,
     help="Also show deactivated/erased users", show_default=True)
+@optgroup.group(
+    "Admin filtering options",
+    cls=MutuallyExclusiveOptionGroup,
+    help="Whether to filter for admins, or non-admins.")
+@optgroup.option(
+    "--admins", "-a", is_flag=True,
+    help="Filter for admins")
+@optgroup.option(
+    "--non-admins", is_flag=True,
+    help="Filter for non admins")
 @optgroup.group(
     "Search options",
     cls=MutuallyExclusiveOptionGroup,
@@ -67,12 +77,19 @@ def user():
     help="""Search users by ID - filters to only return users with Matrix IDs
     (@user:server) that contain this value""")
 @click.pass_obj
-def list_user_cmd(helper, from_, limit, guests, deactivated, name, user_id):
+def list_user_cmd(helper, from_, limit, guests, deactivated, name, user_id,
+                  admins, non_admins):
     """ List users, search for users.
     """
+    admin_filter = None
+    if admins:
+        admin_filter = True
+    if non_admins:
+        admin_filter = False
+
     mxid = helper.generate_mxid(user_id)
     users = helper.api.user_list(from_, limit, guests, deactivated, name,
-                                 mxid)
+                                 mxid, admin_filter)
     if users is None:
         click.echo("Users could not be fetched.")
         raise SystemExit(1)