django-bulk-hooks 0.2.9__py3-none-any.whl → 0.2.93__py3-none-any.whl

django_bulk_hooks/registry.py

@@ -1,288 +1,276 @@
-"""
-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 Dict, List, Optional, Tuple, Type, Union
-
-from django_bulk_hooks.enums import Priority
-
-logger = logging.getLogger(__name__)
-
-# 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: 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()
+"""
+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 django_bulk_hooks.enums import Priority
+
+logger = logging.getLogger(__name__)
+
+# Type alias for hook info tuple
+HookInfo = tuple[type, str, Callable | None, 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: Callable | None,
+        priority: 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])
+            else:
+                pass  # Hook already registered
+
+    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, [])
+            logger.debug(f"Retrieved {len(hooks)} hooks for {model.__name__}.{event}")
+            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]
+
+    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()
+
+    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)
+
+    @property
+    def hooks(self) -> dict[tuple[type, str], list[HookInfo]]:
+        """
+        Expose internal hooks dictionary for testing purposes.
+
+        This property provides direct access to the internal hooks storage
+        to allow tests to clear the registry state between test runs.
+        """
+        return self._hooks
+
+    def count_hooks(
+        self,
+        model: type | None = None,
+        event: str | None = 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())
+            if model is not None and event is not None:
+                # Count hooks for specific model and event
+                return len(self._hooks.get((model, event), []))
+            if model is not None:
+                # Count all hooks for a model
+                return sum(len(hooks) for (m, _), hooks in self._hooks.items() if m == model)
+            # 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: HookRegistry | None = 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: type,
+    event: str,
+    handler_cls: type,
+    method_name: str,
+    condition: Callable | None,
+    priority: 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()
+
+
+# Expose hooks dictionary for testing purposes
+# This provides backward compatibility with tests that expect to access _hooks directly
+_hooks = get_registry().hooks

{django_bulk_hooks-0.2.9.dist-info → django_bulk_hooks-0.2.93.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.2.9
+Version: 0.2.93
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks
@@ -244,17 +244,68 @@ LoanAccount.objects.bulk_update(reordered)  # fields are auto-detected
 
 ## 🧩 Integration with Other Managers
 
-You can extend from `BulkHookManager` to work with other manager classes. The manager uses a cooperative approach that dynamically injects bulk hook functionality into any queryset, ensuring compatibility with other managers.
+### Recommended: QuerySet-based Composition (New Approach)
+
+For the best compatibility and to avoid inheritance conflicts, use the queryset-based composition approach:
+
+```python
+from django_bulk_hooks.queryset import HookQuerySet
+from queryable_properties.managers import QueryablePropertiesManager
+
+class MyManager(QueryablePropertiesManager):
+    """Manager that combines queryable properties with hooks"""
+
+    def get_queryset(self):
+        # Get the QueryableProperties QuerySet
+        qs = super().get_queryset()
+        # Apply hooks on top of it
+        return HookQuerySet.with_hooks(qs)
+
+class Article(models.Model):
+    title = models.CharField(max_length=100)
+    published = models.BooleanField(default=False)
+
+    objects = MyManager()
+
+# This gives you both queryable properties AND hooks
+# No inheritance conflicts, no MRO issues!
+```
+
+### Alternative: Explicit Hook Application
+
+For more control, you can apply hooks explicitly:
+
+```python
+class MyManager(QueryablePropertiesManager):
+    def get_queryset(self):
+        return super().get_queryset()
+
+    def with_hooks(self):
+        """Apply hooks to this queryset"""
+        return HookQuerySet.with_hooks(self.get_queryset())
+
+# Usage:
+Article.objects.with_hooks().filter(published=True).update(title="Updated")
+```
+
+### Legacy: Manager Inheritance (Not Recommended)
+
+The old inheritance approach still works but is not recommended due to potential MRO conflicts:
 
 ```python
 from django_bulk_hooks.manager import BulkHookManager
 from queryable_properties.managers import QueryablePropertiesManager
 
 class MyManager(BulkHookManager, QueryablePropertiesManager):
-    pass
+    pass  # ⚠️ Can cause inheritance conflicts
 ```
 
-This approach uses the industry-standard injection pattern, similar to how `QueryablePropertiesManager` works, ensuring both functionalities work seamlessly together without any framework-specific knowledge.
+**Why the new approach is better:**
+- ✅ No inheritance conflicts
+- ✅ No MRO (Method Resolution Order) issues
+- ✅ Works with any manager combination
+- ✅ Cleaner and more maintainable
+- ✅ Follows Django's queryset enhancement patterns
 
 Framework needs to:
 Register these methods