Add example app to demonstrate the use of drf-url-filters (#1)

* add example app to demonstrate the use of drf-url-filters

* update README.md

* update README.md

* update docstrings for queryset

Author: manjitkumar

README.md

@@ -7,7 +7,7 @@ on incoming query params and their values. A beautiful python package voluptouos
 # Quick start
 ---
 **Installation**
-    
+
 1. Download `drf-url-filters` app package from this git repo or can be isnatlled using python-pip like `pip install drf-url-filters`.
 
 2. Add `filters` in INSTALLED_APPS in settings.py file of django project.
@@ -16,73 +16,96 @@ on incoming query params and their values. A beautiful python package voluptouos
 
 1. Your View or ModelViewSet should inherit `FiltersMixin` from filters.mixins.FiltersMixin .
 
-2. To apply filters using `drf-url-filters` we need to configure our view to have a dict mapping `filter_mappings` which converts incoming query parameters to query you want to make on the column name on the queryset. 
+2. To apply filters using `drf-url-filters` we need to configure our view to have a dict mapping `filter_mappings` which converts incoming query parameters to query you want to make on the column name on the queryset.
 
-```python
 # validations.py
+
+```python
+
+from filters.schema import base_query_param_schema
 from filters.validations import (
     CSVofIntegers,
     IntegerLike,
     DatetimeWithTZ
 )
 
-from filters.schema import base_query_param_schema
-
+# make a validation schema for players filter query params
 players_query_schema = base_query_param_schema.extend(
     {
-        "id": IntegerLike()
+        "id": IntegerLike(),
         "name": unicode,
-        "team_id": CSVofIntegers(),
-        "install_ts" :DatetimeWithTZ(),
+        "team_id": CSVofIntegers(),  # /?team_id=1,2,3
+        "install_ts": DatetimeWithTZ(),
         "update_ts": DatetimeWithTZ(),
     }
 )
+```
 
 # views.py
-from rest_framework import viewsets
-from filters.mixins import FiltersMixin
-from .models import Players
-from .serializers import PlayersViewSet
-from .validations import players_query_schema
+
+```python
+
+from rest_framework import (
+    viewsets,
+    filters,
+)
+
+from .models import Player, Team
+from .serializers import PlayerSerializer, TeamSerializer
+from .pagination import ResultSetPagination
+from .validations import teams_query_schema, players_query_schema
+from filters.mixins import (
+    FiltersMixin,
+)
 
 
 class PlayersViewSet(FiltersMixin, viewsets.ModelViewSet):
     """
-    This viewset automatically provides `list`, `create`,
-    `retrieve`, `update` and `destroy` actions.
+    This viewset automatically provides `list`, `create`, `retrieve`,
+    `update` and `destroy` actions.
     """
-    serializer_class = PlayersSerializer
-    pagination_class = PlayersPagination
-    
-    # add a mapping of query_params to db_columns(queries) 
+    serializer_class = PlayerSerializer
+    pagination_class = ResultSetPagination
+    filter_backends = (filters.OrderingFilter,)
+    ordering_fields = ('id', 'name', 'update_ts')
+    ordering = ('id',)
+
+    # add a mapping of query_params to db_columns(queries)
     filter_mappings = {
         'id': 'id',
         'name': 'name__icontains',
-        'team_id': 'teams',  # considering a many-to-many related field
+        'team_id': 'teams',
         'install_ts': 'install_ts',
         'update_ts': 'update_ts',
         'update_ts__gte': 'update_ts__gte',
         'update_ts__lte': 'update_ts__lte',
     }
+
     # add validation on filters
     filter_validation_schema = players_query_schema
-    
+
     def get_queryset(self):
         """
         Optionally restricts the queryset by filtering against
         query parameters in the URL.
         """
         query_params = self.request.query_params
-        queryset = Players.objects.all()
+        queryset = Player.objects.prefetch_related(
+            'teams'  # use prefetch_related to minimize db hits.
+        ).all()
+
         # This dict will hold filter kwargs to pass in to Django ORM calls.
         db_filters = {}
-        # update filters on players queryset using FiltersMixin.get_queryset_filters
-        db_filters.update(
+
+        # update filters dict with incoming query params and then pass as
+        # **kwargs to queryset.filter()
+         db_filters.update(
             self.get_queryset_filters(
                 query_params
             )
         )
         return queryset.filter(**db_filters)
+
 ```
 
 With the use of `drf-url-filters` adding a new filter on a new column is as simple as adding a new key in the dict. Prohibitting a filter on particular column is same as removing a a key value mapping from the `filter_mappings` dict.

docs/README.md

@@ -7,7 +7,7 @@ on incoming query params and their values. A beautiful python package voluptouos
 # Quick start
 ---
 **Installation**
-    
+
 1. Download `drf-url-filters` app package from this git repo or can be isnatlled using python-pip like `pip install drf-url-filters`.
 
 2. Add `filters` in INSTALLED_APPS in settings.py file of django project.
@@ -16,73 +16,96 @@ on incoming query params and their values. A beautiful python package voluptouos
 
 1. Your View or ModelViewSet should inherit `FiltersMixin` from filters.mixins.FiltersMixin .
 
-2. To apply filters using `drf-url-filters` we need to configure our view to have a dict mapping `filter_mappings` which converts incoming query parameters to query you want to make on the column name on the queryset. 
+2. To apply filters using `drf-url-filters` we need to configure our view to have a dict mapping `filter_mappings` which converts incoming query parameters to query you want to make on the column name on the queryset.
 
-```python
 # validations.py
+
+```python
+
+from filters.schema import base_query_param_schema
 from filters.validations import (
     CSVofIntegers,
     IntegerLike,
     DatetimeWithTZ
 )
 
-from filters.schema import base_query_param_schema
-
+# make a validation schema for players filter query params
 players_query_schema = base_query_param_schema.extend(
     {
-        "id": IntegerLike()
+        "id": IntegerLike(),
         "name": unicode,
-        "team_id": CSVofIntegers(),
-        "install_ts" :DatetimeWithTZ(),
+        "team_id": CSVofIntegers(),  # /?team_id=1,2,3
+        "install_ts": DatetimeWithTZ(),
         "update_ts": DatetimeWithTZ(),
     }
 )
+```
 
 # views.py
-from rest_framework import viewsets
-from filters.mixins import FiltersMixin
-from .models import Players
-from .serializers import PlayersViewSet
-from .validations import players_query_schema
+
+```python
+
+from rest_framework import (
+    viewsets,
+    filters,
+)
+
+from .models import Player, Team
+from .serializers import PlayerSerializer, TeamSerializer
+from .pagination import ResultSetPagination
+from .validations import teams_query_schema, players_query_schema
+from filters.mixins import (
+    FiltersMixin,
+)
 
 
 class PlayersViewSet(FiltersMixin, viewsets.ModelViewSet):
     """
-    This viewset automatically provides `list`, `create`,
-    `retrieve`, `update` and `destroy` actions.
+    This viewset automatically provides `list`, `create`, `retrieve`,
+    `update` and `destroy` actions.
     """
-    serializer_class = PlayersSerializer
-    pagination_class = PlayersPagination
-    
-    # add a mapping of query_params to db_columns(queries) 
+    serializer_class = PlayerSerializer
+    pagination_class = ResultSetPagination
+    filter_backends = (filters.OrderingFilter,)
+    ordering_fields = ('id', 'name', 'update_ts')
+    ordering = ('id',)
+
+    # add a mapping of query_params to db_columns(queries)
     filter_mappings = {
         'id': 'id',
         'name': 'name__icontains',
-        'team_id': 'teams',  # considering a many-to-many related field
+        'team_id': 'teams',
         'install_ts': 'install_ts',
         'update_ts': 'update_ts',
         'update_ts__gte': 'update_ts__gte',
         'update_ts__lte': 'update_ts__lte',
     }
+
     # add validation on filters
     filter_validation_schema = players_query_schema
-    
+
     def get_queryset(self):
         """
         Optionally restricts the queryset by filtering against
         query parameters in the URL.
         """
         query_params = self.request.query_params
-        queryset = Players.objects.all()
+        queryset = Player.objects.prefetch_related(
+            'teams'  # use prefetch_related to minimize db hits.
+        ).all()
+
         # This dict will hold filter kwargs to pass in to Django ORM calls.
         db_filters = {}
-        # update filters on players queryset using FiltersMixin.get_queryset_filters
+
+        # update filters dict with incoming query params and then pass as
+        # **kwargs to queryset.filter()
         db_filters.update(
             self.get_queryset_filters(
                 query_params
             )
         )
         return queryset.filter(**db_filters)
+
 ```
 
 With the use of `drf-url-filters` adding a new filter on a new column is as simple as adding a new key in the dict. Prohibitting a filter on particular column is same as removing a a key value mapping from the `filter_mappings` dict.

example_app/__init__.py

@@ -0,0 +1,34 @@
+from django.db import models
+
+
+class Player(models.Model):
+    name = models.CharField(max_length=254)
+    rating = models.FloatField(null=True)
+    teams = models.ManyToManyField(
+        'Team',
+        through='Membership',
+        through_fields=('team', 'player')
+    )
+    install_ts = models.DateTimeField(auto_now_add=True, blank=True)
+    update_ts = models.DateTimeField(auto_now_add=True, blank=True)
+
+
+class Team(models.Model):
+    name = models.CharField(max_length=254)
+    rating = models.FloatField(null=True)
+    players = models.ManyToManyField(
+        'Player',
+        through='Membership',
+        through_fields=('team', 'player')
+    )
+    install_ts = models.DateTimeField(auto_now_add=True, blank=True)
+    update_ts = models.DateTimeField(auto_now_add=True, blank=True)
+
+
+class Membership(models.Model):
+    team = models.ForeignKey('Team')
+    player = models.ForeignKey('Player')
+    is_active = models.BooleanField(default=True)
+    date_of_joining = models.DateTimeField()
+    install_ts = models.DateTimeField(auto_now_add=True, blank=True)
+    update_ts = models.DateTimeField(auto_now_add=True, blank=True)

example_app/migrations/__init__.py

@@ -0,0 +1,6 @@
+from rest_framework.pagination import LimitOffsetPagination
+
+
+class ResultSetPagination(LimitOffsetPagination):
+    default_limit = 10
+    max_limit = 100

example_app/models.py

@@ -0,0 +1,24 @@
+
+# django-drf imports
+from rest_framework import serializers
+
+# app level imports
+from .models import Player, Team
+
+
+class PlayerSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Player
+        fields = (
+            'id', 'name', 'rating', 'teams',
+            'install_ts', 'update_ts'
+        )
+
+
+class TeamSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Team
+        fields = (
+            'id', 'name', 'rating', 'players',
+            'install_ts', 'update_ts'
+        )

example_app/pagination.py

@@ -0,0 +1,15 @@
+from django.conf.urls import include, url
+
+from rest_framework.routers import DefaultRouter
+from example_app.views import PlayersViewSet, TeamsViewSet
+
+
+# Create a router and register our viewsets with it.
+router = DefaultRouter()
+
+router.register(r'players', PlayersViewSet, base_name='players')
+router.register(r'teams', TeamsViewSet, base_name='teams')
+
+urlpatterns = [
+    url(r'^api/', include(router.urls)),
+]

example_app/serializers.py

@@ -0,0 +1,28 @@
+
+from filters.schema import base_query_param_schema
+from filters.validations import (
+    CSVofIntegers,
+    IntegerLike,
+    DatetimeWithTZ
+)
+
+# make a validation schema for players filter query params
+players_query_schema = base_query_param_schema.extend(
+    {
+        "id": IntegerLike(),
+        "name": unicode,
+        "team_id": CSVofIntegers(),  # /?team_id=1,2,3
+        "install_ts": DatetimeWithTZ(),
+        "update_ts": DatetimeWithTZ(),
+    }
+)
+
+teams_query_schema = base_query_param_schema.extend(
+    {
+        "id": IntegerLike(),
+        "name": unicode,
+        "player_id": CSVofIntegers(),  # /?player_id=1,2,3
+        "install_ts": DatetimeWithTZ(),
+        "update_ts": DatetimeWithTZ(),
+    }
+)