<commit_before>Filter Reference
================

This is a reference document with a list of the filters and their arguments.

Filters
-------

``CharFilter``
~~~~~~~~~~~~~~

This filter does simple character matches, used with ``CharField`` and
``TextField`` by default.

``BooleanFilter``
~~~~~~~~~~~~~~~~~

This filter matches a boolean, either ``True`` or ``False``, used with
``BooleanField`` and ``NullBooleanField`` by default.

``ChoiceFilter``
~~~~~~~~~~~~~~~~

This filter matches an item of any type by choices, used with any field that
has ``choices``.


Requires ``choices`` ``kwarg`` to be passed if explicitly declared on the ``FilterSet``. For example::

    class User(models.Model):
        username = models.CharField(max_length=255)
        first_name = SubCharField(max_length=100)
        last_name = SubSubCharField(max_length=100)

        status = models.IntegerField(choices=STATUS_CHOICES, default=0)

    STATUS_CHOICES = (
        (0, 'Regular'),
        (1, 'Manager'),
        (2, 'Admin'),
    )

    class F(FilterSet):
        status = ChoiceFilter(choices=STATUS_CHOICES)
        class Meta:
            model = User
            fields = ['status']



``TypedChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~

The same as ``ChoiceFilter`` with the added possibility to convert value to
match against. This could be done by using `coerce` parameter.
An example use-case is limiting boolean choices to match against so only
some predefined strings could be used as input of a boolean filter::

    import django_filters
    from distutils.util import strtobool

    BOOLEAN_CHOICES = (('false', 'False'), ('true', 'True'),)

    class YourFilterSet(django_filters.FilterSet):
        ...
        flag = django_filters.TypedChoiceFilter(choices=BOOLEAN_CHOICES,
                                                coerce=strtobool)


``MultipleChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~~~~

The same as ``ChoiceFilter`` except the user can select multiple choices 
and the filter will form the OR of these choices by default to match items. 
The filter will form the AND of the selected choices when the ``conjoined=True``
argument is passed to this class.

Multiple choices are represented in the query string by reusing the same key with
different values (e.g. ''?status=Regular&status=Admin'').

Advanced Use: Depending on your application logic, when all or no choices are 
selected, filtering may be a noop. In this case you may wish to avoid the
filtering overhead, particularly of the `distinct` call.

Set `always_filter` to False after instantiation to enable the default `is_noop`
test.

Override `is_noop` if you require a different test for your application.


``DateFilter``
~~~~~~~~~~~~~~

Matches on a date.  Used with ``DateField`` by default.

``DateTimeFilter``
~~~~~~~~~~~~~~~~~~

Matches on a date and time.  Used with ``DateTimeField`` by default.

``TimeFilter``
~~~~~~~~~~~~~~

Matches on a time.  Used with ``TimeField`` by default.

``ModelChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~

Similar to a ``ChoiceFilter`` except it works with related models, used for
``ForeignKey`` by default.

``ModelMultipleChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Similar to a ``MultipleChoiceFilter`` except it works with related models, used
for ``ManyToManyField`` by default.

``NumberFilter``
~~~~~~~~~~~~~~~~

Filters based on a numerical value, used with ``IntegerField``, ``FloatField``,
and ``DecimalField`` by default.

``RangeFilter``
~~~~~~~~~~~~~~~

Filters where a value is between two numerical values, or greater than a minimum or less than a maximum where only one limit value is provided. ::

    class F(FilterSet):
        """Filter for Books by Price"""
        price = RangeFilter()

        class Meta:
            model = Book
            fields = ['price']

    qs = Book.objects.all().order_by('title')

    # Range: Books between 5€ and 15€
    f = F({'price_0': '5', 'price_1': '15'}, queryset=qs)

    # Min-Only: Books costing more the 11€<commit_msg>Document requirement for `queryset` kwarg<commit_after>Filter Reference
================

This is a reference document with a list of the filters and their arguments.

Filters
-------

``CharFilter``
~~~~~~~~~~~~~~

This filter does simple character matches, used with ``CharField`` and
``TextField`` by default.

``BooleanFilter``
~~~~~~~~~~~~~~~~~

This filter matches a boolean, either ``True`` or ``False``, used with
``BooleanField`` and ``NullBooleanField`` by default.

``ChoiceFilter``
~~~~~~~~~~~~~~~~

This filter matches an item of any type by choices, used with any field that
has ``choices``.


Requires ``choices`` ``kwarg`` to be passed if explicitly declared on the ``FilterSet``. For example::

    class User(models.Model):
        username = models.CharField(max_length=255)
        first_name = SubCharField(max_length=100)
        last_name = SubSubCharField(max_length=100)

        status = models.IntegerField(choices=STATUS_CHOICES, default=0)

    STATUS_CHOICES = (
        (0, 'Regular'),
        (1, 'Manager'),
        (2, 'Admin'),
    )

    class F(FilterSet):
        status = ChoiceFilter(choices=STATUS_CHOICES)
        class Meta:
            model = User
            fields = ['status']



``TypedChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~

The same as ``ChoiceFilter`` with the added possibility to convert value to
match against. This could be done by using `coerce` parameter.
An example use-case is limiting boolean choices to match against so only
some predefined strings could be used as input of a boolean filter::

    import django_filters
    from distutils.util import strtobool

    BOOLEAN_CHOICES = (('false', 'False'), ('true', 'True'),)

    class YourFilterSet(django_filters.FilterSet):
        ...
        flag = django_filters.TypedChoiceFilter(choices=BOOLEAN_CHOICES,
                                                coerce=strtobool)


``MultipleChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~~~~

The same as ``ChoiceFilter`` except the user can select multiple choices
and the filter will form the OR of these choices by default to match items.
The filter will form the AND of the selected choices when the ``conjoined=True``
argument is passed to this class.

Multiple choices are represented in the query string by reusing the same key with
different values (e.g. ''?status=Regular&status=Admin'').

Advanced Use: Depending on your application logic, when all or no choices are
selected, filtering may be a noop. In this case you may wish to avoid the
filtering overhead, particularly of the `distinct` call.

Set `always_filter` to False after instantiation to enable the default `is_noop`
test.

Override `is_noop` if you require a different test for your application.


``DateFilter``
~~~~~~~~~~~~~~

Matches on a date.  Used with ``DateField`` by default.

``DateTimeFilter``
~~~~~~~~~~~~~~~~~~

Matches on a date and time.  Used with ``DateTimeField`` by default.

``TimeFilter``
~~~~~~~~~~~~~~

Matches on a time.  Used with ``TimeField`` by default.

``ModelChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~

Similar to a ``ChoiceFilter`` except it works with related models, used for
``ForeignKey`` by default.

If automatically instantiated ``ModelChoiceFilter`` will use the default ``QuerySet`` for the
related field. If manually instantiated you **must** provide the ``queryset`` kwarg.

``ModelMultipleChoiceFilter``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Similar to a ``MultipleChoiceFilter`` except it works with related models, used
for ``ManyToManyField`` by default.

As with ``ModelChoiceFilter``, if automatically instantiated ``ModelMultipleChoiceFilter`` will use
the default ``QuerySet`` for the related field. If manually instantiated you **must** provide the
``queryset`` kwarg.

``NumberFilter``
~~~~~~~~~~~~~~~~

Filters based on a numerical value, used with ``IntegerField``, ``FloatField``,
and ``DecimalField`` by default.

``RangeFilter``
~~~~~~~~~~~~~~~

Filters where a value is between two numerical values, or greater than a minimum or less than a maximum where only one limit value is provided. ::

    class F(FilterSet):
        """Filter for Books by Price"""
        price = RangeFilter()

        class Meta:
            model = Book
            fields = ['price']

    qs = Book.objects.all().order_by('title')

    # Range: Books between 5€ and 15€
    f = F({'price_0': '5', 'price_1': '15'}, queryset=qs)

    # Min-Only: Books costing more the 11€
{'fraction_non_alphanumeric': 0.1479676729260756, 'fraction_numerical': 0.005467078678393154, 'mean_word_length': 3.912434325744308, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6470297', 'n_tokens_mistral': 2298, 'n_tokens_neox': 2197, 'n_words': 918}