📶 User sync signal

Author: danyi1212

docs/source/index.rst

@@ -45,6 +45,7 @@ Features
    reference/settings_reference
    reference/ldap_settings
    reference/decorators
+   reference/signals
    reference/models
    reference/management_commands
    reference/change_log

docs/source/reference/signals.rst

@@ -0,0 +1,32 @@
+
+Signals
+=======
+
+ldap_user_sync
+--------------
+
+Whenever a user is synced against LDAP, pre-saving.
+
+Arguments:
+    * **sender** The LDAPUser instance that is being synced.
+    * **ldap_user** The ``ldap3`` Entry instance received from LDAP server of the user being synced
+    * **group_reader** Reader cursor for all the user's groups, already queried.
+
+Example:
+
+.. code-block:: python
+
+    from django.dispatch import receiver
+    from ldap3 import Entry, Reader
+
+    from windows_auth.models import LDAPUser
+    from windows_auth.signals import ldap_user_sync
+
+
+    @receiver(ldap_user_sync)
+    def on_ldap_sync(sender: LDAPUser, ldap_user: Entry = None, group_reader: Reader = None):
+        # do something...
+        pass
+
+.. warning::
+    Any unhandled exception raised during the signal will terminate the sync process.

windows_auth/models.py

@@ -10,6 +10,7 @@
 from windows_auth import logger
 from windows_auth.conf import WAUTH_USE_CACHE, WAUTH_USE_SPN, WAUTH_LOWERCASE_USERNAME
 from windows_auth.ldap import LDAPManager, get_ldap_manager
+from windows_auth.signals import ldap_user_sync
 from windows_auth.utils import LogExecutionTime
 
 
@@ -201,6 +202,9 @@ def sync(self) -> None:
             with LogExecutionTime(f"Perform field updates for user {self}"):
                 get_user_model().objects.filter(pk=self.user.pk).update(**updated_fields)
 
+        # send signals
+        ldap_user_sync.send(self, ldap_user=ldap_user, group_reader=group_reader)
+
         # update sync time
         if not WAUTH_USE_CACHE:
             with LogExecutionTime(f"Save LDAP User {self}"):

windows_auth/signals.py

@@ -0,0 +1,3 @@
+from django.dispatch import Signal
+
+ldap_user_sync = Signal()