WIP actions/sync_gws_mailing_lists.py

actions/sync_gws_mailing_lists.py

@@ -1,9 +1,7 @@
 """
 Synchronize/update memberships of Google Workspace mailing groups/lists
-to match their corresponding Keycloak "mail groups".
-
-First, some nomenclature. A Keycloak group is a " mail group" if and only
-if it is a direct subgroup of the /mail group.
+to match their corresponding Keycloak "mail groups". A Keycloak group is
+a " mail group" if and only if it is a direct subgroup of the /mail group.
 
 In order to be operated on by this script, mail groups must define attribute
 `email` to match them to the corresponding Google Workspace mailing group/list.
@@ -15,14 +13,13 @@
 list. This is to support such use patterns as:
  - A mail group membership is managed by an automated process, but the
     corresponding mailing list needs to have some extra members that the
-    process doesn't recognize.
+    process doesn't handle.
  - A subgroup of a mail group is automatically managed, for example when
     policy requires members of one group to also be members of another group.
 
-Furthermore, all recursive subgroups called "_admin" and "_managers" will be
-subscribed as managers. The special group _managers is needed to designate
-users with role MANAGER for groups that are automatically generated (and
-therefore can't have an _admin subgroup).
+Members of subgroups called "_admin" and "_managers" will have assigned role
+'MANAGER'. The magic group "_managers" is needed to designate managers for groups
+that are automatically generated (and therefore can't have an _admin subgroup).
 
 Users are subscribed to Google Workspace groups using their KeyCloak
 `canonical_email` attribute, unless it is overridden by `mailing_list_email`.
@@ -73,28 +70,28 @@
 
 from actions.util import retry_execute, group_tree_to_list, reflow_text
 
-logger = logging.getLogger('sync_gws_mailing_lists')
+ACTION_ID = 'sync_gws_mailing_lists'
+logger = logging.getLogger(ACTION_ID)
 
 # Paragraph separator. Used for re-flowing text.
 PARA_SEP = "\n\n"
 
-MESSAGE_FOOTER = """
-This message was generated by the sync_gws_mailing_lists
+MESSAGE_FOOTER = f"""This message was generated by the {ACTION_ID}
 robot. Please contact [email protected] for support and feedback."""
 
-NONE_EXPLANATION = """Note: delivery option NONE is used for IceCube
-addresses of individuals who subscribe to mailing lists with non-IceCube
-emails. This allows using https://groups.google.com with the IceCube
+NONE_EXPLANATION = """Note: delivery mode NONE is used for IceCube
+emails of individuals who subscribe to mailing lists with non-IceCube
+addresses. This allows using https://groups.google.com with the IceCube
 account without receiving duplicate emails."""
 
 SUBSCRIPTION_MESSAGE = ("""You have been subscribed to {group_email} mailing
 list as {email} with role {role} and delivery mode {delivery} because you
 are a member of group(s) {qualifying_groups}.{none_explanation}"""
                         + PARA_SEP + MESSAGE_FOOTER)
 
-ROLE_CHANGE_MESSAGE = ("""The role of {email} in {group_email} has changed from
-{old_role} to {new_role} because of membership change involving a subgroup of
-{group_path}.""" + PARA_SEP + MESSAGE_FOOTER)
+ROLE_CHANGE_MESSAGE = ("""The role of {email} in {group_email} mailing list
+has changed from {old_role} to {new_role} because of membership change involving
+a managerial subgroup of {group_path}.""" + PARA_SEP + MESSAGE_FOOTER)
 
 UNSUBSCRIPTION_MESSAGE = ("""{email} has been unsubscribed from {group_email}
 mailing list because either you are no longer a member of {group_path} and its