Add filter usage examples

README.md

@@ -12,6 +12,7 @@ A custom Django choice field to use with [Python enums.](https://docs.python.org
 - [Postgres ArrayField Usage](#postgres-arrayfield-usage)
 - [Usage with Django Rest Framework](#usage-with-django-rest-framework)
   - [Caveat](#caveat)
+- [Usage with `django-filter`](#usage-with-django-filter)
 - [Serializing PostgreSQL ArrayField](#serializing-postgresql-arrayfield)
 - [Implementation details](#implementation-details)
 - [Using Python's `enum.auto`](#using-pythons-enumauto)
@@ -364,6 +365,67 @@ serializer.save()
 
 The `EnumChoiceModelSerializerMixin` does not need to be used if `enumerated_field` is defined on the serializer class explicitly.
 
+## Usage with `django-filter`
+**By declaring the field explicitly on the `FilterSet`**
+```python
+import django_filters as filters
+
+from django_enum_choices.filters import EnumChoiceFilter
+
+class ExplicitFilterSet(filters.FilterSet):
+    enumerated_field = EnumChoiceFilter(MyEnum)
+
+
+filters = {
+    'enumerated_field': 'a'
+}
+filterset = ExplicitFilterSet(filters, MyModel.objects.all())
+
+print(filterset.qs.values_list('enumerated_field', flat=True))  # <QuerySet [<MyEnum.A: 'a'>, <MyEnum.A: 'a'>, <MyEnum.A: 'a'>]>
+```
+
+**By using a `Meta` inner class and inheriting from `EnumChoiceFilterMixin`**
+```python
+import django_filters as filters
+
+from django_enum_choices.filters import EnumChoiceFilterMixin
+
+class ImplicitFilterSet(EnumChoiceFilterSetMixin, filters.FilterSet):
+    class Meta:
+        model = MyModel
+        fields = ['enumerated_field']
+
+filters = {
+    'enumerated_field': 'a'
+}
+filterset = ImplicitFilterSet(filters)
+
+print(filterset.qs.values_list('enumerated_field', flat=True))  # <QuerySet [<MyEnum.A: 'a'>, <MyEnum.A: 'a'>, <MyEnum.A: 'a'>]>
+```
+
+The `choice_builder` argument can be passed to `django_enum_choices.filters.EnumChoiceFilter` as well when using the field explicitly. When using `EnumChoiceFilterSetMixin`, the `choice_builder` is determined from the model field, for the fields defined inside the `Meta` inner class.
+
+```python
+import django_filters as filters
+
+from django_enum_choices.filters import EnumChoiceFilter
+
+def custom_choice_builder(choice):
+    return 'Custom_' + choice.value, choice.value
+
+class ExplicitCustomChoiceBuilderFilterSet(filters.FilterSet):
+    enumerated_field = EnumChoiceFilter(
+        MyEnum,
+        choice_builder=custom_choice_builder
+    )
+
+filters = {
+    'enumerated_field': 'Custom_a'
+}
+filterset = ExplicitCustomChoiceBuilderFilterSet(filters, MyModel.objects.all())
+
+print(filterset.qs.values_list('enumerated_field', flat=True))  # <QuerySet [<MyEnum.A: 'a'>, <MyEnum.A: 'a'>, <MyEnum.A: 'a'>]>
+```
 
 ## Implementation details
 

examples/examples/filters.py

@@ -0,0 +1,24 @@
+import django_filters as filters
+
+from django_enum_choices.filters import EnumChoiceFilter, EnumChoiceFilterSetMixin
+
+from .enumerations import MyEnum
+from .models import MyModel
+from .choice_builders import custom_choice_builder
+
+
+class ExplicitFilterSet(filters.FilterSet):
+    enumerated_field = EnumChoiceFilter(MyEnum)
+
+
+class ExplicitCustomChoiceBuilderFilterSet(filters.FilterSet):
+    enumerated_field = EnumChoiceFilter(
+        MyEnum,
+        choice_builder=custom_choice_builder
+    )
+
+
+class ImplicitFilterSet(EnumChoiceFilterSetMixin, filters.FilterSet):
+    class Meta:
+        model = MyModel
+        fields = ['enumerated_field']

examples/examples/usage.py

@@ -9,6 +9,7 @@
     CustomChoiceBuilderSerializer
 )
 from .forms import StandardEnumForm, ModelEnumForm, CustomChoiceBuilderEnumForm
+from .filters import ExplicitFilterSet, ExplicitCustomChoiceBuilderFilterSet, ImplicitFilterSet
 
 
 # Object Creation
@@ -169,3 +170,39 @@ def get_value_from_form_with_custom_choice_builder_field():
     form.is_valid()
 
     return form.cleaned_data
+
+
+def filter_with_explicit_field():
+    for choice in MyEnum:
+        MyModel.objects.create(enumerated_field=choice)
+
+    filters = {
+        'enumerated_field': 'a'
+    }
+    filterset = ExplicitFilterSet(filters, MyModel.objects.all())
+
+    return filterset.qs.values_list('enumerated_field', flat=True)
+
+
+def filter_with_explicit_field_with_custom_choice_builder():
+    for choice in MyEnum:
+        MyModel.objects.create(enumerated_field=choice)
+
+    filters = {
+        'enumerated_field': 'Custom_a'
+    }
+    filterset = ExplicitCustomChoiceBuilderFilterSet(filters, MyModel.objects.all())
+
+    return filterset.qs.values_list('enumerated_field', flat=True)
+
+
+def filter_with_implicit_field():
+    for choice in MyEnum:
+        MyModel.objects.create(enumerated_field=choice)
+
+    filters = {
+        'enumerated_field': 'a'
+    }
+    filterset = ImplicitFilterSet(filters)
+
+    return filterset.qs.values_list('enumerated_field', flat=True)

setup.py

@@ -32,7 +32,8 @@
         'django-environ==0.4.5',
         'tox==3.13.2',
         'bumpversion==0.5.3',
-        'tox-pyenv==1.1.0'
+        'tox-pyenv==1.1.0',
+        'django-filter==2.2.0'
     ]
 }
 

tox.ini

@@ -32,9 +32,12 @@ deps =
 2.2 =
     Django>=2.2.0,<2.3.0
     djangorestframework>=3.7.3
+    django-filter>=2.2.0
 2.1 =
     Django>=2.1.0,<2.2.0
     djangorestframework>=3.7.3
+    django-filter>=2.2.0
 1.11 =
     Django>=1.11.0,<2.0.0
-    djangorestframework>=3.6.2
+    djangorestframework>=3.6.2
+    django-filter>=2.2.0