Merge pull request #171 from algolia/feat/should_index_attr

feat: support attribute/property/Field for should_index

Author: PLNech

.gitignore

@@ -23,6 +23,10 @@ var/
 .installed.cfg
 *.egg
 
+# IDE Files
+*.iml
+.idea/
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

README.md

@@ -230,9 +230,18 @@ class ArticleIndex(AlgoliaIndex):
 
 ## Restrict indexing to a subset of your data
 
-You can add constraints controlling if a record must be indexed or not. `should_index` should be a callable that returns a boolean.
+You can add constraints controlling if a record must be indexed or not. `should_index` should be a boolean or a callable that returns a boolean.
 
 ```python
+# with a boolean attribute
+class Article(models.model):
+    name = models.CharField(max_length=64)
+    is_indexable = True
+
+class ArticleIndex(AlgoliaIndex):
+    should_index = "is_indexable"
+
+# with a callable returning a boolean
 class Contact(models.model):
     name = models.CharField(max_lenght=20)
     age = models.IntegerField()

src/models.py

@@ -12,29 +12,34 @@ class AlgoliaIndexError(Exception):
 class AlgoliaIndex(object):
     '''An index in the Algolia backend.'''
 
-    # Use to specify a custom field that will be used for the objectID.
+    # Used to specify a custom field that will be used for the objectID.
     # This field should be unique.
     custom_objectID = None
 
-    # Use to specify the fields that should be included in the index.
+    # Used to specify the fields that should be included in the index.
     fields = ()
 
-    # Use to specify the geo-fields that should be used for location search.
+    # Used to specify the geo-fields that should be used for location search.
     # The attribute should be a callable that returns a tuple.
     geo_field = None
 
-    # Use to specify the field that should be used for filtering by tag.
+    # Used to specify the field that should be used for filtering by tag.
     tags = None
 
-    # Use to specify the index to target on Algolia.
+    # Used to specify the index to target on Algolia.
     index_name = None
 
-    # Use to specify the settings of the index.
+    # Used to specify the settings of the index.
     settings = {}
 
-    # Use to specify a callable that say if the instance should be indexed.
-    # The attribute should be a callable that returns a boolean.
+    # Used to specify if the instance should be indexed.
+    # The attribute should be either:
+    # - a callable that returns a boolean.
+    # - a BooleanField
+    # - a boolean property or attribute
     should_index = None
+    # Name of the attribute to check on instances if should_index is not a callable
+    _should_index_is_method = False
 
     # Instance of the index from algoliasearch client
     __index = None
@@ -52,7 +57,7 @@ def __init__(self, model, client):
 
         # Avoid error when there is only one field to index
         if isinstance(self.fields, str):
-            self.fields = (self.fields, )
+            self.fields = (self.fields,)
 
         # Check fields
         for field in self.fields:
@@ -63,7 +68,7 @@ def __init__(self, model, client):
         # Check custom_objectID
         if self.custom_objectID:
             if not (hasattr(model, self.custom_objectID) or
-                    (self.custom_objectID in all_fields)):
+                        (self.custom_objectID in all_fields)):
                 raise AlgoliaIndexError('{} is not an attribute of {}.'.format(
                     self.custom_objectID, model))
 
@@ -91,18 +96,20 @@ def __init__(self, model, client):
                 raise AlgoliaIndexError('{} is not an attribute of {}.'.format(
                     self.geo_field, model))
 
-        # Check should_index + get the callable
+        # Check should_index + get the callable or attribute/field name
         if self.should_index:
             if hasattr(model, self.should_index):
                 attr = getattr(model, self.should_index)
-                if callable(attr):
+                if type(attr) is not bool:  # if attr is a bool, we keep attr=name to getattr on instance
                     self.should_index = attr
-                else:
-                    raise AlgoliaIndexError('{} should be a callable.'.format(
-                        self.should_index))
+                if callable(self.should_index):
+                    self._should_index_is_method = True
             else:
-                raise AlgoliaIndexError('{} is not an attribute of {}.'.format(
-                    self.should_index, model))
+                try:
+                    model._meta.get_field_by_name(self.should_index)
+                except:
+                    raise AlgoliaIndexError('{} is not an attribute nor a field of {}.'.format(
+                        self.should_index, model))
 
     def __set_index(self, client):
         '''Get an instance of Algolia Index'''
@@ -188,9 +195,9 @@ def _build_object(self, instance):
         return tmp
 
     def update_obj_index(self, instance):
-        '''Update the object.'''
-        if self.should_index:
-            if not self.should_index(instance):
+        """Update the object."""
+        if self._has_should_index():
+            if not self._should_really_index(instance):
                 # Should not index, but since we don't now the state of the
                 # instance, we need to send a DELETE request to ensure that if
                 # the instance was previously indexed, it will be removed.
@@ -201,6 +208,41 @@ def update_obj_index(self, instance):
         self.__index.save_object(obj)
         logger.debug('UPDATE %s FROM %s', obj['objectID'], self.model)
 
+    def _has_should_index(self):
+        """Return True if this AlgoliaIndex has a should_index method or attribute"""
+        return self.should_index is not None
+
+    def _should_index(self, instance):
+        """Return True if the object should be indexed (including when self.should_index is not set)."""
+        if self._has_should_index():
+            return self._should_really_index(instance)
+        else:
+            return True
+
+    def _should_really_index(self, instance):
+        """Return True if according to should_index the object should be indexed."""
+        if self._should_index_is_method:
+            if hasattr(self.should_index, "__self__"):
+                # bound method, call with instance
+                return self.should_index(instance)
+            else:
+                # unbound method, simply call without arguments
+                return self.should_index()
+        else:
+            # property/attribute/Field, evaluate as bool
+            attr_type = type(self.should_index)
+            if attr_type is str:
+                attr_value = getattr(instance, self.should_index)
+            elif attr_type is property:
+                attr_value = self.should_index.__get__(instance)
+            else:
+                raise AlgoliaIndexError('{} should be a boolean attribute or a method that returns a boolean.'.format(
+                    self.should_index))
+            if type(attr_value) is not bool:
+                raise AlgoliaIndexError("%s's should_index (%s) should be a boolean" % (
+                    instance.__class__.__name__, self.should_index))
+            return attr_value
+
     def delete_obj_index(self, instance):
         '''Delete the object.'''
         objectID = self.__get_objectID(instance)

tests/models.py

@@ -7,11 +7,36 @@ class Example(models.Model):
     address = models.CharField(max_length=200)
     lat = models.FloatField()
     lng = models.FloatField()
+    is_admin = models.BooleanField(default=False)
     category = []
     locations = []
+    index_me = True
 
     def location(self):
         return (self.lat, self.lng)
 
     def geolocations(self):
         return self.locations
+
+    def has_name(self):
+        return self.name is not None
+
+    @staticmethod
+    def static_should_index():
+        return True
+
+    @staticmethod
+    def static_should_not_index():
+        return False
+
+    @property
+    def property_should_index(self):
+        return True
+
+    @property
+    def property_should_not_index(self):
+        return False
+
+    @property
+    def property_string(self):
+        return "foo"

tests/test_index.py

@@ -1,5 +1,4 @@
 from django.test import TestCase
-from django.db import models
 
 from django.contrib.algoliasearch import AlgoliaIndex
 from django.contrib.algoliasearch import algolia_engine
@@ -15,7 +14,8 @@ def setUp(self):
                                 name='SuperK',
                                 address='Finland',
                                 lat=63.3,
-                                lng=-32.0)
+                                lng=-32.0,
+                                is_admin=True)
         self.instance.category = ['Shop', 'Grocery']
         self.instance.locations = [
             {'lat': 10.3, 'lng': -20.0},
@@ -166,4 +166,104 @@ class ExampleIndex(AlgoliaIndex):
             fields = ('name', 'color')
 
         with self.assertRaises(AlgoliaIndexError):
-            index = ExampleIndex(Example, self.client)
+            ExampleIndex(Example, self.client)
+
+    def test_should_index_method(self):
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'has_name'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertTrue(index._should_index(self.instance),
+                        "We should index an instance when should_index(instance) returns True")
+
+        instance_should_not = Example(name=None)
+        self.assertFalse(index._should_index(instance_should_not),
+                         "We should not index an instance when should_index(instance) returns False")
+
+    def test_should_index_unbound(self):
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'static_should_index'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertTrue(index._should_index(self.instance),
+                        "We should index an instance when should_index() returns True")
+
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'static_should_not_index'
+
+        index = ExampleIndex(Example, self.client)
+        instance_should_not = Example()
+        self.assertFalse(index._should_index(instance_should_not),
+                         "We should not index an instance when should_index() returns False")
+
+    def test_should_index_attr(self):
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'index_me'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertTrue(index._should_index(self.instance),
+                        "We should index an instance when its should_index attr is True")
+
+        instance_should_not = Example()
+        instance_should_not.index_me = False
+        self.assertFalse(index._should_index(instance_should_not),
+                         "We should not index an instance when its should_index attr is False")
+
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'category'
+
+        index = ExampleIndex(Example, self.client)
+        with self.assertRaises(AlgoliaIndexError, msg="We should raise when the should_index attr is not boolean"):
+            index._should_index(self.instance)
+
+    def test_should_index_field(self):
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'is_admin'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertTrue(index._should_index(self.instance),
+                        "We should index an instance when its should_index field is True")
+
+        instance_should_not = Example()
+        instance_should_not.is_admin = False
+        self.assertFalse(index._should_index(instance_should_not),
+                         "We should not index an instance when its should_index field is False")
+
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'name'
+
+        index = ExampleIndex(Example, self.client)
+        with self.assertRaises(AlgoliaIndexError, msg="We should raise when the should_index field is not boolean"):
+            index._should_index(self.instance)
+
+    def test_should_index_property(self):
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'property_should_index'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertTrue(index._should_index(self.instance),
+                        "We should index an instance when its should_index property is True")
+
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'property_should_not_index'
+
+        index = ExampleIndex(Example, self.client)
+        self.assertFalse(index._should_index(self.instance),
+                         "We should not index an instance when its should_index property is False")
+
+        class ExampleIndex(AlgoliaIndex):
+            fields = 'name'
+            should_index = 'property_string'
+
+        index = ExampleIndex(Example, self.client)
+        with self.assertRaises(AlgoliaIndexError, msg="We should raise when the should_index property is not boolean"):
+            index._should_index(self.instance)