Merge pull request #47 from rpkilby/method-filter-rework

Method filter rework

Author: philipn

README.rst

@@ -177,7 +177,7 @@ then we can filter like so::
     /api/page/?author__username__icontains=john
 
 Automatic Filter Negation/Exclusion
-~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 FilterSets also support automatic exclusion using a simple ``k!=v`` syntax. This syntax
 internally sets the ``exclude`` property on the filter.
@@ -190,8 +190,60 @@ excluding those containing "World".
 
     /api/articles/?title__contains=Hello&title__contains!=World
 
+MethodFilter Reimplementation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``MethodFilter`` has been reimplemented to work across relationships. This is not a
+forwards-compatible change and requires adding a minimal amount of boilerplate to the
+filter method.
+
+When filtering across relationships, the queryset and lookup value will be different.
+For example:
+
+    class PostFilter(filters.FilterSet):
+        author = filters.RelatedFilter('AuthorFilter')
+        is_published = filters.MethodFilter()
+
+        class Meta:
+            model = Post
+            fields = ['title', 'content']
+
+        def filter_is_published(self, name, qs, value):
+            # convert value to boolean
+            null = value.lower() != 'true'
+
+            # The lookup name will end with `is_published`, but could be
+            # preceded by a related lookup path.
+            if LOOKUP_SEP in name:
+                rel, _ = name.rsplit(LOOKUP_SEP, 1)
+                name = LOOKUP_SEP.join([rel, 'date_published__isnull'])
+            else:
+                name = 'date_published__isnull'
+
+            return qs.filter(**{name: null})
+
+    class AuthorFilter(filters.FilterSet):
+        posts = filters.RelatedFilter('PostFilter')
+
+        class Meta:
+            model = Author
+            fields = ['name']
+
+And given these API calls:
+
+    /api/posts/?is_published=true
+
+    /api/authors/?posts__is_published=true
+
+
+In the first API call, the filter method receives a queryset of posts. In the second,
+it receives a queryset of users. The filter method in the example modifies the lookup
+name to work across the relationship, allowing you to find published posts, or authors
+who have published posts.
+
+
 DjangoFilterBackend
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
 
 We implement our own subclass of ``DjangoFilterBackend``, which you should probably use instead
 of the default ``DjangoFilterBackend``.  Our ``DjangoFilterBackend`` caches repeated filter set

rest_framework_filters/filters.py

@@ -87,3 +87,47 @@ class InSetNumberFilter(InSetFilterBase, NumberFilter):
 
 class InSetCharFilter(InSetFilterBase, NumberFilter):
     field_class = fields.ArrayCharField
+
+
+class MethodFilter(Filter):
+    """
+    This filter will allow you to run a method that exists on the filterset class
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.action = kwargs.pop('action', '')
+        super(MethodFilter, self).__init__(*args, **kwargs)
+
+    def resolve_action(self):
+        """
+        This method provides a hook for the parent FilterSet to resolve the filter's
+        action after initialization. This is necessary, as the filter name may change
+        as it's expanded across related filtersets.
+
+        ie, `is_published` might become `post__is_published`.
+        """
+        # noop if a function was provided as the action
+        if callable(self.action):
+            return
+
+        # otherwise, action is a string representing an action to be called on
+        # the parent FilterSet.
+        parent_action = self.action or 'filter_{0}'.format(self.name)
+
+        parent = getattr(self, 'parent', None)
+        self.action = getattr(parent, parent_action, None)
+
+        assert callable(self.action), (
+            'Expected parent FilterSet `%s.%s` to have a `.%s()` method.' %
+            (parent.__class__.__module__, parent.__class__.__name__, parent_action)
+        )
+
+    def filter(self, qs, value):
+        """
+        This filter method will act as a proxy for the actual method we want to
+        call.
+        It will try to find the method on the parent filterset,
+        if not it attempts to search for the method `field_{{attribute_name}}`.
+        Otherwise it defaults to just returning the queryset.
+        """
+        return self.action(self.name, qs, value)

rest_framework_filters/filterset.py

@@ -73,6 +73,9 @@ def __init__(self, *args, **kwargs):
                 if isnull not in self.filters:
                     self.filters[isnull] = filters.BooleanFilter(name=isnull)
 
+            elif isinstance(filter_, filters.MethodFilter):
+                filter_.resolve_action()
+
     def get_filters(self):
         """
         Build a set of filters based on the requested data. The resulting set

tests/filters.py

@@ -1,7 +1,7 @@
 
 from rest_framework_filters import filters
 from rest_framework_filters.filters import RelatedFilter, AllLookupsFilter
-from rest_framework_filters.filterset import FilterSet
+from rest_framework_filters.filterset import FilterSet, LOOKUP_SEP
 
 
 from .models import (
@@ -63,6 +63,40 @@ class Meta:
         model = Post
 
 
+class PostFilterWithMethod(FilterSet):
+    note = RelatedFilter(NoteFilterWithRelatedAll, name='note')
+    is_published = filters.MethodFilter()
+
+    class Meta:
+        model = Post
+
+    def filter_is_published(self, name, qs, value):
+        """
+        `is_published` is based on the actual `date_published`.
+        If the publishing date is null, then the post is not published.
+        """
+        # convert value to boolean
+        null = value.lower() != 'true'
+
+        # The lookup name will end with `is_published`, but could be
+        # preceded by a related lookup path.
+        if LOOKUP_SEP in name:
+            rel, _ = name.rsplit(LOOKUP_SEP, 1)
+            name = LOOKUP_SEP.join([rel, 'date_published__isnull'])
+        else:
+            name = 'date_published__isnull'
+
+        return qs.filter(**{name: null})
+
+
+class CoverFilterWithRelatedMethodFilter(FilterSet):
+    comment = filters.CharFilter(name='comment')
+    post = RelatedFilter(PostFilterWithMethod, name='post')
+
+    class Meta:
+        model = Cover
+
+
 class CoverFilterWithRelated(FilterSet):
     comment = filters.CharFilter(name='comment')
     post = RelatedFilter(PostFilterWithRelated, name='post')

tests/models.py

@@ -12,6 +12,7 @@ class Note(models.Model):
 class Post(models.Model):
     note = models.ForeignKey(Note)
     content = models.TextField()
+    date_published = models.DateField(null=True)
 
 
 class Cover(models.Model):

tests/test_filterset.py

@@ -22,6 +22,8 @@
     NoteFilterWithRelatedAll,
     NoteFilterWithRelatedAllDifferentFilterName,
     PostFilterWithRelated,
+    PostFilterWithMethod,
+    CoverFilterWithRelatedMethodFilter,
     CoverFilterWithRelated,
     # PageFilterWithRelated,
     TagFilter,
@@ -316,6 +318,53 @@ def test_get_filterset_subset(self):
         self.assertEqual(len(filterset_class.base_filters), 1)
 
 
+class MethodFilterTests(TestCase):
+
+    if django.VERSION >= (1, 8):
+        @classmethod
+        def setUpTestData(cls):
+            cls.generateTestData()
+
+    else:
+        def setUp(self):
+            self.generateTestData()
+
+    @classmethod
+    def generateTestData(cls):
+        user = User.objects.create(username="user1", email="user1@example.org")
+
+        note1 = Note.objects.create(title="Test 1", content="Test content 1", author=user)
+        note2 = Note.objects.create(title="Test 2", content="Test content 2", author=user)
+
+        post1 = Post.objects.create(note=note1, content="Test content in post 1")
+        post2 = Post.objects.create(note=note2, content="Test content in post 2", date_published=datetime.date.today())
+
+        Cover.objects.create(post=post1, comment="Cover 1")
+        Cover.objects.create(post=post2, comment="Cover 2")
+
+    def test_method_filter(self):
+        GET = {
+            'is_published': 'true'
+        }
+        filterset = PostFilterWithMethod(GET, queryset=Post.objects.all())
+        results = list(filterset)
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].content, "Test content in post 2")
+
+    def test_related_method_filter(self):
+        """
+        Missing MethodFilter filter methods are silently ignored, returning
+        the unfiltered queryset.
+        """
+        GET = {
+            'post__is_published': 'true'
+        }
+        filterset = CoverFilterWithRelatedMethodFilter(GET, queryset=Cover.objects.all())
+        results = list(filterset)
+        self.assertEqual(len(results), 1)
+        self.assertEqual(results[0].comment, "Cover 2")
+
+
 class DatetimeTests(TestCase):
 
     @classmethod