django-bulk-hooks 0.1.280__py3-none-any.whl → 0.2.1__py3-none-any.whl

django_bulk_hooks/registry.py

@@ -1,41 +1,288 @@
+"""
+Central registry for hook handlers.
+
+Provides thread-safe registration and lookup of hooks with
+deterministic priority ordering.
+"""
+
 import logging
+import threading
 from collections.abc import Callable
-from typing import Union
+from typing import Dict, List, Optional, Tuple, Type, Union
 
-from django_bulk_hooks.priority import Priority
+from django_bulk_hooks.enums import Priority
 
 logger = logging.getLogger(__name__)
 
-_hooks: dict[tuple[type, str], list[tuple[type, str, Callable, int]]] = {}
+# Type alias for hook info tuple
+HookInfo = Tuple[Type, str, Optional[Callable], int]
+
+
+class HookRegistry:
+    """
+    Central registry for all hook handlers.
+
+    Manages registration, lookup, and lifecycle of hooks with
+    thread-safe operations and deterministic ordering by priority.
+
+    This is a singleton - use get_registry() to access the instance.
+    """
+
+    def __init__(self):
+        """Initialize an empty registry with thread-safe storage."""
+        self._hooks: Dict[Tuple[Type, str], List[HookInfo]] = {}
+        self._lock = threading.RLock()
+
+    def register(
+        self,
+        model: Type,
+        event: str,
+        handler_cls: Type,
+        method_name: str,
+        condition: Optional[Callable],
+        priority: Union[int, Priority],
+    ) -> None:
+        """
+        Register a hook handler for a model and event.
+
+        Args:
+            model: Django model class
+            event: Event name (e.g., 'after_update', 'before_create')
+            handler_cls: Hook handler class
+            method_name: Name of the method to call on handler
+            condition: Optional condition to filter records
+            priority: Execution priority (lower values execute first)
+        """
+        with self._lock:
+            key = (model, event)
+            hooks = self._hooks.setdefault(key, [])
+
+            # Check for duplicates before adding
+            hook_info = (handler_cls, method_name, condition, priority)
+            if hook_info not in hooks:
+                hooks.append(hook_info)
+                # Sort by priority (lower values first)
+                hooks.sort(key=lambda x: x[3])
+                logger.debug(
+                    f"Registered {handler_cls.__name__}.{method_name} "
+                    f"for {model.__name__}.{event} (priority={priority})"
+                )
+            else:
+                logger.debug(
+                    f"Hook {handler_cls.__name__}.{method_name} "
+                    f"already registered for {model.__name__}.{event}"
+                )
+
+    def get_hooks(self, model: Type, event: str) -> List[HookInfo]:
+        """
+        Get all hooks for a model and event.
+
+        Args:
+            model: Django model class
+            event: Event name
+
+        Returns:
+            List of hook info tuples (handler_cls, method_name, condition, priority)
+            sorted by priority (lower values first)
+        """
+        with self._lock:
+            key = (model, event)
+            hooks = self._hooks.get(key, [])
+
+            # Only log when hooks are found or for specific events to reduce noise
+            if hooks or event in [
+                "after_update",
+                "before_update",
+                "after_create",
+                "before_create",
+            ]:
+                logger.debug(
+                    f"get_hooks {model.__name__}.{event} found {len(hooks)} hooks"
+                )
+
+            return hooks
+
+    def unregister(
+        self, model: Type, event: str, handler_cls: Type, method_name: str
+    ) -> None:
+        """
+        Unregister a specific hook handler.
+
+        Used when child classes override parent hook methods.
+
+        Args:
+            model: Django model class
+            event: Event name
+            handler_cls: Hook handler class to remove
+            method_name: Method name to remove
+        """
+        with self._lock:
+            key = (model, event)
+            if key not in self._hooks:
+                return
+
+            hooks = self._hooks[key]
+            # Filter out the specific hook
+            self._hooks[key] = [
+                (h_cls, m_name, cond, pri)
+                for h_cls, m_name, cond, pri in hooks
+                if not (h_cls == handler_cls and m_name == method_name)
+            ]
+
+            # Clean up empty hook lists
+            if not self._hooks[key]:
+                del self._hooks[key]
+
+            logger.debug(
+                f"Unregistered {handler_cls.__name__}.{method_name} "
+                f"for {model.__name__}.{event}"
+            )
+
+    def clear(self) -> None:
+        """
+        Clear all registered hooks.
+
+        Useful for testing to ensure clean state between tests.
+        """
+        with self._lock:
+            self._hooks.clear()
+
+            # Also clear HookMeta state to ensure complete reset
+            from django_bulk_hooks.handler import HookMeta
+
+            HookMeta._registered.clear()
+            HookMeta._class_hook_map.clear()
+
+            logger.debug("Cleared all registered hooks")
 
+    def list_all(self) -> Dict[Tuple[Type, str], List[HookInfo]]:
+        """
+        Get all registered hooks for debugging.
 
+        Returns:
+            Dictionary mapping (model, event) tuples to lists of hook info
+        """
+        with self._lock:
+            return dict(self._hooks)
+
+    def count_hooks(
+        self, model: Optional[Type] = None, event: Optional[str] = None
+    ) -> int:
+        """
+        Count registered hooks, optionally filtered by model and/or event.
+
+        Args:
+            model: Optional model class to filter by
+            event: Optional event name to filter by
+
+        Returns:
+            Number of matching hooks
+        """
+        with self._lock:
+            if model is None and event is None:
+                # Count all hooks
+                return sum(len(hooks) for hooks in self._hooks.values())
+            elif model is not None and event is not None:
+                # Count hooks for specific model and event
+                return len(self._hooks.get((model, event), []))
+            elif model is not None:
+                # Count all hooks for a model
+                return sum(
+                    len(hooks)
+                    for (m, _), hooks in self._hooks.items()
+                    if m == model
+                )
+            else:  # event is not None
+                # Count all hooks for an event
+                return sum(
+                    len(hooks)
+                    for (_, e), hooks in self._hooks.items()
+                    if e == event
+                )
+
+
+# Global singleton registry
+_registry: Optional[HookRegistry] = None
+_registry_lock = threading.Lock()
+
+
+def get_registry() -> HookRegistry:
+    """
+    Get the global hook registry instance.
+
+    Creates the registry on first access (singleton pattern).
+    Thread-safe initialization.
+
+    Returns:
+        HookRegistry singleton instance
+    """
+    global _registry
+
+    if _registry is None:
+        with _registry_lock:
+            # Double-checked locking
+            if _registry is None:
+                _registry = HookRegistry()
+
+    return _registry
+
+
+# Backward-compatible module-level functions
 def register_hook(
-    model, event, handler_cls, method_name, condition, priority: Union[int, Priority]
-):
-    key = (model, event)
-    hooks = _hooks.setdefault(key, [])
-    hooks.append((handler_cls, method_name, condition, priority))
-    # Sort by priority (lower values first)
-    hooks.sort(key=lambda x: x[3])
-    logger.debug(f"Registered {handler_cls.__name__}.{method_name} for {model.__name__}.{event}")
-
-
-def get_hooks(model, event):
-    key = (model, event)
-    hooks = _hooks.get(key, [])
-    # Only log when hooks are found or for specific events to reduce noise
-    if hooks or event in ['after_update', 'before_update', 'after_create', 'before_create']:
-        logger.debug(f"get_hooks {model.__name__}.{event} found {len(hooks)} hooks")
-    return hooks
-
-
-def clear_hooks():
-    """Clear all registered hooks. Useful for testing."""
-    global _hooks
-    _hooks.clear()
-    logger.debug("Cleared all registered hooks")
-
-
-def list_all_hooks():
-    """Debug function to list all registered hooks"""
-    return _hooks
+    model: Type,
+    event: str,
+    handler_cls: Type,
+    method_name: str,
+    condition: Optional[Callable],
+    priority: Union[int, Priority],
+) -> None:
+    """
+    Register a hook handler (backward-compatible function).
+
+    Delegates to the global registry instance.
+    """
+    registry = get_registry()
+    registry.register(model, event, handler_cls, method_name, condition, priority)
+
+
+def get_hooks(model: Type, event: str) -> List[HookInfo]:
+    """
+    Get hooks for a model and event (backward-compatible function).
+
+    Delegates to the global registry instance.
+    """
+    registry = get_registry()
+    return registry.get_hooks(model, event)
+
+
+def unregister_hook(
+    model: Type, event: str, handler_cls: Type, method_name: str
+) -> None:
+    """
+    Unregister a hook handler (backward-compatible function).
+
+    Delegates to the global registry instance.
+    """
+    registry = get_registry()
+    registry.unregister(model, event, handler_cls, method_name)
+
+
+def clear_hooks() -> None:
+    """
+    Clear all registered hooks (backward-compatible function).
+
+    Delegates to the global registry instance.
+    Useful for testing.
+    """
+    registry = get_registry()
+    registry.clear()
+
+
+def list_all_hooks() -> Dict[Tuple[Type, str], List[HookInfo]]:
+    """
+    List all registered hooks (backward-compatible function).
+
+    Delegates to the global registry instance.
+    """
+    registry = get_registry()
+    return registry.list_all()

{django_bulk_hooks-0.1.280.dist-info → django_bulk_hooks-0.2.1.dist-info}/METADATA

@@ -1,8 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.280
+Version: 0.2.1
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
-Home-page: https://github.com/AugendLimited/django-bulk-hooks
 License: MIT
 Keywords: django,bulk,hooks
 Author: Konrad Beck
@@ -14,6 +13,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: django (>=5.2.0,<6.0.0)
+Project-URL: Homepage, https://github.com/AugendLimited/django-bulk-hooks
 Project-URL: Repository, https://github.com/AugendLimited/django-bulk-hooks
 Description-Content-Type: text/markdown
 
@@ -84,39 +84,39 @@ class AccountHooks(Hook):
 
 ### Individual Model Operations
 
-The `HookModelMixin` automatically triggers hooks for individual model operations:
+The `HookModelMixin` automatically hooks hooks for individual model operations:
 
 ```python
-# These will trigger BEFORE_CREATE and AFTER_CREATE hooks
+# These will hook BEFORE_CREATE and AFTER_CREATE hooks
 account = Account.objects.create(balance=100.00)
 account.save()  # for new instances
 
-# These will trigger BEFORE_UPDATE and AFTER_UPDATE hooks
+# These will hook BEFORE_UPDATE and AFTER_UPDATE hooks
 account.balance = 200.00
 account.save()  # for existing instances
 
-# This will trigger BEFORE_DELETE and AFTER_DELETE hooks
+# This will hook BEFORE_DELETE and AFTER_DELETE hooks
 account.delete()
 ```
 
 ### Bulk Operations
 
-Bulk operations also trigger the same hooks:
+Bulk operations also hook the same hooks:
 
 ```python
-# Bulk create - triggers BEFORE_CREATE and AFTER_CREATE hooks
+# Bulk create - hooks BEFORE_CREATE and AFTER_CREATE hooks
 accounts = [
     Account(balance=100.00),
     Account(balance=200.00),
 ]
 Account.objects.bulk_create(accounts)
 
-# Bulk update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Bulk update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 for account in accounts:
     account.balance *= 1.1
 Account.objects.bulk_update(accounts)  # fields are auto-detected
 
-# Bulk delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Bulk delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.bulk_delete(accounts)
 ```
 
@@ -125,10 +125,10 @@ Account.objects.bulk_delete(accounts)
 Queryset operations are also supported:
 
 ```python
-# Queryset update - triggers BEFORE_UPDATE and AFTER_UPDATE hooks
+# Queryset update - hooks BEFORE_UPDATE and AFTER_UPDATE hooks
 Account.objects.update(balance=0.00)
 
-# Queryset delete - triggers BEFORE_DELETE and AFTER_DELETE hooks
+# Queryset delete - hooks BEFORE_DELETE and AFTER_DELETE hooks
 Account.objects.delete()
 ```
 
@@ -180,7 +180,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 - **NEW**: Individual model lifecycle hooks that work with `save()` and `delete()`
 - Scalable performance via chunking (default 200)
 - Support for `@hook` decorators and centralized hook classes
-- **NEW**: Automatic hook triggering for admin operations and other Django features
+- **NEW**: Automatic hook hooking for admin operations and other Django features
 - **NEW**: Proper ordering guarantees for old/new record pairing in hooks (Salesforce-like behavior)
 
 ## 📦 Usage Examples
@@ -188,7 +188,7 @@ Django's `bulk_` methods bypass signals and `save()`. This package fills that ga
 ### Individual Model Operations
 
 ```python
-# These automatically trigger hooks
+# These automatically hook hooks
 account = Account.objects.create(balance=100.00)
 account.balance = 200.00
 account.save()
@@ -198,7 +198,7 @@ account.delete()
 ### Bulk Operations
 
 ```python
-# These also trigger hooks
+# These also hook hooks
 Account.objects.bulk_create(accounts)
 Account.objects.bulk_update(accounts)  # fields are auto-detected
 Account.objects.bulk_delete(accounts)
@@ -256,6 +256,13 @@ class MyManager(BulkHookManager, QueryablePropertiesManager):
 
 This approach uses the industry-standard injection pattern, similar to how `QueryablePropertiesManager` works, ensuring both functionalities work seamlessly together without any framework-specific knowledge.
 
+Framework needs to:
+Register these methods
+Know when to execute them (BEFORE_UPDATE, AFTER_UPDATE)
+Execute them in priority order
+Pass ChangeSet to them
+Handle errors (rollback on failure)
+
 ## 📝 License
 
 MIT © 2024 Augend / Konrad Beck

django_bulk_hooks-0.2.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+django_bulk_hooks/__init__.py,sha256=4QlWY5rqR9o2ddrNB-ypM4s1GtNJ1ZvL2ABhybaPpio,1823
+django_bulk_hooks/changeset.py,sha256=WALeiWDcjOBNdCKeidVKOPKAySKj9ZOvUJ-kWaVZYhM,7444
+django_bulk_hooks/conditions.py,sha256=tNnQZvcR-jOB8ZzpoVd03PVIy8rjiFdzmufD5mP7fTg,8107
+django_bulk_hooks/constants.py,sha256=PxpEETaO6gdENcTPoXS586lerGKVP3nmjpDvOkmhYxI,509
+django_bulk_hooks/context.py,sha256=mqaC5-yESDTA5ruI7fuXlt8qSgKuOFp0mjq7h1-4HdQ,1926
+django_bulk_hooks/debug_utils.py,sha256=6T32E_Pms6gbCl94A55fJAe_ynFsK_CJBTaPcsG8tik,4578
+django_bulk_hooks/decorators.py,sha256=UXvQ_tlEbHpmafLG2LZ9WsrvvoQlVACs8aNe8UrtPFE,9601
+django_bulk_hooks/dispatcher.py,sha256=L5_hSqENuKXDftJOdMetfjdZkiakUgkheqU8HpWKaOI,8214
+django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
+django_bulk_hooks/factory.py,sha256=JmjQiJPfAnytXrO6r6qOadX5yX0-sfpbZ9V8nwX3MAg,20013
+django_bulk_hooks/handler.py,sha256=2-k0GPWGSQ6acfvV0qJgDH8aa0z51DqdpX5vSJ6Uawk,4759
+django_bulk_hooks/helpers.py,sha256=Yopvl588VbKOi2kHEsQcEcI5jw5jiNA2MuF6Ce1VP0c,3174
+django_bulk_hooks/manager.py,sha256=3mFzB0ZzHHeXWdKGObZD_H0NlskHJc8uYBF69KKdAXU,4068
+django_bulk_hooks/models.py,sha256=62tn5wL55EjJVOsZofMluhEJB8bH7CzBvH0vd214_RY,2570
+django_bulk_hooks/operations/__init__.py,sha256=5L5NnwiFw8Yn5WO6-38eGdCYBkA0URpwyDcAdeYfc5w,550
+django_bulk_hooks/operations/analyzer.py,sha256=S9qcLRM_VBR6Cy_ObUq0Mok8bp07ALLPDF_S0Yypi2k,6507
+django_bulk_hooks/operations/bulk_executor.py,sha256=Xxv-BuLfX14-daSRPBkrMQgwgXBXbC0dcWTcMNlNjXs,4737
+django_bulk_hooks/operations/coordinator.py,sha256=HMJyvntKXo4aAOwElrvS0F05zoOllfPvYakdAr6JCkk,12326
+django_bulk_hooks/operations/mti_handler.py,sha256=9QLpQCrtaq2sDg-Bb6B-1iVHgSRxe7p8YfbJDxbdpwE,2980
+django_bulk_hooks/queryset.py,sha256=ody4MXrRREL27Ts2ey1UpS0tb5Dxnw-6kN3unxPQ3zY,5860
+django_bulk_hooks/registry.py,sha256=UPerNhtVz_9tKZqrYSZD2LhjAcs4F6hVUuk8L5oOeHc,8821
+django_bulk_hooks-0.2.1.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
+django_bulk_hooks-0.2.1.dist-info/METADATA,sha256=n1Ji7-lnk8Q0HC6ojG_uwyo_3qcv4_3HbXh0UM0Bcl8,9264
+django_bulk_hooks-0.2.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+django_bulk_hooks-0.2.1.dist-info/RECORD,,

{django_bulk_hooks-0.1.280.dist-info → django_bulk_hooks-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.9.1
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

django_bulk_hooks/engine.py

@@ -1,78 +0,0 @@
-import logging
-
-from django.core.exceptions import ValidationError
-
-from django_bulk_hooks.registry import get_hooks
-
-logger = logging.getLogger(__name__)
-
-
-def run(model_cls, event, new_records, old_records=None, ctx=None):
-    """
-    Run hooks for a given model, event, and records.
-    """
-    if not new_records:
-        return
-
-    # Get hooks for this model and event
-    hooks = get_hooks(model_cls, event)
-
-    if not hooks:
-        return
-
-    import traceback
-
-    stack = traceback.format_stack()
-    # Safely get model name, fallback to str representation if __name__ not available
-    model_name = getattr(model_cls, '__name__', str(model_cls))
-    logger.debug(f"engine.run {model_name}.{event} {len(new_records)} records")
-    
-    # Check if we're in a bypass context
-    if ctx and hasattr(ctx, 'bypass_hooks') and ctx.bypass_hooks:
-        logger.debug("engine.run bypassed")
-        return
-
-    # For BEFORE_* events, run model.clean() first for validation
-    if event.lower().startswith("before_"):
-        for instance in new_records:
-            try:
-                instance.clean()
-            except ValidationError as e:
-                logger.error("Validation failed for %s: %s", instance, e)
-                raise
-
-    # Process hooks
-    for handler_cls, method_name, condition, priority in hooks:
-        # Safely get handler class name
-        handler_name = getattr(handler_cls, '__name__', str(handler_cls))
-        logger.debug(f"Processing {handler_name}.{method_name}")
-        handler_instance = handler_cls()
-        func = getattr(handler_instance, method_name)
-
-        to_process_new = []
-        to_process_old = []
-
-        for new, original in zip(
-            new_records,
-            old_records or [None] * len(new_records),
-            strict=True,
-        ):
-            if not condition:
-                to_process_new.append(new)
-                to_process_old.append(original)
-            else:
-                condition_result = condition.check(new, original)
-                if condition_result:
-                    to_process_new.append(new)
-                    to_process_old.append(original)
-
-        if to_process_new:
-            logger.debug(f"Executing {handler_name}.{method_name} for {len(to_process_new)} records")
-            try:
-                func(
-                    new_records=to_process_new,
-                    old_records=to_process_old if any(to_process_old) else None,
-                )
-            except Exception as e:
-                logger.debug(f"Hook execution failed: {e}")
-                raise

django_bulk_hooks/priority.py

@@ -1,16 +0,0 @@
-from enum import IntEnum
-
-
-class Priority(IntEnum):
-    """
-    Named priorities for django-bulk-hooks hooks.
-
-    Lower values run earlier (higher priority).
-    Hooks are sorted in ascending order.
-    """
-
-    HIGHEST = 0  # runs first
-    HIGH = 25  # runs early
-    NORMAL = 50  # default ordering
-    LOW = 75  # runs later
-    LOWEST = 100  # runs last

django_bulk_hooks-0.1.280.dist-info/RECORD

@@ -1,17 +0,0 @@
-django_bulk_hooks/__init__.py,sha256=6afmyFwRwC4E9CSWyQdONFJUPl5PeXp3ZuTebd7Ic0Y,158
-django_bulk_hooks/conditions.py,sha256=V_f3Di2uCVUjoyfiU4BQCHmI4uUIRSRroApDcXlvnso,6349
-django_bulk_hooks/constants.py,sha256=3x1H1fSUUNo0DZONN7GUVDuySZctTR-jtByBHmAIX5w,303
-django_bulk_hooks/context.py,sha256=jlLsqGZbj__J0-iBUp1D6jTrlDEiX3qIo0XlywW4D9I,2244
-django_bulk_hooks/decorators.py,sha256=k70-BzWwS3wZu_uph5B5qXd6YpwXLQ9hMpOzPUy6iMI,8256
-django_bulk_hooks/engine.py,sha256=M3b7Rcb65PYAZTLfWrIRi99BUBPgSLCryL3MSjMVlfQ,2663
-django_bulk_hooks/enums.py,sha256=Zo8_tJzuzZ2IKfVc7gZ-0tWPT8q1QhqZbAyoh9ZVJbs,381
-django_bulk_hooks/handler.py,sha256=e_GACTQT-pFF-zL7POeo232MgOikUoCLcxDVInAUiBw,6207
-django_bulk_hooks/manager.py,sha256=3jNWL-EkvGScsliNc7mW-ozQCG6HyaEevI1u1BFS4AA,3836
-django_bulk_hooks/models.py,sha256=WtSfc4GBOG_oOt8n37cVvid0MtFIGze9JYKSixil2y0,4370
-django_bulk_hooks/priority.py,sha256=HG_2D35nga68lBCZmSXTcplXrjFoRgZFRDOy4ROKonY,376
-django_bulk_hooks/queryset.py,sha256=0yTN0PApX5xAIatUEfceU1bRRs71tUp4qFsJz26FpBY,99765
-django_bulk_hooks/registry.py,sha256=GRUTGVQEO2sdkC9OaZ9Q3U7mM-3Ix83uTyvrlTtpatw,1317
-django_bulk_hooks-0.1.280.dist-info/LICENSE,sha256=dguKIcbDGeZD-vXWdLyErPUALYOvtX_fO4Zjhq481uk,1088
-django_bulk_hooks-0.1.280.dist-info/METADATA,sha256=alNdArO3XON_hhjY7i7GVtkpt1Y7fWFv99AvcDMp8SA,9103
-django_bulk_hooks-0.1.280.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-django_bulk_hooks-0.1.280.dist-info/RECORD,,