django-bulk-hooks 0.1.86__tar.gz → 0.1.88__tar.gz

{django_bulk_hooks-0.1.86 → django_bulk_hooks-0.1.88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-bulk-hooks
-Version: 0.1.86
+Version: 0.1.88
 Summary: Hook-style hooks for Django bulk operations like bulk_create and bulk_update.
 License: MIT
 Keywords: django,bulk,hooks

{django_bulk_hooks-0.1.86 → django_bulk_hooks-0.1.88}/django_bulk_hooks/conditions.py

@@ -195,90 +195,104 @@ class HookCondition:
     def __invert__(self):
         return NotCondition(self)
 
+    def get_required_fields(self):
+        """
+        Returns a set of field names that this condition needs to evaluate.
+        Override in subclasses to specify required fields.
+        """
+        return set()
 
-class IsNotEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+
+class IsEqual(HookCondition):
+    def __init__(self, field, value):
         self.field = field
         self.value = value
-        self.only_on_change = only_on_change
 
     def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        if self.only_on_change:
-            if original_instance is None:
-                return False
-            previous = resolve_dotted_attr(original_instance, self.field)
-            return previous == self.value and current != self.value
-        else:
-            return current != self.value
+        current_value = resolve_dotted_attr(instance, self.field)
+        return current_value == self.value
 
+    def get_required_fields(self):
+        return {self.field.split('.')[0]}
 
-class IsEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+
+class IsNotEqual(HookCondition):
+    def __init__(self, field, value):
         self.field = field
         self.value = value
-        self.only_on_change = only_on_change
 
     def check(self, instance, original_instance=None):
-        current = resolve_dotted_attr(instance, self.field)
-        if self.only_on_change:
-            if original_instance is None:
-                return False
-            previous = resolve_dotted_attr(original_instance, self.field)
-            return previous != self.value and current == self.value
-        else:
-            return current == self.value
+        current_value = resolve_dotted_attr(instance, self.field)
+        return current_value != self.value
 
+    def get_required_fields(self):
+        return {self.field.split('.')[0]}
 
-class HasChanged(HookCondition):
-    def __init__(self, field, has_changed=True):
+
+class WasEqual(HookCondition):
+    def __init__(self, field, value):
         self.field = field
-        self.has_changed = has_changed
+        self.value = value
 
     def check(self, instance, original_instance=None):
-        if not original_instance:
+        if original_instance is None:
             return False
-        current = resolve_dotted_attr(instance, self.field)
-        previous = resolve_dotted_attr(original_instance, self.field)
-        return (current != previous) == self.has_changed
+        original_value = resolve_dotted_attr(original_instance, self.field)
+        return original_value == self.value
 
+    def get_required_fields(self):
+        return {self.field.split('.')[0]}
 
-class WasEqual(HookCondition):
-    def __init__(self, field, value, only_on_change=False):
+
+class HasChanged(HookCondition):
+    def __init__(self, field, has_changed=True):
         """
-        Check if a field's original value was `value`.
-        If only_on_change is True, only return True when the field has changed away from that value.
+        Check if a field's value has changed or remained the same.
+        
+        Args:
+            field: The field name to check
+            has_changed: If True (default), condition passes when field has changed.
+                        If False, condition passes when field has remained the same.
+                        This is useful for:
+                        - Detecting stable/unchanged fields
+                        - Validating field immutability
+                        - Ensuring critical fields remain constant
+                        - State machine validations
         """
         self.field = field
-        self.value = value
-        self.only_on_change = only_on_change
+        self.has_changed = has_changed
 
     def check(self, instance, original_instance=None):
         if original_instance is None:
-            return False
-        previous = resolve_dotted_attr(original_instance, self.field)
-        if self.only_on_change:
-            current = resolve_dotted_attr(instance, self.field)
-            return previous == self.value and current != self.value
-        else:
-            return previous == self.value
+            # For new instances:
+            # - If we're checking for changes (has_changed=True), return False since there's no change yet
+            # - If we're checking for stability (has_changed=False), return True since it's technically unchanged
+            return not self.has_changed
+            
+        current_value = resolve_dotted_attr(instance, self.field)
+        original_value = resolve_dotted_attr(original_instance, self.field)
+        return (current_value != original_value) == self.has_changed
+
+    def get_required_fields(self):
+        return {self.field.split('.')[0]}
 
 
 class ChangesTo(HookCondition):
     def __init__(self, field, value):
-        """
-        Check if a field's value has changed to `value`.
-        Only returns True when original value != value and current value == value.
-        """
         self.field = field
         self.value = value
 
     def check(self, instance, original_instance=None):
         if original_instance is None:
-            return False
-        previous = resolve_dotted_attr(original_instance, self.field)
-        current = resolve_dotted_attr(instance, self.field)
-        return previous != self.value and current == self.value
+            current_value = resolve_dotted_attr(instance, self.field)
+            return current_value == self.value
+
+        current_value = resolve_dotted_attr(instance, self.field)
+        original_value = resolve_dotted_attr(original_instance, self.field)
+        return current_value == self.value and current_value != original_value
+
+    def get_required_fields(self):
+        return {self.field.split('.')[0]}
 
 
 class IsGreaterThan(HookCondition):
@@ -322,30 +336,41 @@ class IsLessThanOrEqual(HookCondition):
 
 
 class AndCondition(HookCondition):
-    def __init__(self, cond1, cond2):
-        self.cond1 = cond1
-        self.cond2 = cond2
+    def __init__(self, condition1, condition2):
+        self.condition1 = condition1
+        self.condition2 = condition2
 
     def check(self, instance, original_instance=None):
-        return self.cond1.check(instance, original_instance) and self.cond2.check(
-            instance, original_instance
+        return (
+            self.condition1.check(instance, original_instance)
+            and self.condition2.check(instance, original_instance)
         )
 
+    def get_required_fields(self):
+        return self.condition1.get_required_fields() | self.condition2.get_required_fields()
+
 
 class OrCondition(HookCondition):
-    def __init__(self, cond1, cond2):
-        self.cond1 = cond1
-        self.cond2 = cond2
+    def __init__(self, condition1, condition2):
+        self.condition1 = condition1
+        self.condition2 = condition2
 
     def check(self, instance, original_instance=None):
-        return self.cond1.check(instance, original_instance) or self.cond2.check(
-            instance, original_instance
+        return (
+            self.condition1.check(instance, original_instance)
+            or self.condition2.check(instance, original_instance)
         )
 
+    def get_required_fields(self):
+        return self.condition1.get_required_fields() | self.condition2.get_required_fields()
+
 
 class NotCondition(HookCondition):
-    def __init__(self, cond):
-        self.cond = cond
+    def __init__(self, condition):
+        self.condition = condition
 
     def check(self, instance, original_instance=None):
-        return not self.cond.check(instance, original_instance)
+        return not self.condition.check(instance, original_instance)
+
+    def get_required_fields(self):
+        return self.condition.get_required_fields()

django_bulk_hooks-0.1.88/django_bulk_hooks/manager.py

@@ -0,0 +1,296 @@
+from django.db import models, transaction
+
+from django_bulk_hooks import engine
+from django_bulk_hooks.constants import (
+    AFTER_CREATE,
+    AFTER_DELETE,
+    AFTER_UPDATE,
+    BEFORE_CREATE,
+    BEFORE_DELETE,
+    BEFORE_UPDATE,
+    VALIDATE_CREATE,
+    VALIDATE_DELETE,
+    VALIDATE_UPDATE,
+)
+from django_bulk_hooks.context import HookContext
+from django_bulk_hooks.queryset import HookQuerySet
+
+
+class BulkHookManager(models.Manager):
+    # Default chunk sizes - can be overridden per model
+    DEFAULT_CHUNK_SIZE = 200
+    DEFAULT_RELATED_CHUNK_SIZE = 500  # Higher for related object fetching
+    
+    def __init__(self):
+        super().__init__()
+        self._chunk_size = self.DEFAULT_CHUNK_SIZE
+        self._related_chunk_size = self.DEFAULT_RELATED_CHUNK_SIZE
+        self._prefetch_related_fields = set()
+        self._select_related_fields = set()
+
+    def configure(self, chunk_size=None, related_chunk_size=None, 
+                 select_related=None, prefetch_related=None):
+        """
+        Configure bulk operation parameters for this manager.
+        
+        Args:
+            chunk_size: Number of objects to process in each bulk operation chunk
+            related_chunk_size: Number of objects to fetch in each related object query
+            select_related: List of fields to always select_related in bulk operations
+            prefetch_related: List of fields to always prefetch_related in bulk operations
+        """
+        if chunk_size is not None:
+            self._chunk_size = chunk_size
+        if related_chunk_size is not None:
+            self._related_chunk_size = related_chunk_size
+        if select_related:
+            self._select_related_fields.update(select_related)
+        if prefetch_related:
+            self._prefetch_related_fields.update(prefetch_related)
+
+    def _load_originals_optimized(self, pks, fields_to_fetch=None):
+        """
+        Optimized loading of original instances with smart batching and field selection.
+        """
+        queryset = self.model.objects.filter(pk__in=pks)
+        
+        # Only select specific fields if provided
+        if fields_to_fetch:
+            queryset = queryset.only('pk', *fields_to_fetch)
+            
+        # Apply configured related field optimizations
+        if self._select_related_fields:
+            queryset = queryset.select_related(*self._select_related_fields)
+        if self._prefetch_related_fields:
+            queryset = queryset.prefetch_related(*self._prefetch_related_fields)
+            
+        # Batch load in chunks to avoid memory issues
+        all_originals = []
+        for i in range(0, len(pks), self._related_chunk_size):
+            chunk_pks = pks[i:i + self._related_chunk_size]
+            chunk_originals = list(queryset.filter(pk__in=chunk_pks))
+            all_originals.extend(chunk_originals)
+            
+        return all_originals
+
+    def _get_fields_to_fetch(self, objs, fields):
+        """
+        Determine which fields need to be fetched based on what's being updated
+        and what's needed for hooks.
+        """
+        fields_to_fetch = set(fields)
+        
+        # Add fields needed by registered hooks
+        from django_bulk_hooks.registry import get_hooks
+        hooks = get_hooks(self.model, "before_update") + get_hooks(self.model, "after_update")
+        
+        for handler_cls, method_name, condition, _ in hooks:
+            if condition:
+                # If there's a condition, we need all fields it might access
+                fields_to_fetch.update(condition.get_required_fields())
+                
+        return fields_to_fetch
+
+    @transaction.atomic
+    def bulk_update(self, objs, fields, bypass_hooks=False, bypass_validation=False, **kwargs):
+        if not objs:
+            return []
+
+        model_cls = self.model
+
+        if any(not isinstance(obj, model_cls) for obj in objs):
+            raise TypeError(
+                f"bulk_update expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
+            )
+
+        if not bypass_hooks:
+            # Determine which fields we need to fetch
+            fields_to_fetch = self._get_fields_to_fetch(objs, fields)
+            
+            # Load originals efficiently
+            pks = [obj.pk for obj in objs if obj.pk is not None]
+            originals = self._load_originals_optimized(pks, fields_to_fetch)
+            
+            # Create a mapping for quick lookup
+            original_map = {obj.pk: obj for obj in originals}
+            
+            # Align originals with new instances
+            aligned_originals = [original_map.get(obj.pk) for obj in objs]
+
+            ctx = HookContext(model_cls)
+
+            # Run validation hooks first
+            if not bypass_validation:
+                engine.run(model_cls, VALIDATE_UPDATE, objs, aligned_originals, ctx=ctx)
+
+            # Then run business logic hooks
+            engine.run(model_cls, BEFORE_UPDATE, objs, aligned_originals, ctx=ctx)
+
+            # Automatically detect fields that were modified during BEFORE_UPDATE hooks
+            modified_fields = self._detect_modified_fields(objs, aligned_originals)
+            if modified_fields:
+                fields_set = set(fields)
+                fields_set.update(modified_fields)
+                fields = list(fields_set)
+
+        # Process in chunks
+        for i in range(0, len(objs), self._chunk_size):
+            chunk = objs[i:i + self._chunk_size]
+            super(models.Manager, self).bulk_update(chunk, fields, **kwargs)
+
+        if not bypass_hooks:
+            engine.run(model_cls, AFTER_UPDATE, objs, aligned_originals, ctx=ctx)
+
+        return objs
+
+    def _detect_modified_fields(self, new_instances, original_instances):
+        """
+        Detect fields that were modified during BEFORE_UPDATE hooks by comparing
+        new instances with their original values.
+        """
+        if not original_instances:
+            return set()
+
+        # Create a mapping of pk to original instance for efficient lookup
+        original_map = {obj.pk: obj for obj in original_instances if obj.pk is not None}
+
+        modified_fields = set()
+
+        for new_instance in new_instances:
+            if new_instance.pk is None:
+                continue
+
+            original = original_map.get(new_instance.pk)
+            if not original:
+                continue
+
+            # Compare all fields to detect changes
+            for field in new_instance._meta.fields:
+                if field.name == "id":
+                    continue
+
+                new_value = getattr(new_instance, field.name)
+                original_value = getattr(original, field.name)
+
+                # Handle different field types appropriately
+                if field.is_relation:
+                    # For foreign keys, compare the pk values
+                    new_pk = new_value.pk if new_value else None
+                    original_pk = original_value.pk if original_value else None
+                    if new_pk != original_pk:
+                        modified_fields.add(field.name)
+                else:
+                    # For regular fields, use direct comparison
+                    if new_value != original_value:
+                        modified_fields.add(field.name)
+
+        return modified_fields
+
+    @transaction.atomic
+    def bulk_create(self, objs, bypass_hooks=False, bypass_validation=False, **kwargs):
+        if not objs:
+            return []
+
+        model_cls = self.model
+        result = []
+
+        if any(not isinstance(obj, model_cls) for obj in objs):
+            raise TypeError(
+                f"bulk_create expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
+            )
+
+        if not bypass_hooks:
+            ctx = HookContext(model_cls)
+
+            # Process validation in chunks to avoid memory issues
+            if not bypass_validation:
+                for i in range(0, len(objs), self._chunk_size):
+                    chunk = objs[i:i + self._chunk_size]
+                    engine.run(model_cls, VALIDATE_CREATE, chunk, ctx=ctx)
+
+            # Process before_create hooks in chunks
+            for i in range(0, len(objs), self._chunk_size):
+                chunk = objs[i:i + self._chunk_size]
+                engine.run(model_cls, BEFORE_CREATE, chunk, ctx=ctx)
+
+        # Perform bulk create in chunks
+        for i in range(0, len(objs), self._chunk_size):
+            chunk = objs[i:i + self._chunk_size]
+            created_chunk = super(models.Manager, self).bulk_create(chunk, **kwargs)
+            result.extend(created_chunk)
+
+        if not bypass_hooks:
+            # Process after_create hooks in chunks
+            for i in range(0, len(result), self._chunk_size):
+                chunk = result[i:i + self._chunk_size]
+                engine.run(model_cls, AFTER_CREATE, chunk, ctx=ctx)
+
+        return result
+
+    @transaction.atomic
+    def bulk_delete(self, objs, batch_size=None, bypass_hooks=False, bypass_validation=False):
+        if not objs:
+            return []
+
+        model_cls = self.model
+        chunk_size = batch_size or self._chunk_size
+
+        if any(not isinstance(obj, model_cls) for obj in objs):
+            raise TypeError(
+                f"bulk_delete expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
+            )
+
+        ctx = HookContext(model_cls)
+
+        if not bypass_hooks:
+            # Process hooks in chunks
+            for i in range(0, len(objs), chunk_size):
+                chunk = objs[i:i + chunk_size]
+                
+                if not bypass_validation:
+                    engine.run(model_cls, VALIDATE_DELETE, chunk, ctx=ctx)
+                engine.run(model_cls, BEFORE_DELETE, chunk, ctx=ctx)
+
+        # Collect PKs and delete in chunks
+        pks = [obj.pk for obj in objs if obj.pk is not None]
+        for i in range(0, len(pks), chunk_size):
+            chunk_pks = pks[i:i + chunk_size]
+            model_cls._base_manager.filter(pk__in=chunk_pks).delete()
+
+        if not bypass_hooks:
+            # Process after_delete hooks in chunks
+            for i in range(0, len(objs), chunk_size):
+                chunk = objs[i:i + chunk_size]
+                engine.run(model_cls, AFTER_DELETE, chunk, ctx=ctx)
+
+        return objs
+
+    @transaction.atomic
+    def update(self, **kwargs):
+        objs = list(self.all())
+        if not objs:
+            return 0
+        for key, value in kwargs.items():
+            for obj in objs:
+                setattr(obj, key, value)
+        self.bulk_update(objs, fields=list(kwargs.keys()))
+        return len(objs)
+
+    @transaction.atomic
+    def delete(self):
+        objs = list(self.all())
+        if not objs:
+            return 0
+        self.bulk_delete(objs)
+        return len(objs)
+
+    @transaction.atomic
+    def save(self, obj):
+        if obj.pk:
+            self.bulk_update(
+                [obj],
+                fields=[field.name for field in obj._meta.fields if field.name != "id"],
+            )
+        else:
+            self.bulk_create([obj])
+        return obj

{django_bulk_hooks-0.1.86 → django_bulk_hooks-0.1.88}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-bulk-hooks"
-version = "0.1.86"
+version = "0.1.88"
 description = "Hook-style hooks for Django bulk operations like bulk_create and bulk_update."
 authors = ["Konrad Beck <konrad.beck@merchantcapital.co.za>"]
 readme = "README.md"

django_bulk_hooks-0.1.86/django_bulk_hooks/manager.py

@@ -1,208 +0,0 @@
-from django.db import models, transaction
-
-from django_bulk_hooks import engine
-from django_bulk_hooks.constants import (
-    AFTER_CREATE,
-    AFTER_DELETE,
-    AFTER_UPDATE,
-    BEFORE_CREATE,
-    BEFORE_DELETE,
-    BEFORE_UPDATE,
-    VALIDATE_CREATE,
-    VALIDATE_DELETE,
-    VALIDATE_UPDATE,
-)
-from django_bulk_hooks.context import HookContext
-from django_bulk_hooks.queryset import HookQuerySet
-
-
-class BulkHookManager(models.Manager):
-    CHUNK_SIZE = 200
-
-    def get_queryset(self):
-        return HookQuerySet(self.model, using=self._db)
-
-    @transaction.atomic
-    def bulk_update(
-        self, objs, fields, bypass_hooks=False, bypass_validation=False, **kwargs
-    ):
-        if not objs:
-            return []
-
-        model_cls = self.model
-
-        if any(not isinstance(obj, model_cls) for obj in objs):
-            raise TypeError(
-                f"bulk_update expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
-            )
-
-        if not bypass_hooks:
-            # Load originals for hook comparison
-            originals = list(
-                model_cls.objects.filter(pk__in=[obj.pk for obj in objs])
-            )
-
-            ctx = HookContext(model_cls)
-
-            # Run validation hooks first
-            if not bypass_validation:
-                engine.run(model_cls, VALIDATE_UPDATE, objs, originals, ctx=ctx)
-
-            # Then run business logic hooks
-            engine.run(model_cls, BEFORE_UPDATE, objs, originals, ctx=ctx)
-
-            # Automatically detect fields that were modified during BEFORE_UPDATE hooks
-            modified_fields = self._detect_modified_fields(objs, originals)
-            if modified_fields:
-                # Convert to set for efficient union operation
-                fields_set = set(fields)
-                fields_set.update(modified_fields)
-                fields = list(fields_set)
-
-        for i in range(0, len(objs), self.CHUNK_SIZE):
-            chunk = objs[i : i + self.CHUNK_SIZE]
-            # Call the base implementation to avoid re-triggering this method
-            super(models.Manager, self).bulk_update(chunk, fields, **kwargs)
-
-        if not bypass_hooks:
-            engine.run(model_cls, AFTER_UPDATE, objs, originals, ctx=ctx)
-
-        return objs
-
-    def _detect_modified_fields(self, new_instances, original_instances):
-        """
-        Detect fields that were modified during BEFORE_UPDATE hooks by comparing
-        new instances with their original values.
-        """
-        if not original_instances:
-            return set()
-
-        # Create a mapping of pk to original instance for efficient lookup
-        original_map = {obj.pk: obj for obj in original_instances if obj.pk is not None}
-
-        modified_fields = set()
-
-        for new_instance in new_instances:
-            if new_instance.pk is None:
-                continue
-
-            original = original_map.get(new_instance.pk)
-            if not original:
-                continue
-
-            # Compare all fields to detect changes
-            for field in new_instance._meta.fields:
-                if field.name == "id":
-                    continue
-
-                new_value = getattr(new_instance, field.name)
-                original_value = getattr(original, field.name)
-
-                # Handle different field types appropriately
-                if field.is_relation:
-                    # For foreign keys, compare the pk values
-                    new_pk = new_value.pk if new_value else None
-                    original_pk = original_value.pk if original_value else None
-                    if new_pk != original_pk:
-                        modified_fields.add(field.name)
-                else:
-                    # For regular fields, use direct comparison
-                    if new_value != original_value:
-                        modified_fields.add(field.name)
-
-        return modified_fields
-
-    @transaction.atomic
-    def bulk_create(self, objs, bypass_hooks=False, bypass_validation=False, **kwargs):
-        model_cls = self.model
-
-        if any(not isinstance(obj, model_cls) for obj in objs):
-            raise TypeError(
-                f"bulk_create expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
-            )
-
-        result = []
-
-        if not bypass_hooks:
-            ctx = HookContext(model_cls)
-
-            # Run validation hooks first
-            if not bypass_validation:
-                engine.run(model_cls, VALIDATE_CREATE, objs, ctx=ctx)
-
-            # Then run business logic hooks
-            engine.run(model_cls, BEFORE_CREATE, objs, ctx=ctx)
-
-        for i in range(0, len(objs), self.CHUNK_SIZE):
-            chunk = objs[i : i + self.CHUNK_SIZE]
-            result.extend(super(models.Manager, self).bulk_create(chunk, **kwargs))
-
-        if not bypass_hooks:
-            engine.run(model_cls, AFTER_CREATE, result, ctx=ctx)
-
-        return result
-
-    @transaction.atomic
-    def bulk_delete(
-        self, objs, batch_size=None, bypass_hooks=False, bypass_validation=False
-    ):
-        if not objs:
-            return []
-
-        model_cls = self.model
-
-        if any(not isinstance(obj, model_cls) for obj in objs):
-            raise TypeError(
-                f"bulk_delete expected instances of {model_cls.__name__}, but got {set(type(obj).__name__ for obj in objs)}"
-            )
-
-        ctx = HookContext(model_cls)
-
-        if not bypass_hooks:
-            # Run validation hooks first
-            if not bypass_validation:
-                engine.run(model_cls, VALIDATE_DELETE, objs, ctx=ctx)
-
-            # Then run business logic hooks
-            engine.run(model_cls, BEFORE_DELETE, objs, ctx=ctx)
-
-        pks = [obj.pk for obj in objs if obj.pk is not None]
-        
-        # Use base manager for the actual deletion to prevent recursion
-        # The hooks have already been fired above, so we don't need them again
-        model_cls._base_manager.filter(pk__in=pks).delete()
-
-        if not bypass_hooks:
-            engine.run(model_cls, AFTER_DELETE, objs, ctx=ctx)
-
-        return objs
-
-    @transaction.atomic
-    def update(self, **kwargs):
-        objs = list(self.all())
-        if not objs:
-            return 0
-        for key, value in kwargs.items():
-            for obj in objs:
-                setattr(obj, key, value)
-        self.bulk_update(objs, fields=list(kwargs.keys()))
-        return len(objs)
-
-    @transaction.atomic
-    def delete(self):
-        objs = list(self.all())
-        if not objs:
-            return 0
-        self.bulk_delete(objs)
-        return len(objs)
-
-    @transaction.atomic
-    def save(self, obj):
-        if obj.pk:
-            self.bulk_update(
-                [obj],
-                fields=[field.name for field in obj._meta.fields if field.name != "id"],
-            )
-        else:
-            self.bulk_create([obj])
-        return obj