diff --git a/README.md b/README.md index 1520e68..e9a47b0 100644 --- a/README.md +++ b/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)) # , , ]> +``` + +**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)) # , , ]> +``` + +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)) # , , ]> +``` ## Implementation details diff --git a/examples/examples/filters.py b/examples/examples/filters.py new file mode 100644 index 0000000..afacda2 --- /dev/null +++ b/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'] diff --git a/examples/examples/usage.py b/examples/examples/usage.py index 5b8dec3..7c4523b 100644 --- a/examples/examples/usage.py +++ b/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) diff --git a/setup.py b/setup.py index 97d979f..b54b5e4 100644 --- a/setup.py +++ b/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' ] } diff --git a/tox.ini b/tox.ini index 07d86fd..9e410ba 100644 --- a/tox.ini +++ b/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 \ No newline at end of file + djangorestframework>=3.6.2 + django-filter>=2.2.0 \ No newline at end of file